thirdweb 5.121.1 → 5.121.3

package/src/x402/fetchWithPayment.ts

@@ -4,7 +4,7 @@ import { getAddress } from "../utils/address.js";
 import type { AsyncStorage } from "../utils/storage/AsyncStorage.js";
 import { webLocalStorage } from "../utils/storage/webStorage.js";
 import type { Wallet } from "../wallets/interfaces/wallet.js";
-import { safeBase64Decode } from "./encode.js";
+import { base64DecodeUtf8 } from "./encode.js";
 import {
   getPaymentRequestHeader,
   getPaymentResponseHeader,
@@ -13,8 +13,9 @@ import { clearPermitSignatureFromCache } from "./permitSignatureStorage.js";
 import {
   extractEvmChainId,
   networkToCaip2ChainId,
+  normalizePaymentRequirements,
+  parsePaymentRequired,
   type RequestedPaymentRequirements,
-  RequestedPaymentRequirementsSchema,
 } from "./schemas.js";
 import { createPaymentHeader } from "./sign.js";
 import { x402Version as defaultX402Version } from "./types.js";
@@ -33,7 +34,7 @@ import { x402Version as defaultX402Version } from "./types.js";
  * @param fetch - The fetch function to wrap (typically globalThis.fetch)
  * @param client - The thirdweb client used to access RPC infrastructure
  * @param wallet - The wallet used to sign payment messages
- * @param maxValue - The maximum allowed payment amount in base units
+ * @param maxValue - The maximum allowed payment amount in base units. `0n` only allows zero-amount payments
  * @returns A wrapped fetch function that handles 402 responses automatically
  *
  * @example
@@ -64,6 +65,10 @@ export function wrapFetchWithPayment(
   wallet: Wallet,
   options?: {
     maxValue?: bigint;
+    /**
+     * Selects the payment requirement to pay. Return one of the provided requirements;
+     * the returned requirement is validated again before payment.
+     */
     paymentRequirementsSelector?: (
       paymentRequirements: RequestedPaymentRequirements[],
     ) => RequestedPaymentRequirements | undefined;
@@ -81,49 +86,25 @@ export function wrapFetchWithPayment(
       return response;
     }
 
-    let x402Version: number;
-    let parsedPaymentRequirements: RequestedPaymentRequirements[];
-    let error: string | undefined;
+    const initParams = init || {};
+
+    if ((initParams as { __is402Retry?: boolean }).__is402Retry) {
+      throw new Error("Payment already attempted");
+    }
 
     // Check payment-required header first before falling back to JSON body
     const paymentRequiredHeader = response.headers.get("payment-required");
-    if (paymentRequiredHeader) {
-      const decoded = safeBase64Decode(paymentRequiredHeader);
-      const parsed = JSON.parse(decoded) as {
-        x402Version: number;
-        accepts: unknown[];
-        error?: string;
-      };
-      if (!Array.isArray(parsed.accepts)) {
-        throw new Error(
-          `402 response has no usable x402 payment requirements. ${parsed.error ?? ""}`,
-        );
-      }
-
-      x402Version = parsed.x402Version ?? defaultX402Version;
-      parsedPaymentRequirements = parsed.accepts.map((x) =>
-        RequestedPaymentRequirementsSchema.parse(x),
-      );
-      error = parsed.error;
-    } else {
-      const body = (await response.json()) as {
-        x402Version: number;
-        accepts: unknown[];
-        error?: string;
-      };
-
-      if (!Array.isArray(body.accepts)) {
-        throw new Error(
-          `402 response has no usable x402 payment requirements. ${body.error ?? ""}`,
-        );
-      }
+    const paymentRequired: unknown = paymentRequiredHeader
+      ? JSON.parse(base64DecodeUtf8(paymentRequiredHeader))
+      : await response.json();
 
-      x402Version = body.x402Version ?? defaultX402Version;
-      parsedPaymentRequirements = body.accepts.map((x) =>
-        RequestedPaymentRequirementsSchema.parse(x),
-      );
-      error = body.error;
-    }
+    const parsed = parsePaymentRequired(paymentRequired, getRequestUrl(input));
+    const x402Version = parsed.x402Version ?? defaultX402Version;
+    const error = parsed.error;
+    const normalizedPaymentRequirements = parsed.accepts;
+    const parsedPaymentRequirements = normalizedPaymentRequirements.map(
+      (x) => x.requirements,
+    );
 
     const account = wallet.getAccount();
     let chain = wallet.getChain();
@@ -133,7 +114,7 @@ export function wrapFetchWithPayment(
         "Wallet not connected. Please connect your wallet to continue.",
       );
     }
-    const selectedPaymentRequirements = options?.paymentRequirementsSelector
+    const selected = options?.paymentRequirementsSelector
       ? options.paymentRequirementsSelector(parsedPaymentRequirements)
       : defaultPaymentRequirementsSelector(
           parsedPaymentRequirements,
@@ -141,14 +122,22 @@ export function wrapFetchWithPayment(
           error,
         );
 
-    if (!selectedPaymentRequirements) {
+    if (!selected) {
       throw new Error(
         `No suitable payment requirements found for chain ${chain.id}. ${error}`,
       );
     }
 
+    const { requirements: selectedPaymentRequirements } =
+      normalizePaymentRequirements(selected, {
+        resourceUrl: parsed.resourceUrl,
+      });
+    const acceptedRequirement =
+      normalizedPaymentRequirements.find((x) => x.requirements === selected)
+        ?.raw ?? selected;
+
     if (
-      options?.maxValue &&
+      options?.maxValue !== undefined &&
       BigInt(selectedPaymentRequirements.maxAmountRequired) > options.maxValue
     ) {
       throw new Error(
@@ -176,23 +165,27 @@ export function wrapFetchWithPayment(
       }
     }
 
+    const storage = options?.storage ?? webLocalStorage;
     const paymentHeader = await createPaymentHeader(
       client,
       account,
       selectedPaymentRequirements,
       x402Version,
-      options?.storage ?? webLocalStorage,
+      storage,
+      {
+        accepted: acceptedRequirement,
+        resource: parsed.resource ?? {
+          url: selectedPaymentRequirements.resource,
+          description: selectedPaymentRequirements.description,
+          mimeType: selectedPaymentRequirements.mimeType,
+        },
+      },
+      options?.maxValue,
     );
 
     const paymentRequestHeaderName = getPaymentRequestHeader(x402Version);
     const paymentResponseHeaderName = getPaymentResponseHeader(x402Version);
 
-    const initParams = init || {};
-
-    if ((initParams as { __is402Retry?: boolean }).__is402Retry) {
-      throw new Error("Payment already attempted");
-    }
-
     const newInit = {
       ...initParams,
       headers: {
@@ -206,8 +199,8 @@ export function wrapFetchWithPayment(
     const secondResponse = await fetch(input, newInit);
 
     // If payment was rejected (still 402), clear cached signature
-    if (secondResponse.status === 402 && options?.storage) {
-      await clearPermitSignatureFromCache(options.storage, {
+    if (secondResponse.status === 402) {
+      await clearPermitSignatureFromCache(storage, {
         chainId: paymentChainId,
         asset: selectedPaymentRequirements.asset,
         owner: getAddress(account.address),
@@ -219,6 +212,31 @@ export function wrapFetchWithPayment(
   };
 }
 
+/**
+ * Resolves the absolute URL of a fetch input, if it can be determined.
+ * @internal
+ */
+export function getRequestUrl(input: RequestInfo | URL): string | undefined {
+  const url =
+    typeof input === "string"
+      ? input
+      : input instanceof URL
+        ? input.href
+        : (input as Partial<Request> | undefined)?.url;
+  if (typeof url !== "string") {
+    return undefined;
+  }
+  try {
+    const base =
+      typeof globalThis.location !== "undefined"
+        ? globalThis.location.href
+        : undefined;
+    return new URL(url, base).toString();
+  } catch {
+    return undefined;
+  }
+}
+
 function defaultPaymentRequirementsSelector(
   paymentRequirements: RequestedPaymentRequirements[],
   chainId: number,

package/src/x402/schemas.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import {
+  normalizePaymentRequirements,
+  parsePaymentRequirementsForDisplay,
+} from "./schemas.js";
+
+const PAY_TO = "0x1234567890123456789012345678901234567890";
+const ASSET = "0x0000000000000000000000000000000000000001";
+const REQUEST_URL = "https://api.example.com/paid";
+
+const canonicalV2Requirement = {
+  scheme: "exact",
+  network: "eip155:8453",
+  amount: "1000",
+  payTo: PAY_TO,
+  maxTimeoutSeconds: 300,
+  asset: ASSET,
+  extra: { name: "Test Token", version: "1" },
+};
+
+describe("normalizePaymentRequirements", () => {
+  it("canonicalises the amount", () => {
+    const { requirements } = normalizePaymentRequirements(
+      { ...canonicalV2Requirement, amount: "0100" },
+      { resourceUrl: REQUEST_URL },
+    );
+    expect(requirements.maxAmountRequired).toBe("100");
+  });
+
+  it("accepts amount and maxAmountRequired with the same value", () => {
+    const { requirements } = normalizePaymentRequirements(
+      { ...canonicalV2Requirement, amount: "0100", maxAmountRequired: "100" },
+      { resourceUrl: REQUEST_URL },
+    );
+    expect(requirements.maxAmountRequired).toBe("100");
+  });
+
+  it.each([
+    { amount: "1", maxAmountRequired: "1000000000" },
+    { amount: "1000000000", maxAmountRequired: "1" },
+  ])("rejects mismatched amounts (%j)", (amounts) => {
+    expect(() =>
+      normalizePaymentRequirements(
+        { ...canonicalV2Requirement, ...amounts },
+        { resourceUrl: REQUEST_URL },
+      ),
+    ).toThrow("do not match");
+  });
+
+  it("keeps the raw requirement", () => {
+    const raw = { ...canonicalV2Requirement };
+    expect(
+      normalizePaymentRequirements(raw, { resourceUrl: REQUEST_URL }).raw,
+    ).toBe(raw);
+  });
+});
+
+describe("parsePaymentRequirementsForDisplay", () => {
+  it("parses a canonical v2 requirement without a resource using the request URL", () => {
+    expect(
+      parsePaymentRequirementsForDisplay(
+        { x402Version: 2, accepts: [canonicalV2Requirement] },
+        REQUEST_URL,
+      ),
+    ).toEqual([
+      expect.objectContaining({
+        network: "eip155:8453",
+        asset: ASSET,
+        maxAmountRequired: "1000",
+        resource: REQUEST_URL,
+      }),
+    ]);
+  });
+
+  it("prefers the top-level resource URL", () => {
+    expect(
+      parsePaymentRequirementsForDisplay(
+        {
+          x402Version: 2,
+          resource: { url: "https://api.example.com/resource" },
+          accepts: [canonicalV2Requirement],
+        },
+        REQUEST_URL,
+      ),
+    ).toEqual([
+      expect.objectContaining({ resource: "https://api.example.com/resource" }),
+    ]);
+  });
+
+  it("skips invalid entries", () => {
+    const requirements = parsePaymentRequirementsForDisplay(
+      {
+        x402Version: 2,
+        accepts: [
+          { ...canonicalV2Requirement, amount: "1", maxAmountRequired: "2" },
+          { ...canonicalV2Requirement, amount: "1e3" },
+          { ...canonicalV2Requirement, network: "eip155:1" },
+        ],
+      },
+      REQUEST_URL,
+    );
+    expect(requirements).toHaveLength(1);
+    expect(requirements[0]?.network).toBe("eip155:1");
+  });
+
+  it.each([[undefined], [null], [{}], [{ accepts: "invalid" }]])(
+    "returns no requirements for %j",
+    (paymentRequired) => {
+      expect(
+        parsePaymentRequirementsForDisplay(paymentRequired, REQUEST_URL),
+      ).toEqual([]);
+    },
+  );
+
+  it("returns no requirements when no resource URL can be resolved", () => {
+    expect(
+      parsePaymentRequirementsForDisplay({
+        x402Version: 2,
+        accepts: [canonicalV2Requirement],
+      }),
+    ).toEqual([]);
+  });
+});

package/src/x402/schemas.ts

@@ -23,7 +23,12 @@ const RequestedPaymentPayloadSchema = PaymentPayloadSchema.extend({
 
 export type RequestedPaymentPayload = z.infer<
   typeof RequestedPaymentPayloadSchema
->;
+> & {
+  /** x402 v2: the payment requirement accepted by the client, as sent by the server */
+  accepted?: Record<string, unknown>;
+  /** x402 v2: the resource being paid for */
+  resource?: Record<string, unknown>;
+};
 export type UnsignedPaymentPayload = Omit<
   RequestedPaymentPayload,
   "payload"
@@ -31,16 +36,204 @@ export type UnsignedPaymentPayload = Omit<
   payload: Omit<ExactEvmPayload, "signature"> & { signature: undefined };
 };
 
-export const RequestedPaymentRequirementsSchema =
-  PaymentRequirementsSchema.extend({
-    network: FacilitatorNetworkSchema,
-    scheme: PaymentSchemeSchema,
-  });
+const RequestedPaymentRequirementsSchema = PaymentRequirementsSchema.extend({
+  network: FacilitatorNetworkSchema,
+  scheme: PaymentSchemeSchema,
+});
 
 export type RequestedPaymentRequirements = z.infer<
   typeof RequestedPaymentRequirementsSchema
 >;
 
+const MAX_UINT256 = 2n ** 256n - 1n;
+const ATOMIC_AMOUNT_REGEX = /^\d{1,78}$/;
+
+/**
+ * Returns true if the value is a base-10 integer string that fits in a uint256.
+ * @internal
+ */
+export function isAtomicAmount(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    ATOMIC_AMOUNT_REGEX.test(value) &&
+    BigInt(value) <= MAX_UINT256
+  );
+}
+
+/**
+ * Reads an amount field and returns it in canonical form (no leading zeros).
+ */
+function readAtomicAmount(
+  requirement: Record<string, unknown>,
+  field: "amount" | "maxAmountRequired",
+): string | undefined {
+  const value = requirement[field];
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!isAtomicAmount(value)) {
+    throw new Error(
+      `Invalid payment requirements: ${field} must be an integer string in base units`,
+    );
+  }
+  return BigInt(value).toString();
+}
+
+/**
+ * Payment requirements normalised from a server 402 response.
+ * @internal
+ */
+type NormalizedPaymentRequirements = {
+  /** The normalised requirement */
+  requirements: RequestedPaymentRequirements;
+  /** The requirement exactly as sent by the server */
+  raw: Record<string, unknown>;
+};
+
+/**
+ * Extracts the top-level resource object of a 402 payment required response, if any.
+ */
+function getPaymentRequiredResource(
+  paymentRequired: unknown,
+): Record<string, unknown> | undefined {
+  if (!isRecord(paymentRequired)) {
+    return undefined;
+  }
+  const resource = paymentRequired.resource;
+  if (isRecord(resource) && typeof resource.url === "string") {
+    return resource;
+  }
+  return undefined;
+}
+
+/**
+ * Normalises a payment requirement from a 402 response (x402 v1, v2, or v2 envelopes with v1 requirements).
+ *
+ * @param requirement - The raw payment requirement
+ * @param context - Fallback values for fields that v2 moves out of the requirement
+ * @returns The normalised requirement and the raw requirement
+ * @throws If the amount is missing, malformed, or ambiguous, or the requirement is otherwise invalid
+ * @internal
+ */
+export function normalizePaymentRequirements(
+  requirement: unknown,
+  context: { resourceUrl?: string } = {},
+): NormalizedPaymentRequirements {
+  if (!isRecord(requirement)) {
+    throw new Error("Invalid payment requirements: expected an object");
+  }
+
+  const amount = readAtomicAmount(requirement, "amount");
+  const maxAmountRequired = readAtomicAmount(requirement, "maxAmountRequired");
+  if (
+    amount !== undefined &&
+    maxAmountRequired !== undefined &&
+    amount !== maxAmountRequired
+  ) {
+    throw new Error(
+      `Invalid payment requirements: amount (${amount}) and maxAmountRequired (${maxAmountRequired}) do not match`,
+    );
+  }
+  const normalizedAmount = amount ?? maxAmountRequired;
+  if (normalizedAmount === undefined) {
+    throw new Error(
+      "Invalid payment requirements: missing amount or maxAmountRequired",
+    );
+  }
+
+  const requirements = RequestedPaymentRequirementsSchema.parse({
+    ...requirement,
+    maxAmountRequired: normalizedAmount,
+    resource:
+      typeof requirement.resource === "string"
+        ? requirement.resource
+        : context.resourceUrl,
+    description:
+      typeof requirement.description === "string"
+        ? requirement.description
+        : "",
+    mimeType:
+      typeof requirement.mimeType === "string" ? requirement.mimeType : "",
+  });
+
+  return { requirements, raw: requirement };
+}
+
+/**
+ * Parses a decoded 402 payment required object (PAYMENT-REQUIRED header or JSON body).
+ * Every entry of `accepts` is normalised with {@link normalizePaymentRequirements}.
+ *
+ * @param paymentRequired - The decoded payment required object
+ * @param requestUrl - The URL of the request, used when the response carries no resource URL
+ * @returns The x402 version, error, top-level resource, resolved resource URL and normalised requirements
+ * @throws If the object has no accepts array or any requirement is invalid
+ * @internal
+ */
+export function parsePaymentRequired(
+  paymentRequired: unknown,
+  requestUrl?: string,
+): {
+  x402Version: number | undefined;
+  error: string | undefined;
+  resource: Record<string, unknown> | undefined;
+  resourceUrl: string | undefined;
+  accepts: NormalizedPaymentRequirements[];
+} {
+  const data = isRecord(paymentRequired) ? paymentRequired : {};
+  const error = typeof data.error === "string" ? data.error : undefined;
+  if (!Array.isArray(data.accepts)) {
+    throw new Error(
+      `402 response has no usable x402 payment requirements. ${error ?? ""}`,
+    );
+  }
+  const resource = getPaymentRequiredResource(data);
+  const resourceUrl =
+    typeof resource?.url === "string" ? resource.url : requestUrl;
+  return {
+    x402Version:
+      typeof data.x402Version === "number" ? data.x402Version : undefined,
+    error,
+    resource,
+    resourceUrl,
+    accepts: data.accepts.map((requirement) =>
+      normalizePaymentRequirements(requirement, { resourceUrl }),
+    ),
+  };
+}
+
+/**
+ * Parses the payment requirements of a 402 response for display only, skipping invalid entries.
+ *
+ * @param paymentRequired - The decoded payment required object
+ * @param requestUrl - The URL of the request, used when the response carries no resource URL
+ * @returns The normalised requirements that passed validation
+ * @internal
+ */
+export function parsePaymentRequirementsForDisplay(
+  paymentRequired: unknown,
+  requestUrl?: string,
+): RequestedPaymentRequirements[] {
+  if (!isRecord(paymentRequired) || !Array.isArray(paymentRequired.accepts)) {
+    return [];
+  }
+  const resource = getPaymentRequiredResource(paymentRequired);
+  const resourceUrl =
+    typeof resource?.url === "string" ? resource.url : requestUrl;
+  return paymentRequired.accepts.flatMap((requirement) => {
+    try {
+      return [
+        normalizePaymentRequirements(requirement, { resourceUrl }).requirements,
+      ];
+    } catch {
+      return [];
+    }
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 const FacilitatorSettleResponseSchema = SettleResponseSchema.extend({
   network: FacilitatorNetworkSchema,
   errorMessage: z.string().optional(),