10 KiB
Extension: builder-code
Summary
The builder-code extension enables on-chain attribution tracking for x402 payments by appending ERC-8021 Schema 2 builder codes to settlement transaction calldata. It attributes which application exposed the paid endpoint and which facilitator settled the payment.
This extension implements Schema 2 (CBOR-encoded) of ERC-8021. The m (custom metadata) and r (custom registries) fields are not supported.
ERC-8021 Schema 2 Overview
ERC-8021 defines a structured data suffix appended to transaction calldata for entity attribution. Schema 2 uses CBOR encoding for extensibility.
Suffix Format
The complete suffix appended to calldata is (ordered end of calldata backwards):
| Component | Size | Description |
|---|---|---|
ercMarker |
16 bytes | Constant identifier: 80218021802180218021802180218021 |
schemaId |
1 byte | 0x02 for Schema 2 |
cborLength |
2 bytes | Length of CBOR data (big-endian) |
cborData |
variable | CBOR-encoded map of attribution fields |
Wire order: [cborData][cborLength (2B)][schemaId (1B)][ercMarker (16B)]
CBOR Map Fields
| Key | Type | Description |
|---|---|---|
a |
string | App code — the application that exposed the paid endpoint |
w |
string | Wallet code — the facilitator that settled the payment on-chain |
s |
array of string | Service codes — clients and intermediaries that participated |
All fields are optional.
Builder Code Format
Codes must match the pattern ^[a-z0-9_]{1,32}$:
- Length: 1-32 characters
- Characters: lowercase alphanumeric and underscores only
PaymentRequired
The application declares its builder code per-route in the payment middleware configuration.
{
"x402Version": 2,
"error": "Payment required",
"accepts": [ ... ],
"extensions": {
"builder-code": {
"info": {
"a": "my_app"
},
"schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"a": {
"type": "string",
"pattern": "^[a-z0-9_]{1,32}$",
"description": "App builder code"
},
"w": {
"type": "string",
"pattern": "^[a-z0-9_]{1,32}$",
"description": "Wallet builder code"
},
"s": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z0-9_]{1,32}$"
},
"description": "Service builder codes"
}
},
"additionalProperties": false
}
}
}
}
PaymentPayload
The client echoes the builder code extension from PaymentRequired into its PaymentPayload, and may append its own code(s) to the s array.
{
"extensions": {
"builder-code": {
"a": "my_app",
"s": ["my_client"]
}
}
}
The w (wallet) field is not set by the client. It is added by the facilitator at settlement time.
Builder Code Fields
| Field | Set by | When | Description |
|---|---|---|---|
a |
Application | Per-route middleware configuration | Identifies the application exposing the paid endpoint |
w |
Facilitator | Settlement | Identifies the facilitator settling the payment on-chain |
s |
Client | Payment payload construction | Identifies the client(s) and intermediaries that participated |
Facilitator Behavior
When a facilitator settles a payment containing the builder-code extension, it:
- Verifies that
PaymentPayload.extensions["builder-code"].amatchesPaymentRequired.extensions["builder-code"].info.a - Reads
a(app code) ands(service codes) from the payment payload extensions - Adds its own builder code as the
w(wallet) field - Encodes the combined data as an ERC-8021 Schema 2 CBOR suffix
- Appends the suffix to the settlement transaction calldata
The facilitator's builder code is configured at initialization and validated against the same ^[a-z0-9_]{1,32}$ pattern.
Calldata Suffix Construction
The facilitator builds the suffix as follows:
- CBOR-encode a map containing all present fields (
a,s,w) - Compute
cborLengthas the byte length of the CBOR data (2 bytes, big-endian) - Append:
[cborData][cborLength][0x02][80218021802180218021802180218021] - Return the hex-encoded result for the settlement mechanism to append to calldata
Protocol Flow
Client (App) Resource Server Facilitator
| | |
1. |--- request ----------------->| |
| | |
2. |<-- 402 PaymentRequired ------| |
| extensions.builder-code: | |
| { a: "my_app" } | |
| | |
3. | (sign payment, echo extensions) |
| | |
4. |--- request + payment ------->| |
| extensions.builder-code: | |
| { a: "my_app", | |
| s: ["my_client"] } | |
| | |
5. | |--- verify/settle ----------->|
| | extensions.builder-code: |
| | { a: "my_app", |
| | s: ["my_client"] } |
| | |
6. | | Facilitator adds w, |
| | encodes CBOR suffix, |
| | appends to calldata: |
| | [cbor({a:"my_app", |
| | s:["my_client"], |
| | w:"my_fac"})] |
| | [cborLen][0x02][mark] |
| | |
7. |<-- 200 OK + resource data ---| |
| | |
Examples
Single App Attribution
Application declares its builder code:
{
"extensions": {
"builder-code": {
"info": {
"a": "bc_myapp"
},
"schema": { ... }
}
}
}
Settlement calldata suffix (hex):
{original_calldata} a161616862635f6d79617070 000c 02 80218021802180218021802180218021
Decoded:
- CBOR:
{"a": "bc_myapp"} - cborLength:
0x000c(12 bytes) - schemaId:
0x02 - marker:
80218021802180218021802180218021
App + Facilitator Attribution
After facilitator adds its w code at settlement:
{original_calldata} a261616862635f6d7961707061777062635f6d79666163696c697461746f72 001f 02 80218021802180218021802180218021
Decoded:
- CBOR:
{"a": "bc_myapp", "w": "bc_myfacilitator"} - cborLength:
0x001f(31 bytes) - schemaId:
0x02 - marker:
80218021802180218021802180218021
Validation
Builder Code Validation
All builder codes (a, w, and each entry in s) must:
- Match
^[a-z0-9_]{1,32}$ - Be 1-32 characters long
- Contain only lowercase letters, digits, and underscores
Invalid codes must be rejected at declaration time (application) and at construction time (facilitator). The facilitator validates each entry in s for format only — s is client self-reported and cannot be verified against any authoritative source.
App Code Echo Validation
The facilitator MUST verify that the a field echoed by the client in PaymentPayload.extensions["builder-code"] exactly matches the a field declared by the application in PaymentRequired.extensions["builder-code"].info. A mismatch indicates the client tampered with the attribution and the payment MUST be rejected.
Schema Validation
The schema field uses JSON Schema Draft 2020-12. Facilitators should validate info against the provided schema.
Parsing
Off-chain parsers can extract builder code attribution from settlement calldata using the ERC-8021 parsing algorithm:
- Extract the last 16 bytes and verify they match the ERC-8021 marker (
80218021...) - Extract the preceding byte as
schemaIdand verify it equals0x02 - Extract the preceding 2 bytes as
cborLength(big-endian) - Extract the preceding
cborLengthbytes ascborData - Decode
cborDataas a CBOR map - Read
a(app code),w(wallet code), ands(service codes array) from the map
Responsibilities
| Role | Responsibility |
|---|---|
| Application | Declares a (app code) per-route in the payment middleware configuration |
| Client | Echoes a from PaymentRequired; optionally populates s with its own service code(s) in PaymentPayload |
| Facilitator | Adds w (wallet code) at settlement, encodes the full CBOR suffix (a, s, w), appends to calldata |