Skip to content

Merkle batches

Batch construction

The gateway periodically selects confirmed, unbatched attestations. Candidates are ordered deterministically by (sequence, hash) and the attestation hashes become the batch leaves. A batch records its ID, network ID, period, count, and 32-byte Merkle root. A retried job that confirms late remains eligible for a later batch; reservation time does not create a permanent gap.

The batch tree follows RFC 9162's Merkle Tree Hash rules:

  • a leaf is SHA-256(0x00 || leaf);
  • an internal node is SHA-256(0x01 || left || right);
  • left and right are positional, not sorted; and
  • an unbalanced tree splits at the largest power of two strictly below its size.

An inclusion proof carries the raw leaf, its zero-based index, tree size, siblings, and root. The position-aware verifier rejects index, size, path, and root mismatches.

RFC 9162 log

The gateway also issues a Signed Tree Head (STH) over the append-only log. An STH commits to the network ID, tree size, timestamp, and root hash. Its digest is wrapped in a synthetic attestation and threshold-signed by the same witness flow. Clients and the independent auditor can verify STH signatures and RFC 9162 consistency proofs between old and new STHs. A valid consistency chain shows that the old tree is a prefix of the new tree.

Implemented behavior

The gateway exposes current or size-specific STHs, consistency proofs, log proofs, and attestation inclusion data. Batch closure and STH issuance are background operations; an attestation can be threshold-confirmed before it is batched.

Assumptions

Verifiers trust the network configuration and obtain a complete, ordered proof path. STH monitoring is most useful when an auditor or multiple clients retain earlier STHs and check consistency over time.

Non-goals

An RFC 9162 tree proves commitment and append-only extension, not that the underlying content was supplied, authored, or private. It is not a consensus protocol and does not make an operator's log globally canonical.

TODO — maintainer review

Confirm and document the exact persisted “log leaf” mapping used by get_log_leaves (batch roots versus another stored representation), and state the intended relationship between per-batch trees and the global STH log.