> ## Documentation Index
> Fetch the complete documentation index at: https://docs.algovoi.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Retention Chain Substrate

> Self verifiable audit chain linking payment receipts with no external infrastructure. Cross validated in eight languages. Satisfies MiCA 80 and DORA 14.

[![Keystone Enabled](https://img.shields.io/badge/Keystone-enabled-5cb9f8)](/keystone)

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`](https://datatracker.ietf.org/doc/draft-hopley-x402-retention-chain/), sole AlgoVoi authorship. Cross-validated byte-for-byte across **8 implementations in 8 programming languages**.

<Info>
  **Apache-2.0 open source.** Install via `pip install algovoi-retention-chain`. Conformance vectors are published at [chopmob-cloud/algovoi-jcs-conformance-vectors](https://github.com/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](#adopters) below.
</Info>

## How it works

The chain reference is computed as:

```
retention_chain_ref = "sha256:" + SHA-256(JCS(preimage))
```

The preimage is a four-field JSON object, JCS-canonicalised (RFC 8785) so the key order is deterministic across all implementations:

```json theme={null}
{
  "chain_seq":         0,
  "issuer_id":         "acme:payments",
  "prev_receipt_hash": "",
  "receipt_hash":      "sha256:24c3e22bc6ece631..."
}
```

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

| Auditor holds                   | What they can check                                     |
| ------------------------------- | ------------------------------------------------------- |
| A single receipt                | That the `retention_chain_ref` is internally consistent |
| A contiguous range              | That no receipt was inserted, deleted, or reordered     |
| A non-contiguous subset         | That each held receipt is individually intact           |
| All receipts, chain\_seq 0 to N | Complete chain audit from genesis                       |

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

## Regulatory mapping

| Obligation                   | Article      | How the chain ref satisfies it                                                                                      |
| ---------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
| Transaction record integrity | MiCA Art. 80 | Any receipt can be re-verified years later from locally held data; no issuer callback required                      |
| ICT audit trail              | DORA Art. 14 | `chain_seq` enforces ordering; hash linkage makes deletion detectable by any receipt-adjacent party                 |
| AML record retention         | AMLR Art. 56 | A competent authority holding receipts can verify integrity without requesting further data from the obliged entity |

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

| Language   | Conformance status             |
| ---------- | ------------------------------ |
| Python     | 8/8 vectors verified (v0 + v1) |
| TypeScript | 8/8 vectors verified (v0 + v1) |
| Go         | 8/8 vectors verified (v0 + v1) |
| Ruby       | 8/8 vectors verified (v0 + v1) |
| Rust       | 8/8 vectors verified (v0 + v1) |
| C# (.NET)  | 8/8 vectors verified (v0 + v1) |
| Java       | 8/8 vectors verified (v0 + v1) |
| Kotlin     | 8/8 vectors verified (v0 + v1) |

Conformance vectors are published at [chopmob-cloud/algovoi-jcs-conformance-vectors](https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors/tree/main/vectors/retention_chain_v1). 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`).

| # | chain\_seq  | Expected chain\_ref                                                       |
| - | ----------- | ------------------------------------------------------------------------- |
| 0 | 0 (genesis) | `sha256:f15a1dcd03cc039204dff24619ff4815ad041ad8796b94f59d52252043d0d08f` |
| 1 | 1           | `sha256:7114dc39543710bf26d0a5825acddd915ffd51fb5b14503024f70fda403053d9` |
| 2 | 2           | `sha256:d3bddca79477e6003cb6ef199897bffed185f5d785b4e7333f9b0585b2b81144` |

**`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](https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors/tree/main/vectors/retention_chain_v1).

## 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 [chopmob@gmail.com](mailto:chopmob@gmail.com) 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](/canonicalisation-substrate). It uses the same RFC 8785 JCS canonicalization and SHA-256 primitives that the open substrate defines  -  no additional cryptographic dependencies.

```
Retention Chain Substrate      Apache-2.0 open source (this page)
        |
        v
JCS + SHA-256 primitives       open substrate (Apache-2.0)
        |
        v
RFC 8785 (JCS)                 IETF standard
```

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-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](/compliance-gate-lite): 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)