Skip to main content

Crate cll

Crate cll 

Source
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 (the CheckpointRecord shape and its JSON signing body) and cll.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 the NodeReader/NodeAppender a serving-path plugin should hold so its MMR survives a process restart without replaying the whole ledger to rebuild it – mmr::MemoryNodeStore stays 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’s checkpoint.Runner (go/checkpoint/runner.go).
store
checkpoints.jsonl reader/writer – the exact on-disk shape capsule-emit-mesh/checkpointing.py’s CheckpointState reads and writes (which is itself wire-identical to the CLL checkpoint shape this crate’s checkpoint::CheckpointRecord carries): one JSON object per line, each line CheckpointRecord::canonical_json() (i.e. CheckpointRecord.to_dict()) with an ADDITIVE checkpoint_cose hex field when a COSE_Sign1 envelope was built alongside the JSON record. Lines are strictly append-only and strictly chained (each line’s prev_size/prev_root must match the previous line’s mmr_size/root) – this module does not enforce that chain (callers building a checkpointer do), only reads/writes the shape faithfully so a Rust checkpointer and checkpoint_daemon.py can 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 /checkpoints COSE route) and check durable status via GET /v1/inclusion/{capsule_id}. Mirrors capsule-emit-mesh/plugins/capsule-producer/src/anchor.rs byte-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 DeliveryRunner delivers the witness rows a CheckpointRunner queues, and the HttpWitnessClient posts a checkpoint statement to a witness’s /checkpoints route – ports of Go’s witness.DeliveryRunner and witness.Client (go/witness/).