

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.

Address¶

The unique ID of an entry or agent on the DHT. Every entry has an address that is generated from its content, usually by a hash function.

Address space¶

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

Agency¶

The power of an agent to act in their environment.

Agent¶

Anyone or anything acting with agency, such as a human or bot.
An agent (see definition 1) who participates in a Holochain #network through their #DNA instance.
The DNA instance that mediates the participation of an agent (see definition 2) in a Holochain network.

Agent-centric¶

A 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 distributed and use public-key cryptography to identify agents. Git, Holochain, and Secure Scuttlebutt are highly agent-centric, while client/server 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 node-to-node messaging and in choosing validators for public entries.

Agent ID¶

The second of the two genesis entries at the the beginning of an agent‘s source chain, which identifies them and contains their public key and other information, such as human-readable identifiers or credentials necessary for joining the DNA’s network. This entry becomes an agent’s unique identifier in the app. The address of this entry is also the agent’s address on the DHT.

Anchor¶

A data modelling pattern that allows application designers to simulate collections or tables on the DHT. A base entry type is defined as containing a value, such as "user_handles", "city_names", or "blog_posts_2019", and all relevant entries are linked to it.

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.

Application (app)¶

Synonymous with hApp, an app is a collection of back end and front end components that comprise something a Holochain user can interact with.

Aspect¶

A piece of metadata on an entry, such as a link, provenance, validation signature, warrant, or CRUD status.

Author¶

The agent who has published a DHT entry, as shown by their provenance.

Back end¶

Synonymous with a collection of DNA instances for a hApp—this is code that contains the base-level persistence and validation logic.

Blockchain¶

A distributed system that promises Byzantine fault tolerance by using a coordination 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.

Bridge¶

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

Bundle¶

A hApp bundle.
A group of commits that succeed or fail ‘atomically’, like a transaction in an SQL database (not yet supported).

Byzantine fault tolerance (BFT)¶

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

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’. In Holochain, an agent‘s conductor protects their running DNA instances and authorizes subjects‘ access to them by issuing and checking tokens.

Capability grant¶

A special, private entry that an agent writes to their source chain to record the issuing of a capability and its terms, including the intended subject. The address of this grant becomes a capability token.

Capability claim¶

A special, private entry that a subject writes to their source chain to record the token they received. This allows them to exercise their capability later.

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 DNA instance on the user’s machine, or it can be another agent.

Capability token¶

An identifier for a capability grant, which proves that its bearer has been granted a capability and is allowed to exercise it. In a Holochain app, this token is the hash of the grant.

Centralization¶

The degree to which agency, decision-making power, or responsibility in a distributed system is concentrated in certain nodes. Client/server systems are highly centralized. The complement of centralization is, of course, decentralization.

Client¶

Any piece of software that accesses a DNA instance‘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 lives on the same machine as the conductor.

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.

Commit¶

The act of adding an entry to a source chain. If an entry is a public entry it also gets published to the DHT.

Commons¶

Any resource that is used 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 a user’s device and hosts all of their DNA instances, stores their data, and handles network communication between their instances and other users’ instances.

Conductor API¶

The RPC interface that a conductor exposes, which allows locally running clients to access and manipulate the configuration of DNAs, agents, instances, and RPC interfaces.

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.

Consensus¶

Synonymous with consistency in a distributed system.
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.

Content-addressable store (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.

Core API¶

See Holochain Core API.

Create, read, update, delete (CRUD)¶

The four main operations an application needs to do with data. Even though all data structures in Holochain are append-only, data can still be updated or deleted by adding a new entry that marks the old data as obsolete.

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.

DeepKey¶

Holochain’s standard DPKI library.

Development conductor¶

A Holochain conductor used for running and testing a hApp during development.

DHT entry¶

A public entry that lives in the DHT. DHT entries are assigned to a neighborhood of validators, are deduplicated, can have many authors, and have metadata attached to them in aspects.

Distributed hash table (DHT)¶

A collection of data stored collectively by many nodes in a distributed system. A node retrieves data by address, usually its cryptographic hash, searching for a peer responsible for holding the data. Holochain uses a validating DHT to store public entries. 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 sort 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.

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, and zome functions for agents to take action.

DNA instance¶

A particular Holochain DNA when it’s bound to an agent. DNA + agent = instance.

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 messaging uses E2EE, as does gossip between nodes.

Entry¶

A basic unit of data in a Holochain app. Each entry has its own defined entry type. When an agent commits an entry, it is written to their source chain. If it’s marked as a public entry, it’s also published to the DHT.

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 a data schema and validation rule for its entries, as well as a public or private sharing directive.

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 are guaranteed to reach consistency without conflicts, which is possible for any system whose state transition functions adhere to the CALM theorem.

Front end¶

Synonymous with graphical user interface.

Genesis entries¶

The two entries at the beginning of an agent‘s source chain for a DNA instance, consisting of:

The DNA hash, which shows that the agent has seen the network’s rules and agrees to abide by them.
The agent ID entry, which advertises the agent’s public key and may also provide other identifications or credentials.

Global consensus¶

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

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 entries, metadata, neighborhood health, and peer addresses via gossip.

Graphical user interface (GUI)¶

A client that presents a visual, easy-to-understand way for a user to interact with a DNA instance or collection of instances running in their conductor. As with any client, the GUI always runs on the same machine as the conductor.

hApp bundle¶

One or more DNA packages, bridge definitions between them, and an optional HTML-based UI package. Together they form a complete hApp, both back end and front end. 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.

hApp manifest¶

The file that specifies the components of a hApp bundle. Supporting conductors, such as Holoscape and the Holochain development conductor, can install and run fully functional applications from this file.

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.

History¶

The entries created by an agent and recorded in their source chain.

Holo¶

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

Holochain Development Kit (HDK)¶

Holochain’s standard software development kit (SDK) for zome and DNA developers. It provides developer-friendly access to the low-level Holochain core 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, typically distributd as a hApp bundle.

Holochain Core¶

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

Holochain Core API¶

The set of core functions that the nucleus makes available to the ribosome, so the ribosome can in turm make them available to a running DNA instance. These functions allow the DNA to access and manipulate an agent‘s source chain, run cryptographic functions, retrieve and write DHT entries and links, and send node-to-node messages to peers.

Holo Host¶

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

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. While each node is individually responsible for taking action, the cumulative effect is a collective rejection of the corrupt nodes.

Init callback¶

A function in a DNA that the nucleus calls when an agent runs the DNA instance for the first time. This can be used to set up initial variables, etc.

Intrinsic data integrity¶

Holochain’s fundamental 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 the source chain of a Holochain agent.

Link¶

A piece of metadata connecting one DHT entry to another. Each link has a defined type, as well as a tag.

Link base¶

The DHT entry that a link links from. The link is stored in the DHT as an aspect attached to its base entry.

Link tag¶

An arbitrary piece of string content attached to a link. It can be used for things like describing the nature of the relation, containing a small portion of the target’s data to avoid asking the DHT to retrieve the full target entry, or serving as an index for filtering links.

Link target¶

The DHT entry that a link points to.

Link tag¶

A piece of content embedded in a link that further describes the link beyond its type or includes information about its target.

Link type¶

A specification for any sort of link that a DNA should recognize and understand, similar to an entry type. It defines the base and target types that the link is valid for, as well as a validation rule. Because links only exist on the DHT, all link types are public.

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 update/delete operations only add new entries without removing old ones.

Membrane¶

One of two types of permeable boundary that allow appropriate access and disallow inappropriate access:

The layer of protection around an agent‘s DNA instance, secured by capability-based security, that prevents unauthorized access to the instance or its source chain data.
A special validation rule in a DNA that checks the agent ID entry and determines the agent‘s right to become part of the DNA’s network.

Metadata¶

Supplementary data attached to a piece of data. In a Holochain DHT, metadata like links are stored on entries as aspects.

Microservice¶

An application architecture pattern that encourages small, single-purpose back end services. Holochain DNAs can be designed 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 balance 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 intentions, so by running the application a participant consents to the group’s rules and norms.

Nearness¶

The proximity of two addresses to each other in the DHT‘s address space, expressed as the XOR distance between them.

Neighborhood¶

A group of nodes in a Holochain DHT who are near to one another (in terms of address space, not geography). Neighbors collectively support the resilience of all DHT entries whose address is near to them by storing and validating those entries and gossiping to each other about the entries they have.

Network¶

A community 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.

Node¶

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

Node-to-node message¶

A direct, end-to-end encrypted exchange between two nodes on a network.

Nucleus¶

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

Package¶

Synonymous with DNA.
The act of compiling zome source code and configuration data into a DNA package.

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.

Peer¶

Synonymous with node.

Peer-to-peer¶

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

Private entry¶

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

Progenitor¶

The first user to run a DNA and bootstrap its DHT. The progenitor usually has special responsibilities and privileges to set up necessary global DHT entries.

Provenance¶

A public key and a public-key signature, stored as a piece of metadata on a DHT entry. It proves that an agent (represented by the public key) actually authored the entry (as proven by the signature) and allows anyone to verify that a third party hasn’t tampered with it.

Public entry¶

Synonymous with a DHT entry, any entry marked ‘public’ will be published to the DHT.

Public-key cryptography¶

A cryptographic system that consists of two keys, a public component and a private, or secret, 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, the public key lives in the DHT as an agent‘s identity while the private key stays on the agent’s device as a proof that they control their public key. Peers can verify an agent’s claim of authorship on an entry by checking their provenance, or use an agent’s public key to encrypt a private message that only they 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 SSL certificate authority system, are centralized. Holochain provides 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. In Holochain, this is used in a provenance on each DHT entry to prove authorship and detect third-party tampering.

Public/private key pair¶

See public-key cryptography.

Publish¶

The act of sending a public entry to the DHT after it has passed the author’s own copy of the validation rules for the entry. The neighborhood of validators who are responsible for that entry’s address receive it, validate it, and if it’s valid, store a copy of it.

Remote procedure call (RPC)¶

A call that a client makes to a zome function or conductor API function over a local socket interface.

RPC interface¶

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

Resilience¶

The level of a network‘s capacity to hold itself in integrity as nodes leave, join, or attempt to attack it.

Resilience factor¶

A value set in the DNA that specifies the desired number of copies of an entry that should exist in a DHT. The nodes in a neighborhood responsible for an entry collectively work to make sure this factor is met at all times. As an example, for a resilience factor of 5, each entry is expected to exist on five nodes with 100% uptime, or ten nodes with 50% uptime. If an entry has reached saturation, it’s met the resilience factor.

Ribosome¶

The ‘sandbox’ or ‘virtual machine’ inside which a DNA instance runs. In Holochain’s current design, the ribosome is a WebAssembly interpreter that exposes Holochain’s core API to the instance and allows the nucleus to call the instance’s validation functions, init function, as well as other callbacks.

Rust¶

The programming language used to build Holochain Core and DNAs/zomes.

Saturation¶

The state at which the peers holding a DHT entry have satisfied the DNA‘s expected resilience factor.

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.

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 separate nodes into discrete shards, Holochain’s DHT separates them into overlapping neighborhoods.

Signal¶

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

Source chain¶

A hash chain of data committed by an agent. For each DHT, every agent stores their own source chain as a record of the state transitions they’ve made—that is, the entries they’ve committed.

Source chain entry¶

An individual record stored on a source chain, which may be private or public.

Source chain header¶

A meta-entry that links a source chain entry to the previous entry in an agent‘s source chain.

State transition¶

A modification of application state. In Holochain, state transitions begin life as entries in an agent‘s source chain and are optionally published to the DHT as a permanent public record.

Subconscious¶

The ‘base’ validation rules defined by the Holochain nucleus that check validity of hashes and provenances, as well as the integrity of each agent‘s source chain.

Trait¶

A contract or interface that a zome is expected fulfill, consisting of a specification for a collection of zome functions and their input and return types. All zomes that promise to implement a trait are expected to supply functions that conform to the trait’s specification. A DNA can require that a bridged DNA supply certain traits, and the conductor will make sure that this requirement is satisfied.

Trustless¶

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.

Validating DHT¶

Holochain’s DHT design which creates an immune system for the network. Validators are chosen at random, based on their nearness to the address of the entry to be validated. If an entry fails validation, the validator publishes a warrant against the entry’s author, along with proof of invalidity.

Validation rule¶

A function that checks the correctness of an entry or link. If validation fails, a validator can publish a warrant proving that the entry’s author has broken the ‘rules of the game’.

Validation signature¶

A provenance created by the validator of a DHT entry, attesting to the validity of that entry according to its validation rule.

Validator¶

A node in the validating DHT, chosen at random to validate a DHT entry, based on their agent address‘ nearness to the address of the entry. After validating, they also store the entry and help maintain its resilience.

Warrant¶

An entry created by the validator of a DHT entry, attesting that the entry is invalid according to its validation rule and proving that its author has broken the ‘rules of the game’ in the DNA‘s executable code.

WebAssembly (WASM)¶

A low-level byte code 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.

Zome¶

A basic unit of modularity inside a DNA. A zome defines entry and link types, validation rules, public zome functions, node-to-node message handlers, and init functions.

Zome function¶

A function, created by the author of a zome, that allows a client to access the zome’s functionality. This includes data retrieval and storage, as well as node-to-node messaging. 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, or a client via the conductor’s RPC interface.