thirdweb 5.107.1 → 5.108.0

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 `settlePayment` 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/settle-payment.ts

@@ -0,0 +1,186 @@
+import { stringify } from "../utils/json.js";
+import { decodePaymentRequest } from "./common.js";
+import { safeBase64Encode } from "./encode.js";
+import {
+  type PaymentArgs,
+  type SettlePaymentResult,
+  x402Version,
+} from "./types.js";
+
+/**
+ * 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
+ *
+ * ### Next.js API route example
+ *
+ * ```ts
+ * // Usage in a Next.js API route
+ * import { settlePayment, 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");
+ *
+ *   // verify and process the payment
+ *   const result = await settlePayment({
+ *     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" });
+ *   } else {
+ *     // Payment required
+ *     return Response.json(result.responseBody, {
+ *       status: result.status,
+ *       headers: result.responseHeaders,
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * ### Express middleware example
+ *
+ * ```ts
+ * // Usage in Express middleware
+ * import express from "express";
+ * import { settlePayment, facilitator } from "thirdweb/x402";
+ * import { createThirdwebClient } from "thirdweb";
+ *
+ * const client = createThirdwebClient({
+ *   secretKey: process.env.THIRDWEB_SECRET_KEY,
+ * });
+ *
+ * const thirdwebFacilitator = facilitator({
+ *   client,
+ *   serverWalletAddress: "0x1234567890123456789012345678901234567890",
+ * });
+ *
+ * const app = express();
+ *
+ * async function paymentMiddleware(req, res, next) {
+ *   // verify and process the payment
+ *   const result = await settlePayment({
+ *     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 settlePayment(
+  args: PaymentArgs,
+): Promise<SettlePaymentResult> {
+  const { routeConfig = {}, facilitator } = args;
+  const { errorMessages } = routeConfig;
+
+  const decodePaymentResult = await decodePaymentRequest(args);
+
+  if (decodePaymentResult.status !== 200) {
+    return decodePaymentResult;
+  }
+
+  const { selectedPaymentRequirements, decodedPayment, paymentRequirements } =
+    decodePaymentResult;
+
+  // 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,
+      },
+    };
+  }
+}