# The Holochain Visual Glossary

Holochain development has a lot of specialised vocabulary. At the begining this can be very confusing. This document can act as a quick reference with visual aids to help with understanding. It also introduces the visual language used throughout the devcamp.

<details>
<summary>Network</summary>

A group of *nodes* all running the same *DNA* connected together. Together they form a *DHT* for that *DNA* and validate each other entries to provide data integrity and persistence.


</details>

<details>
<summary>DNA</summary>

Much like the DNA in cells defines the characteristics of an organism, the Holochain DNA defines the shared validation rules and characteristics of a single DHT.

Every node/agent who is part of a Holochain DHT must have an identical copy of the DNA. In fact the DNA must be the first entry on every agents local chain in order to prove they have an identical copy.


The DNA file (.dna.json) is what is produced by running `hc package` for a Holochain project. It contains the definitions and WASM bytecode for all of the zomes plus some metadata and DNA specific properties.

Changing a single character in the DNA file will result in a different hash and therefore a whole new DHT network is created. This is called *forking* a DNA.

</details>

<details>
<summary>Zome</summary>

A DNA is composed of one or more Zomes (short for Chromosomes) which are pieces of WASM code plus definitions of the *entries* and *functions* the zome contains.


#### Zome: Entry

An entry is like a schema for data that can be stored in the DHT. Any string of data that is stored in the DHT must be a type of entry that is defined in one of the zomes of the DNA.

An entry is defined by its *type* and its *validation callback*.

The validation callback is a WASM function that determines if a particular string is valid as as the given entry type. When you attempt to add a particular type entry to the DHT it must first pass the validation locally and also by any node that stored the entry in their DHT shard.

Entries also define if the data should be stored in the DHT or local chain only and what data should be available to the validation function. The validation function may have access to:
- Just the entry data and author address
- The authors local chain headers
- The entire authors local chain

#### Zome: Function

A zome function is the primary way to interact with a Holochain DNA running in the conductor. These are special WASM functions exposed by the conductor to the outside world. They provide an extra layer of code between any data modification or retrieval actions in Holochain.

Zome functions accept a string and return a string. Using the Rust HDK this is handled as stringified JSON allowing structured data to be passed.

Zome functions are essentially a layer for convenience only and can not be relied upon to ensure data integrity.

</details>

<details>
<summary>DHT - Distributed Hash Table</summary>

A DHT is a data structure for storing and retrieving data in a peer-to-peer network. It is a hash table where different parts of the hash space (shards) are stored by different nodes (typically with a high level of redundency).

Knowing the hash of the data you wish to store/retrieve it is possible to discover which agents you must communicate with to store/retrieve your data.

The Holochain DHT is combined with a gossip protocol so that changes can be propagated to the correct nodes and agents can join/leave the network while maintaining the correct levels of redundency.

It is also special in that it is a **validated** DHT. Nodes must run new data through the validation functions in the network DNA before adding it to the DHT. This is required for maintaining data integrity and preventing certain attacks.

</details>

<details>
<summary>Local Chain</summary>

The local chain is an immutable record of every action an agent has taken for a particular DNA. It is immutable as every action must reference the hash of the previous (hash chained) and the *header* of every action is published to the DHT. Each header is also signed with the private key of the agent.


Every local chain begins with a special entry which contains the DNA itself. This makes it possible to prove that the agent is running the exact same DNA as everyone else on the network. The second entry is also special. This is where the agent registers themselves on the network by publishing their public key and grants themselves the capability to add further entries to the chain.

Each agent must store their own local chain and is responsible for ensuring its safety and integrity.

### Local Chain: Header

A chain header for an *entry* contains:

- The entry type string
- Hash of the entry data
- public key and Signature of the entry data by the authoring agent
- Hash of previous header
- timestamp by the authors local clock


</details>

<details>
<summary>Conductor/Node</summary>

The conductor is the runtime environment for DNAs. It is comparable to a tracker for bitTorrent. A single conductor can host many agents and many DNAs.


It is responsible for providing:
- Networking functionality
- WASM execution environment
- Data persistence for the DHT and local chain
- key management
- exposing an interface for calling zome functions

In fact the conductor does practically everything which is why our reference implementation conductor is simply called `holochain`.

Much like there can be different trackers for bitTorrent there can be different conductors for Holochain.

</details>

<details>
<summary>Links</summary>

Links are a system entry type that can be used in a zome. They contains a base address, a target address and some additional tag data. They are handled in a special way such that agents who hold the base will also hold a list of the addresses that are linked to the base. These agents are responsible for responding to *get_links* requests for that base.

Links must be defined on either the base or target entry. They also have their own validation callbacks. Links themselves have a *link_type* which, much like an entry type, is used to refer to a particular base, target and validation callback combination.

### Anchors

Anchors are just regular entries but they serve a special purpose. Anchors themselves carry no real information but serve as bases for links that are easy to locate by hash. For example an entry containing the string `"posts_anchor"` can be hardcoded into the DNA. This entry address can be easily looked up by any agent by calculating the hash. This provides a shared, known location to discover linked posts.

Warning: While this pattern seems nice it may not be the most scaleable. Recall that the holders of the base entry are required to store all the links on that base. In the prior example that means that holders of the posts anchor would need to store a link to every post. This can lead to DHT hotspots where some agents must store more data and handle more requests than others.

</details>