| Internet-Draft | x402-settlement-anchoring | November 2026 |
| Hopley | Expires 21 May 2027 | [Page] |
This document specifies how a canonical content-addressed settlement reference is anchored into a transaction on any blockchain, uniformly across chain families, so that the same agentic-payment settlement can be recorded on-chain and later verified offline from the transaction bytes alone.¶
The settlement reference is a SHA-256 digest over the JSON Canonicalization Scheme (JCS, RFC 8785) form of a settlement record. This document does not redefine the digest; it defines (1) a chain identification rule that rejects ambiguous chain names before a settlement is bound to a network, and (2) a family-uniform anchor encoding that places the reference in the one field each chain family makes available for opaque data (EVM calldata or a log topic, an SVM memo, an AVM note, a UTXO OP_RETURN output, or a generic metadata carrier). The anchor carries only the digest; it carries no party identifiers, amounts, or personal data in cleartext.¶
Because the reference is content-addressed and the encoding is fixed per family, any holder of the settlement record can recompute the reference, read the anchor from the on-chain field, and confirm the two match with no call to the settling party and no chain-specific verification logic beyond reading one field.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 21 May 2027.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.¶
The x402 payment protocol [x402] and related agentic-payment systems produce settlement records: structured statements that a payment between two agents settled on a particular network for a particular amount. A companion body of work specifies how such records are canonicalised [CANONJCS], chained into tamper-evident audit trails [RETENTIONCHAIN], and enveloped for transport [PEF]. All of that work operates on content-addressed references derived by SHA-256 over the JCS-canonical bytes of a record.¶
A gap remains at the chain boundary. Once a settlement reference exists off-chain, an operator frequently wants to anchor it on-chain, so that the settlement is timestamped and ordered by an independent ledger and can be cited by transaction identifier. Two problems arise:¶
Ambiguous chain identity. A settlement offer that names a chain as "base" or "bitcoin" does not name a network. "base" may be mainnet or a testnet; "bitcoin" may be mainnet, testnet, or a signet. Binding a settlement to the wrong network destroys its value. A settlement flow MUST resolve every chain name to an unambiguous identifier, or refuse to settle.¶
Per-chain anchor drift. Each chain exposes a different field for opaque application data. Without a fixed rule, the same reference is encoded differently on each chain by each implementation, and a verifier must special-case every chain to read it back. This drift is precisely what a diligence reader checks for; it is avoided by pinning one encoding per family from a single source of truth.¶
This document closes both. It specifies a chain identification rule (Section 4) and a family-uniform anchor encoding (Section 5), so that the settlement reference is written identically on every chain of a family and read back by a verifier that need not know the specific chain. No new cryptographic primitive is introduced: the reference is the JCS + SHA-256 content address defined by [CANONJCS].¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals.¶
settlement record: a JSON object stating the terms of a settled agentic payment (the settling parties, the network, the amount, and a nonce, at minimum). Its exact schema is out of scope; this document constrains only how a reference to it is anchored.¶
settlement_ref: the content-addressed reference to a settlement
record, of the form sha256:<lowercase-hex-64>, equal to "sha256:"
concatenated with the lowercase hexadecimal SHA-256 digest of the
JCS-canonical bytes of the settlement record. See Section 3.¶
canonical chain id: an unambiguous chain identifier of the form
<namespace>:<reference>, following the CAIP-2 convention [CAIP2]
(for example eip155:8453, bip122:000000000933ea01ad0ee984209779ba,
algorand:mainnet).¶
anchor value: the family-specific encoding of a settlement_ref
placed in a transaction field. See Section 5.¶
settlement family: one of evm, svm, avm, or generic,
determining which transaction field carries the anchor and how the
reference is encoded into it. See Section 5.1.¶
This document is additive to the agentic-payment receipt stack and introduces no new hashing primitive:¶
The canonicalisation discipline and the SHA-256-over-JCS content
address are specified in [CANONJCS]. settlement_ref is that
content address applied to a settlement record.¶
[RETENTIONCHAIN] defines an execution_ref (Section 7.10 of that
document) that is a distinct primitive: it is a 64-hex value with no
sha256: prefix, bound to a pre-payment decision. The
settlement_ref in this document is sha256:-prefixed and bound to
a settlement record. The two references belong to different layers
and MUST NOT be conflated; an implementation carrying both retains
their distinct encodings.¶
[PEF] envelopes settlement receipts for transport; a
settlement_ref MAY appear as a field within a transported receipt.
This document specifies the on-chain anchoring of the reference, not
its transport.¶
A settlement_ref is computed as:¶
settlement_ref = "sha256:" + hex(SHA256(JCS(settlement_record)))¶
where JCS is RFC 8785 [RFC8785] canonicalisation as disciplined by
[CANONJCS] (in particular, integer epoch-millisecond timestamps, not
RFC 3339 strings), SHA256 is FIPS 180-4 [FIPS180-4], and hex is
lowercase hexadecimal. The result is exactly 71 characters: the
7-character prefix sha256: followed by 64 hexadecimal characters.¶
The reference is a commitment to the settlement record. Any party holding the record recomputes the reference deterministically; any change to any field of the record changes the reference. The record itself is retained off-chain by the parties; only the reference is anchored.¶
Before a settlement is bound to a network, its chain name MUST be normalised to a canonical chain id (Section 1.1). The normalisation rule is:¶
If the name is a known alias, replace it with its canonical id.
Aliases are a deployment-configured mapping; examples are
base -> eip155:8453, ethereum -> eip155:1,
sepolia -> eip155:11155111, algorand -> algorand:mainnet,
solana -> solana:mainnet, stellar -> stellar:pubnet.¶
Otherwise, if the name already contains a : it is treated as a
canonical id and accepted as-is.¶
Otherwise the name is bare and unknown. It MUST be rejected as ambiguous. An implementation MUST NOT guess a network for a bare unknown name.¶
Rule 3 is load-bearing. A bare name such as bitcoin names a family
but not a network, so it MUST be rejected; a settlement on Bitcoin
MUST name a canonical id such as
bip122:000000000933ea01ad0ee984209779ba (testnet) or the
corresponding mainnet genesis-hash id. A negotiation between two
agents succeeds only on an exact, network-specific match; this
prevents a wrong-network settlement that a permissive name-match would
allow.¶
The settlement family (Section 1.1) is determined from the namespace of the canonical chain id:¶
| Namespace | Family | Examples |
|---|---|---|
eip155
|
evm
|
Ethereum, Base, Arc, and other EVM chains |
solana, eclipse
|
svm
|
Solana and SVM chains |
algorand, voi
|
avm
|
Algorand, VOI |
| any other namespace |
generic
|
Stellar, UTXO chains, Move chains, and any chain not otherwise mapped |
An unmapped namespace falls through to the generic family, so a
chain that has never been seen before still anchors, through the
generic encoding of Section 5.2. This is the property that makes the
scheme chain-agnostic: adding a chain requires no change to a verifier
that already reads the four family encodings.¶
Chains whose anchor field carries an opaque text string (an AVM transaction note, an SVM memo, a generic metadata field) encode the reference in a namespaced, self-describing form:¶
anchor_value = "algovoi-mesh:" + settlement_ref
= "algovoi-mesh:sha256:" + hex(SHA256(JCS(record)))
¶
The fixed prefix algovoi-mesh: makes the anchor greppable and
self-describing on-chain and identifies the value as a settlement
reference rather than unrelated memo text. A verifier strips the fixed
prefix to recover the settlement_ref. Implementations MUST anchor
this exact value and MUST NOT hand-roll a per-chain variant of the
prefix; a single anchor-value producer is the source of truth so the
form cannot drift per chain.¶
EVM chains carry the anchor in transaction calldata or a log topic, which is a 32-byte word. The word holds the raw digest only:¶
anchor_value = "0x" + hex(SHA256(JCS(record)))¶
The sha256: textual prefix is not carried on EVM: the field is a
fixed 32-byte word, and the digest is exactly 32 bytes, so the word
holds the digest and nothing else. This is the one family whose
encoding differs from Section 5.1, and it differs only because the
carrier is a fixed-width binary word rather than a text field. A
verifier reconstructs the settlement_ref by prefixing the recovered
32-byte word with sha256:.¶
On UTXO chains such as Bitcoin, the anchor is carried in an OP_RETURN
output. The standard relay limit for OP_RETURN data is 80 bytes. The
full 84-character hexadecimal form of the text encoding
(algovoi-mesh:sha256: plus 64 hex characters, 84 bytes) exceeds this
limit. Implementations therefore carry the raw digest rather than its
hex form:¶
anchor_bytes = b"algovoi-mesh:sha256:" + SHA256(JCS(record))¶
that is, the 20-byte ASCII prefix algovoi-mesh:sha256: followed by
the raw 32-byte digest, for a total of 52 bytes, within the 80-byte
limit. A verifier reads the OP_RETURN data, strips the 20-byte ASCII
prefix, and hex-encodes the trailing 32 bytes to recover the digest.¶
A chain in the generic family whose data carrier is a fixed-width
binary field rather than a text field (for example a Stellar
manage_data entry, whose value is at most 64 bytes) MAY carry the
raw 32-byte digest directly, as in Section 5.3 but without the ASCII
prefix where the field width does not admit it. The controlling
constraint is the carrier width; the reference recovered MUST be the
same sha256:-prefixed value in all cases.¶
A verifier holding the settlement record and the anchoring transaction confirms the anchor as follows:¶
Recompute settlement_ref from the retained record per Section 3.¶
Determine the settlement family from the canonical chain id per Section 4.1.¶
Read the anchor field for that family and decode the
settlement_ref per the applicable subsection of Section 5
(strip the text prefix, or hex-encode the raw 32-byte word or
OP_RETURN payload, and re-apply the sha256: prefix).¶
Compare the decoded reference to the recomputed reference. The anchor is confirmed if and only if they are byte-identical.¶
The comparison requires no contact with the settling party and no chain-specific logic beyond reading one field. A settlement whose record has been altered in any field yields a different recomputed reference and fails the comparison.¶
The anchor carries only the SHA-256 digest of the settlement record. Party identifiers, amounts, and any other record content appear only inside the off-chain record, never in the on-chain field. An observer of the chain learns that a settlement was anchored and its content address, not who settled or for how much. The record is disclosed only to a party that already holds it.¶
The ambiguity rejection of Section 4 (Rule 3) is a security control, not a convenience. Accepting a bare chain name and defaulting it to a network would allow a counterparty to induce a settlement anchored on a network the other party did not intend (for example a valueless testnet in place of mainnet, or the reverse). Implementations MUST reject bare unknown names rather than default them.¶
Because one family (EVM, Section 5.2) omits the textual prefix while the others carry it, a verifier MUST select the decoding by the settlement family derived from the canonical chain id, not by inspecting the field content. A field that does not decode to a 32-byte digest under the family's rule MUST be treated as absent or invalid, not reinterpreted under a different family's rule.¶
The reference is a SHA-256 digest, collision-resistant to currently known attacks. A verifier SHOULD reject an all-zero or otherwise degenerate anchor value, which indicates an implementation error rather than a valid empty settlement.¶
This document has no IANA actions. The algovoi-mesh: anchor prefix
is a vendor-scoped literal carried in application data fields and
requires no registry.¶
The following testnet transactions anchor a settlement_ref under the
encodings of Section 5 and were confirmed on public testnets. Each
exercises a distinct family and carrier. They are provided as
reference deployments; the digests are content addresses of test
settlement records and carry no production data.¶
| Network | Family / carrier | Transaction |
|---|---|---|
Ethereum Sepolia (eip155:11155111) |
evm / calldata |
0x8d94a77228a919eb1bacf5f04dc4e08bd8fa3812c8b25b0fdc8359ec8b09ac56 (block 11276567) |
Bitcoin testnet (bip122:...) |
generic / OP_RETURN |
d9b10aa3e821f75098a90418be05862d415617165f80ff7aaa101acdde735932 (block 5062123) |
| XRP Ledger testnet | generic / memo |
E5529C1A1D8DEA91AB1E05894C8CE3F0BCEE4546A514A0C4AC86ED0EC61EE978 (ledger 19081862) |
The EVM vector carries the raw 32-byte digest in calldata (Section
5.2); the Bitcoin vector carries the algovoi-mesh:sha256: prefix plus
the raw digest in a 52-byte OP_RETURN (Section 5.3); the XRPL vector
carries the algovoi-mesh:sha256:<hex> text form in a memo (Section
5.1).¶
The content-addressing and canonicalisation discipline on which this anchoring builds is specified in draft-hopley-x402-canonicalisation-jcs under the same authorship. The author acknowledges Anders Rundgren as editor of RFC 8785, the JSON Canonicalization Scheme on which the content address builds.¶