thirdweb 5.107.1 → 5.108.0-nightly-a94f22928a662a5aff7a203fc2d383d9fa0907ec-20250923000340

package/src/x402/encode.ts

@@ -0,0 +1,81 @@
+import type { ExactEvmPayload } from "x402/types";
+import {
+  type RequestedPaymentPayload,
+  RequestedPaymentPayloadSchema,
+} from "./schemas.js";
+
+/**
+ * Encodes a payment payload into a base64 string, ensuring bigint values are properly stringified
+ *
+ * @param payment - The payment payload to encode
+ * @returns A base64 encoded string representation of the payment payload
+ */
+export function encodePayment(payment: RequestedPaymentPayload): string {
+  let safe: RequestedPaymentPayload;
+
+  // evm
+  const evmPayload = payment.payload as ExactEvmPayload;
+  safe = {
+    ...payment,
+    payload: {
+      ...evmPayload,
+      authorization: Object.fromEntries(
+        Object.entries(evmPayload.authorization).map(([key, value]) => [
+          key,
+          typeof value === "bigint" ? (value as bigint).toString() : value,
+        ]),
+      ) as ExactEvmPayload["authorization"],
+    },
+  };
+  return safeBase64Encode(JSON.stringify(safe));
+}
+
+/**
+ * Decodes a base64 encoded payment string back into a PaymentPayload object
+ *
+ * @param payment - The base64 encoded payment string to decode
+ * @returns The decoded and validated PaymentPayload object
+ */
+export function decodePayment(payment: string): RequestedPaymentPayload {
+  const decoded = safeBase64Decode(payment);
+  const parsed = JSON.parse(decoded);
+
+  const obj: RequestedPaymentPayload = {
+    ...parsed,
+    payload: parsed.payload as ExactEvmPayload,
+  };
+  const validated = RequestedPaymentPayloadSchema.parse(obj);
+  return validated;
+}
+
+/**
+ * Encodes a string to base64 format
+ *
+ * @param data - The string to be encoded to base64
+ * @returns The base64 encoded string
+ */
+export function safeBase64Encode(data: string): string {
+  if (
+    typeof globalThis !== "undefined" &&
+    typeof globalThis.btoa === "function"
+  ) {
+    return globalThis.btoa(data);
+  }
+  return Buffer.from(data).toString("base64");
+}
+
+/**
+ * Decodes a base64 string back to its original format
+ *
+ * @param data - The base64 encoded string to be decoded
+ * @returns The decoded string in UTF-8 format
+ */
+function safeBase64Decode(data: string): string {
+  if (
+    typeof globalThis !== "undefined" &&
+    typeof globalThis.atob === "function"
+  ) {
+    return globalThis.atob(data);
+  }
+  return Buffer.from(data, "base64").toString("utf-8");
+}

package/src/x402/facilitator.ts

@@ -1,5 +1,12 @@
-import type { FacilitatorConfig } from "x402/types";
+import type { SupportedPaymentKindsResponse, VerifyResponse } from "x402/types";
 import type { ThirdwebClient } from "../client/client.js";
+import { stringify } from "../utils/json.js";
+import { withCache } from "../utils/promise/withCache.js";
+import type {
+  FacilitatorSettleResponse,
+  RequestedPaymentPayload,
+  RequestedPaymentRequirements,
+} from "./schemas.js";
 
 export type ThirdwebX402FacilitatorConfig = {
   client: ThirdwebClient;
@@ -12,7 +19,7 @@ const DEFAULT_BASE_URL = "https://api.thirdweb.com/v1/payments/x402";
 
 /**
  * Creates a facilitator for the x402 payment protocol.
- * Use this with any x402 middleware to enable settling transactions with your thirdweb server wallet.
+ * You can use this with `verifyPayment` or with any x402 middleware to enable settling transactions with your thirdweb server wallet.
  *
  * @param config - The configuration for the facilitator
  * @returns a x402 compatible FacilitatorConfig
@@ -48,9 +55,7 @@ const DEFAULT_BASE_URL = "https://api.thirdweb.com/v1/payments/x402";
  *
  * @bridge x402
  */
-export function facilitator(
-  config: ThirdwebX402FacilitatorConfig,
-): FacilitatorConfig {
+export function facilitator(config: ThirdwebX402FacilitatorConfig) {
   const secretKey = config.client.secretKey;
   if (!secretKey) {
     throw new Error("Client secret key is required for the x402 facilitator");
@@ -61,7 +66,7 @@ export function facilitator(
       "Server wallet address is required for the x402 facilitator",
     );
   }
-  return {
+  const facilitator = {
     url: (config.baseUrl ?? DEFAULT_BASE_URL) as `${string}://${string}`,
     createAuthHeaders: async () => {
       return {
@@ -83,5 +88,108 @@ export function facilitator(
         },
       };
     },
+    /**
+     * Verifies a payment payload with the facilitator service
+     *
+     * @param payload - The payment payload to verify
+     * @param paymentRequirements - The payment requirements to verify against
+     * @returns A promise that resolves to the verification response
+     */
+    async verify(
+      payload: RequestedPaymentPayload,
+      paymentRequirements: RequestedPaymentRequirements,
+    ): Promise<VerifyResponse> {
+      const url = config.baseUrl ?? DEFAULT_BASE_URL;
+
+      let headers = { "Content-Type": "application/json" };
+      const authHeaders = await facilitator.createAuthHeaders();
+      headers = { ...headers, ...authHeaders.verify };
+
+      const res = await fetch(`${url}/verify`, {
+        method: "POST",
+        headers,
+        body: stringify({
+          x402Version: payload.x402Version,
+          paymentPayload: payload,
+          paymentRequirements: paymentRequirements,
+        }),
+      });
+
+      if (res.status !== 200) {
+        const text = `${res.statusText} ${await res.text()}`;
+        throw new Error(`Failed to verify payment: ${res.status} ${text}`);
+      }
+
+      const data = await res.json();
+      return data as VerifyResponse;
+    },
+
+    /**
+     * Settles a payment with the facilitator service
+     *
+     * @param payload - The payment payload to settle
+     * @param paymentRequirements - The payment requirements for the settlement
+     * @returns A promise that resolves to the settlement response
+     */
+    async settle(
+      payload: RequestedPaymentPayload,
+      paymentRequirements: RequestedPaymentRequirements,
+    ): Promise<FacilitatorSettleResponse> {
+      const url = config.baseUrl ?? DEFAULT_BASE_URL;
+
+      let headers = { "Content-Type": "application/json" };
+      const authHeaders = await facilitator.createAuthHeaders();
+      headers = { ...headers, ...authHeaders.settle };
+
+      const res = await fetch(`${url}/settle`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          x402Version: payload.x402Version,
+          paymentPayload: payload,
+          paymentRequirements: paymentRequirements,
+        }),
+      });
+
+      if (res.status !== 200) {
+        const text = `${res.statusText} ${await res.text()}`;
+        throw new Error(`Failed to settle payment: ${res.status} ${text}`);
+      }
+
+      const data = await res.json();
+      return data as FacilitatorSettleResponse;
+    },
+
+    /**
+     * Gets the supported payment kinds from the facilitator service.
+     *
+     * @returns A promise that resolves to the supported payment kinds
+     */
+    async supported(): Promise<SupportedPaymentKindsResponse> {
+      const url = config.baseUrl ?? DEFAULT_BASE_URL;
+      return withCache(
+        async () => {
+          let headers = { "Content-Type": "application/json" };
+          const authHeaders = await facilitator.createAuthHeaders();
+          headers = { ...headers, ...authHeaders.supported };
+          const res = await fetch(`${url}/supported`, { headers });
+
+          if (res.status !== 200) {
+            throw new Error(
+              `Failed to get supported payment kinds: ${res.statusText}`,
+            );
+          }
+
+          const data = await res.json();
+          return data as SupportedPaymentKindsResponse;
+        },
+        {
+          cacheKey: `supported-payment-kinds-${url}`,
+          cacheTime: 1000 * 60 * 60 * 24, // 24 hours
+        },
+      );
+    },
   };
+
+  return facilitator;
 }

package/src/x402/fetchWithPayment.ts

@@ -1,15 +1,13 @@
-import { createPaymentHeader } from "x402/client";
-import {
-  ChainIdToNetwork,
-  EvmNetworkToChainId,
-  type PaymentRequirements,
-  PaymentRequirementsSchema,
-  type Signer,
-} from "x402/types";
-import { viemAdapter } from "../adapters/viem.js";
+import { ChainIdToNetwork } from "x402/types";
 import { getCachedChain } from "../chains/utils.js";
 import type { ThirdwebClient } from "../client/client.js";
 import type { Wallet } from "../wallets/interfaces/wallet.js";
+import {
+  networkToChainId,
+  type RequestedPaymentRequirements,
+  RequestedPaymentRequirementsSchema,
+} from "./schemas.js";
+import { createPaymentHeader } from "./sign.js";
 
 /**
  * Enables the payment of APIs using the x402 payment protocol.
@@ -52,7 +50,7 @@ import type { Wallet } from "../wallets/interfaces/wallet.js";
  */
 export function wrapFetchWithPayment(
   fetch: typeof globalThis.fetch,
-  client: ThirdwebClient,
+  _client: ThirdwebClient,
   wallet: Wallet,
   maxValue: bigint = BigInt(1 * 10 ** 6), // Default to 1 USDC
 ) {
@@ -68,7 +66,7 @@ export function wrapFetchWithPayment(
       accepts: unknown[];
     };
     const parsedPaymentRequirements = accepts
-      .map((x) => PaymentRequirementsSchema.parse(x))
+      .map((x) => RequestedPaymentRequirementsSchema.parse(x))
       .filter((x) => x.scheme === "exact"); // TODO (402): accept other schemes
 
     const account = wallet.getAccount();
@@ -89,16 +87,10 @@ export function wrapFetchWithPayment(
       throw new Error("Payment amount exceeds maximum allowed");
     }
 
-    const paymentChainId = EvmNetworkToChainId.get(
+    const paymentChainId = networkToChainId(
       selectedPaymentRequirements.network,
     );
 
-    if (!paymentChainId) {
-      throw new Error(
-        `No chain found for the selected payment requirement: ${selectedPaymentRequirements.network}`,
-      );
-    }
-
     // switch to the payment chain if it's not the current chain
     if (paymentChainId !== chain.id) {
       await wallet.switchChain(getCachedChain(paymentChainId));
@@ -108,14 +100,8 @@ export function wrapFetchWithPayment(
       }
     }
 
-    const walletClient = viemAdapter.wallet.toViem({
-      wallet: wallet,
-      chain,
-      client,
-    }) as Signer;
-
     const paymentHeader = await createPaymentHeader(
-      walletClient,
+      account,
       x402Version,
       selectedPaymentRequirements,
     );
@@ -142,7 +128,7 @@ export function wrapFetchWithPayment(
 }
 
 function defaultPaymentRequirementsSelector(
-  paymentRequirements: PaymentRequirements[],
+  paymentRequirements: RequestedPaymentRequirements[],
   chainId: number,
   scheme: "exact",
 ) {
@@ -151,7 +137,7 @@ function defaultPaymentRequirementsSelector(
       "No valid payment requirements found in server 402 response",
     );
   }
-  const currentWalletNetwork = ChainIdToNetwork[chainId];
+  const currentWalletNetwork = ChainIdToNetwork[chainId] || `eip155:${chainId}`;
   // find the payment requirements matching the connected wallet chain
   const matchingPaymentRequirements = paymentRequirements.find(
     (x) => x.network === currentWalletNetwork && x.scheme === scheme,

package/src/x402/schemas.ts

@@ -0,0 +1,76 @@
+import {
+  EvmNetworkToChainId,
+  type ExactEvmPayload,
+  type Network,
+  PaymentPayloadSchema,
+  PaymentRequirementsSchema,
+  SettleResponseSchema,
+} from "x402/types";
+import { z } from "zod";
+
+const FacilitatorNetworkSchema = z.union([
+  z.literal("base-sepolia"),
+  z.literal("base"),
+  z.literal("avalanche-fuji"),
+  z.literal("avalanche"),
+  z.literal("iotex"),
+  z.literal("solana-devnet"),
+  z.literal("solana"),
+  z.literal("sei"),
+  z.literal("sei-testnet"),
+  z.string().refine((value) => value.startsWith("eip155:"), {
+    message: "Invalid network",
+  }),
+]);
+
+export type FacilitatorNetwork = z.infer<typeof FacilitatorNetworkSchema>;
+
+export const RequestedPaymentPayloadSchema = PaymentPayloadSchema.extend({
+  network: FacilitatorNetworkSchema,
+});
+
+export type RequestedPaymentPayload = z.infer<
+  typeof RequestedPaymentPayloadSchema
+>;
+export type UnsignedPaymentPayload = Omit<
+  RequestedPaymentPayload,
+  "payload"
+> & {
+  payload: Omit<ExactEvmPayload, "signature"> & { signature: undefined };
+};
+
+export const RequestedPaymentRequirementsSchema =
+  PaymentRequirementsSchema.extend({
+    network: FacilitatorNetworkSchema,
+  });
+
+export type RequestedPaymentRequirements = z.infer<
+  typeof RequestedPaymentRequirementsSchema
+>;
+
+const FacilitatorSettleResponseSchema = SettleResponseSchema.extend({
+  network: FacilitatorNetworkSchema,
+});
+export type FacilitatorSettleResponse = z.infer<
+  typeof FacilitatorSettleResponseSchema
+>;
+
+export function networkToChainId(network: string): number {
+  if (network.startsWith("eip155:")) {
+    const chainId = parseInt(network.split(":")[1] ?? "0");
+    if (!Number.isNaN(chainId) && chainId > 0) {
+      return chainId;
+    } else {
+      throw new Error(`Invalid network: ${network}`);
+    }
+  }
+  const mappedChainId = EvmNetworkToChainId.get(network as Network);
+  if (!mappedChainId) {
+    throw new Error(`Invalid network: ${network}`);
+  }
+  // TODO (402): support solana networks
+  if (mappedChainId === 101 || mappedChainId === 103) {
+    throw new Error("Solana networks not supported yet.");
+  }
+  return mappedChainId;
+}

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)));
+}