Skip to content

Proof bundles

A proof bundle is the portable JSON object returned by the gateway's /v1/bundle/:hash endpoint. It can contain four layers:

  1. Home threshold signature: the Ed25519 multi-signature or BLS aggregate over the attestation.
  2. Batch inclusion: an RFC 9162 Merkle proof connecting the attestation hash to a home-network batch root.
  3. Federation cross-anchors: signed commitments to that same batch root by configured peer networks.
  4. External anchors: provider-specific records for the batch root.

The core verify_proof_bundle function verifies the home signature, checks the batch leaf/index/tree-size/root linkage, and verifies each cross-anchor against the supplied peer configurations and per-peer minimums. It returns a level: Basic, Batched, or Federated; invalid optional layers lower the result or are reported per layer rather than silently becoming home-network signatures.

The CLI can load a bundle from disk or fetch it, load a local verification configuration (or fetch one in online mode), load peer configurations, and run the same offline core verification.

Implemented behavior

The verification result reports verified signature count, required count, batch inclusion status, per-peer cross-anchor status, and the number of external anchor proofs present.

External anchor proofs are deliberately reported as present, not verified cryptographically by verify_proof_bundle. Their provider-specific proof and optional anchored_data must be checked against the provider independently.

An STH is not automatically part of a ProofBundle; STH and log consistency verification use the separate log endpoints and proof types.

Assumptions

Offline verification is only as strong as the home and peer NetworkVerificationConfigs supplied to it. A configuration fetched from an untrusted gateway should be pinned or independently reviewed when the trust anchor matters.

Non-goals

A bundle is not proof that external providers will remain available, that a provider's record is immutable, or that the content behind a hash is genuine. Presence of an anchor object is not equivalent to successful independent provider verification.

TODO — maintainer review

Define a versioned bundle verification profile, including whether and how each external provider's inclusion/transaction/DNS evidence should be checked by the CLI and core.