Protocol Reference — Overview

This reference explains how a Calimero cluster works and why it is built that way. It follows one call from the client that makes it to the log entry that records it, rather than touring the crates. The crates are merod (the node binary), calimero-node (everything the node does), calimero-log (the replicated log), calimero-sealed (the encrypted transport), calimero-identity (passkeys, sessions, API keys) and calimero-client (the Rust client, whose attestation check every client and peer shares).

New here? Read these first, in order

Concepts → The system group → Replication → Application execution. Everything else builds on those four.

The one idea everything hangs on

A Calimero app is a WASM module whose state lives on a cluster of attested Intel TDX nodes. Each app instance has its own Raft log, replicated on several nodes (three by default). The log’s leader runs every call against the app’s current state and appends the call together with what it produced: the result, the exact storage writes (the diff) and the events. Every replica applies the diff in log order. Nobody runs the call a second time.

A second Raft log, the system group, is shared by the whole cluster. It holds who exists and who may do what: nodes, accounts and their passkeys, sessions and API keys, organizations and teams, installed packages and the directory of app instances. Every command in it names the actor it acts for, and the state machine checks that actor’s authority when the command applies, so the log alone decides every outcome.

Nothing a node holds leaves it in the clear. Clients and peers verify a node’s TDX quote before they send it anything, then speak to it only through a sealed channel bound to the key that quote attests. Everything a node writes to disk is sealed under the cluster’s key, which it keeps wrapped under a storage key it receives from mero-kms only after proving its own image.

Hold onto that: one log per app, one log for the cluster, the leader runs and everyone applies, and nothing crosses a trust boundary unsealed. Every chapter is a detail of it.

Why it is built this way

A cluster of attested nodes can afford coordination. With one leader per app and a log every replica applies in the same order:

• Calls are linearized. Two writes to one instance never race; the second runs against the state the first left. CRDT collections are the storage format, but no merge is needed to converge.
• Authorization is one verdict. A command is checked against the state it applies to, which is the same state on every replica.
• Execution need not be deterministic for convergence. Followers apply the leader’s diff, so time_now and random_bytes are read once, on the leader.
• Confidentiality comes from the hardware and the channel, not from a key per scope delivered to each member. A member’s client never holds app state; it reads through the node.

The life of a call

▶ Replay

The client half (attest, handshake, seal) is in Networking & sealed channels and Attestation & receipts. The node half (authenticate, check access, route, run, append, apply) is in The write path, Application execution and Replication.

How this reference is organized

1. The model. Concepts, The system group, Replication.
2. The call path. Application execution, The write path, Reads, views & events.
3. Trust. Networking & sealed channels, Attestation & receipts, Encryption, Keys & their lifetimes, Security & threat model.
4. People and authority. Accounts, passkeys & sessions, Who a run acts as, Organizations, teams & access, Deployment governance, The consent page, The operator & the Ops API.
5. Apps. Packages & frontends, App instance lifecycle, Upgrades & migrations, Event handlers & cross-app calls, Blobs, Compute actions, Presence.
6. Reference. Storage schema, Limits, Glossary.

Status

Release candidate

This describes the system as the code stands. It is not a frozen wire specification: request and entry formats are JSON and may change before they are versioned. Some parts are not done yet and are named where they matter: a rollback counter for restored nodes, keys per app from mero-kms, placement across zones, restoring a snapshot into a running cluster, event audiences, and search indexes that survive a restart.

Apps are built with calimero-sdk into calimero:app components, which run on calimero-app-engine-wasmtime. What they do inside a run is described only as far as the node depends on it.