On confidential ledgers, disclosure is all-or-nothing. To prove a holding, an issuer hands over a master blinding key, permanently revealing every position to whoever holds it, or asks the auditor to take their word for it.
liquid-proofpack defines Confidential Attestation Bundles: portable, signed evidence packages for specific claims, specific verifiers, and specific time windows. The verifier uses the bundle to learn what to check and what scoped material was disclosed, then verifies against independently obtained chain data.
Caution
Template reference implementation. Not audited. Not production software. Not a compliance product. Do not use as audit assurance, legal advice, or custody infrastructure.
flowchart LR
R["AMP registry export"] --> C["Registry commitment"]
D["Scoped disclosure"] --> B["CAB bundle"]
C --> B
K["Per-address blinding keys"] --> B
B --> V["Independent verifier"]
N["Liquid node / Esplora / LWK"] --> V
V --> O["VERIFIED / DEMO / ASSERTED / PARTIAL / FAILED"]
Solid evidence is recomputed by the verifier from chain data. Issuer records are committed and labelled, but not treated as independently true.
This repository demonstrates the CAB v0.2 format, strict verdict semantics, deterministic registry commitments, per-record inclusion proofs, Ed25519 manifest signing, CAB archive hash verification, a master-key disclosure guard, source-backed Elements asset-id derivation, and C1 supply verification against either an Elements RPC backend or a clearly labelled replay snapshot.
It does not yet implement full Liquid chain recomputation for all six claim types. C1 supply is the v0.2 live-verification path. The committed zero-setup example reports DEMO, not VERIFIED, because its chain data comes from a fixture snapshot rather than the verifier's own node.
| Component | Status | Evidence / boundary |
|---|---|---|
| CAB manifest, claim, disclosure, and verdict schemas | Implemented | v0.1 bundles remain parseable; v0.2 adds DEMO |
| Registry ingest and Merkle commitment | Implemented | Unit tests cover mutation sensitivity and inclusion proofs |
| Per-record registry proof | Implemented | proofpack registry prove-record |
| Master blinding-key guard | Implemented | Tests reject key names and values containing master-key material |
| Bundle hash integrity | Implemented | Parser recomputes every manifest hash |
| Ed25519 manifest signing | Implemented | Detached signature helper; CLI key generation |
| C1 supply verifier | Implemented | Anchor hash, asset-id derivation, issuance-set completeness, and total recomputation |
| Elements asset-id derivation | Implemented | Tested against rust-elements issuance vectors |
| Replay backend | Implemented | Emits DEMO; never VERIFIED |
| Elements RPC backend | Partial | Typed JSON-RPC transport and issuance adapter; burn scans and full regtest orchestration remain roadmap |
| Regtest harness | Partial | Frozen replay snapshot is committed; live Docker fixture remains roadmap |
| Zero-knowledge aggregate proofs | Out of scope | See LIMITATIONS.md |
python -m pip install -e ".[dev]"
python -m pytest
ruff check .
mypy liquid_proofpackVerify the committed supply example in zero-setup replay mode:
proofpack verify examples/regtest-supply.cab \
--backend replay \
--chain-snapshot examples/regtest-snapshot.json.zst \
--jsonExpected verdict shape:
{
"verifier_backend": "replay",
"overall": "DEMO",
"claims": [
{
"claim_id": "c1",
"status": "DEMO",
"checks": [
{ "name": "anchor-block-hash", "result": "pass" },
{ "name": "asset-id-derivation", "result": "pass" },
{ "name": "issuance-set-complete", "result": "pass" },
{ "name": "supply-total", "result": "pass" },
{ "name": "demo-chain-source", "result": "demo" }
]
}
],
"warnings": [
"DEMO: chain data was supplied by a fixture snapshot; this does not attest to live network state."
]
}DEMO is successful for the example path, but it is not live verification. Use --backend elements-rpc with ELEMENTS_RPC_URL, credentials, and wallet configuration for node-backed verification.
VERIFIED means the verifier independently reproduced the claim from chain data and got the stated result. DEMO means the same verification logic ran against fixture-supplied chain data. ASSERTED means the bundle is internally consistent but the relevant input is issuer-supplied or the chain adapter was not configured. PARTIAL means unresolved candidates remain and the unresolved count is non-zero. FAILED means independent recomputation disagreed with the claim.
The strict separation is the core design rule. A template adapter must never report VERIFIED.
| Approach | Disclosure boundary | Trade-off |
|---|---|---|
| Master blinding-key handover | Entire wallet, indefinite | High evidentiary power, excessive disclosure |
| Issuer PDF / spreadsheet | Issuer assertion | Low technical assurance |
| CAB scoped disclosure | Specific assets, addresses, block range, verifier | Verifier learns disclosed components in v0.1 |
| Future aggregate proofs | Total without components | Research path; not implemented here |
The signature binds issuer identity to bundle content. It does not make a claim true. Truth comes only from independent verification against chain data and from clearly labelled issuer-supplied records. See docs/threat-model.md.
liquid_proofpack/models.py: CAB schema and verdict models.liquid_proofpack/registry: AMP export parsing, Merkle commitments, inclusion proofs.liquid_proofpack/disclosure: scoped-key normalization and master-key guard.liquid_proofpack/bundle: archive assembly, parsing, hashing, signing.liquid_proofpack/elements: Elements asset-id derivation and consensus helpers.liquid_proofpack/claims: C1 supply verifier.liquid_proofpack/backends: replay and Elements RPC chain adapters.liquid_proofpack/verify: structural verifier and verdict aggregation.docs: threat model, MiCA/DORA mapping, AMP integration notes.examples: small registry fixture for the 30-second local workflow.
The release plan is in ROADMAP.md. Start with CONTRIBUTING.md, and read SECURITY.md before reporting a vulnerability.
Use CITATION.cff or GitHub's Cite this repository button. The citation describes a CAB template reference implementation and does not imply audit, deployment, or regulatory assurance.
- Blockstream Liquid Network documentation - Liquid and Confidential Transactions context.
- Blockstream AMP documentation - asset management and registry workflow context.
- rust-elements issuance source - asset entropy, asset-id, and reissuance-token derivation.
- Elements transaction source - Elements transaction serialization context.
- RFC 8785 JSON Canonicalization Scheme - canonical JSON motivation for registry commitments.
- European Banking Authority MiCA overview - regulatory context, not legal advice.
- DORA regulation text - operational resilience context, not legal advice.
Vishnu Govind - GitHub | Medium | LinkedIn
MIT licensed.