thirdweb 5.107.1 → 5.108.0

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/types.ts

@@ -0,0 +1,90 @@
+import type {
+  ERC20TokenAmount,
+  Money,
+  PaymentMiddlewareConfig,
+} from "x402/types";
+import type { Address } from "../utils/address.js";
+import type { Prettify } from "../utils/type-utils.js";
+import type { facilitator as facilitatorType } from "./facilitator.js";
+import type {
+  FacilitatorNetwork,
+  FacilitatorSettleResponse,
+  RequestedPaymentPayload,
+  RequestedPaymentRequirements,
+} from "./schemas.js";
+
+export const x402Version = 1;
+
+/**
+ * Configuration object for verifying or processing X402 payments.
+ *
+ * @public
+ */
+export type PaymentArgs = {
+  /** 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;
+};
+
+export type PaymentRequiredResult = {
+  /** HTTP 402 - Payment Required, verification or processing 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>;
+};
+
+/**
+ * The result of a payment settlement operation.
+ *
+ * @public
+ */
+export type SettlePaymentResult = Prettify<
+  | {
+      /** HTTP 200 - Payment was successfully processed */
+      status: 200;
+      /** Response headers including payment receipt information */
+      responseHeaders: Record<string, string>;
+      /** The payment receipt from the payment facilitator */
+      paymentReceipt: FacilitatorSettleResponse;
+    }
+  | PaymentRequiredResult
+>;
+
+/**
+ * The result of a payment verification operation.
+ *
+ * @public
+ */
+export type VerifyPaymentResult = Prettify<
+  | {
+      /** HTTP 200 - Payment was successfully verified */
+      status: 200;
+      decodedPayment: RequestedPaymentPayload;
+      selectedPaymentRequirements: RequestedPaymentRequirements;
+    }
+  | PaymentRequiredResult
+>;

package/src/x402/verify-payment.ts

@@ -0,0 +1,133 @@
+import { decodePaymentRequest } from "./common.js";
+import {
+  type PaymentArgs,
+  type VerifyPaymentResult,
+  x402Version,
+} from "./types.js";
+
+/**
+ * Verifies X402 payments for protected resources. This function only verifies the payment,
+ * you should use `settlePayment` to settle the payment.
+ *
+ * @param args - Configuration object containing payment verification parameters
+ * @returns A promise that resolves to either a successful verification 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 paymentArgs = {
+ *     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,
+ *     },
+ *   };
+ *
+ *   // verify the payment
+ *   const result = await verifyPayment(paymentArgs);
+ *
+ *   if (result.status === 200) {
+ *     // Payment verified, but not settled yet
+ *     // you can do the work that requires payment first
+ *     const result = await doSomething();
+ *     // then settle the payment
+ *     const settleResult = await settlePayment(paymentArgs);
+ *
+ *     // then return the result
+ *     return Response.json(result);
+ *   } else {
+ *     // verification failed, return payment required
+ *     return Response.json(result.responseBody, {
+ *       status: result.status,
+ *       headers: result.responseHeaders,
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ * @beta
+ * @bridge x402
+ */
+export async function verifyPayment(
+  args: PaymentArgs,
+): Promise<VerifyPaymentResult> {
+  const { routeConfig = {}, facilitator } = args;
+  const { errorMessages } = routeConfig;
+
+  const decodePaymentResult = await decodePaymentRequest(args);
+
+  if (decodePaymentResult.status !== 200) {
+    return decodePaymentResult;
+  }
+
+  const { selectedPaymentRequirements, decodedPayment, paymentRequirements } =
+    decodePaymentResult;
+
+  // Verify payment
+  try {
+    const verification = await facilitator.verify(
+      decodedPayment,
+      selectedPaymentRequirements,
+    );
+
+    if (verification.isValid) {
+      return {
+        status: 200,
+        decodedPayment,
+        selectedPaymentRequirements,
+      };
+    } else {
+      return {
+        status: 402,
+        responseHeaders: {
+          "Content-Type": "application/json",
+        },
+        responseBody: {
+          x402Version,
+          error:
+            errorMessages?.verificationFailed ||
+            verification.invalidReason ||
+            "Verification failed",
+          accepts: paymentRequirements,
+        },
+      };
+    }
+  } catch (error) {
+    return {
+      status: 402,
+      responseHeaders: {
+        "Content-Type": "application/json",
+      },
+      responseBody: {
+        x402Version,
+        error:
+          errorMessages?.verificationFailed ||
+          (error instanceof Error ? error.message : "Verification error"),
+        accepts: paymentRequirements,
+      },
+    };
+  }
+}