Glossary

The words used in the code, logs, API and docs, and what they mean here.

Nodes and the swarm

node: a running continuum instance, together with its transports (and a Mycelium daemon it supervises), document, lifecycle (Joining, Ready, Rejoining), API and log. The word for what a single instance does: "the node becomes ready", "a new node joins". Rule of thumb: say node when nobody else is involved.

peer: another node, seen from one node's side. Always relative to someone, which is why PeerState, /peers and dormancy are per peer. "A node forgets a dormant peer" reads right; "a peer becomes ready" doesn't. Rule of thumb: say peer when you mean "the other side" or "the others".

swarm: all the nodes together, sharing one document. Identified by the swarm ID, which the genesis node chooses and records in the document (_continuum/swarm). An optional swarm key (--swarm-key-file) is a shared secret every node must prove in the handshake.

node ID: who a node is, continuum:<hex>, from its node key (--node-key-file); the same whatever transport reaches it. An address says where a node is on one transport (mycelium:<public key>); a node proves its node ID at an address with WHO and ME (peers.md).

seed: something that can be resolved to reach a node (--seeds): an address on any transport, or a transport's own short form (for Mycelium a public key, an IPv6 address, or a host name with an AAAA record for one; transports.md).

state file: what a node remembers across restarts (--state-file): its swarm ID and some members to rejoin through. Not the document.

document file: a node's document on disk (--document-file), with the actor IDs it wrote with; the node resumes with it after a restart.

standing of a peer, from one node's side (Standing):

• stranger: has sent us something, nothing more.
• admitted: proved the swarm key (or there is none).
• member: completed the handshake and belongs to our swarm. Only members sync.

registered member: a node listed in the swarm's member registry (_continuum/members/<node ID>), which every node writes for itself once ready. The registry, not the handshake, decides the topology and who votes on remakes. When the context doesn't make clear which is meant, say registered member.

neighbour: a member this node keeps alive and syncs with on its own (keepalives, sync openings, relay). Up to --neighbours (k) of them, chosen from the registry (swarm::topology); with at most k + 1 reachable members, everyone is everyone's neighbour (full mesh). Other members are only answered.

alias: the name a node gives itself (--alias), published in the registry. Not unique, never an identity; the node ID is.

dormant: a peer we haven't heard from for 4 × keepalive. It is probed rarely and left out of the topology until it answers again.

stability tier: what a node judges about itself and publishes in the registry. It becomes stable once it was connected at least 95 % of a full day, and transient again below 80 %. Stable members are preferred as neighbours, forming a backbone.

alive stamp: the time a node last renewed its registry entry (about daily). Nodes renewed within --electorate-window form the electorate of a remake.

The document and sync

document: the replicated Automerge document. The store API reads and writes paths in it.

protocol data: what the nodes keep under _continuum in the document: the swarm ID, the member registry, forget records, remake records, the votes register and epoch metadata. Only users listed in --protocol-writers may change it through the store API; the swarm ID and epoch metadata never.

heads: the hashes of the document's latest changes, those no other change depends on. Several heads mean concurrent changes that no later change has merged yet. Two nodes with the same heads have the same document.

opening: the first sync message to a peer after a reset, before anything has come back from it. After reset_sync() the Automerge sync::State is new, so their_heads, their_have and their_need are all unset; an opening can only say "these are my heads, here is a Bloom filter of what we share", and carries no changes since we don't know yet what the peer has. The code doesn't track openings separately: their_heads.is_none() means nothing has come from the peer since the reset. Who may open towards whom: peers.md, Handshake and join.

path: an address of a peer on one of this node's transports (<scheme>:<target>). A peer with several (on several transports) is reached on the best: paths are measured with a PING each answered by a PONG, and a path that fails, or stops answering, is passed over for the next.

keepalive: what a pair exchanges when it has been quiet for a keepalive interval (--keepalive): a PING and its PONG, and every third time a STATUS and its STATUS_REPLY instead, carrying the sender's heads (or a digest of them and some of them), epoch and readiness. The two sides of a pair take turns; the one that leads the pair sends the first.

initial sync: a joining node's first complete sync. It's caught up once a ready peer with non-empty heads has nothing left that it lacks.

catch-up source: the one peer a joining node syncs with while catching up, the closest by round-trip time first.

relay: in a partial mesh, a node announces new heads to its neighbours, which pull the changes they lack.

blob: bytes too large for one message, fetched in chunks from several peers at once: an epoch's snapshot change (for a rejoining node) or a remake's content (for voters).

Epochs and remakes

epoch: one stretch of the document's life, from one remake to the next. Peers on different epochs don't sync. Identified by its generation and its ID (the hash of its snapshot change), shown as generation:id.

generation: an epoch's counter: the number of remakes since genesis. It orders epochs, so a node can tell whether a peer is behind or ahead. Two epochs of the same generation (different IDs) can only come from concurrent remakes.

genesis: the first epoch (generation 0), and the genesis node that started the swarm (started with --genesis, empty or with content from --remake).

remake: a coordinated move of the whole swarm to a new epoch. Kinds: compact (same content, no history), replace (new content as JSON), import (new content as an Automerge document).

base: the heads the new epoch's content accounts for. Writes made after them are carried over into the new epoch (replayed), at their path or where the remake's rules say: by every node that switches, and by their author when it rejoins. A compaction's base is the coordinator's heads when it commits; other kinds fix it when proposed.

snapshot: the new epoch's first change, which every node builds itself, byte for byte the same; its hash is the epoch ID.

coordinator: the node a remake was proposed to. It counts the votes and writes the decision. If it is gone for good, another node can adopt the remake and become its coordinator.

electorate: the registered members whose votes count for a remake, fixed when it is proposed. The remake commits once a majority (the quorum: more than half) voted for it. Each member has one vote per epoch, kept in the votes register (_continuum/votes); it is free again only if that remake is aborted.

switch: a node moving to a committed epoch by building its snapshot itself.

rejoin: a node moving to a newer epoch by fetching it from peers instead (it was away, or its own build failed).

replay window: how far behind a rejoining node may be and still have its own writes carried over automatically.

quarantine: a node's own writes a remake couldn't place, kept on that node for an operator to replay or discard.

archive: the documents of previous epochs a node keeps for a while.