Expand description
cll – Rust implementation of the Checkpointed Local Log (CLL)
mechanism: a Merkle Mountain Range (MMR) over an append-only log, signed
COSE checkpoints, per-record range proofs, and a witness-registration
client.
This crate is the Rust sibling of the checkpointed-local-log Python
package (cll on PyPI) – same repository, same conformance vectors
(mmr-conformance-vectors/, commitment-conformance-vectors/). Rust
and Python are two implementations of one spec; the vectors are the
contract, not either implementation.
Scope is deliberately narrow, matching this repo’s Go/TypeScript ports: the checkpoint + MMR + storage substrate only – append-only log indexing, the MMR with inclusion/consistency/range proofs, signed COSE checkpoints, and witness delivery. This crate carries no payload semantics of any kind and no ledger admission/revocation layer (that stays Python-only, by decision – see the repo README); it defines nothing about how the entries it indexes are produced, interpreted, or governed.
log holds the storage interfaces every CLL implementation shares (the
entry log, checkpoint state and witness state of the repository’s
docs/backend-contract.md), their in-memory, JSONL, SQLite (feature
sqlite) and MySQL (feature mysql) backends, and the conformance runner
for any backend.
runner and witness_delivery are the host-run loops over those
interfaces, ports of the Go runners: runner::CheckpointRunner indexes
entries and signs checkpoints on a cadence, and
witness_delivery::DeliveryRunner delivers each checkpoint to its
witnesses (over witness_delivery::HttpWitnessClient or any
witness_delivery::Submitter) with bounded retry. The shared
runner-conformance-vectors/ pin their behavior.
Modules§
- checkpoint
- Signed checkpoint emission and offline verification – byte-for-byte
port of the Python reference’s
cll.checkpoint.emit(theCheckpointRecordshape and its JSON signing body) andcll.checkpoint.cose_wire(the COSE_Sign1 wire form, Decision 1, 2026-08-24). - log
- The CLL entry log, checkpoint state and witness state: the storage interfaces every CLL backend implements, in every language.
- mmr
- Merkle Mountain Range (MMR) core algorithm – byte-for-byte port of the
Python reference’s
cll.checkpoint.core(see that module’s docstring for the full provenance/design rationale; this port carries only the wire contract, not the essay). - node_
store - Durable, append-only MMR node store: a flat file of fixed 32-byte
records,
position = record index(byte offset =pos * 32). This is theNodeReader/NodeAppendera serving-path plugin should hold so its MMR survives a process restart without replaying the whole ledger to rebuild it –mmr::MemoryNodeStorestays the in-memory store for tests and short-lived processes. - range_
proof - Per-record range membership proof (CLL #13, shipped in the Python
reference’s 0.4.0) – byte-for-byte port of
cll.checkpoint.core’s range section. - runner
- The checkpoint runner: indexes a
CheckpointStore’s entries into its MMR and signs a COSE checkpoint when the cadence says one is due – a port of Go’scheckpoint.Runner(go/checkpoint/runner.go). - store
checkpoints.jsonlreader/writer – the exact on-disk shapecapsule-emit-mesh/checkpointing.py’sCheckpointStatereads and writes (which is itself wire-identical to the CLL checkpoint shape this crate’scheckpoint::CheckpointRecordcarries): one JSON object per line, each lineCheckpointRecord::canonical_json()(i.e.CheckpointRecord.to_dict()) with an ADDITIVEcheckpoint_cosehex field when a COSE_Sign1 envelope was built alongside the JSON record. Lines are strictly append-only and strictly chained (each line’sprev_size/prev_rootmust match the previous line’smmr_size/root) – this module does not enforce that chain (callers building a checkpointer do), only reads/writes the shape faithfully so a Rust checkpointer andcheckpoint_daemon.pycan share one file.- witness
- Witness-registration client: POST a checkpoint digest to a SCITT
Transparency Service’s
/v1/digest(the legacy generic-digest-anchoring route –cll.ledger.checkpoint.register_checkpoint’s wire contract, distinct from the newer checkpoint-aware/checkpointsCOSE route) and check durable status viaGET /v1/inclusion/{capsule_id}. Mirrorscapsule-emit-mesh/plugins/capsule-producer/src/anchor.rsbyte-for-byte on the wire (same endpoints, same{"capsule_id": "<64-hex>"}request, same response shape) so this client and that one – and the Python ones – are interchangeable against the same service. - witness_
delivery - Witness delivery: the
DeliveryRunnerdelivers the witness rows aCheckpointRunnerqueues, and theHttpWitnessClientposts a checkpoint statement to a witness’s/checkpointsroute – ports of Go’switness.DeliveryRunnerandwitness.Client(go/witness/).