Architecture
Module layout, on-chain anchors and data flow for cipher-core.
Module structure
cipher-core/src/ is organised by concern. Each module is a Rust sub-crate in the workspace.
| Module | Responsibility |
|---|---|
| privacy/ | Groth16 circuits, Poseidon hash, Pedersen commits, sparse merkle tree, proof codec, batch verification |
| bridge/ | Base contract client, deposit listener, withdrawal submitter, version handshake |
| consensus/ | Withdrawal BFT, leader rotation, reputation tracker, slashing evidence catalog |
| compute/ | WASM job engine, executor sandbox, distribution coordinator, ownership-proof gadget |
| ceremony/ | BGM17 phase-2 contribution, verifier and transcript chain |
| coordinator/ | Active/passive coordinator role, snapshot replication, failover |
| network/ | libp2p (Kademlia, gossipsub, request-response), peer registry |
| storage/ | RocksDB-backed merkle, nullifier, blockchain and compute stores; fsync on hot writes |
| validator/ | Validator role, registration, signing, heartbeat |
| node/ | Process lifecycle, task spawning, graceful shutdown |
What's anchored on Base
The on-chain contract is the truth that makes Cipher a Layer 2: it enforces replay, uniqueness and validator economics. Off-chain proof verification is wrapped by on-chain settlement.
BridgeState.merkle_root— pool root, updated by the authority on consensusBridgeState.program_version— version handshake; L2 refuses to talk to the wrong on-chain version- Per-nullifier records — guarantee each nullifier is spent at most once
expiration_slotcheck on withdraw — replay protection for stale requestsValidatorAccountrecords — stake, reputation, earnings and slashing record
Validator role
Validators are verify-only. They do not generate proofs. Each validator subscribes to gossipsub topics for blocks, votes and compute results; verifies Groth16 proofs in ~10 ms on a single core; signs and broadcasts a vote; and participates in failover election if the primary's heartbeat is missed.
Coordinator HA
Exactly one coordinator is primary at any time; the rest are passives that watch the primary's heartbeat and replicate its state snapshot. The failover test asserts a passive becomes primary in under 30 seconds.
Storage
| Store | Backend | Notes |
|---|---|---|
| Merkle tree | RocksDB | Sparse, fsync on hot writes |
| Nullifier set | RocksDB | Append-only, fsync (durability-critical) |
| Blockchain state | RocksDB | Block headers, finality records |
| Compute store | RocksDB | Job queue, results, audit log |