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.
The settlement attestation closes the lifecycle gap between admission-time compliance receipts and post-settlement refund receipts. 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 (POSTED on IETF datatracker 2026-05-25, Independent Submission, Informational), and published as a standalone reference implementation:
Both packages depend on algovoi-substrate / @algovoi/substrate for the JCS canonicalisation primitive. Apache 2.0.
Lifecycle position
admission settlement refund
compliance --> settlement --> refund
receipt attestation receipt
urn:x402:canonicalisation:jcs-rfc8785-v1). A verifier walking the audit chain confirms admission → settlement → refund under one byte-deterministic pin.
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.
{
"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. |
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 |
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)
vectors/settlement_attestation_v1/.
Quick start
TypeScript
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 (Independent Submission, Informational). AlgoVoi-authored, sole authorship. Normatively references draft-hopley-x402-canonicalisation-jcs-v1.
See also
