feat(python): add builder-code settlement metadata m

python/x402/changelog.d/+builder-code-settlement-metadata.feature.md

@@ -0,0 +1 @@
+Added facilitator-authored settlement metadata (`m`) to the builder-code ERC-8021 Schema 2 suffix. `DataSuffixContext` accepts `metadata`, the CBOR encoder and parser handle `m`, and encoding fails when the CBOR exceeds 65,535 bytes.

python/x402/extensions/__init__.py

@@ -51,6 +51,10 @@
     BuilderCodeFacilitatorConfig,
     BuilderCodeFacilitatorExtension,
     BuilderCodeResourceServerExtension,
+    BuilderCodeSuffixData,
+    DataSuffixContext,
+    SettlementMetadata,
+    SettlementMetadataValue,
     builder_code_resource_server_extension,
     declare_builder_code_extension,
     encode_builder_code_suffix,
@@ -191,6 +195,10 @@
     # Builder Code types
     "BuilderCodeExtensionData",
     "BuilderCodeFacilitatorConfig",
+    "BuilderCodeSuffixData",
+    "DataSuffixContext",
+    "SettlementMetadata",
+    "SettlementMetadataValue",
     # Builder Code CBOR encoding
     "encode_builder_code_suffix",
     "parse_builder_code_suffix_from_calldata",

python/x402/extensions/builder_code/README.md

@@ -61,7 +61,7 @@ facilitator.register_extension(
 )
 ```
 
-At settlement the extension reads `a` and `s` from the client payment payload, adds its configured `w`, appends its own `service_code` to `s` (deduped), CBOR-encodes the present fields, and returns the hex suffix for the settlement mechanism to append to calldata. It returns `None` when no attribution is present.
+At settlement the extension reads `a` and `s` from the client payment payload, adds its configured `w`, appends its own `service_code` to `s` (deduped), and encodes `m` when the settling mechanism supplies settlement metadata. Any `m` on the payload is ignored. It CBOR-encodes the present fields and returns the hex suffix for the settlement mechanism to append to calldata. It returns `None` when no attribution or metadata is present.
 
 Each side reserves its own slice of `s` (`MAX_CLIENT_SERVICE_CODES`, `MAX_SERVER_SERVICE_CODES`, `MAX_FACILITATOR_SERVICE_CODES`) so none can crowd out another; facilitators additionally truncate the echoed client+server codes to that combined budget as a defensive backstop against a malformed payload.
 
@@ -74,7 +74,7 @@ from x402.extensions.builder_code import parse_builder_code_suffix_from_calldata
 
 data = parse_builder_code_suffix_from_calldata(calldata)
 if data:
-    # BuilderCodeExtensionData(a="bc_my_service", w="bc_my_facilitator", s=["bc_my_client"])
+    # BuilderCodeSuffixData(a="bc_my_service", w="bc_my_facilitator", s=["bc_my_client"], m={"x402Example": 7})
     ...
 ```
 
@@ -94,7 +94,7 @@ Client extension that attaches the client's service code(s) as `s`. Constructor
 
 ### `encode_builder_code_suffix(data)` / `parse_builder_code_suffix_from_calldata(calldata)`
 
-Low-level CBOR helpers to encode a `BuilderCodeExtensionData` into an ERC-8021 suffix and to parse the suffix back out of settlement calldata.
+Low-level CBOR helpers to encode a `BuilderCodeSuffixData` (or `BuilderCodeExtensionData`) into an ERC-8021 suffix and to parse the suffix back out of settlement calldata. Encoding fails when the CBOR exceeds 65,535 bytes.
 
 ### Constants and types
 
@@ -105,7 +105,7 @@ Low-level CBOR helpers to encode a `BuilderCodeExtensionData` into an ERC-8021 s
 - `MAX_FACILITATOR_SERVICE_CODES` — `1` (facilitator's dedicated `s` reservation)
 - `MAX_SERVICE_CODES` — `11` (on-chain cap for `s`; the sum of each side's reservation)
 - `ERC_8021_MARKER`, `SCHEMA_2_ID`, `BUILDER_CODE_SCHEMA`
-- Types: `BuilderCodeExtensionData`, `BuilderCodeFacilitatorConfig`
+- Types: `BuilderCodeExtensionData`, `BuilderCodeSuffixData`, `BuilderCodeFacilitatorConfig`, `DataSuffixContext`, `SettlementMetadata`
 
 ## Related resources
 

python/x402/extensions/builder_code/__init__.py

@@ -61,6 +61,10 @@
     SCHEMA_2_ID,
     BuilderCodeExtensionData,
     BuilderCodeFacilitatorConfig,
+    BuilderCodeSuffixData,
+    DataSuffixContext,
+    SettlementMetadata,
+    SettlementMetadataValue,
 )
 
 __all__ = [
@@ -77,6 +81,10 @@
     # Types
     "BuilderCodeExtensionData",
     "BuilderCodeFacilitatorConfig",
+    "BuilderCodeSuffixData",
+    "DataSuffixContext",
+    "SettlementMetadata",
+    "SettlementMetadataValue",
     # CBOR encoding
     "encode_builder_code_suffix",
     "parse_builder_code_suffix_from_calldata",