> ## 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. # Settlement Attestation Format > AlgoVoi authored multi-chain settlement attestation format: a categorical SETTLED, PENDING_FINALITY, REVERSED enumeration under JCS RFC 8785. The settlement attestation closes the lifecycle gap between admission-time compliance receipts and post-settlement refund receipts. ## Protocol coverage The AlgoVoi gateway returns a signed `settlement_attestation` on confirmed payment across all four payment protocols: | Protocol | Endpoint | Attestation on | | -------- | ---------------------------------------------------- | ---------------- | | **x402** | `POST /checkout/{token}/verify`, `POST /x402/verify` | `verified: true` | | **MPP** | `GET /mpp/{resource_id}` | `verified: true` | | **AP2** | `POST /ap2/confirm` | `verified: true` | | **A2A** | `POST /a2a/v1/tasks` (verify-payment) | `verified: true` | In `ALGOVOI_MODE=standard` the field is stripped at the MCP client layer. In `ALGOVOI_MODE=substrate` (default) it is returned alongside the standard verdict fields. See the [MCP server docs](/integrations/mcp-server#response-model-algovoi_mode) for details. It records that a payment has reached a particular settlement state on a particular chain, at a particular instant, under the attesting party's risk model. It is AlgoVoi-authored, specified in IETF Internet-Draft [`draft-hopley-x402-settlement-attestation`](https://datatracker.ietf.org/doc/draft-hopley-x402-settlement-attestation/) (POSTED on IETF datatracker 2026-05-25, Independent Submission, Informational), and published as a standalone reference implementation: * TypeScript: [`@algovoi/settlement-attestation`](https://www.npmjs.com/package/@algovoi/settlement-attestation) (live, v0.1.0) * Python: [`algovoi-settlement-attestation`](https://pypi.org/project/algovoi-settlement-attestation/) (live, v0.1.0) Both packages depend on [`algovoi-substrate`](https://pypi.org/project/algovoi-substrate/) / [`@algovoi/substrate`](https://www.npmjs.com/package/@algovoi/substrate) for the JCS canonicalisation primitive. Apache 2.0. ## Lifecycle position ``` admission settlement refund compliance --> settlement --> refund receipt attestation receipt ``` All three formats anchor to the same canonicalisation discipline ([`urn:x402:canonicalisation:jcs-rfc8785-v1`](https://datatracker.ietf.org/doc/draft-hopley-x402-canonicalisation-jcs-v1/)). A verifier walking the audit chain confirms admission → settlement → refund under one byte-deterministic pin. ## Why this format Settlement is the state transition at which a broadcast payment is considered final by the attesting party's risk model. The operational and regulatory significance is load-bearing: * Under **MiCA Article 80** (Regulation (EU) 2023/1114) and **AMLR Article 56** (Regulation (EU) 2024/1624), operator records of settled crypto-asset transactions must be retained and re-verifiable for the statutory period. * Under **PSD2 Article 89** (Directive 2015/2366), the unauthorised-payment refund obligation is tied to when the payment was settled, not broadcast. A `PENDING_FINALITY` state is operationally distinct from `SETTLED` for refund-window calculation. * Under **AML Directives 5 and 6**, a settled payment that is subsequently `REVERSED` (by chain reorganisation or court-ordered fraud reversal) requires an audit trail independent of the original settlement event. The receipt format preserves these distinctions at the canonical-bytes level via a closed three-element enumeration. ## Receipt shape A settlement attestation is an eight-field JSON object canonicalised under RFC 8785 (JCS). Field names are sorted lexicographically by JCS during canonicalisation. ```json theme={null} { "canon_version": "jcs-rfc8785-v1", "jurisdiction_flags": ["UK", "EU"], "settled_payment_ref": "sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f", "settlement_amount": {"amount_minor": "100000", "asset_id": "USDC.6"}, "settlement_chain": "ethereum:8453", "settlement_provider_did": "did:web:api.algovoi.co.uk", "settlement_result": "SETTLED", "settlement_timestamp_ms": 1716494400000 } ``` | Field | Type | Description | | ------------------------- | -------------------- | ---------------------------------------------------------------------------------------- | | `canon_version` | string | In-band canonicalisation pin. Fixed `jcs-rfc8785-v1`. | | `jurisdiction_flags` | ordered array | ISO-3166-1 codes. Order significant under RFC 8785. | | `settled_payment_ref` | string | `sha256:{hex}` reference to original payment record. | | `settlement_amount` | object | `{amount_minor: string, asset_id: string}`. | | `settlement_chain` | string | `{chain_family}` or `{chain_family}:{network}` (e.g. `algo`, `solana`, `ethereum:8453`). | | `settlement_provider_did` | string | DID URI of attesting party. | | `settlement_result` | string (closed enum) | `SETTLED` / `PENDING_FINALITY` / `REVERSED`. | | `settlement_timestamp_ms` | integer | Epoch milliseconds. **Substrate Rule 2**. | ## The closed enumeration: `settlement_result` | Value | Semantic | Regulatory significance | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `SETTLED` | Payment confirmed on-chain with sufficient finality for the operator's risk model. | Triggers MiCA Art. 80 / AMLR Art. 56 record-keeping. PSD2 Art. 89 refund-window clock starts. | | `PENDING_FINALITY` | Payment broadcast and included, awaiting the operator's required confirmation depth. | Operator has visibility but does not assert finality. PSD2 refund-window timing differs from SETTLED. | | `REVERSED` | Previously SETTLED payment now considered reversed (chain reorg, fraud reversal, operator-initiated under regulatory directive). | Triggers reversal-evidence obligations under POCA s.330 and AML5/6. | Each value produces a byte-distinct `content_hash`. Score, depth, or confirmation-count representations are not acceptable substitutes. ## Multi-chain `settlement_chain` identifiers AlgoVoi's production xChain runs on 8 chain families. Conventional identifiers: | Chain | Identifier | | ---------------- | ------------------------- | | Algorand mainnet | `algo` | | VOI mainnet | `voi` | | Solana mainnet | `solana` | | Stellar Pubnet | `stellar` | | Hedera mainnet | `hedera` | | Base L2 | `base` or `ethereum:8453` | | Tempo mainnet | `tempo:mainnet` | | Ethereum mainnet | `ethereum:1` | The string is opaque under JCS — case-sensitive, no decomposition. Operators requiring richer chain metadata emit it in separate operator-layer audit records, not as nested fields. ## Composition A settlement attestation `settled_payment_ref` MAY reference a compliance receipt `content_hash`. A refund receipt `original_payment_ref` MAY reference a settlement attestation `content_hash`. The full lifecycle chain: ``` compliance receipt (ALLOW) | v (settled_payment_ref) settlement attestation (SETTLED) | v (original_payment_ref) refund receipt (FULL | PARTIAL | REJECTED) ``` A verifier walking this chain confirms admission → settlement → refund under one canonicalisation pin. ## Conformance vectors 8 byte-level reference vectors + 5 pair invariants + 3 chain invariants at [`vectors/settlement_attestation_v1/`](https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors/tree/main/vectors/settlement_attestation_v1). ## Quick start ### TypeScript ```typescript theme={null} import { buildSettlementAttestation } from "@algovoi/settlement-attestation"; import { sha256Jcs } from "@algovoi/substrate"; const a = buildSettlementAttestation({ settled_payment_ref: "sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f", settlement_result: "SETTLED", settlement_timestamp_ms: 1716494400000, settlement_provider_did: "did:web:api.algovoi.co.uk", settlement_amount: { amount_minor: "100000", asset_id: "USDC.6" }, settlement_chain: "ethereum:8453", jurisdiction_flags: ["UK", "EU"], }); console.log(sha256Jcs(a)); // 0ead75bfe7fc74cc0421124903e56cb5c5006d02c393231a1d5f260fa87e96d3 ``` ## What this is NOT * **Not a cryptographic settlement proof.** Cryptographic proofs of payment conditions are orthogonal; this format records the operator's categorical claim at the canonical-bytes level. The two layers compose. * **Not a chain-specific finality declaration.** Chain-specific finality semantics (block depth, validator quorum) are out of scope; verifiers apply them at verification time. * **Not a cross-chain bridge proof.** Cross-asset substitution is permitted in the format; the bridge mechanism is out of scope. ## Companion IETF Internet-Draft [`draft-hopley-x402-settlement-attestation`](https://datatracker.ietf.org/doc/draft-hopley-x402-settlement-attestation/) (Independent Submission, Informational). AlgoVoi-authored, sole authorship. Normatively references [`draft-hopley-x402-canonicalisation-jcs-v1`](https://datatracker.ietf.org/doc/draft-hopley-x402-canonicalisation-jcs-v1/). ## See also * [Canonicalisation substrate](/canonicalisation-substrate) — the JCS discipline * [Refund receipt](/refund-receipt) — post-settlement counterpart * [Conformance vectors](/conformance-vectors) — full vector corpus * [Substrate authorship and provenance](/substrate-authorship-provenance) — citable AlgoVoi authorship record * [Verifiable x402 receipts](/verifiable-x402-receipt) — the full x402 receipt chain (compliance, settlement, refund) in one place