uvd-x402-sdk 2.78.0 → 2.79.0

package/README.md

@@ -1351,6 +1351,50 @@ const body = buildVerifyRequestV2(
 > error that names no field. If you see it, check the envelope shape first, not
 > the fields inside it.
 
+### The top-level `x402Version` names the ENVELOPE
+
+`VerifyRequest.x402Version` is typed `1`, not `1 | 2`: it says which of the two
+shapes above the body has, and `VerifyRequest` **is** the v1 shape. The payer's
+own version stays where the payer put it, in `paymentPayload.x402Version`, and
+the SDK never rewrites it.
+
+```typescript
+// A buyer that declares v2 while carrying plain network names — legal, and what
+// a 402 advertising CAIP-2 invites.
+const body = buildVerifyRequest({ x402Version: 2, scheme: 'exact', network: 'base', payload }, reqs);
+
+body.x402Version;                 // 1  — the envelope is v1
+body.paymentPayload.x402Version;  // 2  — the payer's marker, untouched
+```
+
+`resolveEnvelopeVersion` (and therefore the `'auto'` default) accepts a **v2
+payload** as well as a v1 header. A v2 payload has no top-level `network` at all
+— v2 moved the chain id into `accepted` — so `auto` reads it from there. Before
+**2.79.0** it read only the top level and threw
+`Cannot read properties of undefined` on exactly that shape, which is why
+integrators were pinning `x402Version` instead of using the default.
+
+A network with **no CAIP-2 form** cannot travel in a v2 body at all, so pinning
+version 2 on one throws instead of building it — `xrpl-mainnet` is the case: its
+v1 string *is* its network id. `auto` leaves those on v1, where they work, so
+you only reach the throw by pinning. It names the network and the escape, which
+the facilitator's `400` (`data did not match any variant of untagged enum`) does
+not.
+
+Until **2.79.0** the top level inherited `paymentHeader.x402Version`, so that
+call emitted a body declaring `2` around a `paymentRequirements` — a v1 shape.
+It was served correctly then and it is served correctly now: the facilitator's
+envelope enum is untagged and matches on shape. But the facilitator already
+reads that marker for one thing — choosing the hint in its `400`:
+
+> `This body declares `x402Version: 2`. x402 v2 is a JSON object with
+> `paymentPayload`, `resource` and `accepted`…`
+
+So the first time such a body failed for an unrelated reason, the diagnosis sent
+you to fix the wrong shape. If you were constructing a `VerifyRequest` by hand
+with a `1 | 2` variable, that no longer type-checks — write `1`, or use
+`buildVerifyRequestForVersion` and let it pick.
+
 ## Metrics and history (`getStats` / `getTransactions`)
 
 ```typescript

package/dist/backend/index.d.mts

@@ -234,18 +234,30 @@ interface PaymentRequirements {
     extra?: unknown;
 }
 /**
- * Verify request body for the facilitator /verify endpoint
+ * Verify request body for the facilitator /verify endpoint -- the **v1**
+ * envelope. {@link VerifyRequestV2} is the other one.
  */
 interface VerifyRequest {
-    x402Version: X402Version;
+    /**
+     * Always `1`: this marker names the ENVELOPE, and this envelope is v1.
+     *
+     * Narrowed from `X402Version` on 2026-09-04. A `VerifyRequest` carrying `2`
+     * was always an uninhabitable value -- a body declaring v2 while shaped as
+     * v1 -- and typing it as `1 | 2` is what let the payer's marker be copied in
+     * here. The payer's version lives in `paymentPayload.x402Version`, which is
+     * still the full union.
+     */
+    x402Version: 1;
     paymentPayload: X402Header;
     paymentRequirements: PaymentRequirements;
 }
 /**
- * Settle request body for the facilitator /settle endpoint
+ * Settle request body for the facilitator /settle endpoint -- the **v1**
+ * envelope. {@link SettleRequestV2} is the other one.
  */
 interface SettleRequest {
-    x402Version: X402Version;
+    /** Always `1` -- see {@link VerifyRequest.x402Version}. */
+    x402Version: 1;
     paymentPayload: X402Header;
     paymentRequirements: PaymentRequirements;
 }
@@ -551,6 +563,14 @@ declare function toResourceInfoV2(requirements: PaymentRequirements): ResourceIn
  * `extra` is carried through when present -- it is where the EIP-712 domain
  * `name`/`version` live for tokens the facilitator does not know by address, so
  * dropping it breaks EURC and the bridged USDCs.
+ *
+ * @throws If `requirements.network` has NO CAIP-2 form. `chainToCAIP2` answers
+ * with the name unchanged when it does not know a chain, and XRPL maps to
+ * itself on purpose -- its v1 string IS its network id. Passing that through
+ * would put a plain name inside a v2 body, which is a measured 400 (the same
+ * `no variant matched` that names no field). Only reachable by PINNING version
+ * 2 on such a network; `auto` leaves them on v1, where they work. Failing here
+ * names the network and the fix, which a 400 from the facilitator does not.
  */
 declare function toPaymentRequirementsV2(requirements: PaymentRequirements): PaymentRequirementsV2;
 /**
@@ -561,24 +581,48 @@ declare function toPaymentRequirementsV2(requirements: PaymentRequirements): Pay
  *
  * **Auto keys off CAIP-2, NOT off `paymentHeader.x402Version`,** and that is a
  * measured decision rather than a stylistic one. The facilitator's envelope enum
- * is untagged: it matches on SHAPE and ignores the version marker. Measured
- * against production on 2026-09-03:
+ * is untagged: it matches on SHAPE and ignores the version marker.
+ *
+ * Re-measured against `https://facilitator.ultravioletadao.xyz/verify` on
+ * **2026-09-04** with a fabricated signature. The signature never verifies, so
+ * every row is an HTTP 400 and the STATUS discriminates nothing -- what does is
+ * the error code. `invalid_request_body` means the facilitator could not
+ * deserialize the body; `contract_call_failed` means it read the body, resolved
+ * the chain and got as far as the on-chain call, i.e. the envelope was fine.
  *
  * | payload network | requirements network | v1 envelope today |
  * |-----------------|----------------------|-------------------|
- * | `base`          | `base`               | **200**           |
- * | `base` (header says `x402Version: 2`) | `base` | **200**  |
- * | `eip155:8453`   | `base`               | 400               |
- * | `base`          | `eip155:8453`        | 400               |
- * | `eip155:8453`   | `eip155:8453`        | 400 (`unknown variant \`eip155:8453\``) |
- *
- * So a header that merely *declares* version 2 while carrying plain names is
- * being served correctly today. Upgrading it on the strength of the marker would
- * change a call that works -- the one thing this must not do. Every CAIP-2
- * combination, by contrast, is already a hard 400, so switching those to v2
- * cannot regress anyone: it can only turn a failure into a payment.
- */
-declare function resolveEnvelopeVersion(paymentHeader: X402Header, requirements: PaymentRequirements, requested?: X402Version | 'auto'): X402Version;
+ * | `base`          | `base`               | understood        |
+ * | `base` (header says `x402Version: 2`) | `base` | understood |
+ * | `eip155:8453`   | `base`               | understood        |
+ * | `base`          | `eip155:8453`        | understood        |
+ * | `eip155:8453`   | `eip155:8453`        | understood        |
+ *
+ * **The last three rows used to be a hard 400** (`unknown variant
+ * \`eip155:8453\``) when this function was written on 2026-09-03. The
+ * facilitator has since taught the v1 envelope to read CAIP-2, so the original
+ * argument for this rule -- "every CAIP-2 combination is already a 400, so
+ * upgrading them cannot regress anyone" -- **is no longer true**. The rule is
+ * unchanged; three other reasons hold it up:
+ *
+ * 1. A CAIP-2 network on the wire means the 402 that produced it advertised v2.
+ *    Answering in v2 is speaking the protocol the seller announced.
+ * 2. v2-with-CAIP-2 is the only shape BOTH generations of the facilitator
+ *    accept. v1-with-CAIP-2 is a hard 400 on any build older than 2026-09-04,
+ *    so choosing v1 there is what breaks against a self-hosted or pinned one.
+ * 3. The Python SDK resolves the identical rule, so the same wire produces the
+ *    same body in both SDKs -- pinned by phase 6 of `npm run test:xlang`.
+ *
+ * And the marker still decides nothing: row 2 above is served correctly today,
+ * so upgrading on the strength of it would change a call that works.
+ *
+ * The negative half of that measurement, without which "understood" proves
+ * nothing -- the same run, bodies broken on purpose, all three
+ * `invalid_request_body`: a v2 body carrying a plain network name, one with
+ * `resource` as a bare string, and one with `accepted` removed. A well-formed
+ * v2 body with CAIP-2 reached `contract_call_failed` like the rows above.
+ */
+declare function resolveEnvelopeVersion(paymentHeader: X402Header | PaymentPayloadV2, requirements: PaymentRequirements, requested?: X402Version | 'auto'): X402Version;
 /**
  * Build a `/verify` body in whichever envelope `version` names.
  *

package/dist/backend/index.d.ts

@@ -234,18 +234,30 @@ interface PaymentRequirements {
     extra?: unknown;
 }
 /**
- * Verify request body for the facilitator /verify endpoint
+ * Verify request body for the facilitator /verify endpoint -- the **v1**
+ * envelope. {@link VerifyRequestV2} is the other one.
  */
 interface VerifyRequest {
-    x402Version: X402Version;
+    /**
+     * Always `1`: this marker names the ENVELOPE, and this envelope is v1.
+     *
+     * Narrowed from `X402Version` on 2026-09-04. A `VerifyRequest` carrying `2`
+     * was always an uninhabitable value -- a body declaring v2 while shaped as
+     * v1 -- and typing it as `1 | 2` is what let the payer's marker be copied in
+     * here. The payer's version lives in `paymentPayload.x402Version`, which is
+     * still the full union.
+     */
+    x402Version: 1;
     paymentPayload: X402Header;
     paymentRequirements: PaymentRequirements;
 }
 /**
- * Settle request body for the facilitator /settle endpoint
+ * Settle request body for the facilitator /settle endpoint -- the **v1**
+ * envelope. {@link SettleRequestV2} is the other one.
  */
 interface SettleRequest {
-    x402Version: X402Version;
+    /** Always `1` -- see {@link VerifyRequest.x402Version}. */
+    x402Version: 1;
     paymentPayload: X402Header;
     paymentRequirements: PaymentRequirements;
 }
@@ -551,6 +563,14 @@ declare function toResourceInfoV2(requirements: PaymentRequirements): ResourceIn
  * `extra` is carried through when present -- it is where the EIP-712 domain
  * `name`/`version` live for tokens the facilitator does not know by address, so
  * dropping it breaks EURC and the bridged USDCs.
+ *
+ * @throws If `requirements.network` has NO CAIP-2 form. `chainToCAIP2` answers
+ * with the name unchanged when it does not know a chain, and XRPL maps to
+ * itself on purpose -- its v1 string IS its network id. Passing that through
+ * would put a plain name inside a v2 body, which is a measured 400 (the same
+ * `no variant matched` that names no field). Only reachable by PINNING version
+ * 2 on such a network; `auto` leaves them on v1, where they work. Failing here
+ * names the network and the fix, which a 400 from the facilitator does not.
  */
 declare function toPaymentRequirementsV2(requirements: PaymentRequirements): PaymentRequirementsV2;
 /**
@@ -561,24 +581,48 @@ declare function toPaymentRequirementsV2(requirements: PaymentRequirements): Pay
  *
  * **Auto keys off CAIP-2, NOT off `paymentHeader.x402Version`,** and that is a
  * measured decision rather than a stylistic one. The facilitator's envelope enum
- * is untagged: it matches on SHAPE and ignores the version marker. Measured
- * against production on 2026-09-03:
+ * is untagged: it matches on SHAPE and ignores the version marker.
+ *
+ * Re-measured against `https://facilitator.ultravioletadao.xyz/verify` on
+ * **2026-09-04** with a fabricated signature. The signature never verifies, so
+ * every row is an HTTP 400 and the STATUS discriminates nothing -- what does is
+ * the error code. `invalid_request_body` means the facilitator could not
+ * deserialize the body; `contract_call_failed` means it read the body, resolved
+ * the chain and got as far as the on-chain call, i.e. the envelope was fine.
  *
  * | payload network | requirements network | v1 envelope today |
  * |-----------------|----------------------|-------------------|
- * | `base`          | `base`               | **200**           |
- * | `base` (header says `x402Version: 2`) | `base` | **200**  |
- * | `eip155:8453`   | `base`               | 400               |
- * | `base`          | `eip155:8453`        | 400               |
- * | `eip155:8453`   | `eip155:8453`        | 400 (`unknown variant \`eip155:8453\``) |
- *
- * So a header that merely *declares* version 2 while carrying plain names is
- * being served correctly today. Upgrading it on the strength of the marker would
- * change a call that works -- the one thing this must not do. Every CAIP-2
- * combination, by contrast, is already a hard 400, so switching those to v2
- * cannot regress anyone: it can only turn a failure into a payment.
- */
-declare function resolveEnvelopeVersion(paymentHeader: X402Header, requirements: PaymentRequirements, requested?: X402Version | 'auto'): X402Version;
+ * | `base`          | `base`               | understood        |
+ * | `base` (header says `x402Version: 2`) | `base` | understood |
+ * | `eip155:8453`   | `base`               | understood        |
+ * | `base`          | `eip155:8453`        | understood        |
+ * | `eip155:8453`   | `eip155:8453`        | understood        |
+ *
+ * **The last three rows used to be a hard 400** (`unknown variant
+ * \`eip155:8453\``) when this function was written on 2026-09-03. The
+ * facilitator has since taught the v1 envelope to read CAIP-2, so the original
+ * argument for this rule -- "every CAIP-2 combination is already a 400, so
+ * upgrading them cannot regress anyone" -- **is no longer true**. The rule is
+ * unchanged; three other reasons hold it up:
+ *
+ * 1. A CAIP-2 network on the wire means the 402 that produced it advertised v2.
+ *    Answering in v2 is speaking the protocol the seller announced.
+ * 2. v2-with-CAIP-2 is the only shape BOTH generations of the facilitator
+ *    accept. v1-with-CAIP-2 is a hard 400 on any build older than 2026-09-04,
+ *    so choosing v1 there is what breaks against a self-hosted or pinned one.
+ * 3. The Python SDK resolves the identical rule, so the same wire produces the
+ *    same body in both SDKs -- pinned by phase 6 of `npm run test:xlang`.
+ *
+ * And the marker still decides nothing: row 2 above is served correctly today,
+ * so upgrading on the strength of it would change a call that works.
+ *
+ * The negative half of that measurement, without which "understood" proves
+ * nothing -- the same run, bodies broken on purpose, all three
+ * `invalid_request_body`: a v2 body carrying a plain network name, one with
+ * `resource` as a bare string, and one with `accepted` removed. A well-formed
+ * v2 body with CAIP-2 reached `contract_call_failed` like the rows above.
+ */
+declare function resolveEnvelopeVersion(paymentHeader: X402Header | PaymentPayloadV2, requirements: PaymentRequirements, requested?: X402Version | 'auto'): X402Version;
 /**
  * Build a `/verify` body in whichever envelope `version` names.
  *

package/dist/backend/index.js

@@ -1261,7 +1261,23 @@ function buildPaymentRequirements(options) {
 }
 function buildVerifyRequest(paymentHeader, requirements) {
   return {
-    x402Version: paymentHeader.x402Version,
+    // The literal `1` names THIS ENVELOPE, not the payer's header. Echoing
+    // `paymentHeader.x402Version` here -- what this did until 2026-09-04 --
+    // let a buyer who declared `2` produce a body that says "2" while carrying
+    // `paymentRequirements`, which is the v1 shape. The facilitator serves it
+    // anyway because its envelope enum is untagged and matches on shape, so
+    // nothing broke; but it ALREADY picks the hint in its 400 off this marker:
+    //
+    //   "This body declares `x402Version: 2`. x402 v2 is a JSON object with
+    //    `paymentPayload`, `resource` and `accepted`..."
+    //
+    // So the day that body fails for any other reason, the diagnosis sends the
+    // integrator to document the wrong shape. That inversion -- being told to
+    // fix the fields when the wrapper is what is wrong -- is what cost two
+    // teams a day. The payer's own marker survives untouched inside
+    // `paymentPayload`, where it belongs: it describes the payment, not the
+    // envelope carrying it.
+    x402Version: 1,
     paymentPayload: paymentHeader,
     paymentRequirements: requirements
   };
@@ -1284,13 +1300,21 @@ function buildSettleRequestV2(payload, resource, accepted) {
 }
 function buildSettleRequest(paymentHeader, requirements) {
   return {
-    x402Version: paymentHeader.x402Version,
+    // `1` for the same reason as {@link buildVerifyRequest}: it names the
+    // envelope, and `/settle` takes the same body as `/verify`.
+    x402Version: 1,
     paymentPayload: paymentHeader,
     paymentRequirements: requirements
   };
 }
 function isCaip2Network(network) {
-  return network.includes(":");
+  return typeof network === "string" && network.includes(":");
+}
+function networkOfPayload(payload) {
+  const top = payload.network;
+  if (typeof top === "string") return top;
+  const accepted = payload.accepted;
+  return typeof accepted?.network === "string" ? accepted.network : void 0;
 }
 function toResourceInfoV2(requirements) {
   return {
@@ -1300,9 +1324,15 @@ function toResourceInfoV2(requirements) {
   };
 }
 function toPaymentRequirementsV2(requirements) {
+  const network = isCaip2Network(requirements.network) ? requirements.network : chainToCAIP2(requirements.network);
+  if (!isCaip2Network(network)) {
+    throw new Error(
+      `Network '${requirements.network}' has no CAIP-2 form, so it cannot travel in the x402 v2 envelope. Use x402Version: 1 for this network.`
+    );
+  }
   return {
     scheme: requirements.scheme,
-    network: isCaip2Network(requirements.network) ? requirements.network : chainToCAIP2(requirements.network),
+    network,
     asset: requirements.asset,
     amount: requirements.maxAmountRequired,
     payTo: requirements.payTo,
@@ -1315,7 +1345,7 @@ function resolveEnvelopeVersion(paymentHeader, requirements, requested = "auto")
   if (requested !== "auto") {
     return requested;
   }
-  return isCaip2Network(paymentHeader.network) || isCaip2Network(requirements.network) ? 2 : 1;
+  return isCaip2Network(networkOfPayload(paymentHeader)) || isCaip2Network(requirements.network) ? 2 : 1;
 }
 function buildVerifyRequestForVersion(paymentHeader, requirements, version) {
   if (version === 2) {