Metadata-Version: 2.4
Name: algovoi-retention-chain
Version: 0.3.0
Summary: AlgoVoi Retention Chain Substrate — self-verifiable audit chain linking payment receipts without external infrastructure. MiCA Art. 80, DORA Art. 14, AMLR Art. 56.
Project-URL: Homepage, https://docs.algovoi.co.uk/retention-chain-substrate
Project-URL: Repository, https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors
Project-URL: Changelog, https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors/blob/main/CHANGELOG.md
Author-email: AlgoVoi <chopmob@gmail.com>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agentic-payments,amlr,audit-chain,compliance,dora,http-message-signatures,jcs,mica,payment-receipts,retention-chain,rfc8785,rfc9421,x402
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Requires-Dist: rfc8785>=0.1.2
Provides-Extra: dev
Requires-Dist: algovoi-rfc9421-signer>=0.1.0; extra == 'dev'
Requires-Dist: algovoi-rfc9421-verifier>=0.3.0; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: fastapi<1.0,>=0.111; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: uvicorn[standard]<1.0,>=0.29; extra == 'dev'
Provides-Extra: rfc9421
Requires-Dist: algovoi-rfc9421-verifier>=0.3.0; extra == 'rfc9421'
Provides-Extra: serve
Requires-Dist: fastapi<1.0,>=0.111; extra == 'serve'
Requires-Dist: uvicorn[standard]<1.0,>=0.29; extra == 'serve'
Description-Content-Type: text/markdown

# algovoi-retention-chain

Self-verifiable audit chain for payment receipts. Apache-2.0.

Each receipt carries a `retention_chain_ref` computed as:

```
retention_chain_ref = SHA-256(JCS({chain_seq, issuer_id, prev_receipt_hash, receipt_hash}))
```

Any party holding a receipt set can verify chain integrity by recomputing the reference
from locally held data alone. No AlgoVoi infrastructure, registry lookup, or network
access required.

Satisfies transaction-recording and audit-trail obligations under MiCA Art. 80,
DORA Art. 14, and AMLR Art. 56. Normative spec:
[draft-hopley-x402-retention-chain](https://datatracker.ietf.org/doc/draft-hopley-x402-retention-chain/)
(IETF Independent Submission).

## Install

```
pip install algovoi-retention-chain
```

## Usage

```python
from algovoi_retention_chain import retention_chain_ref, verify_chain_sequence

# Compute a chain ref for an authorized charge
ref = retention_chain_ref(
    prev_receipt_hash="",                          # "" for the genesis (first) charge
    receipt_hash="sha256:<64-hex>",                # SHA-256 of your receipt payload
    chain_seq=0,
    issuer_id="mandate:acct-123",                  # scope per mandate / account
)
# ref = "sha256:<64-hex>" — embed in the receipt; any holder can recompute it

# Verify a full sequence offline
chain = [
    {"chain_seq": 0, "issuer_id": "mandate:acct-123",
     "prev_receipt_hash": "", "receipt_hash": "sha256:...", "chain_ref": "sha256:..."},
    {"chain_seq": 1, ...},
]
assert verify_chain_sequence(chain)
```

## Conformance vectors

Canonical test vectors (v0 and v1) are published at
[`chopmob-cloud/algovoi-jcs-conformance-vectors`](https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors/tree/main/vectors/retention_chain_v1),
verified byte-for-byte across Python, TypeScript, Go, Rust, Ruby, C#, Java, and Kotlin (2026-06-17).

The v1 set covers three invariant classes:
- **Part A** — 6-link extended chain (seq 0–5, single issuer)
- **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`)

Use these in your test suite to prove interoperability. If you embed at least one canonical
hash in your conformance tests, you qualify for the Adopters programme below.

## Adopters — free mandate auditor key

If you build on `algovoi-retention-chain` and meet the criteria below, 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` appears in your
   conformance tests — proving you verified against the canonical vectors, not a reimplementation
3. A `NOTICE` file in your project preserving the Apache-2.0 attribution

**To apply:** email **chopmob@gmail.com** with your project's 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. The key is valid for 12 months and gives access to
`build_audit_report` and the HTTP audit service — `verify_audit_report` is always free with no
key required.

## HTTP service

```bash
pip install "algovoi-retention-chain[serve]"
RETENTION_CHAIN_BIND=0.0.0.0:8096 algovoi-retention-chain
# POST /v1/chain-ref   POST /v1/verify-link   POST /v1/verify-sequence   GET /health
```

## Acceptance

```bash
python scripts/acceptance.py   # exit 0 + "ALL GREEN"
```

## Licence

Apache-2.0. See `LICENSE` and `NOTICE`.
