Everything you need to understand how Settled works, how its cryptographic guarantees are constructed, and how to integrate it into your applications.
Settled's guarantees are constructed from four composable cryptographic primitives. Understanding each one makes the overall system legible.
Every submitted entry is hashed with a domain-separation prefix before being inserted into the tree. The prefix prevents a class of second-preimage attacks where an attacker crafts an interior node that collides with a valid leaf.
SHA-256(0x00 ‖ data)Leaf hashes are combined pairwise up a binary tree using RFC 6962's construction. Each interior node commits to both subtrees beneath it. The root hash commits to the entire log — every entry, in order.
RFC 6962 binary treePeriodically, the server signs the current Merkle root, tree size, and timestamp with Ed25519. This Signed Tree Head is the cryptographic anchor — a compact, independently verifiable snapshot of the entire log's state at a point in time.
Ed25519 · 48-byte payloadAny entry can be proven to be part of the log at the time of a particular STH. The proof is a path of O(log n) sibling hashes from the leaf to the root. A verifier recomputes the root and checks it matches the STH — no server access needed.
O(log n) sibling hashesGiven two STHs, a consistency proof (O(log n) hashes) confirms every entry present at the earlier snapshot is still present and unchanged in the later tree — no re-reading of entries required. It proves the log was not rewritten, but does not verify the content of entries added between the two snapshots.
Integrity, not completenessSigning keys are versioned. Each rotation event is itself countersigned by the outgoing key, creating a verifiable chain of custody. Historical proofs remain valid across rotations — a verifier determines which key was active for a given STH by its tree size range.
Auditable chain of custodySettled operates as an independent service alongside your existing infrastructure. Your application submits audit events; Settled returns cryptographic proof of each one.
Your application calls the Settled server with a key (a stable identifier for the entity being audited — e.g. a user ID, a document reference) and a data payload (the audit event content). The server assigns a monotonically increasing sequence number and acknowledges durably via write-ahead log before responding.
The key enables O(1) lookup of the most recent entry for any entity. It is not included in the Merkle commitment — the sequence number is the canonical identifier.
The server returns an AppendResponse containing the assigned sequence number, the entry's leaf_hash (SHA-256(0x00 ‖ data)), and a reference to the Signed Tree Head current at write time.
Your application should store the seq and leaf_hash alongside the original record. These are what a verifier will need. The STH can be retrieved from the server at any time — your application does not need to store it, though distributing it to auditors at significant points (regulatory snapshots, end-of-period) adds independent anchors.
To prove that a specific entry was committed, request an inclusion proof from the server by sequence number. The server returns the O(log n) sibling hash path from that entry's leaf to the tree root.
Combined with the entry's leaf_hash, the proof, and a Signed Tree Head, any party can independently verify the entry's presence in the log — without querying your application or the Settled server.
verify_inclusion(
leaf_hash, // SHA-256(0x00 ‖ entry_data)
seq, // entry's sequence number (0-based index in tree)
tree_size, // from the STH
proof_path, // O(log n) sibling hashes from server
root_hash // from the STH
)Verification requires only: the entry data (to recompute the leaf hash), the inclusion proof path, and a Signed Tree Head. All three can be delivered to a regulator or auditor as a bundle. The verifier needs only the server's Ed25519 public key — a 32-byte value that can be published or embedded in a client.
Consistency proofs allow a party holding any historical STH to verify that newer STHs represent a superset of the same entries — confirming the log has never been rewritten.
Settled's guarantees are strongest when the Signed Tree Head is published outside the system it protects. At significant milestones — end of financial period, regulatory filing, before and after a high-stakes operation — submit the current STH to a regulator, a notary, or a public ledger.
An attacker who subsequently modifies the log cannot produce a valid STH that matches both the tampered content and the previously published root hash. The external anchor is what makes the tamper-evidence binding against a fully compromised server.
Settled's append-only design is compatible with mandatory retention obligations and right-to-erasure requirements, provided you follow two practices.
Log opaque identifiers — user IDs, account references, transaction numbers — rather than names, email addresses, or other personal data. Keep personal data in your existing mutable store. The audit chain proves that events happened and in what order; your application resolves who was involved.
This gives you clean erasure: deleting a person's record from your application satisfies the right to erasure without touching the audit log at all. The chain remains intact.
Regulatory frameworks typically require audit records to be retained for a fixed period — seven years is common in financial services. When records age out of that window, Settled supports pruning at snapshot boundaries.
Snapshots are the only safe pruning points. Because each entry's hash incorporates the previous entry's hash, you cannot delete a record mid-chain without breaking every hash that follows it. A snapshot root is a clean break: it commits to everything before it, so entries older than that snapshot can be deleted and the snapshot root alone carries forward the proof of their prior existence.
The retention rule is: retain all entries back to the oldest snapshot that still falls within the mandatory retention window, and prune everything before it. The retained log runs from that snapshot forward and remains fully verifiable. The externally-published snapshot root proves the prior state.
This means your log always contains at least one complete retention window of entries, bounded cleanly at a snapshot on each end.
These guarantees hold unconditionally given the security of SHA-256 and Ed25519. They do not require trusting the Settled server after the fact.
Complete specifications for all hash constructions, proof algorithms, signing payloads, and key management procedures.
Complete specification for all hash constructions (leaf, node, Merkle root), inclusion and consistency proof algorithms, the Ed25519 signing payload format, key versioning, and duplicate key semantics.
Read the specification →The Rust implementation, canonical test vectors for all hash constructions and proof algorithms, and cargo-fuzz targets for all verifier functions. Reference implementation for SDK authors.
View on GitHub →