[SDK] Cache and reuse x402 permit signatures for upto schemes

.changeset/warm-clouds-judge.md

@@ -0,0 +1,5 @@
+---
+"thirdweb": patch
+---
+
+Automatically store and re-use permit x402 signatures for upto schemes

apps/portal/src/app/x402/server/page.mdx

@@ -132,30 +132,7 @@ You can call verifyPayment() and settlePayment() multiple times using the same p
 
  If any of these checks fail, `verifyPayment()` will return a 402 response requiring a new payment authorization.
 
-You can retrieve the previously signed paymentData from any storage mechanism, for example:
-
-```typescript
-const paymentData = retrievePaymentDataFromStorage(userId, sessionId); // example implementation, can be any storage mechanism
-const paymentArgs = { ...otherPaymentArgs, paymentData };
-
-// verify paymentData is still valid
-const verifyResult = await verifyPayment(paymentArgs);
-
-if (verifyResult.status !== 200) {
-	return Response.json(verifyResult.responseBody, {
-		status: verifyResult.status,
-		headers: verifyResult.responseHeaders,
-	});
-}
-
-// settle payment based on usage, re-using the previous paymentData
-const settleResult = await settlePayment({
-	...paymentArgs,
-	price: tokensUsed * pricePerTokenUsed, // adjust final price based on usage
-});
-
-return Response.json(answer);
-```
+`wrapFetchWithPayment()` and `useFetchWithPayment()` will automatically handle the caching and re-use of the payment data for you, so you don't need to have any additional state or storage on the backend.
 
 ## Signature expiration configuration
 

packages/thirdweb/src/react/core/hooks/x402/useFetchWithPaymentCore.ts

@@ -2,6 +2,7 @@
 
 import { useMutation } from "@tanstack/react-query";
 import type { ThirdwebClient } from "../../../../client/client.js";
+import type { AsyncStorage } from "../../../../utils/storage/AsyncStorage.js";
 import type { Wallet } from "../../../../wallets/interfaces/wallet.js";
 import { wrapFetchWithPayment } from "../../../../x402/fetchWithPayment.js";
 import type { RequestedPaymentRequirements } from "../../../../x402/schemas.js";
@@ -14,6 +15,11 @@ export type UseFetchWithPaymentOptions = {
     paymentRequirements: RequestedPaymentRequirements[],
   ) => RequestedPaymentRequirements | undefined;
   parseAs?: "json" | "text" | "raw";
+  /**
+   * Storage for caching permit signatures (for "upto" scheme).
+   * When provided, permit signatures will be cached and reused if the on-chain allowance is sufficient.
+   */
+  storage?: AsyncStorage;
 };
 
 type ShowErrorModalCallback = (data: {
@@ -81,7 +87,11 @@ export function useFetchWithPaymentCore(
           globalThis.fetch,
           client,
           currentWallet,
-          options,
+          {
+            maxValue: options?.maxValue,
+            paymentRequirementsSelector: options?.paymentRequirementsSelector,
+            storage: options?.storage,
+          },
         );
 
         const response = await wrappedFetch(input, init);

packages/thirdweb/src/react/native/hooks/x402/useFetchWithPayment.ts

@@ -1,6 +1,7 @@
 "use client";
 
 import type { ThirdwebClient } from "../../../../client/client.js";
+import { nativeLocalStorage } from "../../../../utils/storage/nativeStorage.js";
 import {
   type UseFetchWithPaymentOptions,
   useFetchWithPaymentCore,
@@ -29,6 +30,7 @@ export type { UseFetchWithPaymentOptions };
  * @param options.maxValue - The maximum allowed payment amount in base units
  * @param options.paymentRequirementsSelector - Custom function to select payment requirements from available options
  * @param options.parseAs - How to parse the response: "json" (default), "text", or "raw"
+ * @param options.storage - Storage for caching permit signatures (for "upto" scheme). Provide your own AsyncStorage implementation for React Native.
  * @returns An object containing:
  * - `fetchWithPayment`: Function to make fetch requests with automatic payment handling (returns parsed data)
  * - `isPending`: Boolean indicating if a request is in progress
@@ -92,5 +94,8 @@ export function useFetchWithPayment(
   options?: UseFetchWithPaymentOptions,
 ) {
   // Native version doesn't show modal, errors bubble up naturally
-  return useFetchWithPaymentCore(client, options);
+  return useFetchWithPaymentCore(client, {
+    ...options,
+    storage: options?.storage ?? nativeLocalStorage,
+  });
 }

packages/thirdweb/src/react/web/hooks/x402/useFetchWithPayment.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import { useContext } from "react";
+import { useContext, useMemo } from "react";
 import type { ThirdwebClient } from "../../../../client/client.js";
+import { webLocalStorage } from "../../../../utils/storage/webStorage.js";
 import type { Wallet } from "../../../../wallets/interfaces/wallet.js";
 import type { Theme } from "../../../core/design-system/index.js";
 import {
@@ -255,9 +256,18 @@ export function useFetchWithPayment(
       }
     : undefined;
 
+  // Default to webLocalStorage for permit signature caching
+  const resolvedOptions = useMemo(
+    () => ({
+      ...options,
+      storage: options?.storage ?? webLocalStorage,
+    }),
+    [options],
+  );
+
   return useFetchWithPaymentCore(
     client,
-    options,
+    resolvedOptions,
     showErrorModal,
     showConnectModal,
   );

packages/thirdweb/src/x402/fetchWithPayment.ts

@@ -1,6 +1,10 @@
 import { getCachedChain } from "../chains/utils.js";
 import type { ThirdwebClient } from "../client/client.js";
+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 { clearPermitSignatureFromCache } from "./permitSignatureStorage.js";
 import {
   extractEvmChainId,
   networkToCaip2ChainId,
@@ -57,6 +61,11 @@ export function wrapFetchWithPayment(
     paymentRequirementsSelector?: (
       paymentRequirements: RequestedPaymentRequirements[],
     ) => RequestedPaymentRequirements | undefined;
+    /**
+     * Storage for caching permit signatures (for "upto" scheme).
+     * When provided, permit signatures will be cached and reused if the on-chain allowance is sufficient.
+     */
+    storage?: AsyncStorage;
   },
 ) {
   return async (input: RequestInfo, init?: RequestInit) => {
@@ -131,6 +140,7 @@ export function wrapFetchWithPayment(
       account,
       selectedPaymentRequirements,
       x402Version,
+      options?.storage ?? webLocalStorage,
     );
 
     const initParams = init || {};
@@ -150,6 +160,17 @@ 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, {
+        chainId: paymentChainId,
+        asset: selectedPaymentRequirements.asset,
+        owner: getAddress(account.address),
+        spender: getAddress(selectedPaymentRequirements.payTo),
+      });
+    }
+
     return secondResponse;
   };
 }

packages/thirdweb/src/x402/permitSignatureStorage.ts

@@ -0,0 +1,99 @@
+import type { AsyncStorage } from "../utils/storage/AsyncStorage.js";
+import type { RequestedPaymentPayload } from "./schemas.js";
+
+/**
+ * Cached permit signature data structure
+ */
+type CachedPermitSignature = {
+  payload: RequestedPaymentPayload;
+  deadline: string;
+  maxAmount: string;
+};
+
+/**
+ * Parameters for generating a permit cache key
+ */
+export type PermitCacheKeyParams = {
+  chainId: number;
+  asset: string;
+  owner: string;
+  spender: string;
+};
+
+const CACHE_KEY_PREFIX = "x402:permit";
+
+/**
+ * Generates a cache key for permit signature storage
+ * @param params - The parameters to generate the cache key from
+ * @returns The cache key string
+ */
+function getPermitCacheKey(params: PermitCacheKeyParams): string {
+  return `${CACHE_KEY_PREFIX}:${params.chainId}:${params.asset.toLowerCase()}:${params.owner.toLowerCase()}:${params.spender.toLowerCase()}`;
+}
+
+/**
+ * Retrieves a cached permit signature from storage
+ * @param storage - The AsyncStorage instance to use
+ * @param params - The parameters identifying the cached signature
+ * @returns The cached signature data or null if not found
+ */
+export async function getPermitSignatureFromCache(
+  storage: AsyncStorage,
+  params: PermitCacheKeyParams,
+): Promise<CachedPermitSignature | null> {
+  try {
+    const key = getPermitCacheKey(params);
+    const cached = await storage.getItem(key);
+    if (!cached) {
+      return null;
+    }
+    return JSON.parse(cached) as CachedPermitSignature;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Saves a permit signature to storage cache
+ * @param storage - The AsyncStorage instance to use
+ * @param params - The parameters identifying the signature
+ * @param payload - The signed payment payload to cache
+ * @param deadline - The deadline timestamp of the permit
+ * @param maxAmount - The maximum amount authorized
+ */
+export async function savePermitSignatureToCache(
+  storage: AsyncStorage,
+  params: PermitCacheKeyParams,
+  payload: RequestedPaymentPayload,
+  deadline: string,
+  maxAmount: string,
+): Promise<void> {
+  try {
+    const key = getPermitCacheKey(params);
+    const data: CachedPermitSignature = {
+      payload,
+      deadline,
+      maxAmount,
+    };
+    await storage.setItem(key, JSON.stringify(data));
+  } catch {
+    // Silently fail - caching is optional
+  }
+}
+
+/**
+ * Clears a cached permit signature from storage
+ * @param storage - The AsyncStorage instance to use
+ * @param params - The parameters identifying the cached signature
+ */
+export async function clearPermitSignatureFromCache(
+  storage: AsyncStorage,
+  params: PermitCacheKeyParams,
+): Promise<void> {
+  try {
+    const key = getPermitCacheKey(params);
+    await storage.removeItem(key);
+  } catch {
+    // Silently fail
+  }
+}