algovoi-settlement-attestation 0.1.1

AlgoVoi settlement attestation format reference implementation -- multi-chain categorical attestation under urn:x402:canonicalisation:jcs-rfc8785-v1, companion to algovoi-substrate compliance and refund receipts

algovoi-settlement-attestation

AlgoVoi-authored reference implementation for the settlement attestation format specified in IETF Internet-Draft draft-hopley-x402-settlement-attestation-00 (Independent Submission, Informational).

Multi-chain categorical attestation under the JCS RFC 8785 canonicalisation discipline (urn:x402:canonicalisation:jcs-rfc8785-v1). Companion to the AlgoVoi compliance receipt and refund receipt I-Ds — closes the lifecycle gap between admission and refund.

Python and TypeScript reference implementations, byte-for-byte parity, Apache 2.0.

Lifecycle position

admission         settlement        refund
compliance   -->  settlement   -->  refund
receipt           attestation       receipt

All three formats anchor to the same canonicalisation discipline. A verifier walking the audit chain confirms admission → settlement → refund under one byte-deterministic pin.

Packages

Language	Package	Install
Python	algovoi-settlement-attestation	pip install algovoi-settlement-attestation
TypeScript	@algovoi/settlement-attestation	npm install @algovoi/settlement-attestation

Both depend on algovoi-substrate / @algovoi/substrate for the JCS canonicalisation primitive.

Quick start

Python

from algovoi_settlement_attestation import build_settlement_attestation
from algovoi_substrate import sha256_jcs

a = build_settlement_attestation(
    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"],
)
print(sha256_jcs(dict(a)))
# 0ead75bfe7fc74cc0421124903e56cb5c5006d02c393231a1d5f260fa87e96d3

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

Receipt format

Eight-field JSON object canonicalised under RFC 8785 (JCS):

Field	Type	Description
canon_version	string	jcs-rfc8785-v1
jurisdiction_flags	ordered array	ISO-3166-1 codes; primary jurisdiction first
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> (e.g. algo, solana) or <chain_family>:<network> (e.g. 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 ms (Substrate Rule 2)

Closed enumeration: settlement_result

Value	Semantic	Regulatory significance
SETTLED	Payment confirmed on-chain with sufficient finality.	Triggers settlement-finality record-keeping under MiCA Article 80 and AMLR Article 56. PSD2 Article 89 refund-window clock starts.
PENDING_FINALITY	Broadcast and included, awaiting confirmation depth.	Operator has visibility of inclusion 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.

Multi-chain settlement_chain identifier

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

Conformance vectors

8 byte-level reference vectors + 5 pair invariants + 3 chain invariants at vectors/settlement_attestation_v1/.

Companion IETF Internet-Draft

draft-hopley-x402-settlement-attestation-00 (Independent Submission, Informational). AlgoVoi-authored, sole authorship.

Related AlgoVoi packages

Package	Purpose
algovoi-substrate / @algovoi/substrate	JCS RFC 8785 canonicalisation, action_ref, compliance receipts
algovoi-refund-receipt / @algovoi/refund-receipt	Refund receipt format
algovoi-rfc9421-verifier / @algovoi/rfc9421-verifier	RFC 9421 HTTP message signature verifier
algovoi-settlement-attestation / @algovoi/settlement-attestation	This package. Settlement attestation format

Conformance to the canonicalisation discipline

This package emits settlement attestations pinned to canon_version: jcs-rfc8785-v1 on every emitted attestation. The pin is in-band; downstream verifiers (including algovoi-audit-verifier and any conformant third-party verifier) read the pin to select the canonicalisation rule applied at emission.

The pin is the load-bearing primitive for the Substrate Adopters Registry: adopters anchoring to this discipline pin the same canon_version value in their own publicly-citable artefacts. AlgoVoi maintains the registry as a neutral observer; this package itself is recorded there as the AlgoVoi reference implementation.

Substrate adopters

AlgoVoi is recorded in the Substrate Adopters Registry as the substrate author (v1 and v2). Parties anchoring their own services or specifications to canon_version: jcs-rfc8785-v1 are recorded in the registry via the submission process. AlgoVoi validates submissions against the artefact's canonical bytes and adds qualifying entries.

Licence

Apache 2.0.