thirdweb 5.107.1-nightly-51177fbe17153b711d80ec87b43aadc8ca12fb9e-20250922000346 → 5.108.0-nightly-a94f22928a662a5aff7a203fc2d383d9fa0907ec-20250923000340

package/src/x402/sign.ts

@@ -0,0 +1,206 @@
+import type { ExactEvmPayloadAuthorization } from "x402/types";
+import { type Address, getAddress } from "../utils/address.js";
+import { type Hex, toHex } from "../utils/encoding/hex.js";
+import type { Account } from "../wallets/interfaces/wallet.js";
+import { encodePayment } from "./encode.js";
+import {
+  networkToChainId,
+  type RequestedPaymentPayload,
+  type RequestedPaymentRequirements,
+  type UnsignedPaymentPayload,
+} from "./schemas.js";
+
+/**
+ * Prepares an unsigned payment header with the given sender address and payment requirements.
+ *
+ * @param from - The sender's address from which the payment will be made
+ * @param x402Version - The version of the X402 protocol to use
+ * @param paymentRequirements - The payment requirements containing scheme and network information
+ * @returns An unsigned payment payload containing authorization details
+ */
+function preparePaymentHeader(
+  from: Address,
+  x402Version: number,
+  paymentRequirements: RequestedPaymentRequirements,
+): UnsignedPaymentPayload {
+  const nonce = createNonce();
+
+  const validAfter = BigInt(
+    Math.floor(Date.now() / 1000) - 600, // 10 minutes before
+  ).toString();
+  const validBefore = BigInt(
+    Math.floor(Date.now() / 1000 + paymentRequirements.maxTimeoutSeconds),
+  ).toString();
+
+  return {
+    x402Version,
+    scheme: paymentRequirements.scheme,
+    network: paymentRequirements.network,
+    payload: {
+      signature: undefined,
+      authorization: {
+        from,
+        to: paymentRequirements.payTo as Address,
+        value: paymentRequirements.maxAmountRequired,
+        validAfter: validAfter.toString(),
+        validBefore: validBefore.toString(),
+        nonce,
+      },
+    },
+  };
+}
+
+/**
+ * Signs a payment header using the provided client and payment requirements.
+ *
+ * @param client - The signer wallet instance used to sign the payment header
+ * @param paymentRequirements - The payment requirements containing scheme and network information
+ * @param unsignedPaymentHeader - The unsigned payment payload to be signed
+ * @returns A promise that resolves to the signed payment payload
+ */
+async function signPaymentHeader(
+  account: Account,
+  paymentRequirements: RequestedPaymentRequirements,
+  unsignedPaymentHeader: UnsignedPaymentPayload,
+): Promise<RequestedPaymentPayload> {
+  const { signature } = await signAuthorization(
+    account,
+    unsignedPaymentHeader.payload.authorization,
+    paymentRequirements,
+  );
+
+  return {
+    ...unsignedPaymentHeader,
+    payload: {
+      ...unsignedPaymentHeader.payload,
+      signature,
+    },
+  };
+}
+
+/**
+ * Creates a complete payment payload by preparing and signing a payment header.
+ *
+ * @param client - The signer wallet instance used to create and sign the payment
+ * @param x402Version - The version of the X402 protocol to use
+ * @param paymentRequirements - The payment requirements containing scheme and network information
+ * @returns A promise that resolves to the complete signed payment payload
+ */
+async function createPayment(
+  account: Account,
+  x402Version: number,
+  paymentRequirements: RequestedPaymentRequirements,
+): Promise<RequestedPaymentPayload> {
+  const from = getAddress(account.address);
+  const unsignedPaymentHeader = preparePaymentHeader(
+    from,
+    x402Version,
+    paymentRequirements,
+  );
+  return signPaymentHeader(account, paymentRequirements, unsignedPaymentHeader);
+}
+
+/**
+ * Creates and encodes a payment header for the given client and payment requirements.
+ *
+ * @param client - The signer wallet instance used to create the payment header
+ * @param x402Version - The version of the X402 protocol to use
+ * @param paymentRequirements - The payment requirements containing scheme and network information
+ * @returns A promise that resolves to the encoded payment header string
+ */
+export async function createPaymentHeader(
+  account: Account,
+  x402Version: number,
+  paymentRequirements: RequestedPaymentRequirements,
+): Promise<string> {
+  const payment = await createPayment(
+    account,
+    x402Version,
+    paymentRequirements,
+  );
+  return encodePayment(payment);
+}
+
+/**
+ * Signs an EIP-3009 authorization for USDC transfer
+ *
+ * @param walletClient - The wallet client that will sign the authorization
+ * @param params - The authorization parameters containing transfer details
+ * @param params.from - The address tokens will be transferred from
+ * @param params.to - The address tokens will be transferred to
+ * @param params.value - The amount of USDC tokens to transfer (in base units)
+ * @param params.validAfter - Unix timestamp after which the authorization becomes valid
+ * @param params.validBefore - Unix timestamp before which the authorization is valid
+ * @param params.nonce - Random 32-byte nonce to prevent replay attacks
+ * @param paymentRequirements - The payment requirements containing asset and network information
+ * @param paymentRequirements.asset - The address of the USDC contract
+ * @param paymentRequirements.network - The network where the USDC contract exists
+ * @param paymentRequirements.extra - The extra information containing the name and version of the ERC20 contract
+ * @returns The signature for the authorization
+ */
+async function signAuthorization(
+  account: Account,
+  {
+    from,
+    to,
+    value,
+    validAfter,
+    validBefore,
+    nonce,
+  }: ExactEvmPayloadAuthorization,
+  { asset, network, extra }: RequestedPaymentRequirements,
+): Promise<{ signature: Hex }> {
+  const chainId = networkToChainId(network);
+  const name = extra?.name;
+  const version = extra?.version;
+
+  // TODO (402): detect permit vs transfer on asset contract
+  const data = {
+    types: {
+      TransferWithAuthorization: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "validAfter", type: "uint256" },
+        { name: "validBefore", type: "uint256" },
+        { name: "nonce", type: "bytes32" },
+      ],
+    },
+    domain: {
+      name,
+      version,
+      chainId,
+      verifyingContract: getAddress(asset),
+    },
+    primaryType: "TransferWithAuthorization" as const,
+    message: {
+      from: getAddress(from),
+      to: getAddress(to),
+      value,
+      validAfter,
+      validBefore,
+      nonce: nonce,
+    },
+  };
+
+  const signature = await account.signTypedData(data);
+  return {
+    signature,
+  };
+}
+
+/**
+ * Generates a random 32-byte nonce for use in authorization signatures
+ *
+ * @returns A random 32-byte nonce as a hex string
+ */
+function createNonce(): Hex {
+  const cryptoObj =
+    typeof globalThis.crypto !== "undefined" &&
+    typeof globalThis.crypto.getRandomValues === "function"
+      ? globalThis.crypto
+      : // Dynamic require is needed to support node.js
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        require("crypto").webcrypto;
+  return toHex(cryptoObj.getRandomValues(new Uint8Array(32)));
+}

package/src/x402/verify-payment.ts

@@ -0,0 +1,469 @@
+import {
+  type ERC20TokenAmount,
+  type Money,
+  moneySchema,
+  type Network,
+  type PaymentMiddlewareConfig,
+  SupportedEVMNetworks,
+} from "x402/types";
+import { type Address, getAddress } from "../utils/address.js";
+import { stringify } from "../utils/json.js";
+import { decodePayment, safeBase64Encode } from "./encode.js";
+import type { facilitator as facilitatorType } from "./facilitator.js";
+import {
+  type FacilitatorNetwork,
+  type FacilitatorSettleResponse,
+  networkToChainId,
+  type RequestedPaymentPayload,
+  type RequestedPaymentRequirements,
+} from "./schemas.js";
+
+const x402Version = 1;
+
+/**
+ * Configuration object for verifying X402 payments.
+ *
+ * @public
+ */
+export type VerifyPaymentArgs = {
+  /** The URL of the resource being protected by the payment */
+  resourceUrl: string;
+  /** The HTTP method used to access the resource */
+  method: "GET" | "POST" | ({} & string);
+  /** The payment data/proof provided by the client, typically from the X-PAYMENT header */
+  paymentData?: string | null;
+  /** The wallet address that should receive the payment */
+  payTo: Address;
+  /** The blockchain network where the payment should be processed */
+  network: FacilitatorNetwork;
+  /** The price for accessing the resource - either a USD amount (e.g., "$0.10") or a specific token amount */
+  price: Money | ERC20TokenAmount;
+  /** The payment facilitator instance used to verify and settle payments */
+  facilitator: ReturnType<typeof facilitatorType>;
+  /** Optional configuration for the payment middleware route */
+  routeConfig?: PaymentMiddlewareConfig;
+};
+
+/**
+ * The result of a payment verification operation.
+ *
+ * @public
+ */
+export type VerifyPaymentResult =
+  | {
+      /** HTTP 200 - Payment was successfully verified and settled */
+      status: 200;
+      /** Response headers including payment receipt information */
+      responseHeaders: Record<string, string>;
+      /** The settlement receipt from the payment facilitator */
+      paymentReceipt: FacilitatorSettleResponse;
+    }
+  | {
+      /** HTTP 402 - Payment Required, verification failed or payment missing */
+      status: 402;
+      /** The error response body containing payment requirements */
+      responseBody: {
+        /** The X402 protocol version */
+        x402Version: number;
+        /** Human-readable error message */
+        error: string;
+        /** Array of acceptable payment methods and requirements */
+        accepts: RequestedPaymentRequirements[];
+        /** Optional payer address if verification partially succeeded */
+        payer?: string;
+      };
+      /** Response headers for the error response */
+      responseHeaders: Record<string, string>;
+    };
+
+/**
+ * Verifies and processes X402 payments for protected resources.
+ *
+ * This function implements the X402 payment protocol, verifying payment proofs
+ * and settling payments through a facilitator service. It handles the complete
+ * payment flow from validation to settlement.
+ *
+ * @param args - Configuration object containing payment verification parameters
+ * @returns A promise that resolves to either a successful payment result (200) or payment required error (402)
+ *
+ * @example
+ * ```ts
+ * // Usage in a Next.js API route
+ * import { verifyPayment, facilitator } from "thirdweb/x402";
+ * import { createThirdwebClient } from "thirdweb";
+ *
+ * const client = createThirdwebClient({
+ *   secretKey: process.env.THIRDWEB_SECRET_KEY,
+ * });
+ *
+ * const thirdwebFacilitator = facilitator({
+ *   client,
+ *   serverWalletAddress: "0x1234567890123456789012345678901234567890",
+ * });
+ *
+ * export async function GET(request: Request) {
+ *   const paymentData = request.headers.get("x-payment");
+ *
+ *   const result = await verifyPayment({
+ *     resourceUrl: "https://api.example.com/premium-content",
+ *     method: "GET",
+ *     paymentData,
+ *     payTo: "0x1234567890123456789012345678901234567890",
+ *     network: "eip155:84532", // CAIP2 format: "eip155:<chain_id>"
+ *     price: "$0.10", // or { amount: "100000", asset: { address: "0x...", decimals: 6 } }
+ *     facilitator: thirdwebFacilitator,
+ *     routeConfig: {
+ *       description: "Access to premium API content",
+ *       mimeType: "application/json",
+ *       maxTimeoutSeconds: 300,
+ *     },
+ *   });
+ *
+ *   if (result.status === 200) {
+ *     // Payment verified and settled successfully
+ *     return Response.json({ data: "premium content" }, {
+ *       headers: result.responseHeaders,
+ *     });
+ *   } else {
+ *     // Payment required
+ *     return Response.json(result.responseBody, {
+ *       status: result.status,
+ *       headers: result.responseHeaders,
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Usage in Express middleware
+ * import express from "express";
+ * import { verifyPayment, facilitator } from "thirdweb/x402";
+ *
+ * const app = express();
+ *
+ * async function paymentMiddleware(req, res, next) {
+ *   const result = await verifyPayment({
+ *     resourceUrl: `${req.protocol}://${req.get('host')}${req.originalUrl}`,
+ *     method: req.method,
+ *     paymentData: req.headers["x-payment"],
+ *     payTo: "0x1234567890123456789012345678901234567890",
+ *     network: "eip155:8453", // CAIP2 format: "eip155:<chain_id>"
+ *     price: "$0.05",
+ *     facilitator: thirdwebFacilitator,
+ *   });
+ *
+ *   if (result.status === 200) {
+ *     // Set payment receipt headers and continue
+ *     Object.entries(result.responseHeaders).forEach(([key, value]) => {
+ *       res.setHeader(key, value);
+ *     });
+ *     next();
+ *   } else {
+ *     // Return payment required response
+ *     res.status(result.status)
+ *        .set(result.responseHeaders)
+ *        .json(result.responseBody);
+ *   }
+ * }
+ *
+ * app.get("/api/premium", paymentMiddleware, (req, res) => {
+ *   res.json({ message: "This is premium content!" });
+ * });
+ * ```
+ *
+ * @public
+ * @beta
+ * @bridge x402
+ */
+export async function verifyPayment(
+  args: VerifyPaymentArgs,
+): Promise<VerifyPaymentResult> {
+  const {
+    price,
+    network,
+    routeConfig = {},
+    resourceUrl,
+    method,
+    payTo,
+    paymentData: paymentProof,
+    facilitator,
+  } = args;
+  const {
+    description,
+    mimeType,
+    maxTimeoutSeconds,
+    inputSchema,
+    outputSchema,
+    errorMessages,
+    discoverable,
+  } = routeConfig;
+
+  const atomicAmountForAsset = await processPriceToAtomicAmount(
+    price,
+    network,
+    facilitator,
+  );
+  if ("error" in atomicAmountForAsset) {
+    return {
+      status: 402,
+      responseHeaders: { "Content-Type": "application/json" },
+      responseBody: {
+        x402Version,
+        error: atomicAmountForAsset.error,
+        accepts: [],
+      },
+    };
+  }
+  const { maxAmountRequired, asset } = atomicAmountForAsset;
+
+  const paymentRequirements: RequestedPaymentRequirements[] = [];
+
+  if (
+    SupportedEVMNetworks.includes(network as Network) ||
+    network.startsWith("eip155:")
+  ) {
+    paymentRequirements.push({
+      scheme: "exact",
+      network,
+      maxAmountRequired,
+      resource: resourceUrl,
+      description: description ?? "",
+      mimeType: mimeType ?? "application/json",
+      payTo: getAddress(payTo),
+      maxTimeoutSeconds: maxTimeoutSeconds ?? 300,
+      asset: getAddress(asset.address),
+      // TODO: Rename outputSchema to requestStructure
+      outputSchema: {
+        input: {
+          type: "http",
+          method,
+          discoverable: discoverable ?? true,
+          ...inputSchema,
+        },
+        output: outputSchema,
+      },
+      extra: (asset as ERC20TokenAmount["asset"]).eip712,
+    });
+  } else {
+    return {
+      status: 402,
+      responseHeaders: {
+        "Content-Type": "application/json",
+      },
+      responseBody: {
+        x402Version,
+        error: `Unsupported network: ${network}`,
+        accepts: paymentRequirements,
+      },
+    };
+  }
+
+  // Check for payment header
+  if (!paymentProof) {
+    return {
+      status: 402,
+      responseHeaders: {
+        "Content-Type": "application/json",
+      },
+      responseBody: {
+        x402Version,
+        error: errorMessages?.paymentRequired || "X-PAYMENT header is required",
+        accepts: paymentRequirements,
+      },
+    };
+  }
+
+  // Verify payment
+  let decodedPayment: RequestedPaymentPayload;
+  try {
+    decodedPayment = decodePayment(paymentProof);
+    decodedPayment.x402Version = x402Version;
+  } catch (error) {
+    return {
+      status: 402,
+      responseHeaders: {
+        "Content-Type": "application/json",
+      },
+      responseBody: {
+        x402Version,
+        error:
+          errorMessages?.invalidPayment ||
+          (error instanceof Error ? error.message : "Invalid payment"),
+        accepts: paymentRequirements,
+      },
+    };
+  }
+
+  const selectedPaymentRequirements = paymentRequirements.find(
+    (value) =>
+      value.scheme === decodedPayment.scheme &&
+      value.network === decodedPayment.network,
+  );
+  if (!selectedPaymentRequirements) {
+    return {
+      status: 402,
+      responseHeaders: {
+        "Content-Type": "application/json",
+      },
+      responseBody: {
+        x402Version,
+        error:
+          errorMessages?.noMatchingRequirements ||
+          "Unable to find matching payment requirements",
+        accepts: paymentRequirements,
+      },
+    };
+  }
+
+  try {
+    const verification = await facilitator.verify(
+      decodedPayment,
+      selectedPaymentRequirements,
+    );
+
+    if (!verification.isValid) {
+      return {
+        status: 402,
+        responseHeaders: {
+          "Content-Type": "application/json",
+        },
+        responseBody: {
+          x402Version,
+          error:
+            errorMessages?.verificationFailed ||
+            verification.invalidReason ||
+            "Payment verification failed",
+          accepts: paymentRequirements,
+          payer: verification.payer,
+        },
+      };
+    }
+  } catch (error) {
+    return {
+      status: 402,
+      responseHeaders: {
+        "Content-Type": "application/json",
+      },
+      responseBody: {
+        x402Version,
+        error:
+          errorMessages?.verificationFailed ||
+          (error instanceof Error
+            ? error.message
+            : "Payment Verification error"),
+        accepts: paymentRequirements,
+      },
+    };
+  }
+
+  // Settle payment
+  try {
+    const settlement = await facilitator.settle(
+      decodedPayment,
+      selectedPaymentRequirements,
+    );
+
+    if (settlement.success) {
+      return {
+        status: 200,
+        paymentReceipt: settlement,
+        responseHeaders: {
+          "Access-Control-Expose-Headers": "X-PAYMENT-RESPONSE",
+          "X-PAYMENT-RESPONSE": safeBase64Encode(stringify(settlement)),
+        },
+      };
+    } else {
+      return {
+        status: 402,
+        responseHeaders: {
+          "Content-Type": "application/json",
+        },
+        responseBody: {
+          x402Version,
+          error:
+            errorMessages?.settlementFailed ||
+            settlement.errorReason ||
+            "Settlement failed",
+          accepts: paymentRequirements,
+        },
+      };
+    }
+  } catch (error) {
+    return {
+      status: 402,
+      responseHeaders: {
+        "Content-Type": "application/json",
+      },
+      responseBody: {
+        x402Version,
+        error:
+          errorMessages?.settlementFailed ||
+          (error instanceof Error ? error.message : "Settlement error"),
+        accepts: paymentRequirements,
+      },
+    };
+  }
+}
+
+/**
+ * Parses the amount from the given price
+ *
+ * @param price - The price to parse
+ * @param network - The network to get the default asset for
+ * @returns The parsed amount or an error message
+ */
+async function processPriceToAtomicAmount(
+  price: Money | ERC20TokenAmount,
+  network: FacilitatorNetwork,
+  facilitator: ReturnType<typeof facilitatorType>,
+): Promise<
+  | { maxAmountRequired: string; asset: ERC20TokenAmount["asset"] }
+  | { error: string }
+> {
+  // Handle USDC amount (string) or token amount (ERC20TokenAmount)
+  let maxAmountRequired: string;
+  let asset: ERC20TokenAmount["asset"];
+
+  if (typeof price === "string" || typeof price === "number") {
+    // USDC amount in dollars
+    const parsedAmount = moneySchema.safeParse(price);
+    if (!parsedAmount.success) {
+      return {
+        error: `Invalid price (price: ${price}). Must be in the form "$3.10", 0.10, "0.001", ${parsedAmount.error}`,
+      };
+    }
+    const parsedUsdAmount = parsedAmount.data;
+    const defaultAsset = await getDefaultAsset(network, facilitator);
+    if (!defaultAsset) {
+      return {
+        error: `Unable to get default asset on ${network}. Please specify an asset in the payment requirements.`,
+      };
+    }
+    asset = defaultAsset;
+    maxAmountRequired = (parsedUsdAmount * 10 ** asset.decimals).toString();
+  } else {
+    // Token amount in atomic units
+    maxAmountRequired = price.amount;
+    asset = price.asset;
+  }
+
+  return {
+    maxAmountRequired,
+    asset,
+  };
+}
+
+async function getDefaultAsset(
+  network: FacilitatorNetwork,
+  facilitator: ReturnType<typeof facilitatorType>,
+): Promise<ERC20TokenAmount["asset"] | undefined> {
+  const supportedAssets = await facilitator.supported();
+  const chainId = networkToChainId(network);
+  const matchingAsset = supportedAssets.kinds.find(
+    (supported) => supported.network === `eip155:${chainId}`,
+  );
+  const assetConfig = matchingAsset?.extra
+    ?.defaultAsset as ERC20TokenAmount["asset"];
+  return assetConfig;
+}