Metadata-Version: 2.4
Name: algovoi-retention-chain
Version: 0.1.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/algovoi/retention-chain
Project-URL: Changelog, https://github.com/algovoi/retention-chain/blob/main/python/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,jcs,mica,payment-receipts,retention-chain,rfc8785,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: 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: 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 at [`vectors/retention-chain-v1.json`](../vectors/retention-chain-v1.json),
verified byte-for-byte across Python, TypeScript, Go, Rust, Ruby, C#, and Java (2026-06-17).

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 three criteria below, you qualify
for a free **v0 licence key** for [`algovoi-mandate-auditor`](https://pypi.org/project/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)
2. At least one canonical vector hash from `retention-chain-v1.json` 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:** run [`check_v0_adoption.py`](https://github.com/algovoi/retention-chain/blob/main/python/scripts/check_v0_adoption.py)
against your project and email the output to **chopmob@gmail.com**. If it exits 0,
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`.
