Trust-anchored transparency logs. MerkleVerifier is the primary normie surface for verifying signed checkpoints, inclusion proofs, and consistency proofs against a fixed log identity. MerkleLog is the memory-backed producer companion for in-process logs, fixtures, and demo code. Both are safe-by-default: the dangerous parts of merkle composition (raw trees, custom storage, the wire-format codec) sit behind a divider further down this page.

Table of Contents

• Overview
• Module Init
• MerkleVerifier
• MerkleLog
• Supported suites
• Security Notes
• SignedLog
• Sha256Tree and Blake3Tree
• Free-function verifiers
• Checkpoint and signed-note codec
• MerkleStorage and MemoryStorage
• Error Conditions
• Cross-References

A transparency log is an append-only sequence of leaves whose Merkle root is signed at every step. A verifier with a trusted log identity (origin string, public key, signature suite, hash function) can decide three independent questions from short proofs alone:

1. Checkpoint: does this signed envelope come from the log I trust?
2. Inclusion: is this leaf at this index actually in the tree that envelope commits to?
3. Consistency: is the tree at envelope B a superset (an append-only extension) of the tree at envelope A?

The wire format follows the C2SP family: c2sp.org/tlog-checkpoint for the body, c2sp.org/signed-note for the envelope, c2sp.org/tlog-cosignature for the cosignature lines. The Merkle math is RFC 9162 §2.1.1 (tree hash), §2.1.3 (inclusion), and §2.1.4 (consistency).

leviathan ships two hash specialisations and two cosignature suites. Both produce envelopes consumers of any C2SP-conformant log can verify, including Sigsum logs (Ed25519) and any future ML-DSA-44-cosigning log.

MerkleLog and MerkleVerifier need three module families: sha2 (always, for the key-ID SHA-256), the suite's modules, and the hasher's modules. The exact init({...}) call depends on the combination you pick.

The class refuses to construct if any required module has not been initialised; MerkleLogError('module-not-initialized') names the missing one.

import { init, MerkleLog, MerkleVerifier, MlDsa44Suite } from 'leviathan-crypto';
import { sha2Wasm }  from 'leviathan-crypto/sha2/embedded';
import { sha3Wasm }  from 'leviathan-crypto/sha3/embedded';
import { mldsaWasm } from 'leviathan-crypto/mldsa/embedded';

await init({ sha2: sha2Wasm, sha3: sha3Wasm, mldsa: mldsaWasm });

The ./merkle subpath (leviathan-crypto/merkle) exposes the same surface tree-shakeably when you want to import only the merkle module without pulling the root barrel.

Trust-anchored verifier. Construct it once with the identity of a log you trust, then call the three verify methods as input arrives. Methods always return boolean; the class only throws at construction time, on a violated contract.

import {
  init, MerkleVerifier, MlDsa44Suite, utf8ToBytes,
} from 'leviathan-crypto';
import { sha2Wasm }  from 'leviathan-crypto/sha2/embedded';
import { sha3Wasm }  from 'leviathan-crypto/sha3/embedded';
import { mldsaWasm } from 'leviathan-crypto/mldsa/embedded';

await init({ sha2: sha2Wasm, sha3: sha3Wasm, mldsa: mldsaWasm });

// `pubkey` is the trusted log's public key, obtained out-of-band
// (e.g. baked into the client, distributed via a key-management
// surface). The verifier never fetches it.
const verifier = new MerkleVerifier({
  origin:  'example.com/log42',
  pubkey,
  hashing: 'sha256',
  suite:   MlDsa44Suite,
});

// 1. Verify a signed checkpoint envelope as it arrives.
if (!verifier.verifyCheckpoint(envelopeBytes)) reject('bad checkpoint');

// 2. Verify a leaf's inclusion in the tree that envelope commits to.
const ok = verifier.verifyInclusion({
  envelopeBytes,
  leafBytes,        // raw leaf bytes; verifier re-hashes with `hashing`
  leafIndex,
  proof,            // Uint8Array[] from the log's inclusion-proof endpoint
});
if (!ok) reject('bad inclusion proof');

// 3. Verify that newEnvelope's tree is an append-only extension of oldEnvelope.
const extended = verifier.verifyConsistency({
  oldEnvelopeBytes,
  newEnvelopeBytes,
  proof,
});
if (!extended) reject('log forked or rolled back');

Construction throws MerkleLogError with one of these discriminators:

• 'origin-invalid' if origin is empty, contains whitespace, or contains +.
• 'pubkey-size' if pubkey is not a Uint8Array or its length is not suite.pkSize.
• 'unsupported-hashing' if hashing is not 'sha256' or 'blake3'.
• 'unsupported-suite' if suite.formatEnum has no entry in the c2sp.org/tlog-cosignature §Format algorithm-byte registry.
• 'module-not-initialized' if any required WASM module has not been init()d.

Memory-backed producer. Build a log from caller-supplied keys with MerkleLog.create, or let the class generate a fresh keypair with MerkleLog.generate and persist the keys yourself. Hot-path methods (append, head, size, rootHash, inclusionProof, consistencyProof) are synchronous; only create and generate are async.

import { init, MerkleLog, MerkleVerifier, utf8ToBytes } from 'leviathan-crypto';
import { sha2Wasm }  from 'leviathan-crypto/sha2/embedded';
import { sha3Wasm }  from 'leviathan-crypto/sha3/embedded';
import { mldsaWasm } from 'leviathan-crypto/mldsa/embedded';

await init({ sha2: sha2Wasm, sha3: sha3Wasm, mldsa: mldsaWasm });

// Defaults: hashing = 'sha256', suite = MlDsa44Suite.
const { log, signingKey, pubkey } = await MerkleLog.generate({
  origin: 'example.com/log42',
});

// Persist signingKey + pubkey wherever you keep secrets. The library
// does not touch disk or any network.

try {
  const { leafIndex, inclusionProof } = log.append(utf8ToBytes('leaf-zero'));
  const envelope = log.head();   // signed checkpoint envelope bytes
  // ... publish envelope and proofs to your consumers
} finally {
  log.dispose();   // wipes the signing-key copy
}

import { init, MerkleLog, Ed25519Suite } from 'leviathan-crypto';
import { sha2Wasm }    from 'leviathan-crypto/sha2/embedded';
import { ed25519Wasm } from 'leviathan-crypto/ed25519/embedded';

await init({ sha2: sha2Wasm, ed25519: ed25519Wasm });

const { log, signingKey, pubkey } = await MerkleLog.generate({
  origin: 'example.com/sigsum-log',
  suite:  Ed25519Suite,
});

create's signingKey is copied internally; modifying the caller's view of the buffer after construction does not affect the log. generate's returned signingKey and pubkey are independent allocations; the log keeps its own copies.

The suite option on MerkleLog and MerkleVerifier must be a leviathan SignatureSuite whose formatEnum is registered in the c2sp.org/tlog-cosignature §Format algorithm-byte registry. As of v3.0.0 the registry covers two suites:

Any other suite (EcdsaP256Suite, prehash variants, ML-DSA-65/87, SLH-DSA, hybrids) raises MerkleLogError('unsupported-suite') at MerkleLog.create, MerkleLog.generate, or MerkleVerifier constructor time. The registry grows additively: when C2SP registers a new algorithm byte, the table here updates in the same PR that lands the registry extension in src/ts/merkle/signed-note.ts. The single source of truth is the ALGO_REGISTRY const in signed-note.ts; lookupAlgoEntryByFormatEnum and lookupAlgoEntryByByte expose the registry to power users.

The defaults are intentionally not exported as named constants. MerkleLog resolves them internally so call sites stay terse; pinning an explicit value is the way to opt out.

SignedLog<S extends SignatureSuite> ties a MerkleTree (Sha256Tree or Blake3Tree), a registered cosignature SignatureSuite, and an origin string into one object that produces signed checkpoints and verifies received ones.

import {
  init, SignedLog, Sha256Tree, MemoryStorage, MlDsa44Suite, utf8ToBytes,
} from 'leviathan-crypto';

const tree = new Sha256Tree(new MemoryStorage());
const log  = new SignedLog({
  tree,
  suite: MlDsa44Suite,
  origin: 'example.com/log42',
  signingKey,
  pubkey,
});

try {
  for (const leafBytes of incoming) tree.append(leafBytes);
  const envelope = log.signCheckpoint({ timestamp: 1740000000 });
  if (!log.verifyCheckpoint(envelope)) throw new Error('verify');
} finally {
  log.dispose();
}

MerkleStorage is the extension point for file, database, or hybrid backends. Implement the interface and pass an instance to the tree constructor:

import { MerkleStorage } from 'leviathan-crypto';

class FileStorage implements MerkleStorage {
  // ... implementation, sync everywhere per the merkle layer's invariant
  size(): number { /* ... */ return 0; }
  appendLeaf(leafIndex: number, leafHash: Uint8Array): void { /* ... */ }
  getLeaf(leafIndex: number): Uint8Array { /* ... */ return new Uint8Array(); }
  putNode(level: number, index: number, hash: Uint8Array): void { /* ... */ }
  getNode(level: number, index: number): Uint8Array { /* ... */ return new Uint8Array(); }
  hasNode(level: number, index: number): boolean { /* ... */ return false; }
}

const tree = new Sha256Tree(new FileStorage());

If your backend genuinely needs async IO, wrap it externally: pre-load the leaves and nodes synchronously into memory at the boundaries of your operation, then drive the merkle layer.

SignedLog rejects unregistered suites with SigningError('sig-unsupported-suite'); the normie classes wrap this with MerkleLogError('unsupported-suite') so callers can branch on either.

Two MerkleTree specialisations sharing the same algorithmic core. Both produce 32-byte root hashes and consume / emit 32-byte proof entries; the wire format is identical and only differs in how hashLeaf and hashInternal are computed.

Blake3Tree.hashInternal does not stack RFC 6962 prefix bytes on top of BLAKE3. The BLAKE3 spec already provides domain separation via flag bytes; the parent compress is called with modeFlags = 0 (default mode) and isRoot = 0 at every internal node, including the top of the tree. Stacking 0x00 / 0x01 prefixes on top of this would be redundant separation and would also discard compress4 parallelism at the internal-node layer.

Sha256Hasher and Blake3Hasher are exported as standalone Hasher consts; pass them directly to the free-function verifiers below if you do not need a stateful tree.

verifyInclusionProof and verifyConsistencyProof are the thin-verifier path. They take a Hasher and the proof bytes, decide RFC 9162 §2.1.3 / §2.1.4 in isolation, and return boolean. Use them when you want a checkpoint-less verification (e.g. a witness verifying against a root it already holds), or when you want to integrate the merkle math with a non-leviathan signature stack.

import { Sha256Hasher, verifyInclusionProof } from 'leviathan-crypto';

const ok = verifyInclusionProof({
  hasher: Sha256Hasher,
  leafHash: hasher.hashLeaf(leafBytes),
  leafIndex,
  treeSize,
  proof,
  rootHash,
});

The verifier-and-builder pair is hash-agnostic by design; the Hasher argument fully determines the domain separation. SHA-256 and BLAKE3 trees produce identical proof wire format and consume the same algorithmic core.

Two layered codecs implement the C2SP wire format.

Per c2sp.org/tlog-checkpoint §Note text. Three newline-terminated lines:

<origin>\n
<treeSize-decimal>\n
<base64(rootHash)>\n

origin is non-empty UTF-8, no whitespace, no plus characters. treeSize is ASCII decimal with no leading zeroes. rootHash uses RFC 4648 §4 standard base64 with padding (not the URL-safe variant). Extension lines are rejected: the cosignature wire format does not commit to them.

import { serializeCheckpointBody, parseCheckpointBody } from 'leviathan-crypto';

const body = serializeCheckpointBody({ origin, treeSize, rootHash });
const cp   = parseCheckpointBody(body, 32 /* expectedHashLen */);

Per c2sp.org/signed-note §Format. Body, blank separator line, then one or more — <name> <base64(keyId||signature)> signature lines.

import { emitSignedNote, parseSignedNote } from 'leviathan-crypto';

const envelope = emitSignedNote(body, [signatureLine]);
const env      = parseSignedNote(envelope);
// env.body is the body region (including its trailing newline)
// env.signatures is the parsed signature lines
// env.ignoredCount is the number of signature lines that failed structural validation

Structural envelope errors throw RangeError; individual signature lines that fail structural validation are silently discarded into ignoredCount per the signed-note §Signatures rule "unknown signatures MUST be ignored".

Per c2sp.org/tlog-cosignature §Format timestamped_signature struct:

uint64 timestamp_be || signature[N]

N is the suite's raw signature size (64 for Ed25519, 2420 for ML-DSA-44).

import {
  emitCosigSignaturePayload, parseCosigSignaturePayload,
} from 'leviathan-crypto';

const payload = emitCosigSignaturePayload(timestamp, sigBytes);
const parsed  = parseCosigSignaturePayload(payload, 64 /* sigSize */);

Two constructions dispatch on the algorithm byte registry's messageConstruction field:

buildCosigSignedMessage and buildCosignedMessage are exported for code paths that need to reconstruct the signed message manually. SignedLog, MerkleLog, and MerkleVerifier dispatch internally so you never have to choose.

keyId = SHA-256(utf8(origin) || 0x0A || algoByte || pubkey)[:4]

Per c2sp.org/tlog-cosignature §Format. The key ID is the first 4 bytes of the signature line's base64 payload; the verifier matches it against the keyId derived from the trusted identity to find the right signature line.

import { deriveKeyId, ALGO_BYTE_MLDSA44_COSIG } from 'leviathan-crypto';

const keyId = deriveKeyId('example.com/log42', ALGO_BYTE_MLDSA44_COSIG, pubkey);

MerkleStorage is the per-node persistence interface a MerkleTree drives. Two-axis key: (level, index). Level 0 is the leaf row; level >= 1 stores the hash of a perfect aligned subtree covering [index * 2^level, (index + 1) * 2^level). Roots of partial right-edge subtrees are recomputed on demand by the tree.

export interface MerkleStorage {
  size(): number;
  appendLeaf(leafIndex: number, leafHash: Uint8Array): void;
  getLeaf(leafIndex: number): Uint8Array;
  putNode(level: number, index: number, hash: Uint8Array): void;
  getNode(level: number, index: number): Uint8Array;
  hasNode(level: number, index: number): boolean;
}

Sync everywhere. The merkle layer is synchronous; callers that need async IO wrap externally.

MemoryStorage is the only backend leviathan ships. It is suitable for tests, witnesses without persistent storage, and the MerkleVerifier short-lived flow. Production logs that need durability implement the interface over a file or database and feed an instance to Sha256Tree / Blake3Tree.

A bare skeleton for a file backend:

import { MerkleStorage } from 'leviathan-crypto';

class JsonlFileStorage implements MerkleStorage {
  // Two files: leaves.jsonl (append-only), nodes.jsonl (level/index -> hex).
  // size() reads the leaf-count footer; appendLeaf appends to leaves.jsonl
  // and updates the count; putNode appends to nodes.jsonl with a (level, index)
  // header; getNode / getLeaf / hasNode use an in-memory index map populated
  // at startup. Sync IO via Node's fs.readFileSync / writeFileSync /
  // appendFileSync, which keeps the surface compatible with the merkle
  // layer's sync invariant.
  // ...
}

const tree = new Sha256Tree(new JsonlFileStorage());

The merkle module surfaces three error classes plus standard RangeError / TypeError for caller-side contract violations.

MerkleVerifier's verifyCheckpoint / verifyInclusion / verifyConsistency return boolean on every input; they only throw the construction-time MerkleLogErrors above. SignedLog.verifyCheckpoint matches.