Learn Holochain

Welcome to Learn Holochain! This guide is an implementation of the Open Holochain Curriculum, a self-directed, self-paced, free online course designed to help you learn Holochain development.

What is Holochain?

Holochain is a framework for building distributed applications that doesn’t rely on centralized servers or global consensus blockchains. Instead, it uses an agent-centric approach where each participant maintains their own chain of cryptographically signed records, while a distributed hash table (DHT) enables data sharing and validation across the network.

Prerequisites

This curriculum assumes you have:

• Basic familiarity with JavaScript
• Some experience with Rust programming
• Comfort with command-line tools
• Understanding of basic programming concepts

If you need to brush up on Rust, these resources can help:

• Chapters 1–11 in the Rust Book
• Leetcode problems
• Rust on Exercism

Learning Path

This curriculum is organized around four progressive modules, each building on the skills and concepts from the previous one:

1. Module 1: Actions and Entries: Learn the fundamentals of Holochain’s data model by building a joke app with CRUD operations
2. Module 2: Links and Collections: Explore relationships between data by creating a blog with posts and comments
3. Module 3: Testing and Validation: Implement data validation rules and tests to ensure integrity
4. Module 4: Scaffolding and Signals: Learn rapid app development with scaffolding tools and real-time communication

Other Helpful Links

• Holochain Developer Discord - Join the #app-developers channel for help
• Developer Portal
• Holochain Glossary
• Programming References

How to Use This Guide

We recommend working through the modules in order. Start with Module 1 to grasp the fundamentals, then progress through each subsequent module to build your Holochain development skills.

Before diving into the modules, make sure to complete the Installation steps to set up your development environment.

Ready to begin your Holochain journey? Let’s get started!

Installation

Before starting the curriculum modules, you need to set up your development environment for Holochain.

Getting Holochain Installed

Your first mission is to install Holochain and run the “Hello World” application. This will ensure you have all the necessary components to work through the curriculum.

Please follow the official installation guide:

Holochain Getting Started Guide

The guide will walk you through:

1. Installing the Holochain development environment
2. Setting up the necessary tools and dependencies
3. Installing and running your first Holochain application

Verifying Your Installation

After following the installation guide, you should be able to successfully run the hello world application. You’re welcome to go through the full guide if you wish, but we will be covering that material (and a lot more) in this course.

If you encounter any issues during installation, check the Troubleshooting section of the guide or ask for help in the Holochain Developer Discord.

Development Environment

For this curriculum, you’ll need:

• Nix package manager: Used to provide a consistent development environment
• Text editor or IDE: VS Code with Rust and JavaScript extensions is recommended

Optionally it is useful to have the following, they you can get by without them and just use them in the nix environment.

• Rust and Cargo: For developing Holochain zomes
• Node.js and npm: For UI development and testing

Once you have successfully installed Holochain and run the “Hello World” application, you’re ready to start Module 1!

Actions and Entries

Module 1 introduces the fundamental data model of Holochain applications. In Holochain, all data is organized around two core concepts: Entries (the nouns) and Actions (the verbs).

What You’ll Learn

• Entries: The basic units of data in Holochain
• Actions: Operations that create or modify entries
• Records: Combined Actions and Entries that form the immutable history
• CRUD Operations: How to create, read, update, and delete data
• Hash Types: Understanding ActionHash vs EntryHash for data referencing

The Joke App

In this module, you’ll build a simple joke application that demonstrates core Holochain data operations. You’ll implement:

• Creating new jokes
• Reading existing jokes
• Updating joke content
• Deleting jokes
• Understanding how the DHT preserves history even after updates

This foundational knowledge forms the basis for all Holochain development, as you’ll learn how data flows from an agent’s source chain to the distributed hash table (DHT).

The challenge is designed to give you hands-on experience with Holochain’s agent-centric data model, which differs significantly from both traditional databases and other distributed systems like blockchains.

Slides & Lectures

Slides

• Actions and Entries - Learn about Holochain’s core data model, entries, actions, and CRUD operations.
• Building Blocks - Understand fundamental Holochain concepts and architecture.
• Project Structure - Explore how Holochain projects are organized.

Video Lectures

Video recordings of the lecture presentations will be made available here.

Coming soon

Challenge: Joke App

Overview

Your challenge is to build a simple joke application that implements basic CRUD operations (Create, Read, Update, Delete) using Holochain’s Actions and Entries model.

Key Learning Goals

Through this challenge, you’ll gain practical experience with:

• Working with Entry and Action types
• Understanding how data is referenced through hashes
• Implementing basic CRUD operations
• Experiencing Holochain’s immutable history model

Getting Started

The starter code and detailed instructions are available in the challenge repository:

Joke App Challenge Repository

You can view the difference between the starter code and the sample solution here.

Quick Setup

# Clone the repository
git clone https://github.com/CodeWithJV/holochain-challenge-1
cd holochain-challenge-1

# Enter the nix shell for development
nix develop

Tips

• Take time to understand the structure of the project before diving into implementation
• Pay attention to how ActionHash and EntryHash are used differently
• Test your implementation at each step using the provided test suite
• Remember that in Holochain, entries are never truly deleted - they’re marked as deleted

Requirements

1. Create a Joke Entry Type

   • Define a Joke entry type with fields for content and optional metadata
   • Implement a function to create new jokes

2. Implement Read Operations

   • Create a function to get a joke by its ActionHash
   • Add a function to get a joke by its EntryHash
   • Observe the differences between these two approaches

3. Update Functionality

   • Implement a function to update an existing joke
   • Ensure only the original author can update their jokes
   • Understand how updates create new records while preserving history

4. Delete Operation

   • Create a function to delete jokes
   • Understand that deletion in Holochain marks entries as deleted rather than removing them

Links and Collections

Module 2 builds on your knowledge of Entries and Actions by introducing Links and Collections - essential mechanisms for creating relationships between data in Holochain.

What You’ll Learn

• Links: How to create connections between entries in the DHT
• Link Structure: Understanding base, target, tag, and link types
• Collections: Creating grouped sets of data using Paths
• Relationships: Building complex data relationships in a distributed environment
• Querying: Techniques for retrieving linked data efficiently

The Blog App

In this module, you’ll build a blog application that demonstrates how to create and manage relationships between different types of data. You’ll implement:

• Creating blog posts with authors
• Linking comments to posts
• Creating collections of posts using Paths
• Retrieving related content through links
• Managing updates to linked content

Links are a fundamental concept in Holochain that enable you to build sophisticated data structures in a distributed environment. Unlike traditional databases with tables and foreign keys, Holochain uses links to establish connections between entries in the DHT.

By the end of this module, you’ll understand how to design and implement relationships between data in your Holochain applications, enabling more complex and feature-rich applications.

Slides & Lectures

Slides

• Links and Collections - Learn how to create relationships between data and build collections in Holochain.

Video Lectures

Video recordings of the lecture presentations will be made available here.

Coming soon

Challenge: Blog App

Overview

Your challenge is to build a blog application that implements relationships between different types of data using Holochain’s Links and Collections features.

Key Learning Goals

Through this challenge, you’ll gain practical experience with:

• Creating and managing links between entries
• Using Paths to create collections
• Retrieving data through relationship queries
• Designing a relational data structure in a distributed environment

Getting Started

The starter code and detailed instructions are available in the challenge repository:

Blog App Challenge Repository

You can view the difference between the starter code and the sample solution here.

Quick Setup

# Clone the repository
git clone https://github.com/CodeWithJV/holochain-challenge-2
cd holochain-challenge-2

# Enter the nix shell for development
nix develop

Tips

• Pay attention to how links are established between different entry types
• Remember that Paths are a powerful way to create predictable locations in the DHT
• When updating entries, make sure to update any relevant links as well
• Test your link queries thoroughly to ensure they return the expected data
• Use the tag field in links to store additional metadata when needed

Requirements

1. Create Blog Post Entry Types

   • Define a Post entry type with title, content, and timestamp
   • Implement functions to create and retrieve posts

2. Implement Comments

   • Create a Comment entry type
   • Link comments to their parent post
   • Create functions to add and retrieve comments for a post

3. Author Relationships

   • Link posts to their authors (agents)
   • Create functions to get all posts by a specific author

4. Collections with Paths

   • Create a collection of all posts using a Path
   • Implement a function to get all posts in the system
   • Add a function to get the latest posts

5. Updating Linked Content

   • Allow updating posts while maintaining comment links
   • Ensure updates preserve the relationship structure

Testing and Validation

Module 3 focuses on two critical aspects of Holochain development: ensuring data integrity through validation rules and confirming application functionality through testing.

What You’ll Learn

• Validation Rules: How to create rules that verify data meets your requirements
• Deterministic Validation: Understanding validation that must be consistent across the network
• Non-Deterministic Validation: Adding flexible validation like rate limiting or time-based rules
• Test Framework: Using Tryorama and Vitest to test Holochain applications
• Test Scenarios: Creating multi-agent test scenarios that simulate real-world usage

Extending the Blog App

In this module, you’ll continue developing the blog application from Module 2, adding validation rules and comprehensive tests:

• Implementing character limits for posts and comments
• Ensuring only original authors can update content
• Creating rate limiting validation to prevent spam
• Writing tests to verify CRUD operations
• Testing with multiple agents to simulate network interactions

Validation is a cornerstone of Holochain’s integrity, ensuring that even in a distributed network, all data conforms to the rules your application defines. By creating robust validation rules, you ensure that your application’s DHT remains consistent and trustworthy.

Comprehensive testing is equally important, allowing you to verify that your application functions correctly across different scenarios and with multiple users. By the end of this module, you’ll be able to create reliable Holochain applications with integrated validation and testing.

Slides & Lectures

Slides

• Testing and Validation - Learn how to implement validation rules and test your Holochain applications.

Video Lectures

Video recordings of the lecture presentations will be made available here.

Coming soon

Challenge: Blog App with Validation & Tests

Overview

Your challenge is to enhance the blog application from Module 2 by adding validation rules and comprehensive tests to ensure data integrity and verify functionality.

Key Learning Goals

Through this challenge, you’ll gain practical experience with:

• Implementing various types of validation rules
• Writing comprehensive tests for Holochain applications
• Creating multi-agent test scenarios
• Ensuring data integrity in a distributed application

Getting Started

The starter code and detailed instructions are available in the challenge repository:

Blog App Validation Challenge Repository

You can view the difference between the starter code and the sample solution here.

Quick Setup

# Clone the repository
git clone https://github.com/CodeWithJV/holochain-challenge-3
cd holochain-challenge-3

# Enter the nix shell for development
nix develop

Tips

• Focus on the validation callbacks in the integrity zome
• Remember that validation must be deterministic across the network
• Use the ValidationPackage to access necessary context for validation
• Write test cases that specifically target your validation rules
• For rate limiting, you’ll need to retrieve the agent’s previous actions
• Test both successful and failing scenarios to ensure validation works correctly

Requirements

1. Content Validation

   • Add character limits for posts (min/max length)
   • Implement validation for comment content
   • Create validation for post titles (no empty titles, reasonable length)

2. Privilege Validation

   • Ensure only the original author can update or delete their posts
   • Implement validation for comment authorship
   • Add validation to prevent tampering with author links

3. Rate Limiting

   • Create validation rules to prevent spam (limit posts per timeframe)
   • Implement rate limiting for comments

4. Tests with Tryorama

   • Write tests to verify all CRUD operations
   • Create multi-agent test scenarios
   • Test validation rules to ensure they properly reject invalid data
   • Implement tests for edge cases

5. Test Coverage

   • Ensure tests cover all main functionality
   • Include both positive tests (valid operations) and negative tests (operations that should fail)

Scaffolding and Signals

Module 4 introduces powerful tools for accelerating development and enabling real-time communication in Holochain applications.

What You’ll Learn

• Scaffolding: Using Holochain’s scaffolding tools to generate common code patterns
• Code Generation: Automating the creation of CRUD operations and validation rules
• Signals: Implementing real-time communication between agents in a Holochain network
• Remote Calls: Sending notifications and updates to other users
• Real-time Applications: Building interactive applications with immediate updates

The Messaging App

In this module, you’ll build a messaging application that demonstrates real-time communication between users:

• Creating direct messages between users
• Implementing real-time notifications using signals
• Building conversation threads with multiple participants
• Using scaffolding to rapidly develop the application structure
• Managing user presence and typing indicators

Scaffolding tools accelerate development by automating repetitive code patterns, allowing you to focus on unique aspects of your application. Signals enable real-time interactivity, creating a more responsive user experience.

By the end of this module, you’ll be able to rapidly develop sophisticated Holochain applications with interactive features, bringing your applications closer to the responsiveness users expect from modern web applications.

Slides & Lectures

Slides

• Scaffolding and Signals - Learn about rapid development tools and real-time communication in Holochain.

Video Lectures

Video recordings of the lecture presentations will be made available here.

Coming soon

Challenge: Messaging App

Overview

Your challenge is to build a real-time messaging application using Holochain’s scaffolding tools and signals functionality.

Key Learning Goals

Through this challenge, you’ll gain practical experience with:

• Using Holochain’s scaffolding tools for rapid development
• Implementing real-time communication with signals
• Building interactive features in a distributed application
• Creating secure messaging between agents

Getting Started

The starter code and detailed instructions are available in the challenge repository:

Messaging App Challenge Repository

You can view the difference between the starter code and the sample solution here.

Quick Setup

# Clone the repository
git clone https://github.com/CodeWithJV/holochain-challenge-4
cd holochain-challenge-4

# Enter the nix shell for development
nix develop

Tips

• The hc scaffold command can save you lots of time on boilerplate code
• Signal handlers must be registered during initialization
• Test signals with multiple agent scenarios to ensure they work properly
• For typing indicators, consider using a debounce function to avoid sending too many signals
• Remember that signals are not guaranteed to be delivered, so design your application accordingly
• Use the scaffolding tool’s generated code as a reference, but customize it to fit your specific needs

Requirements

1. Use Scaffolding Tools

   • Use the hc scaffold command to generate entry types and CRUD operations
   • Create a message entry type with scaffolding
   • Generate appropriate validation callbacks

2. Implement Direct Messaging

   • Create functionality for sending messages between agents
   • Implement conversation threads
   • Add support for retrieving message history

3. Real-time Notifications with Signals

   • Send signals when new messages are created
   • Implement handlers to receive signals from other agents
   • Create real-time notifications for message delivery

4. Enhanced Features

   • Add typing indicators using signals
   • Implement read receipts
   • Create user presence indicators (online/offline status)

5. Security and Validation

   • Ensure message privacy between participants
   • Validate message content appropriately
   • Implement proper error handling for signals