Settlement Attestation Format

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 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 (POSTED on IETF datatracker 2026-05-25, Independent Submission, Informational), and published as a standalone reference implementation:

TypeScript: @algovoi/settlement-attestation (live, v0.1.0)
Python: algovoi-settlement-attestation (live, v0.1.0)

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

All three formats anchor to the same canonicalisation discipline (urn:x402:canonicalisation:jcs-rfc8785-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.

{
  "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/.

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.

Get started

Platform

Concepts

Keystone

Agent Mesh

Substrate 2

Commercial

Open substrate

Payment protocols

Chains

Integrations

Help

Company

Settlement Attestation Format

Protocol coverage

Lifecycle position

Why this format

Receipt shape

The closed enumeration: `settlement_result`

Multi-chain `settlement_chain` identifiers

Composition

Conformance vectors

Quick start

TypeScript

What this is NOT

Companion IETF Internet-Draft

See also

​Protocol coverage

​Lifecycle position

​Why this format

​Receipt shape

​The closed enumeration: settlement_result

​Multi-chain settlement_chain identifiers

​Composition

​Conformance vectors

​Quick start

​TypeScript

​What this is NOT

​Companion IETF Internet-Draft

​See also

Protocol coverage

Lifecycle position

Why this format

Receipt shape

The closed enumeration: `settlement_result`

Multi-chain `settlement_chain` identifiers

Composition

Conformance vectors

Quick start

TypeScript

What this is NOT

Companion IETF Internet-Draft

See also