avm-mesh 0.4.2__py3-none-any.whl

avm_mesh/__init__.py

@@ -0,0 +1,45 @@
+"""avm-mesh -- settlement receipts.
+
+A receipt is what moves between meshes. It is deliberately small: a digest,
+a pointer to a proofpack, and the trust tier that proofpack actually earned.
+The bundle itself is stored once per attested interval, never per transaction.
+"""
+from .attestation import ConsensusAttestation, attest, verify_attestation
+from .effects import verify_settlement_amount
+from . import a2a, rails, produce, service, trust
+from .produce import produce as produce_receipt
+from .service import Store, WitnessInfo
+from .trust import TrustPolicy, load_policy, verify_with_policy
+from .sealed import seal, verify_sealed
+from .receipt import (
+    MeshError,
+    ProofpackPointer,
+    SettlementReceipt,
+    create_receipt,
+    verify_receipt,
+)
+
+__all__ = [
+    "produce",
+    "service",
+    "trust",
+    "produce_receipt",
+    "Store",
+    "WitnessInfo",
+    "TrustPolicy",
+    "load_policy",
+    "verify_with_policy",
+    "a2a",
+    "seal",
+    "verify_sealed",
+    "ConsensusAttestation",
+    "attest",
+    "verify_attestation",
+    "verify_settlement_amount",
+    "MeshError",
+    "ProofpackPointer",
+    "SettlementReceipt",
+    "create_receipt",
+    "verify_receipt",
+]
+__version__ = "0.4.2"

avm_mesh/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

avm_mesh/a2a.py

@@ -0,0 +1,150 @@
+"""A2A settlement-evidence extension.
+
+A2A is the transport agents already use to talk to each other. This
+extension lets one agent hand another a settlement receipt as evidence, and
+lets the receiver check it against chain consensus instead of taking the
+sender's word.
+
+Design follows the A2A extension mechanism rather than inventing a parallel
+one: the extension is declared on the agent card, negotiated per request, and
+the evidence travels as an ordinary Artifact with a `data` part. Nothing in
+the protocol changes; a peer that does not implement the extension simply
+ignores it and falls back to whatever it trusted before.
+
+The extension URI is the versioning boundary. Never change the semantics
+behind a published URI -- publish a v2.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .receipt import MeshError
+from .sealed import verify_sealed
+
+EXTENSION_URI = "https://algovoi.co.uk/a2a/extensions/settlement-evidence/v1"
+ARTIFACT_NAME = "settlement-receipt"
+
+
+def extension_descriptor() -> dict:
+    """The object to place in an agent card's capabilities.extensions."""
+    return {
+        "uri": EXTENSION_URI,
+        "description": (
+            "Carries a sealed settlement receipt whose settlement is attested by "
+            "Algorand or Voi consensus state proofs (Falcon-1024). Receivers verify "
+            "offline against a pinned genesis hash; no operator key is required in "
+            "the trust base."
+        ),
+        "required": False,
+        "params": {
+            "tiers": ["stake_attested", "structural"],
+            "chains": ["mainnet-v1.0", "voimain-v1.0"],
+            "proofpack_delivery": "by-reference",
+        },
+    }
+
+
+def advertise(card: dict) -> dict:
+    """Return the card with this extension declared. Does not mutate the input."""
+    if not isinstance(card, dict):
+        raise MeshError("agent card must be an object")
+    out = dict(card)
+    caps = dict(out.get("capabilities") or {})
+    existing = list(caps.get("extensions") or ())
+    if not any(e.get("uri") == EXTENSION_URI for e in existing if isinstance(e, dict)):
+        existing.append(extension_descriptor())
+    caps["extensions"] = existing
+    out["capabilities"] = caps
+    return out
+
+
+def wants_extension(message_or_params: Any) -> bool:
+    """True if a peer asked for this extension in a request.
+
+    A2A puts requested extensions on the message params as `extensions`, and
+    older peers omit it entirely, so absence means "not requested" rather
+    than "refused".
+    """
+    if not isinstance(message_or_params, dict):
+        return False
+    for container in (message_or_params, message_or_params.get("params") or {}):
+        if isinstance(container, dict):
+            exts = container.get("extensions")
+            if isinstance(exts, (list, tuple)) and EXTENSION_URI in exts:
+                return True
+    return False
+
+
+def as_artifact(sealed: dict, *, artifact_id: str = "settlement-receipt") -> dict:
+    """Wrap a sealed receipt as an A2A Artifact.
+
+    Returns the receipt itself in a ``data`` part rather than as text, so a
+    receiver never has to parse prose or trust a base64 blob's framing.
+
+    EMITS THE v1.0 FORM. A2A v1.0 removed the inline ``kind`` discriminator as a
+    breaking change (spec appendix A.2.1): a DataPart is now identified by the
+    presence of the ``data`` member, not by a tag. The legacy v0.3.x form was
+    ``{"kind": "data", "data": {...}}``; emitting it against a v1.0 peer makes the
+    part unparseable, because there is no ``kind`` field to read and the extra
+    member is unexpected.
+    """
+    if not isinstance(sealed, dict):
+        raise MeshError("sealed receipt must be an object")
+    for key in ("canonical_bytes_b64", "content_hash"):
+        if key not in sealed:
+            raise MeshError(f"sealed receipt missing {key}")
+    return {
+        "artifact_id": artifact_id,
+        "name": ARTIFACT_NAME,
+        "parts": [{
+            "data": {"avm_mesh_receipt": sealed, "extension": EXTENSION_URI},
+            "mediaType": "application/json",
+        }],
+    }
+
+
+def verify_artifact(artifact: dict, resolve: Callable[[str], dict],
+                    *, trusted_voters: Any = None,
+                    expected_genesis_hash_b64: str | None = None,
+                    verify_signature: Callable[[bytes, dict], bool] | None = None) -> dict:
+    """Verify settlement evidence received from a peer.
+
+    Fail-closed: an artifact that does not carry this extension's data is an
+    error, not an empty success. Returning "no evidence" as success is how
+    receivers end up accepting nothing and thinking they verified something.
+    """
+    if not isinstance(artifact, dict):
+        raise MeshError("artifact must be an object")
+    parts = artifact.get("parts")
+    if not isinstance(parts, list):
+        raise MeshError("artifact has no parts")
+
+    payload = None
+    for part in parts:
+        if not isinstance(part, dict):
+            continue
+        # v1.0: the presence of "data" identifies a DataPart; the inline `kind`
+        # discriminator was removed (spec appendix A.2.1). v0.3.x peers still send
+        # it, so accept both -- the spec tells implementors to dual-handle during
+        # the overlap period.
+        if "data" not in part:
+            continue
+        if "kind" in part and part.get("kind") != "data":
+            continue
+        data = part.get("data")
+        if isinstance(data, dict) and data.get("extension") == EXTENSION_URI:
+            payload = data.get("avm_mesh_receipt")
+            break
+
+    if payload is None:
+        raise MeshError("artifact carries no settlement-evidence payload")
+    if not isinstance(payload, dict):
+        raise MeshError("settlement-evidence payload is not an object")
+
+    return verify_sealed(
+        payload,
+        resolve,
+        trusted_voters=trusted_voters,
+        expected_genesis_hash_b64=expected_genesis_hash_b64,
+        verify_signature=verify_signature,
+    )

avm_mesh/attestation.py

@@ -0,0 +1,283 @@
+"""LEVEL 3: consensus attestation for a settlement receipt.
+
+The rails receipt has two levels:
+
+    LEVEL 1  integrity     sha256(canonical_bytes) == content_hash
+    LEVEL 2  authenticity  the OPERATOR's Falcon-1024 signature over that hash
+
+LEVEL 2 is signed by AlgoVoi, so it proves "the operator issued this receipt".
+It cannot prove the settlement happened as described, because the operator
+could sign anything. LEVEL 3 closes that: evidence that the transaction was
+final, authenticated against the chain's own consensus -- and against a
+*trusted voters anchor the verifier supplies*, never one the bundle asserts.
+
+WHY THE ANCHOR IS MANDATORY (scheme v2). An earlier version of this module
+derived the signing set from the bundle's own `previous_state_proof_message`.
+That was forgeable: a bundle author chooses that field, so they could name
+themselves as the only signer and mint a valid-looking stake_attested tier.
+avm-proofpack 0.4.1 fixed this by requiring a caller-supplied
+`TrustedVoters` anchor; v2 here follows. The scheme string is bumped because
+v1 attestations must not be accepted as if they meant the same thing.
+
+Obtain the anchor independently: walk the chain of state proofs from a pinned
+genesis bootstrap (avm_proofpack.consensus.chain), or take it from a node you
+already trust at a known round. Never read it out of the bundle you are
+verifying.
+"""
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from .receipt import MeshError, bundle_digest
+
+SCHEME = "avm-stateproof-falcon1024-v2"
+SUPPORTED_CHAINS = ("mainnet-v1.0", "voimain-v1.0")
+
+
+def _b64(b: bytes) -> str:
+    return base64.b64encode(b).decode("ascii")
+
+
+def _unb64(s: str) -> bytes:
+    return base64.b64decode(s.encode("ascii"), validate=True)
+
+
+@dataclass(frozen=True)
+class ConsensusAttestation:
+    """Evidence that a settlement was final, anchored in chain consensus.
+
+    `anchor_voters_commitment_b64` and `anchor_ln_proven_weight` name the
+    anchor the attestation was built against. The verifier must supply the
+    same anchor independently and it must match; carrying it here makes the
+    claim auditable, not self-certifying.
+    """
+    scheme: str
+    chain: str
+    genesis_hash_b64: str
+    txid: str
+    round: int
+    trust_root: str
+    evidence_uri: str
+    evidence_digest: str
+    first_attested_round: int
+    last_attested_round: int
+    anchor_voters_commitment_b64: str
+    anchor_ln_proven_weight: int
+
+    def __post_init__(self) -> None:
+        if self.scheme != SCHEME:
+            raise MeshError(
+                f"unsupported attestation scheme {self.scheme!r}; "
+                f"v1 attestations were forgeable and are refused"
+            )
+        if self.chain not in SUPPORTED_CHAINS:
+            raise MeshError(
+                f"chain {self.chain!r} has no state-proof consensus; "
+                f"supported: {', '.join(SUPPORTED_CHAINS)}"
+            )
+        if self.trust_root != "stake_attested":
+            raise MeshError(
+                f"a consensus attestation must be stake_attested; got {self.trust_root!r}"
+            )
+        try:
+            gh = _unb64(self.genesis_hash_b64)
+            vc = _unb64(self.anchor_voters_commitment_b64)
+        except Exception as exc:
+            raise MeshError("genesis hash or voters commitment is not valid base64") from exc
+        if len(gh) != 32:
+            raise MeshError("genesis hash must be 32 bytes")
+        if len(vc) != 64:
+            raise MeshError("voters commitment must be 64 bytes")
+        if self.anchor_ln_proven_weight < 0:
+            raise MeshError("anchor proven weight cannot be negative")
+
+    def to_dict(self) -> dict:
+        return {
+            "scheme": self.scheme,
+            "chain": self.chain,
+            "genesis_hash_b64": self.genesis_hash_b64,
+            "txid": self.txid,
+            "round": self.round,
+            "trust_root": self.trust_root,
+            "evidence_uri": self.evidence_uri,
+            "evidence_digest": self.evidence_digest,
+            "first_attested_round": self.first_attested_round,
+            "last_attested_round": self.last_attested_round,
+            "anchor_voters_commitment_b64": self.anchor_voters_commitment_b64,
+            "anchor_ln_proven_weight": self.anchor_ln_proven_weight,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Any) -> "ConsensusAttestation":
+        if not isinstance(data, dict):
+            raise MeshError("consensus_attestation must be an object")
+        try:
+            return cls(
+                scheme=data["scheme"],
+                chain=data["chain"],
+                genesis_hash_b64=data["genesis_hash_b64"],
+                txid=data["txid"],
+                round=int(data["round"]),
+                trust_root=data["trust_root"],
+                evidence_uri=data["evidence_uri"],
+                evidence_digest=data["evidence_digest"],
+                first_attested_round=int(data["first_attested_round"]),
+                last_attested_round=int(data["last_attested_round"]),
+                anchor_voters_commitment_b64=data["anchor_voters_commitment_b64"],
+                anchor_ln_proven_weight=int(data["anchor_ln_proven_weight"]),
+            )
+        except KeyError as exc:
+            raise MeshError(f"attestation missing field {exc}") from exc
+        except (TypeError, ValueError) as exc:
+            raise MeshError(f"attestation has an unusable field: {exc}") from exc
+
+
+def attest(bundle: dict, uri: str, *, trusted_voters: Any) -> ConsensusAttestation:
+    """Build a LEVEL 3 block from a proofpack, or refuse.
+
+    `trusted_voters` is the caller's anchor (avm_proofpack.TrustedVoters).
+    It is required: without it the evidence cannot reach stake_attested, and
+    emitting a weaker block would let a receipt *look* consensus-backed while
+    carrying an operator's word.
+    """
+    from avm_proofpack.bundle import Bundle
+    from avm_proofpack.verify import verify_bundle
+
+    if trusted_voters is None:
+        raise MeshError(
+            "a trusted voters anchor is required for LEVEL 3; derive one from a "
+            "pinned genesis bootstrap or a chain walk, never from this bundle"
+        )
+    if not isinstance(bundle, dict):
+        raise MeshError("bundle must be an object")
+
+    try:
+        report = verify_bundle(Bundle.from_dict(bundle), trusted_voters=trusted_voters)
+    except Exception as exc:
+        raise MeshError(f"evidence failed verification: {exc}") from exc
+    if report.trust_root != "stake_attested":
+        raise MeshError(
+            f"evidence earns {report.trust_root!r}, not stake_attested"
+        )
+    return ConsensusAttestation(
+        scheme=SCHEME,
+        chain=report.genesis_id,
+        genesis_hash_b64=report.genesis_hash_b64,
+        txid=report.txid,
+        round=report.round,
+        trust_root=report.trust_root,
+        evidence_uri=uri,
+        evidence_digest=bundle_digest(bundle),
+        first_attested_round=report.first_attested_round,
+        last_attested_round=report.last_attested_round,
+        anchor_voters_commitment_b64=_b64(bytes(trusted_voters.voters_commitment)),
+        anchor_ln_proven_weight=int(trusted_voters.ln_proven_weight),
+    )
+
+
+def verify_attestation(attestation: ConsensusAttestation | dict,
+                       resolve: Callable[[str], dict],
+                       *, trusted_voters: Any,
+                       expected_genesis_hash_b64: str | None = None) -> Any:
+    """Check LEVEL 3 against a caller-supplied anchor. Returns the report.
+
+    The anchor is required and must match the one recorded in the
+    attestation. Passing the attestation's own anchor back to it would verify
+    nothing: the claim would certify itself.
+    """
+    if isinstance(attestation, dict):
+        attestation = ConsensusAttestation.from_dict(attestation)
+    if not isinstance(attestation, ConsensusAttestation):
+        raise MeshError("attestation must be a ConsensusAttestation")
+    if trusted_voters is None:
+        raise MeshError("a trusted voters anchor is required to check LEVEL 3")
+
+    recorded_vc = _b64(bytes(trusted_voters.voters_commitment))
+    if recorded_vc != attestation.anchor_voters_commitment_b64:
+        raise MeshError(
+            "anchor mismatch: the attestation was built against a different "
+            "voters commitment than the one you trust"
+        )
+    if int(trusted_voters.ln_proven_weight) != attestation.anchor_ln_proven_weight:
+        raise MeshError("anchor mismatch: proven weight differs from the attestation")
+
+    expected_gh_bytes: bytes | None = None
+    if expected_genesis_hash_b64 is not None:
+        if attestation.genesis_hash_b64 != expected_genesis_hash_b64:
+            raise MeshError(
+                "genesis hash mismatch: attestation is anchored to a different chain"
+            )
+        try:
+            expected_gh_bytes = _unb64(expected_genesis_hash_b64)
+        except Exception as exc:
+            raise MeshError("expected genesis hash is not valid base64") from exc
+
+    # evidence_uri is a LOCATOR, not a security binding: it only tells the
+    # caller's resolver where to look. It is deliberately not checked against
+    # any verified value -- there is none to check it against -- because the
+    # integrity binding is the digest below. Whatever the URI points at, only a
+    # bundle hashing to evidence_digest passes, so the URI cannot substitute
+    # evidence. URI policy (which schemes/hosts are acceptable) belongs to the
+    # resolver the caller supplies.
+    try:
+        bundle = resolve(attestation.evidence_uri)
+    except MeshError:
+        raise
+    except Exception as exc:
+        raise MeshError(f"could not resolve evidence {attestation.evidence_uri!r}: {exc}") from exc
+    if not isinstance(bundle, dict):
+        raise MeshError("resolver returned something that is not a proofpack")
+
+    actual = bundle_digest(bundle)
+    if actual != attestation.evidence_digest:
+        raise MeshError(
+            f"evidence digest mismatch: attestation commits to "
+            f"{attestation.evidence_digest[:16]}..., evidence hashes to {actual[:16]}..."
+        )
+
+    from avm_proofpack.bundle import Bundle
+    from avm_proofpack.verify import verify_bundle
+
+    # Pass the pin down so avm-proofpack enforces it against the *authenticated*
+    # block header ('gh' is inside the signed header), not against a field the
+    # evidence author chose. Without this the pin would only ever be compared to
+    # the attestation's own self-asserted genesis_hash_b64 above.
+    try:
+        report = verify_bundle(
+            Bundle.from_dict(bundle),
+            trusted_voters=trusted_voters,
+            expected_genesis_hash=expected_gh_bytes,
+        )
+    except Exception as exc:
+        raise MeshError(f"evidence failed verification: {exc}") from exc
+
+    if report.trust_root != "stake_attested":
+        raise MeshError(f"evidence earns {report.trust_root!r}, not stake_attested")
+    if report.txid != attestation.txid or report.round != attestation.round:
+        raise MeshError("evidence attests a different settlement")
+    if report.genesis_id != attestation.chain:
+        raise MeshError("evidence is for a different chain")
+    # Bind the recorded genesis hash to the one the evidence actually
+    # authenticates to. This ties the attestation's genesis_hash_b64 field (and
+    # therefore any pin checked against it) to verified data rather than to
+    # metadata the bundle author supplied.
+    if report.genesis_hash_b64 != attestation.genesis_hash_b64:
+        raise MeshError(
+            "genesis hash mismatch: attestation records a genesis hash the "
+            "evidence does not authenticate to"
+        )
+    # Bind the claimed attested interval to the one the evidence actually
+    # attests. LEVEL 3 exists precisely so the operator who sealed this is NOT
+    # trusted; without this check that operator could advertise an interval the
+    # evidence does not cover and still verify -- the same gap verify_receipt
+    # already closes on its pointer interval.
+    if (report.first_attested_round, report.last_attested_round) != (
+            attestation.first_attested_round, attestation.last_attested_round):
+        raise MeshError(
+            f"attested interval mismatch: attestation says "
+            f"[{attestation.first_attested_round}, {attestation.last_attested_round}], "
+            f"evidence attests [{report.first_attested_round}, {report.last_attested_round}]"
+        )
+    return report

avm_mesh/bond.py

@@ -0,0 +1,199 @@
+"""Witness bonding: why a witness would tell the truth.
+
+A state proof answers "what did the chain do". A witness answers "here is the
+proof". Without a bond, a witness can withhold, delay or selectively serve
+evidence at zero cost, and "decentralised because node operators run it" is a
+centralised service with a bigger logo. The bond is the only thing that makes
+a false or withholding attestation cost money.
+
+TWO DISTINCT CLAIMS, kept apart on purpose:
+
+  bond      -- an economic stake that can be slashed. IMPORTANT: this module
+               reasons over DECLARED bond values (escrow_txid, bond_microalgo,
+               active); it does NOT read the chain. "bonded" here means "claims
+               a stake at or above the floor", not "a stake proven on-chain to
+               exist, be unspent and be active". On-chain verification of the
+               escrow is deliberately out of scope (Track 3, decisions pending),
+               so until it lands everything downstream of a bond is a model, not
+               a guarantee. The economic argument below is the design intent, not
+               something this code enforces.
+  operator  -- who runs the witness. NOT a trust source; only used to decide
+               independence, because two endpoints of one operator are one
+               witness wearing two hats.
+
+A witness can be perfectly bonded and still be irrelevant to corroboration if
+it shares an operator with the rest of the quorum.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+MIN_BOND_MICROALGO = 1_000_000
+
+
+class BondError(Exception):
+    """Raised when a witness set cannot support the claim being made."""
+
+
+@dataclass(frozen=True)
+class Witness:
+    witness_id: str
+    operator_id: str
+    chain: str
+    bond_microalgo: int
+    escrow_txid: str
+    active: bool = True
+
+    def __post_init__(self) -> None:
+        # Type, not truthiness: 42 is truthy and would become a "witness id" that
+        # no other record could ever match.
+        for name, value in (("witness_id", self.witness_id),
+                            ("operator_id", self.operator_id),
+                            ("chain", self.chain),
+                            ("escrow_txid", self.escrow_txid)):
+            if not isinstance(value, str) or not value:
+                raise BondError(f"{name} must be a non-empty string")
+        if not isinstance(self.bond_microalgo, int) or isinstance(self.bond_microalgo, bool):
+            raise BondError("bond_microalgo must be an integer")
+        if self.bond_microalgo < 0:
+            raise BondError("bond cannot be negative")
+
+    @property
+    def bonded(self) -> bool:
+        return self.active and self.bond_microalgo >= MIN_BOND_MICROALGO
+
+@dataclass(frozen=True)
+class WitnessSet:
+    witnesses: tuple[Witness, ...]
+
+    def __post_init__(self) -> None:
+        seen: set[str] = set()
+        for w in self.witnesses:
+            if w.witness_id in seen:
+                raise BondError(f"duplicate witness_id {w.witness_id!r}")
+            seen.add(w.witness_id)
+
+    def bonded(self) -> tuple[Witness, ...]:
+        return tuple(w for w in self.witnesses if w.bonded)
+
+    def independent_corroborators(self, chain: str) -> tuple[Witness, ...]:
+        """Bonded witnesses on `chain`, at most ONE per operator and per escrow.
+
+        Two endpoints of the same operator are not a quorum, and neither are
+        two witnesses pointing at one escrow -- that is one bond counted
+        twice, which is the cheapest way to fake corroboration.
+        """
+        chosen: list[Witness] = []
+        seen_operators: set[str] = set()
+        seen_escrows: set[str] = set()
+        for w in sorted(self.bonded(), key=lambda x: (-x.bond_microalgo, x.witness_id)):
+            if w.chain != chain:
+                continue
+            if w.operator_id in seen_operators or w.escrow_txid in seen_escrows:
+                continue
+            seen_operators.add(w.operator_id)
+            seen_escrows.add(w.escrow_txid)
+            chosen.append(w)
+        return tuple(chosen)
+
+    def require_corroboration(self, chain: str, threshold: int) -> tuple[Witness, ...]:
+        """Return the independent corroborators, or refuse.
+
+        Refusing is the point: a caller that cannot reach the threshold must
+        not be handed a shorter list and left to interpret it.
+        """
+        if threshold < 1:
+            raise BondError("threshold must be at least 1")
+        got = self.independent_corroborators(chain)
+        if len(got) < threshold:
+            raise BondError(
+                f"insufficient independent corroboration on {chain}: "
+                f"{len(got)} of {threshold} required "
+                f"({len(self.bonded())} bonded, "
+                f"{len({w.operator_id for w in self.bonded()})} distinct operators)"
+            )
+        return got[:threshold]
+
+    def slashable_stake(self, chain: str) -> int:
+        """Total DECLARED microalgo a false attestation could put at risk.
+
+        Counted over independent operators only, because that is the amount
+        that could actually be taken for one lie. This is arithmetic over the
+        declared bond figures, not a chain-verified sum: it is only as real as
+        the bonds themselves, which this module does not verify on-chain.
+        """
+        return sum(w.bond_microalgo for w in self.independent_corroborators(chain))
+
+
+def witnesses(*items: Witness | dict) -> WitnessSet:
+    """Convenience constructor, tolerating dicts from config or JSON."""
+    out = []
+    for item in items:
+        if isinstance(item, Witness):
+            out.append(item)
+        elif isinstance(item, dict):
+            try:
+                out.append(Witness(**item))
+            except TypeError as exc:
+                raise BondError(f"unusable witness record: {exc}") from exc
+        else:
+            raise BondError(f"unusable witness entry: {item!r}")
+    return WitnessSet(tuple(out))
+
+def validate_corroboration(claimed, witness_set: "WitnessSet", chain: str,
+                           threshold: int) -> tuple["Witness", ...]:
+    """Check a receipt's claimed corroboration against the bonded witness set.
+
+    A receipt records who observed the capture. That claim is worthless unless it
+    is checked against bonds, so this refuses on four distinct failures:
+
+      unknown      a witness id nobody has a bond record for
+      unbonded     a real witness whose stake is absent, inactive or too small
+      duplicated   the same operator or the same escrow counted twice
+      insufficient fewer independent corroborators than the threshold demands
+
+    Returning a short list would let a caller read a failed quorum as a pass.
+    """
+    if threshold < 1:
+        raise BondError("threshold must be at least 1")
+    if claimed is None:
+        claimed = ()
+    if not isinstance(claimed, (list, tuple)):
+        raise BondError("corroboration must be a list of witness ids")
+
+    by_id = {w.witness_id: w for w in witness_set.witnesses}
+    chosen: list[Witness] = []
+    seen_operators: set[str] = set()
+    seen_escrows: set[str] = set()
+
+    for wid in claimed:
+        if not isinstance(wid, str) or not wid:
+            raise BondError(f"corroboration entries must be witness ids, got {wid!r}")
+        w = by_id.get(wid)
+        if w is None:
+            raise BondError(f"claimed corroborator {wid!r} has no bond record")
+        if not w.bonded:
+            raise BondError(f"claimed corroborator {wid!r} is not bonded")
+        if w.chain != chain:
+            raise BondError(f"claimed corroborator {wid!r} is bonded on {w.chain!r}, not {chain!r}")
+        if w.operator_id in seen_operators:
+            raise BondError(
+                f"claimed corroborators share operator {w.operator_id!r}: "
+                "one operator is one witness"
+            )
+        if w.escrow_txid in seen_escrows:
+            raise BondError(
+                f"claimed corroborators share escrow {w.escrow_txid!r}: "
+                "one bond is one witness"
+            )
+        seen_operators.add(w.operator_id)
+        seen_escrows.add(w.escrow_txid)
+        chosen.append(w)
+
+    if len(chosen) < threshold:
+        raise BondError(
+            f"insufficient corroboration on {chain}: claimed {len(chosen)} independent "
+            f"witnesses, threshold is {threshold}"
+        )
+    return tuple(chosen)