Protocol Reference — Overview

This is the implementation reference — a design-level description of the Calimero protocol aimed at building an independent node. It follows one operation from birth to convergence rather than touring the Rust crates.

New here? Read the core model first, in order

Concepts & Scopes → Identities & Keys → Operations & the Causal DAG → State, Projection & the Root Hash. Everything else builds on those four.

The one idea everything hangs on

A Calimero node runs sandboxed WASM applications over replicated, causally-consistent shared state. There is no global consensus and no quorum. Every change — a data write, an access-control change, a membership change, an admin action — is a signed operation in a content-addressed DAG.

Each node folds that DAG deterministically into materialized state. Because the fold is order-independent (last-writer-wins per slot, keyed on a hybrid clock), any two nodes that have seen the same set of operations compute the same state and the same scope root hash. Nodes don’t prevent divergence — they detect it by comparing scope roots, and heal it by syncing missing operations.

Hold onto that sentence — “a signed op DAG that folds to a state plus a root hash, with divergence detected, not prevented” — and every chapter is a detail of it.

The life of an operation

The whole reference follows one operation from birth to convergence. This is the spine — and the diagram below is the bespoke animated engine running as an Astro island, the thing this spike set out to prove:

▶ Replay

The write half (build → sign → persist → broadcast), the receive half (verify → authorize → decrypt → fold), and the repair channel (compare roots → transfer what differs) are the substance of this reference.

How this reference is organized

Read it top to bottom. Each part answers the next question you’d naturally ask, and each goes one level deeper than the last — so you can stop wherever your need does.

1. The replication loop — the heart. An app runs locally and produces a change, that change broadcasts as a signed state delta, and peers verify and apply it without re-running the app. Application Execution, The Write Path, The Receive & Apply Path.
2. What gets replicated — what’s actually inside a delta: the Operations & the Causal DAG (the history) and the State, Projection & the Root Hash it folds to, with a visual Anatomy of State.
3. How it is organized — how data is sharded and access-controlled into a tree of scopes: Concepts & Scopes (namespaces, groups, contexts), Governance, and Capability & Membership Inheritance.
4. Confidentiality & identity — who can read and write: Identities & Keys, Encryption, Key Rotation, and the Security & Threat Model.
5. Staying in sync — how nodes that drift apart converge again: Networking, Sync & Convergence, Sync Internals, and Divergence & Recovery.
6. Subsystems — features built on the loop: Blob Transport, Cross-Context Calls, TEE Attestation, and Application Upgrades.
7. Deep internals & reference — exact rules to look up: CRDT Internals, the Hybrid Logical Clock, the on-disk Storage Schema, Limits, governance edge cases, and the Glossary.

The first three parts are the model; the rest is detail you reach for when you need it.

Status, versioning & conformance

Pre-1.0 specification

This reference describes the unified model and is being hardened toward a normative specification — it is not yet a frozen standard. Treat the byte-level details as accurate-to-current-code but subject to change pre-1.0.

• Normative requirements appear in Normative callouts using RFC 2119 wording (MUST / SHOULD / MAY). Everything else is explanatory — an implementer may read only the Normative callouts plus the byte-level Specification sections and build a conformant node.
• Version pinning. Wire and signing formats are versioned. At the time of writing: the signed group op is schema version 8, the signed namespace op is schema version 2, and the libp2p sync/blob stream protocols are …/0.0.2. A conformant implementation MUST match these for the versions it claims to support.
• Conformance, in one line. A node interoperates if it reproduces the operation id computation, the scope root fold, and the authorization-at-the-cut rule exactly — everything else is a consequence of those three.