Holochain Programming Resources

Upgrade guides

If you’re upgrading your hApp to a newer version of Holochain, we have some upgrade guides to make your work easier.

HDK and HDI

When you write a Holochain application, the part that lives in Holochain is called a DNA. It runs as a guest in a WebAssembly sandbox and talks to the host, or Holochain conductor, through the host API. It’s also expected to implement callbacks that the conductor needs to call at certain times. The HDK and HDI Rust crates make it easy for you write guest code that interfaces with the conductor — the HDK for your DNA’s coordinator zomes and the HDI for integrity zomes.

• HDK reference
• HDI reference

Conductor APIs

The conductor exposes two separate RPC APIs over WebSocket interfaces:

• The admin API lets application managers control the conductor to install bundles of DNAs (called hApps), create agent IDs, combine a DNA and an agent ID into a running cell, and activate application RPC interfaces.
• The application API lets front-ends call a running cell’s functions and get information on the DNA bundle that the cell belongs to.

For both of these APIs, you make an RPC call sending a MessagePack-serialized request in a special envelope format to the conductor over WebSocket and listen for a response. The request’s envelope must contain a request ID, and the matching response will have the same ID. On the interface that exposes the app API, you can also listen for signals broadcast by cells. There are client libraries for JavaScript and Rust that make it easy to handle requests/responses and set up signal listeners.

• Conductor Admin API reference
• Conductor App API reference

Conductor clients

For ergonomic interaction with the two conductor APIs, there are two officially supported client implementations: one in JavaScript and one in Rust. If you intend to develop Holochain apps with a web-based UI, it is likely that all you’ll ever need is the JavaScript client.

• Conductor Client reference (JavaScript)
• Conductor Client reference (Rust)
• Conductor Client reference (C#) (community-maintained)

Conductor configuration

The conductor has a few settings that can (and should) be configured via a YAML config file. We’ve provided documentation of the internal structures that hold this config; if you can picture how to serialize this to YAML in your mind, you can write a config file! (We promise we’ll produce a more readable config file guide soon.)

• ConductorConfig structure

Binaries

There are three main developer binaries, and one user-oriented binary. You can run any of these on the command-line with the --help flag to get detailed documentation.

• holochain is the Holochain runtime, or conductor.
• hc is an all-purpose developer tool that:
  • scaffolds a project directory structure, build config, and boilerplate CRUD code for a new hApp
  • packages a DNA manifest file and one or more zomes (in WASM bytecode) into a DNA bundle
  • packages one or more DNAs into a hApp
  • manages Holochain conductor ‘sandboxes’ — configuration files and working folders that can be used to repeatably spin up conductors for testing
  • spawns hApps and UIs for testing
  • runs JavaScript-based integration test scripts
  • runs a local copy of peer discovery and WebRTC signalling services
  • see holochain_cli docs for more info
• lair-keystore is Holochain’s keystore for generating and signing with cryptographically secure keys. Use this command for initialization, configuration, and running of a Lair keystore. During normal operation, holochain will automatically spawn a lair process if it doesn’t find one running.
• Holochain Launcher is an end-user runtime, meant for finding, installing, and running hApps. It runs in an Electron webview container which also hosts the UIs of installed hApps. Developers can also turn on ‘developer mode’ and publish their hApps to a built-in hApp store.
  • Download the latest Launcher release from GitHub

Libraries

The developer community has created some useful utilities, libraries, and reusable modules for you to use in your own apps.

• Syn provides back-end and front-end libraries for creating real-time collaboration apps.
• Holochain Open Dev is a collection of reusable zomes and template repos from the developer community.
  • profiles lets you store user profile information.
  • peer-status lets peers communicate their status (e.g., ‘online’, ‘busy’, ‘on holiday’) with each other.
  • notifications lets a network designate a trusted agent to send out notifications over text, WhatsApp, and email.
  • file-storage chunks, stores, and retrieves arbitrary binary data.
• Matthew Brisebois has created many useful back-end and front-end libraries for building hApps.
  • rust-hc-crud-caps implements a pattern for tracking updates to a piece of data.
  • hc-cooperative-content implements patterns for collaborative content management — permission and authority management, update/delete processes, etc.
  • holo-hash-js is a small JavaScript library for making Holochain data IDs easier to work with on the front end.
  • identicons-js is a JavaScript library that implements our recommended UX pattern of displaying hashes and public keys visually rather than textually.
• hREA (website) is a toolkit for building economic applications, such as bookkeeping, resource management, supply chain, ERM, cooperative marketplaces.

Example applications

Studying existing Holochain applications and tutorials can provide valuable insights and inspiration for your projects. Here are some resources to explore:

• Holochain Foundation sample apps contains application written by Holochain team members.
• Moss (formerly We) is a groupware container for composing multiple applets into one cohesive experience.
• Snapmail is a privacy-first intranet mail app that doesn’t need an intranet server.
• Acorn is a unique, visually intuitive project management app based around defining goals first, then figuring out what needs to be done in order to achieve those goals.
• Flux is a communities app similar to Discord but allows add-ons for new content types such as long-form content and knowledge bases.

Tutorials and training

While you’ll learn a lot looking at the source code from the above GitHub projects, we’ve also produced some training material as a result of running courses in collaboration with our education partner Mythosthesia.

• Developer training materials from past courses
• Self-paced training course in video format

Concepts useful for understanding and building distributed systems

Holochain builds on a wealth of research and knowledge about distributed systems. Here are some carefully picked resources to help you on your journey:

• Keeping CALM: When Distributed Consistency is Easy, a paper by Joseph M Hellerstein and Peter Alvaro that lays down the mathematical foundation for distributed systems that don’t need coordination protocols, such as Holochain.
• CRDT.tech, a resource for learning about conflict-free replicated data types (CRDTs), data structures that let multiple users make concurrent updates to a resource with little to no manual conflict resolution.
• Yjs and Automerge, two CRDTs that can operate on arbitrary JSON. Syn (mentioned above under Libraries) uses Automerge.
• Local-first software: You own your data, in spite of the cloud, a paper by Martin Kleppmann et al of Ink & Switch that explores the user experience of local-first software built on CRDTs.