Customer developer docs

Ledger and proof verification

Per-tenant Merkle ledger history, signed checkpoints, and inclusion, consistency, and bundle proofs.

Ledger and proof verification

Every tenant has an append-only Merkle audit ledger. Decision events are hashed into leaves, sealed under signed checkpoints, and provable with standard inclusion and consistency proofs. Use these endpoints when your team needs to inspect recorded history or verify a specific record cryptographically.

All endpoints authenticate with X-Vault-API-Key and operate on your tenant's ledger only.

Which endpoint to use

FieldTypeRequiredDescription
GET/ledgerHistoryNoList recent decision events for your tenant, including receipt payloads and signatures.
GET/ledger/checkpointsHistoryNoList signed Merkle checkpoints: root hash, previous checkpoint hash, signer key, tree size, export status.
GET/ledger/verifyVerificationNoServer-side verification: recompute event hashes, receipt signatures, and the checkpoint chain.
GET/ledger/verification-summaryVerificationNoSummary form of the same verification.
GET/ledger/proof/bundleVerificationNoThe recommended per-record bundle: event, inclusion proof, checkpoint(s), and key material.
GET/ledger/proof/inclusionVerificationNoRFC 6962-style inclusion proof for one record.
GET/ledger/proof/consistencyVerificationNoAppend-only consistency proof between two checkpoints.
GET/ledger/encryptedAdvancedNoThe ledger list wrapped in a tenant-transport-key encrypted envelope.

Start with a proof bundle rather than the individual primitives:

text
GET /ledger/proof/bundle?request_id=8ee2d480-4e23-49c5-9869-a0247e806e1c HTTP/1.1
Host: vault.example.com
X-Vault-API-Key: sk_prod_example

The bundle contains everything an independent verifier needs:

  • event — the full record, including receipt_payload, receipt_signature, receipt_key_id, and receipt_algorithm.
  • inclusion — event_hash, leaf_hash, leaf_index, tree_size, the sibling path, and the sealing checkpoint.
  • consistency — optionally, a proof that a later checkpoint extends an earlier one.
  • keys — the public JWKs (with key IDs, algorithms, and validity) to check the signatures.

Verification is arithmetic over the bundle plus the published keys — it does not require Definite to stay available. The same keys are served publicly at /.well-known/jwks.json.

Checkpoints and external witnessing

Checkpoints chain to each other by hash, are signed (EdDSA or ES256), can carry an RFC 3161 timestamp-authority countersignature, and are exported to object storage as an external witness, so a rolled-back or forked ledger is externally detectable. GET /ledger/checkpoints reports each checkpoint's export status.

Practical rules

  • Keep the request_id of records you may need to prove later; it is the lookup key for bundles.
  • Use /ledger/verify for routine integrity checks and proof bundles for record-level evidence.
  • Treat ledger and proof APIs as audit surfaces, not as an application data path. Rule-level evidence for reporting checks lives in receipts, which carry their own chain and signatures.