Holochain Glossary

WIP

This article is currently a work in progress and subject to frequent change. See the changelog for details.

As you go through our documentation, you’ll probably find some unfamiliar terms, or familiar ones used in surprising ways. Here are the definitions we use.

Action

Everything an agent does in an application is expressed as a series of actions, recorded on their source chain as a series of elements. That is, when the source chain records a piece of data, it’s more accurate to say that it’s recording the agent’s act of creating it.

Address

  1. DHT address
  2. Transport address

Address space

The entire range of possible DHT addresses. This space is circular, meaning the last address is adjacent to the first address.

Agency

The power of an agent to act in their environment.

Agent

  1. Anyone or anything acting with agency, such as a human or bot.
  2. An agent (see definition 1) who participates in a Holochain network through their cell.

Agent activity

Records of all the source chain headers that an agent has published, along with any warrants against them for malicious activity. An agent’s neighbors, as peers whose agent addresses are near to theirs, are the validation authorities for their agent activity data.

Agent activity operation

A DHT operation produced by the author of a source chain element, notifying the validation authorities for the author’s agent ID entry that they’ve published something.

Agent-centric

Describes any distributed system that puts agents at the center of the design, giving them agency over their online identity and the data they create. Agent-centric systems are usually decentralized and use public-key cryptography to identify agents. Git, Holochain, Dat, and Secure Scuttlebutt are highly agent-centric, while client/server and blockchain systems are less so.

Agent address

The address of an agent ID entry on the DHT, calculated from the agent’s public key. It is used in locating an agent’s transport address for gossiping and making remote calls, and in calculating the proper validation authority to send a DHT operation to or receive a piece of DHT data from.

Agent ID

The public key of an agent. It serves as their unique ID in any DHT they join (although an agent can create multiple IDs to use in different spaces if they like).

Agent ID entry

The entry associated with the third of the four genesis elements at the the beginning of an agent‘s source chain, which contains their agent ID. The address of this entry is also the agent’s address on the DHT.

Append-only

Any data structure that can only be written to. Once written, that data becomes ‘immutable’ (it can’t be modified or deleted). An agent’s source chain and the DHT are both append-only.

App entry

An entity that holds application data. On the DHT, an app entry is created for every new entry operation, and validation authorities who hold the entry also hold the headers of all agents who have published that exact same entry as metadata, along with other metadata such as links. App entries are deduplicated but individual agents’ writes of those entries are distinguished by their headers.

Application (app)

When we’re talking about Holochain, ‘app’ is synonymous with hApp, a collection of back end and front end components that comprise something a Holochain user can interact with.

Assigned capability grant

A capability grant that only allows specified agents to call a zome function in the grantor’s cell.

Atomic commit

The guarantee that all source chain commits performed in one zome function will succeed or fail together, similar to a database transaction. Failure can be caused by validation failure for an individual element or a hardware I/O failure. It can also be caused by a prior atomic commit finishing and advancing the source chain state while the current function call is running, that is, between the time that the conductor creaetd the current function’s workspace and the time that it attempted to persist its own changes to the source chain.

Author

The agent who has written and signed an element to their source chain.

Author grant

A capability grant that allows anyone possessing the source chain author‘s private key to call any zome function in a cell. The only callers that should possess this key are the agent’s own clients and other bridged cells associated with the same agent ID in the same conductor.

Back end

When we’re talking about Holochain, synonymous with one or more DNAs for a hApp—this is code that contains the base-level persistence and validation logic.

Blockchain

A distributed, partially decentralized system that promises Byzantine fault tolerance by using a global consensus protocol to get all nodes to agree on a single, shared history of events. This history is stored as a hash chain of ‘blocks’, or bundles of state transitions. A blockchain can be public (anyone can join) or permissioned/private (membership is controlled). Public blockchains are usually trustless, ensuring tamper-resistance by making cheating more costly than honesty.

Bootstrapping

The act of joining an application’s DHT. Bootstrapping involves finding an initial group of peers to gossip with, either by talking to a bootstrap service, injecting a list of known good peers, or other means appropriate to a particular transport implementation.

Bootstrap service

A service which keeps track of lists of transport addresses for peers, segregated by DNA hash. When an agent wants to bootstrap into an application’s DHT, they ask the bootstrapping service for a list of existing peers and make individual connections to them.

Bridge

A connection between cells in one user’s conductor, which allows one cell to call the zome functions of another cell.

Byzantine fault tolerance (BFT)

The ability of a distributed system to reach consistency despite ‘Byzantine failures’, which are data corruptions caused by accidental or intentional faults in nodes or the networking transport between them.

Capability

A privilege granted by a capability grant to call certain zome functions. The grantor can revoke this capability by deleting the original grant from their source chain.

Capability-based security

A security model that allows the owner of a resource to grant others access while maintaining ultimate control. Instead of allowing direct access to the resource, it mediates access and manages privileges by issuing ‘capabilities’, or tokens representing the resource. In Holochain, an agent‘s conductor protects their running cells and authorizes callers’ access to them by issuing and checking the secrets and credentials they supply against existing grants.

Capability grant

A private system entry that an agent writes to their source chain to record the granting of a capability and its access level, including the secret (if the grant is transferrable or assigned) and the assignees (if the grant is assigned). If the access being granted is unrestricted, no secret or assignees are needed.

Capability grantor

The agent who creates a capability grant.

Capability claim

A private system entry that a subject writes to their source chain to record the secret they received for a transferrable or assigned capability grant. This allows them to later call the zome functions to which access has been granted.

Capability secret

A secret series of bytes for a capability grant, created by the grantor, which proves that its bearer has been granted a capability and is allowed to exercise it.

Capability subject

The entity that is given permission to access a resource via capability-based security. In Holochain, this can be a client or bridged cell on the user’s machine, or it can be another agent making a remote call.

Cell

A particular Holochain DNA when it’s bound to an agent ID and running in the conductor. DNA + agent = cell.

Centralization

The degree to which computing power, agency, decision-making power, or responsibility in a distributed system is concentrated in certain nodes. Client/server systems are highly centralized, both in computer power and agency, while cloud systems have decentralized computing power and centralized agency and peer-to-peer systems have both decentralized computing power and agency. The complement of centralization is, of course, decentralization.

Client

In Holochain terms, any piece of external software that accesses a DNA‘s zome functions. The client makes function calls over the conductor‘s RPC interface, and can be a GUI, shell script, service, or scheduled task. This client usually lives on the same machine as the conductor, because it represents the user’s agency in the application.

Client/server

A highly centralized distributed system architecture in which certain nodes are responsible for most of the processing, storage, and decision-making. Client/server systems typically give low agency to end-users.

Clone (DNA)

The act of modifying the properties of DNA at installation time in order to change its hash and create an isolated network and DHT. This allows users to enjoy a private space using existing rules without creating a DNA from scratch.

Cloud

A specific client/server in which computing power is decentralized but agency is centralized.

Commit

The act of adding an element to a source chain.

Commons

Any resource that is used and managed by a group of agents, but is owned by none. In order to survive, a commons must have rules governing its use. A Holochain DHT is a type of digital commons whose rules are enforced by its DNA and Holochain’s subconscious rules.

Conductor

The service that lives on an agent‘s device and hosts all of their cells, stores their data, makes their zome functions available to local clients via an RPC interface, and handles network communication between their cells and other agents’ cells.

Conductor admin API

The RPC interface that a conductor exposes, which allows local clients to access and manipulate the configuration of DNAs, agents, cells, and RPC interfaces for communicating with individual cells.

Conflict-free replicated data type (CRDT)

A function that allows two nodes in a distributed system to separately make changes to the same piece of data without creating conflicts. A CRDT is logically monotonic, which means it satisfies the CALM theorem and doesn’t need a coordination protocol. Holochain doesn’t use CRDTs directly (yet), but we recommend considering using CRDTs in app design to handle the merging of different agents’ data.

Consensus

  1. Synonymous with consistency in a distributed system.

  2. Synonymous with global consensus in a blockchain or other DLT.

Consistency

The point at which all nodes in a distributed system agree on the state of the data they hold. Blockchains enforce a form of consistency called global consensus, whereas Holochain uses ‘strong’ eventual consistency.

Consistency/availability/partition-tolerance (CAP) theorem

This principle states that all distributed systems are prone to ‘partitions’ (groups of nodes becoming unavailable to each other), and that in the presence of a partition a design can only guarantee availability (data can always be accessed and written) or consistency (data is always correct), but not both.

Consistency as logical monotonicity (CALM) theorem

This principle states that as long as a function is logically monotonic, it can be run on multiple nodes in a distributed system and reach strong eventual consistency without needing coordination protocols. Holochain’s DHT is CALM, in that every DHT operation is simply accumulated without attempts to reconcile it with other operations. State is then determined by processing the accumulated data.

Content-addressable storage (CAS)

Any storage system that gives a unique ID to each piece of data and allows it to be retrieved by its ID rather than its physical location. A DHT is a type of CAS.

Coordination protocol

An algorithm that governs the synchronization of data in a distributed system and aims to prevent or resolve data conflicts that happen when two nodes are out of sync with each other. Any state transition that isn’t logically monotonic needs a coordination protocol. In Holochain, counterparty signing is a simple coordination protocol between two or more agents who want to reach agreement with each other.

Counterparty signing

A simple coordination protocol between two agents in a Holochain DHT in which they agree to lock their respective source chain states, reach consistency on the contents of each other’s source chain, and sign one single shared entry which they then commit to their source chains. Counterparty signing is not yet directly supported by Holochain but will be in the future.

Create-entry action

A new-entry action that, when published to the DHT, causes an entry to be available to other DHT members (unless the entry is private, in which case only a record of its creation is published).

An action that, when published to the DHT, causes a link from one piece of element data to another to be available to other DHT members.

Create, read, update, delete (CRUD)

The four main actions an application needs to do with data. Even though all data structures in Holochain are append-only, data can still be marked as updated or deleted by publishing a new action that marks the old data as modified in a CALM way. New-entry actions create and/or update entries, while delete-entry actions remove them. Links can also be created and deleted.

CRUD action

An element that expresses a CRUD operation on a piece of data or metadata. Create-entry, update-entry, delete-entry, create-link, and delete-link actions are all CRUD actions.

Dead data

As no data in a Holochain DHT or agent’s source chain are ever deleted, existing data must be marked as no longer active. Dead data takes four forms:

  1. A new-entry action header that has been marked as deleted by a delete-entry action.
  2. A create-link action header that has been marked as deleted by a delete-link action.
  3. An entry whose new-entry action headers have all been marked as deleted.
  4. A link whose create-link action headers have all been marked as deleted.

Decentralization

The act of removing central points of control. Many distributed systems are decentralized to various degrees.

Deduplication

The removal of identical entries in a CAS. Most CASes, including Holochain’s DHT, deduplicate content automatically. Holochain’s DHT does, however, disambiguate between individual writes of an entry by storing the authors’ headers alongside it as metadata.

DeepKey

Holochain’s default implementation of a DPKI.

Delete-entry action

An action that, when published to the DHT, causes a new-entry action‘s header to be marked as dead. If all such headers that caused an entry to be published are marked as dead, the entry itself will also be marked as dead.

An action that, when published to the DHT, causes a create-link action‘s header to be marked as dead. If all create-link elements that caused a link to be published are marked as dead, the link itself will also be marked as dead.

DHT address

The unique ID of a piece of element data (entry, header, or agent) on the DHT. Every piece of data has an address that is generated directly from its content, usually by a hash function. This makes the DHT a content-addressable storage system.

DHT data

A piece of data that lives in the DHT. DHT data is assigned to a neighborhood of validation authorities based on the base address of the DHT operation that expresses its creation, and is deduplicated. All DHT data is either element data with an address of its own, or metadata attached to a piece of element data.

DHT operation

A unit of gossip that communicates a request to a validation authority to transform the data they hold in some way. Each DHT operation has a base address and gets sent to the DHT authorities for that address. For each type of element/action, an author produces one or more DHT operations. For example, a create-entry action for a public entry produces three DHT operations:

  • One to publish the header, which is sent to the authorities for the header’s address for validation and storage,
  • One to publish the entry itself, which is sent to the authorities for the entry’s address along with a copy of the header, and
  • One to register agent activity, which is sent to the authorities for the author’s agent ID (that is, the author’s neighbors).

Distributed hash table (DHT)

A collection of data stored collectively by many nodes in a peer-to-peer network. In a DHT, a node retrieves data by address, usually its cryptographic hash, by searching for a peer who holds the data. Holochain uses a validating DHT to store DHT data and chooses agents to hold data based on the nearness of their agent address to the data’s address. Each DNA has its own separate DHT.

Distributed ledger technology (DLT)

Any technology that involves many nodes in a distributed system sharing an append-only history of state transitions. Blockchain DLTs use a global ledger, whereas others use some form of sharded or partially connected ledgers. Holochain is a type of DLT in which each agent is responsible for their own ledger, called a source chain.

Distributed public key infrastructure (DPKI)

A public key infrastructure that doesn’t rely on a central authority. DeepKey is Holochain’s default DPKI implementation.

Distributed system

Any system that involves multiple nodes talking to one another over a network, whether decentralized or centralized. Because communication isn’t instantaneous, different nodes can create conflicting data. Many distributed systems use a coordination protocol to come to consistency, while others rely on the CALM theorem to avoid conflicts altogether.

DNA

A package of executable code that defines the shared ‘rules of the game’ for a group of agents. A DNA is made up of zomes, which define validation rules for data, zome functions that allow agents to write to their source chain, retrieve data from the DHT, send signals to a listening client, or make remote calls to another cell. Each DNA has its own isolated DHT, and is instantiated by each user on their own device as a cell.

DNA bundle

The file that holds a complete DNA, both executable zomes and metadata (see DNA manifest for details on this metadata).

DNA instance

See cell.

DNA manifest

A file that specifies the components of a DNA, including locations of compiled zomes and metadata such as a name, description, hashspace UID, and properties. This manifest can be used by a compilation tool to build a DNA bundle.

DNA properties

Arbitrary data that affects the operation of the DNA. A user can specify properties at DNA installation time, which causes the DNA to be cloned if the user-specified properties are different from the default properties. The executable code can then access those properties to change its behavior, similar to configuration files or environment variables. This is a simple way of allowing separate networks of users to enjoy isolated and slightly modified experiences using a set of base rules.

End-to-end encryption (E2EE)

A channel between two nodes in a public network that allows them to transfer secret messages that cannot be decrypted by eavesdroppers. Holochain’s node-to-node gossip, remote calls, and proxy relay use E2EE (currently QUIC with TLS encryption).

Element

The data structure that holds an action in an agent‘s source chain. Some elements are a combination of header and entry, such as new-entry actions, while others contain all their data inside the header.

Element data

Any piece of addressable data that can (though doesn’t need to) be published to the DHT. Element data consists of anything contained in an element — that is, a header or an entry, which are stored by separate validation authorities on the DHT. This is in contrast to metadata, which is attached to a piece of element data.

Entry

A basic unit of user data in a Holochain app. Each entry has its own defined entry type. When an agent commits an entry, it is combined with a header into an element that expresses a new-entry action. Then it is written to their source chain as a record of the action having taken place. An entry can be public or private; if it’s public, it’s also published to the DHT. There are app entries whose purpose and structure are defined by the DNA developer, and there are special system entries such as an agent ID entry.

Entry type

A specification for any sort of entry that a DNA should recognize and understand, similar to an OOP class or database table schema. It can specify whether entries of its type should be public or private, and how many required validations should exist. DNA developers create their own entry types for the data their app needs to store, and can write validation functions for elements that create, update, or delete entries of those types.

Eventual consistency

A promise made by distributed systems that optimize for availability over consistency (see CAP theorem), meaning that given enough time, every node ought to eventually reach consistency with each other. Strong eventual consistency means that nodes will eventually reach consistency without conflicts, which is possible for any system whose state transition functions adhere to the CALM theorem.

Fork (DNA)

To change a DNA in a way that doesn’t alter its behavior, resulting in a new hash for the DNA that gives it a separate DHT. Forking is most easily done by passing a hashspace UID at DNA installation time.

Fork (source chain)

To create alternate versions of one’s history in an app by basing two source chain elements on one parent element. Forking one’s source chain is always an invalid action, detected at the subconscious level by the author’s agent activity authorities and addressed by both the subconscious and the DNA‘s executable code (zomes).

Front end

In Holochain terms, synonymous with graphical user interface or, more generally, client.

Genesis elements

The four elements at the beginning of an agent‘s source chain, consisting of:

  1. The DNA hash, which shows that the agent has seen the network’s rules and agrees to abide by them,
  2. The membrane proof, which the agent presents as a claim that they should be allowed to join the DHT,
  3. The agent ID, which advertises the agent’s public key,
  4. The init complete element, which tells the conductor that all the DNA’s init callbacks have completed successfully and the source chain is ready to write app entries.

Global consensus

Agreement among all nodes in a blockchain on a single, shared global ledger. Holochain prefers ‘local’ consensus, both between interacting parties using counterparty signatures and among a small set of third-party validation authorities.

Global ledger

A ledger whose contents are identical across all nodes in a blockchain.

Gossip

A protocol used by many peer-to-peer networks to rapidly propagate data. Each node knows a few other nodes, who know a few more, and so forth. Whenever any node receives a message, they broadcast it to some or all of their peers. Data propagates slowly at first, then spreads at an exponential rate. Nodes in a Holochain network share DHT operations, neighborhood health, and peer transport addresses via gossip.

Graphical user interface (GUI)

A client that presents a visual, easy-to-understand way for a user to interact with a cell or collection of cells running in their conductor. As with any client of a Holochain application, the GUI usually runs on the same machine as the conductor.

hApp bundle

One or more DNAs, which together form the back end for a complete hApp. These components are specified in a hApp manifest file, and can be packaged in a zip archive along with the manifest or downloaded separately from the internet.

Hash

A unique ‘fingerprint’ for a piece of data, calculated by running the data through a special function. A hash can serve as a unique identifier for that data (such as with addresses of DHT entries) and makes it easy to retrieve data from a hash table and verify its integrity.

Hash chain

An append-only data structure that can be used as a tamper-evident, sequential log of events, such as a source chain or blockchain.

Hashspace UID

A unique ID, specified in a DNA bundle file or passed at DNA installation time, that forks the DNA without modifying any of its behavior. This can be used to create separate DHTs that use the same set of rules.

A piece of data that represents an element on an agent‘s source chain. Headers link to the hash of their previous header, which creates a tamper-evident journal or ledger of all their actions in an application.

History

The sequence of actions taken by an agent, recorded as elements in their source chain.

Holo

The company funding the development of Holochain and providing hosting services for Holochain apps.

Holochain Development Kit (HDK)

Holochain’s standard software development kit (SDK) for DNA developers. It provides developer-friendly access to the Holochain host API, as well as macros for defining entry and link types, validation functions, and init functions.

Holochain application (hApp)

A collection of DNAs and a client (or clients) that allow users to interact with those DNAs. The DNA components are typically distributed as a DNA bundle.

Holochain Core

The basic components of Holochain—the conductor, the nucleus/ribosome, and the persistence and networking layers.

Holochain host API

The set of core functions that Holochain’s nucleus makes available to a ribosome, so the ribosome can in turm make them available to a running cell. These functions allow the DNA to access and manipulate an agent‘s source chain, run cryptographic functions, retrieve and publish DHT data, bridge to the agent’s other cells, and make remote calls to their peers.

Holo Host

A platform and marketplace where Holochain users offer their spare computing capacity to host cells for web users, functioning as a bridge between Holochain and the traditional web. Read more at Holo’s website.

Host API

See Holochain host API.

Immune system

A property of Holochain’s validating DHT, whereby healthy nodes detect invalid data, share proof of corruption among their peers, and take defensive action against the corrupt nodes that produced it by publishing warrants against them. While each agent is individually free to interact with a peer with warrants attached to their agent ID, most agents will refuse to interact or gossip with them. The cumulative effect is a collective rejection of the corrupt nodes (see mutual sovereignty).

Init callback

A function in a DNA that the nucleus calls when an agent starts a cell for the first time. This can be used to set up initial source chain #state, etc.

Init complete element

An element that Holochain automatically writes to an agent‘s source chain to indicate that all of a DNA‘s init callbacks have successfully run and their cell is ready to use.

Intrinsic data integrity

Holochain’s most basic strategy for guaranteeing data integrity. Data is considered valid or invalid based on the DNA‘s validation rules, as well as Holochain’s subconscious validation rules.

Journal

Synonymous with ledger.

Ledger

A history of events or state transitions. In distributed ledger technology, ledgers are usually stored as hash chains, such as a Holochain agent‘s source chain.

A piece of metadata connecting one address on the DHT to another. Each link has a tag for storing arbitrary content and is stored in the DHT at its base‘s address.

The address of the element data on the DHT that a link links from.

An arbitrary piece of data, stored with a link, that contains application-defined information. A link tag can define an ad-hoc type for the link, be used in a query filter, or store information about the link target to avoid a second DHT query to retrieve the target’s content.

The address of the element data on the DHT that a link links to. Link targets have no metadata pointing back to the base, and therefore have no knowledge that they’re being linked to.

Live data

DHT data or source chain data that meets two criteria:

Logical monotonicity

The property of a set of facts whereby the truth of prior facts are never negated by the addition of later facts. CALM relies on functions that exhibit this property. For example, Holochain’s source chain, DHT, and CRUD actions only add new data without removing old data.

Membrane

One of two types of permeable boundaries that allow or disallow access:

  1. The layer of protection around an agent‘s cell, secured by capability-based security, that prevents unauthorized access to the cell’s zome functions, source chain data, or view of the DHT.

  2. A special validation function in a DNA that checks an agent’s membrane proof and determines their right to become part of the DNA’s network. If a joining proof is invalid, existing members of the network will refuse to talk to the new agent.

Membrane proof

An element written to an agent’s source chain that proves they have permission to join a DHT, for example, an invite code or signed authorization from an existing member. The DNA for the DHT has a validation function that checks the validity of the joining proof; if agents validating the joining proof determine that it’s invalid, they can refuse to communicate with the new agent. This is the immune system‘s first line of defense against malicious actors.

Metadata

Supplementary data attached to a piece of element data on a DHT. All element data (entries and headers) can have links and CRUD status as metadata, while entries can also have copies of the headers that express the new-entry actions that created them. An agent ID entry can also have agent activity records and warrants.

Microservice

An application architecture pattern that encourages small, single-purpose back end services. Holochain DNAs can be seen as microservices that combine to form a fully featured hApp.

Mutual sovereignty

The relationship between the autonomy of the individual and the collective intentions of the group. A successful commons finds a healthy tension between these opposites. Holochain’s design is based on this principle, empowering participants to control their own identity and responses to their peers by equipping each of them with a full copy of the application. The application constitutes the group’s rules and norms, formalized as executable code in its DNA modules, so by running the application a participant consents to become a member of the group.

Nearness

The mathematical distance between two addresses to each other in the DHT‘s address space.

Neighbor

See neighborhood.

Neighborhood

A range of DHT addresses about which a node knows everything they ought to know. Neighbors collectively support the resilience of all DHT data whose address is within their respective store arcs by storing and validating it and gossiping it to each other. They also have a wider neighbourhood of nodes they can talk to to receive authoritative data, defined by their query arc.

Network

In Holochain terms, a collection of nodes gossiping with each other to form a validating DHT, aiding in data storage and retrieval, validation, and peer discovery. Each DNA has a separate network.

New-entry action

Any action that produces a new entry, either a create-entry or update-entry action. If the entry’s type is public, the entry will be published to the DHT along with its header. If the entry’s type is private, only the header is published.

Node

An individual agent in a Holochain network who has an agent address and can be talked to via gossip.

Nucleus

The core of Holochain. With the help of the ribosome, it governs data flow between the conductor and a cell and enforces the subconscious validation rules.

Participant

Synonymous with ‘user’. We often prefer the term ‘participant’ because a Holochain DHT is a commons of mutually sovereign peers who all actively work to maintain its integrity, rather than people who merely ‘use’ an application.

Peer

Synonymous with node or agent; describes an agent who belongs to the same network as another.

Peer discovery

The act of finding peers to communicate with. Initial discovery is done by bootstrapping, and ongoing peer discovery is handled by DHT lookups and gossip.

Peer-to-peer

Describes any highly decentralized distributed system in which nodes talk directly to one another without the intermediation of a server or other type of central node.

Private entry

An entry which is stored on an agent‘s source chain, but not published to the DHT.

Proxy relay

A special software service that helps two Holochain nodes behind restrictive firewalls or NATs communicate with each other. The proxy is blind to the end-to-end-encrypted communications it’s relaying; it only knows how to receive and route messages on behalf of an agent it’s proxying for.

Public entry

An entry whose type is marked ‘public’ and is published to the DHT.

Public-key cryptography

A cryptographic system that consists of two keys, a public component and a private component. These keys are mathematically related to each other in a way that’s easy for the key pair’s owner to prove, but nearly impossible for a third-party to reverse-engineer. In Holochain, an agent‘s public key lives in the DHT and serves as their ID while the private key stays on the agent’s device. Peers can verify an agent’s claim of authorship on published DHT data by checking their signature, and can use an agent’s public key to encrypt a private message that only the holder of the corresponding private key can decrypt.

Public-key infrastructure (PKI)

A way for agents to share their public keys, prove their authenticity, and revoke old keys if they’ve been compromised. Most PKIs, such as the global TLS certificate authority system, are centralized. Holochain will provide a distributed PKI system.

Public-key signature

The hash of a piece of data, encrypted with a private key. It can be decrypted by anyone who has a copy of the public key, which allows them to verify authorship of the signed data. In Holochain, the author of any element data that gets published to the DHT attaches their signature to each of the DHT operations they produce, to prove authorship and allow third-party tampering to be detected by others.

Public/private key pair

See public-key cryptography.

Publish

The act of converting an element into one or more DHT operations and sending them to the respective validation authorities for validation, transformation into element data and storage. This happens after it has passed the author’s own copy of the validation rules. The validation authorities who are responsible for that entry’s address receive it, validate it, and if it’s valid, store a copy of it and pass a validation receipt back to the author.

Query arc

A range of DHT addresses for which an agent knows a sufficient number of peers who collectively have fault-tolerant coverage (see saturation) of that range. An agent knows that they can request DHT data from anyone within this query arc and get a reasonably authoritative answer (making allowances for eventual consistency). This query arc is a looser neighborhood than a store arc.

Remote call

A remote procedure call that one agent’s cell makes to the zome functions of another agent’s cell within a network. The callee controls access to their zome functions via capability-based security.

Remote procedure call (RPC)

  1. A call that a client makes to a zome function or conductor admin API function over a local socket interface.
  2. A remote call between agents in a network.

RPC interface

A network port that the conductor exposes, allowing clients to call the conductor admin API or make zome function calls to running cells. This interface only listens for local connections, so it can’t be accessed over the internet.

Required validations

The number of validation receipts that an element of a given entry type must have in order to be considered accepted by the validation authorities and be ‘live’ on the DHT. On initial publish, the author of an element collects these receipts; thereafter, validation authorities gossip these receipts to each other. If the author can’t collect the required number of receipts, it’ll try to republish to more authorities later.

Resilience

The level of a network‘s capacity to hold itself in integrity as nodes leave, join, or attempt to attack it. In a Holochain DHT, neighbors attempt to collaboratively adjust their store arcs to ensure that every piece of data is covered by enough validation authorities to make it always available.

Ribosome

The ‘sandbox’ or ‘virtual machine’ inside which a cell runs. In Holochain’s current design, the ribosome is a WebAssembly runtime that exposes Holochain’s host API to the cell and allows the nucleus to call the instance’s validation functions, init function, zome functions and other exposed functions.

Rust

The programming language currently used to build Holochain Core and DNAs/zomes. See Rust website.

Saturation

The state at which there are enough peers holding a piece of DHT data to make sure it’s reliably available to anyone who asks for it (see resilience).

Scenario test

An automated test that simulates real-life conditions involving multiple agents on a simulated or real network, used to test a DNA‘s tolerance of various failure modes. Tryorama is used to write scenario tests in JavaScript.

Sharding

A process of reducing the processing and storage load of individual nodes in a distributed system by distributing data and/or work among them. While some sharded systems such as Ethereum 2 separate nodes into discrete shards, Holochain’s DHT separates them into overlapping neighborhoods.

Signal

A message emitted by a cell, meant for a client to receive and act upon.

Source chain

A hash chain of elements committed by an agent. Every agent has a separate source chain for each of the cells they’re running, which stores all of the actions they’ve taken in that cell.

State transition

A modification of application state. In Holochain, all state transitions are recorded as elements in an agent‘s source chain that represent the actions of creating, updating, and deleting data and metadata. If the data is meant to be public, they are then published to the DHT as a set of DHT operations that are sent to the appropriate validation authorities for validation, processing, and storage.

Subconscious

The ‘base’ validation rules defined by the Holochain nucleus that check validity of DHT operations and the integrity of each agent‘s source chain.

Store arc

A range of DHT addresses for which an agent claims authority — that is, responsibility to validate, store, and gossip all DHT data whose addresses fall within the arc. This store arc is an agent’s closest neighborhood in which they know everything that’s going on, as compared to a query arc in which they merely know who exists and what range of addresses they claim authority for.

System entry

A type of entry that Holochain itself understands. System entries can be created, updated, and deleted just like app entries. The system entry types currently defined are:

Transferrable capability grant

A capability grant that allows any caller who can produce the right secret to call a zome function in the grantor’s cell.

Transport address

The underlying network address of an agent in a network, such as its IP address on the internet or a LAN. This is different from its agent address, which is a DHT address, although every agent ID maps to a transport address, published by the agent themselves and held by the validation authorities for the agent address.

Transport implementation

A networking layer that allows peers in the same network to gossip with each other and make remote calls. Currently Holochain only supports two transport implementations:

  • a QUIC-based transport implementation for IP networks such as the internet or a LAN
  • A local-only transport implementation that allows cells within one conductor to communicate directly with each other without touching the network

Trustless

Describes a peer-to-peer distributed system that is Byzantine fault tolerant even when nodes are anonymous and membership is unrestricted. Trust is placed in the algorithm, rather than the reputation of the actors.

Tryorama

A scenario testing library for Holochain. See Tryorama GitHub repo.

Unrestricted capability grant

A capability grant that allows anyone to call a zome function in the grantor’s cell.

Update-entry action

A new-entry action that replaces another new-entry action, essentially allowing the modification of already-written data in a way that allows for multiple branching revision chains. This can be used to modify public or private, system or app entries.

Validating DHT

Holochain’s DHT design which creates an immune system for the network. Validation authorities are chosen at random, based on their nearness to the address of the data being validated and the store arcs they claim authority for. If an entry fails validation, the validation authority publishes a warrant against the entry’s author.

Validation authority

An agent on an application’s validating DHT, chosen at random to validate a DHT operation, based on their agent addressnearness to the base address of the operation and their published store arc. After validating, they also store the entry and help maintain its resilience by gossiping with their neighbors and cooperating to adjust their store arcs to ensure reliable availability.

Validation rule

Any executable code that checks data for validity. Validation rules can either be subconscious or written in a zome as validation functions.

Validation function

A function in an application’s DNA that contains the validation rules for an element. This function allows every agent to check the correctness of data they see. If a validation authority is performing validation on an element and finds that it’s invalid, they can publish a warrant proving that the element’s author has broken the ‘rules of the game’.

Validation signature

A public-key signature created by the validation-authority of a piece of DHT data, attesting to its validity according to the validation rules in the app.

Validator

See validation authority.

Warrant

A validation signature that attests that a piece of DHT data is invalid and its author has broken the ‘rules of the game’ in the DNA‘s executable code. This warrant is produced by the validation authority for the data and gossiped to the validation authorities for the agent ID, who store it as metadata on the agent ID entry.

WebAssembly (WASM)

A low-level byte code format that can be run on almost any platform, including the web browser. Holochain expects DNAs to be compiled to WebAssembly so the ribosome can execute them. See WebAssembly website.

Workspace

A snapshot of an agent’s cell state, that is, their source chain, taken at the start of a zome function call. All commits are staged to this workspace and not written to the source chain until the function completes and validation succeeds for all commits (see atomic commit).

Zome

A basic unit of modularity inside a DNA. A zome defines a package of entry types, validation functions, zome functions, and init functions.

Zome function

A function, created by the developer of a zome, that allows external code to to access the zome’s functionality, including writing to the agent’s source chain, reading from the DHT, making remote calls to other agents’ zome functions or bridged cells, performing cryptographic functions, or sending signals to listening clients. The zome functions act as a public API for the zome, and can be called by another zome within the same DNA, a bridged DNA instance within the same conductor, a client via the conductor’s RPC interface, or a peer in the network via a remote call. An agent can control access to their functions via capability grants.