Skip to main content
Keystone Enabled Every payment receipt in an agentic stack needs to answer one question in a regulatory audit: was this record tampered with, and does it sit in the correct sequence? Today that answer depends on the issuer’s infrastructure being available. If the issuer is offline, acquired, or simply unwilling, the auditor is stuck. The Retention Chain Substrate removes that dependency. Each receipt carries a retention_chain_ref - a single hash computed from four fields the receipt already contains - that lets any party independently verify chain integrity with no network access and no AlgoVoi infrastructure. Specified in IETF Internet-Draft draft-hopley-x402-retention-chain-05, sole AlgoVoi authorship. Cross-validated byte-for-byte across 8 implementations in 8 programming languages.
Apache-2.0 open source. Install via pip install algovoi-retention-chain. Conformance vectors are published at chopmob-cloud/algovoi-jcs-conformance-vectors. Adopters who pin and verify against the canonical vectors qualify for a free v0 licence key for the mandate auditor - see Adopters below.

​
How it works

The chain reference is computed as:
The preimage is a four-field JSON object, JCS-canonicalised (RFC 8785) so the key order is deterministic across all implementations:
Fields in JCS lexicographic order: chain_seq, issuer_id, prev_receipt_hash, receipt_hash. The genesis receipt has chain_seq = 0 and prev_receipt_hash = "". Every subsequent receipt increments chain_seq by 1 and sets prev_receipt_hash to the receipt_hash of the receipt immediately before it - not the previous chain ref, the previous receipt hash. This means an auditor with any subset of receipts can recompute and verify each link independently.

​
What an auditor can verify

No issuer call. No registry lookup. No AlgoVoi service. SHA-256 and a JSON parser is the entire dependency.

​
Regulatory mapping

​
Cross-language conformance

The algorithm is specified at the byte level in the I-D and cross-validated across 8 independent implementations. Every implementation must produce identical retention_chain_ref values for the same inputs. Conformance vectors are published at chopmob-cloud/algovoi-jcs-conformance-vectors. An implementer in any language can verify against the canonical test cases independently.

​
Conformance vectors

Two published vector sets, both cross-validated 8-impl: retention_chain_v0 - 3 vectors. Genesis + 2 chain links, single issuer (algovoi:test). retention_chain_v1 - 14 vectors in three invariant classes:
  • Part A - 6-link extended chain (seq 0-5, issuer_id=algovoi:compliance)
  • Part B - multi-issuer isolation: same receipt, different issuer_id → different chain_ref
  • Part C - seq-gap adversarial pair: correct vs tampered prev_receipt_hash → different chain_ref
Full preimage inputs, JCS canonical forms, and expected bytes are in the vector files.

​
Adopters

If you build on algovoi-retention-chain and verify against the canonical vectors, you qualify for a free v0 licence key for algovoi-mandate-auditor - AlgoVoi’s production-grade MiCA/DORA compliance audit service for payment mandate charge chains. Qualification criteria:
  1. algovoi-retention-chain declared as a dependency, pinned to a specific version (==0.1.0)
  2. At least one canonical vector hash from retention_chain_v0 or retention_chain_v1 in your conformance tests
  3. A NOTICE file preserving the Apache-2.0 attribution
To apply: email [email protected] with your dependency file, a snippet showing the canonical hash in your test suite, and a copy of your NOTICE file. If all criteria are met, a v0 key is issued within one business day. verify_audit_report is always free with no key required.

​
Relationship to the open substrate

The Retention Chain Substrate sits directly on top of the open JCS Canonicalisation Substrate. It uses the same RFC 8785 JCS canonicalization and SHA-256 primitives that the open substrate defines - no additional cryptographic dependencies.
If you already use the open substrate, adding the Retention Chain requires no new cryptographic infrastructure - only the implementation library and the retention_chain_ref field in your receipts.

​
Specification

The normative specification is IETF Internet-Draft draft-hopley-x402-retention-chain-05 (AlgoVoi, sole authorship, 19 June 2026). The I-D defines:
  • The exact preimage schema and field constraints
  • The JCS canonicalization requirement (RFC 8785 normative reference)
  • Chain construction rules (genesis condition, link ordering)
  • Single-link and sequence verification procedures
  • Conformance vectors with exact canonical byte sequences
  • The Payment Action Lifecycle: action_ref, per-state transition_hash, and the exactly-once SKIP-on-retry guarantee (Section 7)
  • The Settlement-Action Binding: binding_ref tying a settled payment to the verified action and its retention-chain entry (Section 7.6)
  • Policy Binding: policy_ref / policy_bound_ref binding a policy snapshot to a frozen subject ref, for version-provable, rotation-detectable records (Section 7.7), with conformance vectors (Section 8.10)
  • Compliance Gate Binding: payer_ref / gate_ref binding a no-PII payer reference and an ALLOW/REFER/DENY verdict to a pinned subject ref, so a screening decision is tied to the policy in force (Section 7.8), with conformance vectors (Section 8.11)
  • Regulatory applicability analysis (MiCA Art. 80, DORA Art. 14, AMLR Art. 56)
  • Security considerations (collision resistance, subset auditability, truncation, issuer isolation)