Skip to content
Public template

About

Scoped attestation bundles for confidential Liquid ledgers

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

liquid-proofpack

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"]
Loading

Solid evidence is recomputed by the verifier from chain data. Issuer records are committed and labelled, but not treated as independently true.

What this demonstrates / what it does not

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.

Implementation status

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

Quickstart

python -m pip install -e ".[dev]"
python -m pytest
ruff check .
mypy liquid_proofpack

Verify the committed supply example in zero-setup replay mode:

proofpack verify examples/regtest-supply.cab \
  --backend replay \
  --chain-snapshot examples/regtest-snapshot.json.zst \
  --json

Expected 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.

Verdict semantics

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.

Design comparison

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

Security boundary

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.

Repository map

  • 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.

Roadmap and contributing

The release plan is in ROADMAP.md. Start with CONTRIBUTING.md, and read SECURITY.md before reporting a vulnerability.

Citing this work

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.

Sources

Author

Vishnu Govind - GitHub | Medium | LinkedIn

MIT licensed.

About

Scoped attestation bundles for confidential Liquid ledgers

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages