Holochain hApps

Holochain Analysis 2: Architecture, Technical Specification, Prototyping of hApps

Nov 13, 2018, 6:46AM
8 min, 28 sec READ

Part two in a three-part Holochain series provides an analysis of the technical architecture of hApps and discusses how to build them.

In part one of this three-part series, we looked at the philosophy and guiding principles behind Holochain and Ceptr. In this second article, we will look at the more technical details, outlining the structure, architecture, and existing prototypes of hApps (Holochain apps).

Structure of a hApp


Distributed Hash Table mapping

First, here is a look at the key features of a hApp:

The DNA file (usually a JSON, Javascript Object Notation) is the hApp's backbone, containing the storage/business logic (but not the front-end UI logic or connection to the outside world). The DNA receives agent actions (through the mediation of the zome functions, which are exposed to the UI and are called via AJAX or WebSockets), transforms the actions into chain entries, validates other people's chain entries, and communicates node-to-node.

Zomes are modular units defining functions (presently in Javascript and available in Rust, with more options introduced further along development), stored in sub-directories within the DNA folder. Zomes can be structured any way it makes sense to those writing them, but are usually expected to take one argument - either a string or JSON object. The chain entries created by zome functions can be shared publicly into the DHT or committed privately. The zome functions can also be internal helper functions or callable by the UI.

The biggest difference between zome functions and smart contracts is that everyone can call a smart contract, but with Holochain only an agent can call a zome function because that function is manipulating their personal state (their source chain). In other words, zomes are agent-centric.

In a countersigning situation (e.g., transactions) it's likely that one will validate the counterparty's chain and vice versa, i.e. mutually audit each other's recorded histories according to the hApp validation rules defined in the DNA. Then when both publish the same transactions, their peers validate their chain entries using the same rules. This validation could grow to be incredibly complex, because as one develops a history of transactions, his history is linked to the history of his counterparties, which is linked to the history of their counterparties, forming a massive DAG resembling the roots of an old tree or a large mycelium colony. So, in practice, most transactional hApps will likely validate the running balance of each counterparty and trust that the greater network of transactions has already been validated by a sufficient number of peers. The components that make up a hApp are:

  • A source chain is an agent's personal ledger of 'things that happened' (whatever that means for the app they're using -- transactions, sensor/temperature readings, messages, etc). It's a hashchain (just like Git trees and blockchains), so any modification to old data breaks the chain and gets noticed. The source chain contains private entries and entries meant to be publicly shared.

  • The DHT in a Holochain app is a Kademlia-like DHT. (Each app -- and each fork of each app -- has its own DHT.) The difference between it and a typical DHT is that nodes that receive the data also validate it against their own copy of the app's shared validation rules (the DNA). The things that live in the DHT are:

    • The DNA of the app
    • Each agent's public key
    • The headers of each chain entry from each agent's source chain (the header contains the typical previous/current hash like in any hash chain in addition to the agent's signature and a local timestamp)
    • The data for all public chain entries
    • Links, a special type of chain entry that points a known piece of data to an unknown piece of data in the DHT-sphere, with a string tag. DHTs constitute a huge universe and a link doesn't actually connect two addresses, but is more like a "pointer" or a "vector" - pointing in the general direction of a target address. For bi-directional connection, two links are necessary.
    • Warrants, a piece of evidence against a bad actor, signed by the validating agent who discovered it.

Importantly, Distributed Hash Tables as such are already sharded without introducing any unnecessary complexity and friction. Each hApp with its individual DHT (or fork thereof), following its defined validation rules and the agents using it (thereby in the process storing the records relevant to them) can be said to constitute a shard and different hApps can be bridged by agents running both hApps and translating between the contextual circumstances of the two.

When searching for some value, the algorithm needs to know the associated key and explores the network in several steps. Each step will find nodes that are closer to the key until the contacted node returns the value or no more closer nodes are found. This is very efficient: like many other DHTs, Kademlia contacts only O(log(n)) nodes during the search out of a total of n nodes in the system.

Further advantages are found particularly in the decentralized structure, which increases the resistance against a denial-of-service attack. Even if a whole set of nodes is flooded, this will have limited effect on network availability, since the network will recover itself by knitting the network around these "holes".

Source: Wikipedia entry on Kademlia.

Another detail that should be pointed out is the formal difference between decentralized and distributed applications. A decentralized app (dApp) runs on a decentralized blockchain (Ethereum), while a distributed app would run locally on one's personal device and offer peer-to-peer connections. Another way of looking at distributed hApps is as scripts that hook into distributed databases, compiling data.

A walkthrough demonstrating the process of building a hApp. A more recent tutorial video intended for developers has been made and will soon be made available. 

Tools Provided

Holochain is built specifically for general dApp development, so it's designed to be as accessible as possible. One can build Holochain dApps and proofs-of-concept in just a few hours.

There is still work to be done and kinks to iron out in the p2p networking protocol, so dApps aren't fully ready to be deployed in production, but between the CLI and scaffolding tool, one has everything needed to begin prototyping dApps available. There is also no need to learn any weird, domain-specific languages as Holochain will support anything that compiles into WebAssembly (validation code is written in JavaScript in the Go version and Rust in the latest release).

Command-Line Interface

The Holochain core libraries and command-line tools implementing the Holochain core functionality were recently rewritten in Rust (from the previous Go build, which will no longer be maintained) so as to enable it to be compiled in WebAssembly, allowing light clients to run in the browser (necessary for the Holo hosting app). The developer preview of the Rust rewrite is found at the Github repository here (with pre-built binaries available for download here).

The available documentation referring to the Go prototype will be replaced by the documentation for the new release in the coming months, the work in progress sections of which are available here

The latest release packs all functionality in a single executable (hc), which is used to initialize apps, start agent nodes, generate zomes, package hApps into compact hcpkg files and start web servers for serving Holochain applications. Additionally, holosqape and hcshell are Holochain app containers (GUI and CLI respectively) - a new entity introduced with the latest release that knits together all Holochain apps and data into an integrated whole with a cohesive interface. Different containers serve different purposes. Holosqape is a GUI container that allows one to install and run any hApp easily. Holochain-cmd is a command-line container that activates, builds, and tests applications and is used to build zome code into a package.

HDK Rust (Holochain Developer Kit) is a library and syntax for writing Zome code in Rust consistent with the WebAssembly (WASM) runtime environment. Any language that compiles to WASM and can serialize/de-serialize JSON data can be available as an option for writing hApps (with a similar Javascript HDK under development).  

$ ./hc
hc 0.0.1
Holochain Core Dev Team <devcore@holochain.org>
A command line for Holochain


  agent       Starts a Holochain node as an agent
  generate   Generates a new zome and scaffolds the given capabilities
  help       Prints this message or the help of the given subcommand(s)
  init       Initializes a new Holochain app at the given directory
  package     Builds the current Holochain app into a .hcpkg file
  test       Runs tests written in the test folder
  unpack     Unpacks a Holochain bundle into it's original file system structure
  web         Starts a web server for the current Holochain app

Scaffolding Tool

Holochain scaffolding tool for generating DNA files and schemas.

A web interface scaffolding tool for generating a DNA file is provided here. Within it one defines the basic parameters of a hApp's backbone, such as name and description of the hApp, zome modules (the data stored and tracked by a zome and the functions which can be called in that zome's API) within it and export/download the basic DNA template either as an JSON or YAML.

Additional Resources

Part one of our series on the philosophy behind Holochain and Ceptr can be found here.

A useful glossary of Holochain terms and definitions is found here.

A list of available working hApps is available here. Examples include a distributed Twitter clone (Clutter), a Holochain implementation of the Ethereum DAO, a distributed notary system and public key infrastructure (DPKI), a vault for managing how other apps access one's personal information, etc.  

The Mattermost Holochain and Ceptr community chat can be logged into here.

The developer documentation (not including the Rust rewrite) is hosted here.

The Github repository - here.

Ceptr official site, blog and included video material and lectures - here.  

Disclaimer: information contained herein is provided without considering your personal circumstances, therefore should not be construed as financial advice, investment recommendation or an offer of, or solicitation for, any transactions in cryptocurrencies.