@x402/extensions 2.4.0 → 2.5.0

package/dist/cjs/index.d.ts

@@ -131,4 +131,230 @@ declare function extractEip2612GasSponsoringInfo(paymentPayload: PaymentPayload)
  */
 declare function validateEip2612GasSponsoringInfo(info: Eip2612GasSponsoringInfo): boolean;
 
-export { EIP2612_GAS_SPONSORING, type Eip2612GasSponsoringExtension, type Eip2612GasSponsoringInfo, type Eip2612GasSponsoringServerInfo, declareEip2612GasSponsoringExtension, extractEip2612GasSponsoringInfo, validateEip2612GasSponsoringInfo };
+/**
+ * Type definitions for the ERC-20 Approval Gas Sponsoring Extension
+ *
+ * This extension enables gasless Permit2 approval for generic ERC-20 tokens
+ * that do NOT implement EIP-2612. The client signs (but does not broadcast) a
+ * raw `approve(Permit2, MaxUint256)` transaction, and the facilitator broadcasts
+ * it atomically before settling the Permit2 payment.
+ */
+
+/**
+ * Signer capability carried by the ERC-20 approval extension when registered in a facilitator.
+ *
+ * Mirrors FacilitatorEvmSigner (from @x402/evm) plus `sendRawTransaction`.
+ * The extension signer owns the full approve+settle flow: it broadcasts the
+ * pre-signed approval transaction AND executes the Permit2 settle call, enabling
+ * production implementations to bundle both atomically (e.g., Flashbots, multicall).
+ *
+ * The method signatures are duplicated here (rather than extending FacilitatorEvmSigner)
+ * to avoid a circular dependency between @x402/extensions and @x402/evm.
+ */
+interface Erc20ApprovalGasSponsoringSigner {
+    getAddresses(): readonly `0x${string}`[];
+    readContract(args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+    }): Promise<unknown>;
+    verifyTypedData(args: {
+        address: `0x${string}`;
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+        signature: `0x${string}`;
+    }): Promise<boolean>;
+    writeContract(args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args: readonly unknown[];
+    }): Promise<`0x${string}`>;
+    sendTransaction(args: {
+        to: `0x${string}`;
+        data: `0x${string}`;
+    }): Promise<`0x${string}`>;
+    waitForTransactionReceipt(args: {
+        hash: `0x${string}`;
+    }): Promise<{
+        status: string;
+    }>;
+    getCode(args: {
+        address: `0x${string}`;
+    }): Promise<`0x${string}` | undefined>;
+    sendRawTransaction(args: {
+        serializedTransaction: `0x${string}`;
+    }): Promise<`0x${string}`>;
+}
+/**
+ * Extension identifier for the ERC-20 approval gas sponsoring extension.
+ */
+declare const ERC20_APPROVAL_GAS_SPONSORING: {
+    readonly key: "erc20ApprovalGasSponsoring";
+};
+/** Current schema version for the ERC-20 approval gas sponsoring extension info. */
+declare const ERC20_APPROVAL_GAS_SPONSORING_VERSION = "1";
+/**
+ * Extended extension object registered in a facilitator via registerExtension().
+ * Carries the signer that owns the full approve+settle flow for ERC-20 tokens
+ * that lack EIP-2612. The signer must have all FacilitatorEvmSigner capabilities
+ * plus `sendRawTransaction` for broadcasting the pre-signed approval tx.
+ *
+ * @example
+ * ```typescript
+ * import { createErc20ApprovalGasSponsoringExtension } from '@x402/extensions';
+ *
+ * facilitator.registerExtension(
+ *   createErc20ApprovalGasSponsoringExtension(evmSigner, viemClient),
+ * );
+ * ```
+ */
+interface Erc20ApprovalGasSponsoringFacilitatorExtension extends FacilitatorExtension {
+    key: "erc20ApprovalGasSponsoring";
+    /** Signer with broadcast + settle capability. Optional — settlement fails gracefully if absent. */
+    signer?: Erc20ApprovalGasSponsoringSigner;
+}
+/**
+ * Signer input for {@link createErc20ApprovalGasSponsoringExtension}.
+ * Matches the FacilitatorEvmSigner shape from @x402/evm (duplicated to avoid circular dep).
+ */
+type Erc20ApprovalGasSponsoringBaseSigner = Omit<Erc20ApprovalGasSponsoringSigner, "sendRawTransaction">;
+/**
+ * Create an ERC-20 approval gas sponsoring extension ready to register in a facilitator.
+ *
+ * @param signer - The EVM facilitator signer (e.g. from `toFacilitatorEvmSigner()`)
+ * @param client - Object providing `sendRawTransaction` (e.g. a viem WalletClient)
+ * @param client.sendRawTransaction - Broadcasts a signed transaction to the network
+ * @returns A fully configured extension to pass to `facilitator.registerExtension()`
+ */
+declare function createErc20ApprovalGasSponsoringExtension(signer: Erc20ApprovalGasSponsoringBaseSigner, client: {
+    sendRawTransaction: (args: {
+        serializedTransaction: `0x${string}`;
+    }) => Promise<`0x${string}`>;
+}): Erc20ApprovalGasSponsoringFacilitatorExtension;
+/**
+ * ERC-20 approval gas sponsoring info populated by the client.
+ *
+ * Contains the RLP-encoded signed `approve(Permit2, MaxUint256)` transaction
+ * that the facilitator broadcasts before settling the Permit2 payment.
+ *
+ * Note: Unlike EIP-2612, there is no nonce/deadline/signature — instead the
+ * entire signed transaction is included as `signedTransaction`.
+ */
+interface Erc20ApprovalGasSponsoringInfo {
+    /** Index signature for compatibility with Record<string, unknown> */
+    [key: string]: unknown;
+    /** The address of the sender (token owner who signed the tx). */
+    from: `0x${string}`;
+    /** The address of the ERC-20 token contract. */
+    asset: `0x${string}`;
+    /** The address of the spender (Canonical Permit2). */
+    spender: `0x${string}`;
+    /** The amount approved (uint256 as decimal string). Always MaxUint256. */
+    amount: string;
+    /** The RLP-encoded signed EIP-1559 transaction as a hex string. */
+    signedTransaction: `0x${string}`;
+    /** Schema version identifier. */
+    version: string;
+}
+/**
+ * Server-side ERC-20 approval gas sponsoring info included in PaymentRequired.
+ * Contains a description and version; the client populates the rest.
+ */
+interface Erc20ApprovalGasSponsoringServerInfo {
+    /** Index signature for compatibility with Record<string, unknown> */
+    [key: string]: unknown;
+    /** Human-readable description of the extension. */
+    description: string;
+    /** Schema version identifier. */
+    version: string;
+}
+/**
+ * The full extension object as it appears in PaymentRequired.extensions
+ * and PaymentPayload.extensions.
+ */
+interface Erc20ApprovalGasSponsoringExtension {
+    /** Extension info - server-provided or client-enriched. */
+    info: Erc20ApprovalGasSponsoringServerInfo | Erc20ApprovalGasSponsoringInfo;
+    /** JSON Schema describing the expected structure of info. */
+    schema: Record<string, unknown>;
+}
+
+/**
+ * Resource Service functions for declaring the ERC-20 Approval Gas Sponsoring extension.
+ *
+ * These functions help servers declare support for ERC-20 approval gas sponsoring
+ * in the PaymentRequired response extensions. Use this for tokens that do NOT
+ * implement EIP-2612 (generic ERC-20 tokens).
+ */
+
+/**
+ * The JSON Schema for the ERC-20 approval gas sponsoring extension info.
+ * Matches the schema defined in the spec.
+ */
+declare const erc20ApprovalGasSponsoringSchema: Record<string, unknown>;
+/**
+ * Declares the ERC-20 approval gas sponsoring extension for inclusion in
+ * PaymentRequired.extensions.
+ *
+ * The server advertises that it (or its facilitator) supports broadcasting
+ * a pre-signed `approve(Permit2, MaxUint256)` transaction on the client's behalf.
+ * Use this for tokens that do NOT implement EIP-2612.
+ *
+ * @returns An object keyed by the extension identifier containing the extension declaration
+ *
+ * @example
+ * ```typescript
+ * import { declareErc20ApprovalGasSponsoringExtension } from '@x402/extensions';
+ *
+ * const routes = [
+ *   {
+ *     path: "/api/data",
+ *     price: { amount: "1000", asset: "0x...", extra: { assetTransferMethod: "permit2" } },
+ *     extensions: {
+ *       ...declareErc20ApprovalGasSponsoringExtension(),
+ *     },
+ *   },
+ * ];
+ * ```
+ */
+declare function declareErc20ApprovalGasSponsoringExtension(): Record<string, Erc20ApprovalGasSponsoringExtension>;
+
+/**
+ * Facilitator functions for extracting and validating ERC-20 Approval Gas Sponsoring
+ * extension data.
+ *
+ * These functions help facilitators extract the pre-signed approve() transaction
+ * from payment payloads and validate it before broadcasting and settling.
+ */
+
+/**
+ * Extracts the ERC-20 approval gas sponsoring info from a payment payload's extensions.
+ *
+ * Performs structural extraction only — checks that the extension is present and
+ * contains all required fields. Does NOT validate field formats (use
+ * validateErc20ApprovalGasSponsoringInfo for that).
+ *
+ * @param paymentPayload - The payment payload to extract from
+ * @returns The ERC-20 approval gas sponsoring info, or null if not present
+ */
+declare function extractErc20ApprovalGasSponsoringInfo(paymentPayload: PaymentPayload): Erc20ApprovalGasSponsoringInfo | null;
+/**
+ * Validates that the ERC-20 approval gas sponsoring info has valid format.
+ *
+ * Validates the info against the canonical JSON Schema, checking:
+ * - All required fields are present
+ * - Addresses are valid hex (0x + 40 hex chars)
+ * - Amount is a numeric string
+ * - signedTransaction is a hex string
+ * - Version is a numeric version string
+ *
+ * @param info - The ERC-20 approval gas sponsoring info to validate
+ * @returns True if the info is valid, false otherwise
+ */
+declare function validateErc20ApprovalGasSponsoringInfo(info: Erc20ApprovalGasSponsoringInfo): boolean;
+
+export { EIP2612_GAS_SPONSORING, ERC20_APPROVAL_GAS_SPONSORING, ERC20_APPROVAL_GAS_SPONSORING_VERSION, type Eip2612GasSponsoringExtension, type Eip2612GasSponsoringInfo, type Eip2612GasSponsoringServerInfo, type Erc20ApprovalGasSponsoringBaseSigner, type Erc20ApprovalGasSponsoringExtension, type Erc20ApprovalGasSponsoringFacilitatorExtension, type Erc20ApprovalGasSponsoringInfo, type Erc20ApprovalGasSponsoringServerInfo, type Erc20ApprovalGasSponsoringSigner, createErc20ApprovalGasSponsoringExtension, declareEip2612GasSponsoringExtension, declareErc20ApprovalGasSponsoringExtension, erc20ApprovalGasSponsoringSchema, extractEip2612GasSponsoringInfo, extractErc20ApprovalGasSponsoringInfo, validateEip2612GasSponsoringInfo, validateErc20ApprovalGasSponsoringInfo };

package/dist/cjs/index.js

@@ -32,6 +32,8 @@ var src_exports = {};
 __export(src_exports, {
   BAZAAR: () => BAZAAR,
   EIP2612_GAS_SPONSORING: () => EIP2612_GAS_SPONSORING,
+  ERC20_APPROVAL_GAS_SPONSORING: () => ERC20_APPROVAL_GAS_SPONSORING,
+  ERC20_APPROVAL_GAS_SPONSORING_VERSION: () => ERC20_APPROVAL_GAS_SPONSORING_VERSION,
   InMemorySIWxStorage: () => InMemorySIWxStorage,
   PAYMENT_IDENTIFIER: () => PAYMENT_IDENTIFIER,
   PAYMENT_ID_MAX_LENGTH: () => PAYMENT_ID_MAX_LENGTH,
@@ -45,6 +47,7 @@ __export(src_exports, {
   appendPaymentIdentifierToExtensions: () => appendPaymentIdentifierToExtensions,
   bazaarResourceServerExtension: () => bazaarResourceServerExtension,
   buildSIWxSchema: () => buildSIWxSchema,
+  createErc20ApprovalGasSponsoringExtension: () => createErc20ApprovalGasSponsoringExtension,
   createSIWxClientHook: () => createSIWxClientHook,
   createSIWxMessage: () => createSIWxMessage,
   createSIWxPayload: () => createSIWxPayload,
@@ -52,17 +55,20 @@ __export(src_exports, {
   createSIWxSettleHook: () => createSIWxSettleHook,
   declareDiscoveryExtension: () => declareDiscoveryExtension,
   declareEip2612GasSponsoringExtension: () => declareEip2612GasSponsoringExtension,
+  declareErc20ApprovalGasSponsoringExtension: () => declareErc20ApprovalGasSponsoringExtension,
   declarePaymentIdentifierExtension: () => declarePaymentIdentifierExtension,
   declareSIWxExtension: () => declareSIWxExtension,
   decodeBase58: () => decodeBase58,
   encodeBase58: () => encodeBase58,
   encodeSIWxHeader: () => encodeSIWxHeader,
+  erc20ApprovalGasSponsoringSchema: () => erc20ApprovalGasSponsoringSchema,
   extractAndValidatePaymentIdentifier: () => extractAndValidatePaymentIdentifier,
   extractDiscoveryInfo: () => extractDiscoveryInfo,
   extractDiscoveryInfoFromExtension: () => extractDiscoveryInfoFromExtension,
   extractDiscoveryInfoV1: () => extractDiscoveryInfoV1,
   extractEVMChainId: () => extractEVMChainId,
   extractEip2612GasSponsoringInfo: () => extractEip2612GasSponsoringInfo,
+  extractErc20ApprovalGasSponsoringInfo: () => extractErc20ApprovalGasSponsoringInfo,
   extractPaymentIdentifier: () => extractPaymentIdentifier,
   extractResourceMetadataV1: () => extractResourceMetadataV1,
   extractSolanaChainReference: () => extractSolanaChainReference,
@@ -90,6 +96,7 @@ __export(src_exports, {
   validateAndExtract: () => validateAndExtract,
   validateDiscoveryExtension: () => validateDiscoveryExtension,
   validateEip2612GasSponsoringInfo: () => validateEip2612GasSponsoringInfo,
+  validateErc20ApprovalGasSponsoringInfo: () => validateErc20ApprovalGasSponsoringInfo,
   validatePaymentIdentifier: () => validatePaymentIdentifier,
   validatePaymentIdentifierRequirement: () => validatePaymentIdentifierRequirement,
   validateSIWxMessage: () => validateSIWxMessage,
@@ -1318,7 +1325,9 @@ function createSIWxSettleHook(options) {
     if (!ctx.result.success) return;
     const address = ctx.result.payer;
     if (!address) return;
-    const resource = new URL(ctx.paymentPayload.resource.url).pathname;
+    const resourceUrl = ctx.paymentPayload.resource?.url;
+    if (!resourceUrl) return;
+    const resource = new URL(resourceUrl).pathname;
     await storage.recordPayment(resource, address);
     onEvent?.({ type: "payment_recorded", resource, address });
   };
@@ -1702,10 +1711,100 @@ function validateEip2612GasSponsoringInfo(info) {
   const versionPattern = /^[0-9]+(\.[0-9]+)*$/;
   return addressPattern.test(info.from) && addressPattern.test(info.asset) && addressPattern.test(info.spender) && numericPattern.test(info.amount) && numericPattern.test(info.nonce) && numericPattern.test(info.deadline) && hexPattern.test(info.signature) && versionPattern.test(info.version);
 }
+
+// src/erc20-approval-gas-sponsoring/types.ts
+var ERC20_APPROVAL_GAS_SPONSORING = {
+  key: "erc20ApprovalGasSponsoring"
+};
+var ERC20_APPROVAL_GAS_SPONSORING_VERSION = "1";
+function createErc20ApprovalGasSponsoringExtension(signer, client) {
+  return {
+    ...ERC20_APPROVAL_GAS_SPONSORING,
+    signer: {
+      ...signer,
+      sendRawTransaction: client.sendRawTransaction.bind(client)
+    }
+  };
+}
+
+// src/erc20-approval-gas-sponsoring/resourceService.ts
+var erc20ApprovalGasSponsoringSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  type: "object",
+  properties: {
+    from: {
+      type: "string",
+      pattern: "^0x[a-fA-F0-9]{40}$",
+      description: "The address of the sender (token owner)."
+    },
+    asset: {
+      type: "string",
+      pattern: "^0x[a-fA-F0-9]{40}$",
+      description: "The address of the ERC-20 token contract."
+    },
+    spender: {
+      type: "string",
+      pattern: "^0x[a-fA-F0-9]{40}$",
+      description: "The address of the spender (Canonical Permit2)."
+    },
+    amount: {
+      type: "string",
+      pattern: "^[0-9]+$",
+      description: "The amount approved (uint256). Always MaxUint256."
+    },
+    signedTransaction: {
+      type: "string",
+      pattern: "^0x[a-fA-F0-9]+$",
+      description: "The RLP-encoded signed EIP-1559 transaction as a hex string."
+    },
+    version: {
+      type: "string",
+      pattern: "^[0-9]+(\\.[0-9]+)*$",
+      description: "Schema version identifier."
+    }
+  },
+  required: ["from", "asset", "spender", "amount", "signedTransaction", "version"]
+};
+function declareErc20ApprovalGasSponsoringExtension() {
+  const key = ERC20_APPROVAL_GAS_SPONSORING.key;
+  return {
+    [key]: {
+      info: {
+        description: "The facilitator broadcasts a pre-signed ERC-20 approve() transaction to grant Permit2 allowance.",
+        version: ERC20_APPROVAL_GAS_SPONSORING_VERSION
+      },
+      schema: erc20ApprovalGasSponsoringSchema
+    }
+  };
+}
+
+// src/erc20-approval-gas-sponsoring/facilitator.ts
+var import__3 = __toESM(require("ajv/dist/2020.js"));
+function extractErc20ApprovalGasSponsoringInfo(paymentPayload) {
+  if (!paymentPayload.extensions) {
+    return null;
+  }
+  const extension = paymentPayload.extensions[ERC20_APPROVAL_GAS_SPONSORING.key];
+  if (!extension?.info) {
+    return null;
+  }
+  const info = extension.info;
+  if (!info.from || !info.asset || !info.spender || !info.amount || !info.signedTransaction || !info.version) {
+    return null;
+  }
+  return info;
+}
+function validateErc20ApprovalGasSponsoringInfo(info) {
+  const ajv = new import__3.default({ strict: false, allErrors: true });
+  const validate = ajv.compile(erc20ApprovalGasSponsoringSchema);
+  return validate(info);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BAZAAR,
   EIP2612_GAS_SPONSORING,
+  ERC20_APPROVAL_GAS_SPONSORING,
+  ERC20_APPROVAL_GAS_SPONSORING_VERSION,
   InMemorySIWxStorage,
   PAYMENT_IDENTIFIER,
   PAYMENT_ID_MAX_LENGTH,
@@ -1719,6 +1818,7 @@ function validateEip2612GasSponsoringInfo(info) {
   appendPaymentIdentifierToExtensions,
   bazaarResourceServerExtension,
   buildSIWxSchema,
+  createErc20ApprovalGasSponsoringExtension,
   createSIWxClientHook,
   createSIWxMessage,
   createSIWxPayload,
@@ -1726,17 +1826,20 @@ function validateEip2612GasSponsoringInfo(info) {
   createSIWxSettleHook,
   declareDiscoveryExtension,
   declareEip2612GasSponsoringExtension,
+  declareErc20ApprovalGasSponsoringExtension,
   declarePaymentIdentifierExtension,
   declareSIWxExtension,
   decodeBase58,
   encodeBase58,
   encodeSIWxHeader,
+  erc20ApprovalGasSponsoringSchema,
   extractAndValidatePaymentIdentifier,
   extractDiscoveryInfo,
   extractDiscoveryInfoFromExtension,
   extractDiscoveryInfoV1,
   extractEVMChainId,
   extractEip2612GasSponsoringInfo,
+  extractErc20ApprovalGasSponsoringInfo,
   extractPaymentIdentifier,
   extractResourceMetadataV1,
   extractSolanaChainReference,
@@ -1764,6 +1867,7 @@ function validateEip2612GasSponsoringInfo(info) {
   validateAndExtract,
   validateDiscoveryExtension,
   validateEip2612GasSponsoringInfo,
+  validateErc20ApprovalGasSponsoringInfo,
   validatePaymentIdentifier,
   validatePaymentIdentifierRequirement,
   validateSIWxMessage,