Skip to content

Ledger internals

You rarely call these directly — ApprovalService does. They are public so you can verify a ledger you obtained from anywhere (a database dump, an export, another process) without the service.

Hash chain

approvo.chain.next_entry

next_entry(prev: LedgerEntry | None, *, event_type: str, payload: dict, at_time: str, request_id: str | None = None) -> LedgerEntry

Build the sealed entry that would follow prev.

approvo.chain.verify_segment

verify_segment(entries: Iterable[LedgerEntry], *, expected_first_seq: int = 0, expected_prev_hash: str = ZERO_HASH) -> tuple[int, str]

Verify a contiguous run of entries; return (last_seq, last_hash).

Pass the previous segment's return values as expected_first_seq and expected_prev_hash to verify a long ledger incrementally, page by page, without holding it all in memory.

Raises a :class:~approvo.errors.LedgerTampered subtype on the first integrity failure.

Merkle tree

approvo.merkle.merkle_root

merkle_root(leaves: list[str]) -> str

approvo.merkle.inclusion_proof

inclusion_proof(leaves: list[str], index: int) -> list[str]

Audit path for leaves[index], bottom-up, as hex strings.

approvo.merkle.verify_inclusion

verify_inclusion(leaf: str, index: int, tree_size: int, proof: list[str], root: str) -> bool

Check that leaf at index is included in root over tree_size leaves.

approvo.merkle.leaf_hash

leaf_hash(leaf: str) -> bytes

Checkpoints

approvo.checkpoint.build_checkpoint

build_checkpoint(leaf_hashes: list[str], *, log_id: str, at_time: str, prev: Checkpoint | None = None) -> Checkpoint

Compute an unsigned checkpoint over leaf_hashes.

approvo.checkpoint.sign_checkpoint

sign_checkpoint(cp: Checkpoint, signer: Signer) -> Checkpoint

Return cp with a synchronous signer's signature appended.

approvo.checkpoint.verify_checkpoint

verify_checkpoint(cp: Checkpoint, key_dir: KeyDirectory) -> list[str]

Return owner ids whose signatures on cp verify; raise if none do.

Only keys with key_use == "log" scoped to cp.log_id count.

approvo.checkpoint.verify_consistency

verify_consistency(trusted: Checkpoint, prefix_leaf_hashes: list[str]) -> None

Prove the log extends a previously trusted checkpoint.

prefix_leaf_hashes must be the first trusted.tree_size leaves of the current log. Their Merkle root must reproduce trusted.root_hash exactly; anything else means history was rewritten.

(Bandwidth-optimized RFC 6962 consistency proofs, for verifiers that cannot fetch the prefix, are on the roadmap — see ADR-0003.)

approvo.checkpoint.signable_bytes

signable_bytes(cp: Checkpoint) -> bytes