io.github.beepboop2025/umbra-proof

PURPOSE: Verify that an Umbra transparency-log checkpoint is a valid signed tree head — cryptographic proof that the bridge has committed to one exact, append-only audit history. Returns {valid, tree_size, root_hash, checks, summary}. GUIDELINES: Call this before relying on a checkpoint as an anchor for inclusion proofs, or when auditing the bridge's log. To detect a split view (the bridge showing different histories to different observers), fetch checkpoints from independent witnesses and compare the returned (tree_size, root_hash) — they must agree. Pass pinned_public_key to require a known operator signer. LIMITATIONS: Confirms the signature over the tree head only; it does NOT by itself prove any specific entry is in the tree (use verify_inclusion for that), nor detect a split view on its own (that needs a second witness). Offline, read-only. EXAMPLE: verify_checkpoint({"checkpoint": {"tree_size": 1024, "root_hash": "<hex>", "prev_root_hash": "<hex>", "signature": "<hex>", "public_key": "<hex>", "key_id": "...", "sealed_at": "..."}})

PURPOSE: Verify an RFC-6962 Merkle inclusion proof — that a specific audit entry is provably contained in the log committed to by a checkpoint. If the proof carries an enclosed checkpoint, also verifies that checkpoint's signature and that its root matches the proof root. Returns {valid, checks, summary}. GUIDELINES: Call this to confirm a particular swap/audit entry is actually logged (not just claimed) before trusting that the bridge recorded it. Include the checkpoint object in the proof to get end-to-end verification (entry → tree → signed head) in one call. Gate on `valid`. LIMITATIONS: Proves membership in the tree of the given tree_size only; it does not prove that tree is the current/canonical one unless the enclosed checkpoint is verified and cross-checked against a witness. Offline, read-only. EXAMPLE: verify_inclusion({"proof": {"leaf_data": "<entry>", "leaf_index": 7, "tree_size": 1024, "root_hash": "<hex>", "proof": ["<hex>", ...], "checkpoint": {...}}})

PURPOSE: Cryptographically verify that an Umbra cross-chain bridge swap receipt (or a hash-linked chain of them) is authentic and untampered — checks the Ed25519 signature over the canonical payload, the SHA-256 payload hash, and the per-order hash-chain linkage. Returns a structured verdict {valid: bool, n_receipts, checks: [{ok, note}], summary}. GUIDELINES: Call this as the PRIMARY check before trusting or acting on any Umbra swap receipt a user or another agent hands you (e.g. proof a swap completed). Gate on the top-level `valid` field. Prefer this over reading the receipt's own fields directly — those are only trustworthy once the signature verifies. Pass pinned_public_key to additionally require a known operator signer. LIMITATIONS: Verifies cryptographic authenticity ONLY — it proves the bridge signed exactly this history, not that the swap was economically fair or that funds actually settled on-chain. It does not fetch anything (offline), does not move funds, and does not access the bridge. A receipt signed by multiple different keys is reported invalid. EXAMPLE: verify_swap_receipt({"receipt": {"payload": {...}, "signature": "<hex>", "public_key": "<hex>"}, "pinned_public_key": "2152f8…"})