Crate dig_evidence 

dig-evidence — the DIG Network’s library of ACTIVE on-chain evidence types

One home for the evidence/proof TYPES the ecosystem produces and verifies. Every type here is an ACTIVE piece of evidence: it (a) knows what it proves, (b) GATHERS the specific on-chain information its proof needs through an INJECTED ChainSource reader (never taking an upward dependency on a node or transport), and (c) re-verifies offline from its own gathered contents.

The pattern (modeled on dig-did::prove_lineage)

Each type implements the Evidence trait and follows the same unforgeable-by-construction discipline as dig-did’s AncestryProof:

• Private fields. A value cannot be forged by a struct literal — the only way to obtain one is Evidence::gather, which authenticates every field against the injected reader (or, for a self-contained offline proof, against the supplied inputs). Holding a value witnesses the proof.
• Gather-only construction. Construction reads chain state through the injected ChainSource and authenticates it; it holds NO key, signs nothing, and does its own no network I/O.
• Fail-closed. An unreadable chain, a missing/forged anchor, or a proof that does not fold is an EvidenceError, never a silently-accepted absence.

Phase 1 evidence types (the MVP flywheel read→verify→cache→reshare integrity gate)

Type	Proves	Class
RangeInclusionEvidence	a content range’s leaf is included under a generation root	self-authenticating (offline)
RootAnchorEvidence	a generation root is committed on-chain by the store’s launcher-anchored lineage	locally-observable (chain read)
ReadIntegrityEvidence	both of the above, bound to the same root — the read→cache→reshare gate	composite

See SPEC.md for the full evidence taxonomy and the self-authenticating (broadcastable) vs locally-observable (NEVER broadcastable, #1438 anti-censorship) classification table.

Reused primitives

The merkle inclusion machinery is REUSED verbatim from dig-capsule (MerkleProof / ProofStep, with the digstore:leaf:v1 / digstore:node:v1 domain-separation tags), the DataStore on-chain parse from dig-merkle, and the injected reader from dig-chainsource-interface — this crate reinvents no crypto and cannot skew from the canonical read-crypto.

Structs

CapsuleBytes32

The merkle inclusion-proof shapes and domain-separation tags, REUSED verbatim from dig-capsule. A RangeInclusionClaim is built from a ProofStep path; the tags are the byte-for-byte producer contract. Fixed-width byte container (raw bytes on the wire, no length prefix).

CoinRecord

The injected reads-only chain seam every active evidence type gathers through, plus the coin/lineage shapes it reads. Re-exported so consumers construct claims without a direct dig-chainsource-interface dependency. A coin together with its on-chain lifecycle metadata, as read from a ChainSource.

FoldedProof

The canonical URN content-verification contract (FoldedProof + the gate-then-decrypt verify_inclusion / verify_and_decrypt over injected crypto), re-exported so a consumer reaches the blind-client read-verification surface through dig-evidence alongside the on-chain evidence types. This is the URN-level counterpart to RangeInclusionEvidence. A decoded, folded inclusion proof: its declared leaf and the root its merkle path folds to.

MerkleProof

A complete inclusion proof from a leaf up to the generation root.

ProofStep

One step on a bottom-up inclusion path: the sibling hash and whether that sibling sits on the LEFT of the current node.

RangeInclusionClaim

What a range-inclusion proof claims: that leaf folds, via path, to generation_root.

RangeInclusionEvidence

Authenticated evidence that a range leaf is included under a generation root.

ReadIntegrityClaim

What a read-integrity proof claims: that range_leaf (via range_path) is included under generation_root, AND that generation_root is committed on-chain by the store store_id.

ReadIntegrityEvidence

Authenticated composite evidence that a served range is both included under a generation root and that the root is genuinely anchored on-chain — the single assurance a reader needs to cache + reshare.

RootAnchorClaim

What a root-anchor proof claims: that generation_root is committed on-chain by the store whose launcher coin id is store_id.

RootAnchorEvidence

Authenticated evidence that a generation root is committed by the store’s on-chain lineage.

SingletonLineage

The injected reads-only chain seam every active evidence type gathers through, plus the coin/lineage shapes it reads. Re-exported so consumers construct claims without a direct dig-chainsource-interface dependency. The lineage of a Chia singleton: every coin id from the launcher spend forward to the current unspent tip.

Enums

EvidenceError

The single error type every Evidence gather/verify returns. Each variant is a stable, catalogued failure reason (§6.2) so a consumer can branch on WHY a proof could not be established without parsing prose.

Constants

LEAF_TAG

Domain-separation prefix for a merkle LEAF (leaf = SHA-256(LEAF_TAG || chunk)). Distinct from NODE_TAG so a leaf and an internal node can never collide.

MAX_LINEAGE_DEPTH

The maximum number of lineage coins the backward walk will visit before failing closed with EvidenceError::LineageTooDeep. Bounds the work an adversarial (deep) lineage can force.

NODE_TAG

Domain-separation prefix for an internal merkle NODE (node = SHA-256(NODE_TAG || left || right)). Applied on both the build and the verify paths so a proof folds up to the same domain-separated root.

Traits

ChainSource

The injected reads-only chain seam every active evidence type gathers through, plus the coin/lineage shapes it reads. Re-exported so consumers construct claims without a direct dig-chainsource-interface dependency. A reads-only view of Chia chain state — the single canonical contract every provider implements and every consumer depends on.

ContentCrypto

The canonical URN content-verification contract (FoldedProof + the gate-then-decrypt verify_inclusion / verify_and_decrypt over injected crypto), re-exported so a consumer reaches the blind-client read-verification surface through dig-evidence alongside the on-chain evidence types. This is the URN-level counterpart to RangeInclusionEvidence. The crypto primitives this contract INJECTS from digstore_core (never reimplemented here).

Evidence

An active piece of on-chain evidence: a type that knows what it proves, gathers the on-chain information its proof needs, and re-verifies offline from its own gathered contents.

Functions

verify_and_decrypt

The canonical URN content-verification contract (FoldedProof + the gate-then-decrypt verify_inclusion / verify_and_decrypt over injected crypto), re-exported so a consumer reaches the blind-client read-verification surface through dig-evidence alongside the on-chain evidence types. This is the URN-level counterpart to RangeInclusionEvidence. The full blind-tier pipeline: gate-then-decrypt (rules 1–6). Rejects a rootless URN, verifies inclusion against trusted_root, then decrypts — decryption is reached ONLY after verification passes.

verify_inclusion

The canonical URN content-verification contract (FoldedProof + the gate-then-decrypt verify_inclusion / verify_and_decrypt over injected crypto), re-exported so a consumer reaches the blind-client read-verification surface through dig-evidence alongside the on-chain evidence types. This is the URN-level counterpart to RangeInclusionEvidence. Rules 2–4: the integrity gate. The served ciphertext must be the proof’s leaf, the path must fold to a root (via the injected decoder), and that root must equal trusted_root. Any failure is a hard fail-closed ResolveError::VerifyFailed.

Type Aliases

EvidenceResult

A convenience result alias for evidence gather/verify.