thirdweb 5.115.4 → 5.116.1

package/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
+  }
+}

package/src/x402/schemas.ts

@@ -45,6 +45,8 @@ const FacilitatorSettleResponseSchema = SettleResponseSchema.extend({
   network: FacilitatorNetworkSchema,
   errorMessage: z.string().optional(),
   fundWalletLink: z.string().optional(),
+  allowance: z.string().optional(),
+  balance: z.string().optional(),
 });
 export type FacilitatorSettleResponse = z.infer<
   typeof FacilitatorSettleResponseSchema
@@ -53,6 +55,8 @@ export type FacilitatorSettleResponse = z.infer<
 const FacilitatorVerifyResponseSchema = VerifyResponseSchema.extend({
   errorMessage: z.string().optional(),
   fundWalletLink: z.string().optional(),
+  allowance: z.string().optional(),
+  balance: z.string().optional(),
 });
 
 export type FacilitatorVerifyResponse = z.infer<

package/src/x402/sign.ts

@@ -3,12 +3,19 @@ import type { ExactEvmPayloadAuthorization } from "x402/types";
 import { getCachedChain } from "../chains/utils.js";
 import type { ThirdwebClient } from "../client/client.js";
 import { getContract } from "../contract/contract.js";
+import { allowance } from "../extensions/erc20/__generated__/IERC20/read/allowance.js";
 import { nonces } from "../extensions/erc20/__generated__/IERC20Permit/read/nonces.js";
 import { type Address, getAddress } from "../utils/address.js";
 import { type Hex, toHex } from "../utils/encoding/hex.js";
+import type { AsyncStorage } from "../utils/storage/AsyncStorage.js";
 import type { Account } from "../wallets/interfaces/wallet.js";
 import { getSupportedSignatureType } from "./common.js";
 import { encodePayment } from "./encode.js";
+import {
+  getPermitSignatureFromCache,
+  type PermitCacheKeyParams,
+  savePermitSignatureToCache,
+} from "./permitSignatureStorage.js";
 import {
   extractEvmChainId,
   networkToCaip2ChainId,
@@ -63,6 +70,7 @@ function preparePaymentHeader(
  * @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
+ * @param storage - Optional storage for caching permit signatures (for "upto" scheme)
  * @returns A promise that resolves to the signed payment payload
  */
 async function signPaymentHeader(
@@ -70,6 +78,7 @@ async function signPaymentHeader(
   account: Account,
   paymentRequirements: RequestedPaymentRequirements,
   x402Version: number,
+  storage?: AsyncStorage,
 ): Promise<RequestedPaymentPayload> {
   const from = getAddress(account.address);
   const caip2ChainId = networkToCaip2ChainId(paymentRequirements.network);
@@ -91,6 +100,55 @@ async function signPaymentHeader(
 
   switch (supportedSignatureType) {
     case "Permit": {
+      const shouldCache =
+        paymentRequirements.scheme === "upto" && storage !== undefined;
+      const spender = getAddress(paymentRequirements.payTo);
+
+      const cacheParams: PermitCacheKeyParams = {
+        chainId,
+        asset: paymentRequirements.asset,
+        owner: from,
+        spender,
+      };
+
+      // Try to reuse cached signature for "upto" scheme
+      if (shouldCache && storage) {
+        const cached = await getPermitSignatureFromCache(storage, cacheParams);
+
+        if (cached) {
+          // Validate deadline hasn't passed
+          const now = BigInt(Math.floor(Date.now() / 1000));
+          if (BigInt(cached.deadline) > now) {
+            // Check on-chain allowance
+            const currentAllowance = await allowance({
+              contract: getContract({
+                address: paymentRequirements.asset,
+                chain: getCachedChain(chainId),
+                client,
+              }),
+              owner: from,
+              spender,
+            });
+
+            // Determine threshold - use minAmountRequired if present, else maxAmountRequired
+            const extra = paymentRequirements.extra as
+              | (ERC20TokenAmount["asset"]["eip712"] & {
+                  minAmountRequired?: string;
+                })
+              | undefined;
+            const threshold = extra?.minAmountRequired
+              ? BigInt(extra.minAmountRequired)
+              : BigInt(paymentRequirements.maxAmountRequired);
+
+            // If allowance >= threshold, reuse signature
+            if (currentAllowance >= threshold) {
+              return cached.payload;
+            }
+          }
+        }
+      }
+
+      // Generate new signature
       const nonce = await nonces({
         contract: getContract({
           address: paymentRequirements.asset,
@@ -110,13 +168,27 @@ async function signPaymentHeader(
         unsignedPaymentHeader.payload.authorization,
         paymentRequirements,
       );
-      return {
+
+      const signedPayload: RequestedPaymentPayload = {
         ...unsignedPaymentHeader,
         payload: {
           ...unsignedPaymentHeader.payload,
           signature,
         },
       };
+
+      // Cache the signature for "upto" scheme
+      if (shouldCache && storage) {
+        await savePermitSignatureToCache(
+          storage,
+          cacheParams,
+          signedPayload,
+          unsignedPaymentHeader.payload.authorization.validBefore,
+          paymentRequirements.maxAmountRequired,
+        );
+      }
+
+      return signedPayload;
     }
     case "TransferWithAuthorization": {
       // default to transfer with authorization
@@ -153,6 +225,7 @@ async function signPaymentHeader(
  * @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
+ * @param storage - Optional storage for caching permit signatures (for "upto" scheme)
  * @returns A promise that resolves to the encoded payment header string
  */
 export async function createPaymentHeader(
@@ -160,12 +233,14 @@ export async function createPaymentHeader(
   account: Account,
   paymentRequirements: RequestedPaymentRequirements,
   x402Version: number,
+  storage?: AsyncStorage,
 ): Promise<string> {
   const payment = await signPaymentHeader(
     client,
     account,
     paymentRequirements,
     x402Version,
+    storage,
   );
   return encodePayment(payment);
 }

package/src/x402/types.ts

@@ -29,6 +29,8 @@ export type PaymentArgs = {
   network: FacilitatorNetwork | Chain;
   /** The price for accessing the resource - either a USD amount (e.g., "$0.10") or a specific token amount */
   price: Money | ERC20TokenAmount;
+  /** The minimum price for accessing the resource - Only applicable for the "upto" payment scheme */
+  minPrice?: Money | ERC20TokenAmount;
   /** The payment facilitator instance used to verify and settle payments */
   facilitator: ThirdwebX402Facilitator;
   /** The scheme of the payment, either "exact" or "upto", defaults to "exact" */
@@ -97,6 +99,12 @@ export type VerifyPaymentResult = Prettify<
       decodedPayment: RequestedPaymentPayload;
       /** The selected payment requirements */
       selectedPaymentRequirements: RequestedPaymentRequirements;
+      /** The current remaining allowance of the payment of the selected payment asset, only applicable for the "upto" payment scheme */
+      allowance?: string;
+      /** The current balance of the user's wallet in the selected payment asset */
+      balance?: string;
+      /** The payer address if verification succeeded */
+      payer?: string;
     }
   | PaymentRequiredResult
 >;

package/src/x402/verify-payment.ts

@@ -109,6 +109,9 @@ export async function verifyPayment(
         status: 200,
         decodedPayment,
         selectedPaymentRequirements,
+        allowance: verification.allowance,
+        balance: verification.balance,
+        payer: verification.payer,
       };
     } else {
       const error = verification.invalidReason || "Verification failed";