@t402/extensions 2.5.0 → 2.6.1

package/dist/cjs/eip2612-gas-sponsoring/index.js

@@ -0,0 +1,314 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/eip2612-gas-sponsoring/index.ts
+var eip2612_gas_sponsoring_exports = {};
+__export(eip2612_gas_sponsoring_exports, {
+  EIP2612_GAS_SPONSOR_EXTENSION_KEY: () => EIP2612_GAS_SPONSOR_EXTENSION_KEY,
+  EIP2612_GAS_SPONSOR_HEADER_NAME: () => EIP2612_GAS_SPONSOR_HEADER_NAME,
+  buildPermitCallData: () => buildPermitCallData,
+  createEip2612GasSponsorPayload: () => createEip2612GasSponsorPayload,
+  createPermitSignature: () => createPermitSignature,
+  declareEip2612GasSponsorExtension: () => declareEip2612GasSponsorExtension,
+  encodeEip2612GasSponsorHeader: () => encodeEip2612GasSponsorHeader,
+  extractEip2612GasSponsorPayload: () => extractEip2612GasSponsorPayload,
+  parseEip2612GasSponsorHeader: () => parseEip2612GasSponsorHeader,
+  validateAndExtractPermit: () => validateAndExtractPermit,
+  validateEip2612GasSponsorPayload: () => validateEip2612GasSponsorPayload
+});
+module.exports = __toCommonJS(eip2612_gas_sponsoring_exports);
+
+// src/eip2612-gas-sponsoring/server.ts
+var EIP2612_GAS_SPONSOR_SCHEMA = {
+  type: "object",
+  required: ["network", "permitSignature", "owner", "spender", "value", "deadline", "v", "r", "s"],
+  properties: {
+    network: { type: "string" },
+    permitSignature: { type: "string" },
+    owner: { type: "string" },
+    spender: { type: "string" },
+    value: { type: "string" },
+    deadline: { type: "number" },
+    v: { type: "number" },
+    r: { type: "string" },
+    s: { type: "string" }
+  }
+};
+function declareEip2612GasSponsorExtension(options) {
+  const info = {
+    sponsoredNetworks: options.sponsoredNetworks,
+    maxAmount: options.maxAmount,
+    permitDeadline: options.permitDeadline ?? 300,
+    sponsorAddress: options.sponsorAddress
+  };
+  return {
+    info,
+    schema: EIP2612_GAS_SPONSOR_SCHEMA
+  };
+}
+function parseEip2612GasSponsorHeader(header) {
+  if (!header) {
+    throw new Error("Missing EIP-2612 gas sponsor header");
+  }
+  try {
+    const decoded = Buffer.from(header, "base64").toString("utf-8");
+    const payload = JSON.parse(decoded);
+    const required = [
+      "network",
+      "permitSignature",
+      "owner",
+      "spender",
+      "value",
+      "deadline",
+      "v",
+      "r",
+      "s"
+    ];
+    for (const field of required) {
+      if (!(field in payload)) {
+        throw new Error(`Missing required field: ${field}`);
+      }
+    }
+    return payload;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error("Invalid EIP-2612 gas sponsor header: malformed JSON");
+    }
+    throw error;
+  }
+}
+function validateEip2612GasSponsorPayload(payload, extensionInfo, options = {}) {
+  const now = options.now ? options.now() : Date.now();
+  const nowSeconds = Math.floor(now / 1e3);
+  if (!extensionInfo.sponsoredNetworks.includes(payload.network)) {
+    return {
+      valid: false,
+      error: `Network ${payload.network} is not in sponsored networks: ${extensionInfo.sponsoredNetworks.join(", ")}`
+    };
+  }
+  const payloadValue = BigInt(payload.value);
+  const maxAmount = BigInt(extensionInfo.maxAmount);
+  if (payloadValue > maxAmount) {
+    return {
+      valid: false,
+      error: `Value ${payload.value} exceeds maximum amount ${extensionInfo.maxAmount}`
+    };
+  }
+  if (payload.deadline <= nowSeconds) {
+    return {
+      valid: false,
+      error: "Permit deadline has expired"
+    };
+  }
+  const maxDeadline = nowSeconds + extensionInfo.permitDeadline;
+  if (payload.deadline > maxDeadline) {
+    return {
+      valid: false,
+      error: `Permit deadline ${payload.deadline} exceeds maximum allowed deadline ${maxDeadline}`
+    };
+  }
+  if (payload.spender.toLowerCase() !== extensionInfo.sponsorAddress.toLowerCase()) {
+    return {
+      valid: false,
+      error: `Spender ${payload.spender} does not match sponsor address ${extensionInfo.sponsorAddress}`
+    };
+  }
+  const sigHex = payload.permitSignature.startsWith("0x") ? payload.permitSignature.slice(2) : payload.permitSignature;
+  if (sigHex.length !== 130) {
+    return {
+      valid: false,
+      error: `Invalid permit signature length: expected 130 hex chars, got ${sigHex.length}`
+    };
+  }
+  if (payload.v !== 27 && payload.v !== 28) {
+    return {
+      valid: false,
+      error: `Invalid v value: expected 27 or 28, got ${payload.v}`
+    };
+  }
+  const rHex = payload.r.startsWith("0x") ? payload.r.slice(2) : payload.r;
+  if (rHex.length !== 64) {
+    return {
+      valid: false,
+      error: `Invalid r length: expected 64 hex chars, got ${rHex.length}`
+    };
+  }
+  const sHex = payload.s.startsWith("0x") ? payload.s.slice(2) : payload.s;
+  if (sHex.length !== 64) {
+    return {
+      valid: false,
+      error: `Invalid s length: expected 64 hex chars, got ${sHex.length}`
+    };
+  }
+  return { valid: true };
+}
+
+// src/eip2612-gas-sponsoring/client.ts
+var EIP2612_GAS_SPONSOR_EXTENSION_KEY = "eip2612GasSponsoring";
+var EIP2612_GAS_SPONSOR_HEADER_NAME = "X-T402-EIP2612-Gas-Sponsoring";
+async function createPermitSignature(params) {
+  const { signer, tokenAddress, tokenName, chainId, spender, value, deadline, nonce = 0 } = params;
+  const domain = {
+    name: tokenName,
+    version: "1",
+    chainId,
+    verifyingContract: tokenAddress
+  };
+  const types = {
+    Permit: [
+      { name: "owner", type: "address" },
+      { name: "spender", type: "address" },
+      { name: "value", type: "uint256" },
+      { name: "nonce", type: "uint256" },
+      { name: "deadline", type: "uint256" }
+    ]
+  };
+  const message = {
+    owner: signer.address,
+    spender,
+    value,
+    nonce,
+    deadline
+  };
+  const signature = await signer.signTypedData({
+    domain,
+    types,
+    primaryType: "Permit",
+    message
+  });
+  const sigHex = signature.startsWith("0x") ? signature.slice(2) : signature;
+  if (sigHex.length !== 130) {
+    throw new Error(`Invalid signature length: expected 130 hex chars, got ${sigHex.length}`);
+  }
+  const r = "0x" + sigHex.slice(0, 64);
+  const s = "0x" + sigHex.slice(64, 128);
+  let v = parseInt(sigHex.slice(128, 130), 16);
+  if (v < 27) {
+    v += 27;
+  }
+  return {
+    owner: signer.address,
+    spender,
+    value,
+    deadline,
+    v,
+    r,
+    s,
+    permitSignature: signature.startsWith("0x") ? signature : "0x" + signature
+  };
+}
+function createEip2612GasSponsorPayload(permit, network) {
+  return {
+    network,
+    permitSignature: permit.permitSignature,
+    owner: permit.owner,
+    spender: permit.spender,
+    value: permit.value,
+    deadline: permit.deadline,
+    v: permit.v,
+    r: permit.r,
+    s: permit.s
+  };
+}
+function encodeEip2612GasSponsorHeader(payload) {
+  const json = JSON.stringify(payload);
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(json, "utf-8").toString("base64");
+  }
+  return btoa(json);
+}
+
+// src/eip2612-gas-sponsoring/facilitator.ts
+function extractEip2612GasSponsorPayload(extensions) {
+  if (!extensions) {
+    return null;
+  }
+  const raw = extensions[EIP2612_GAS_SPONSOR_EXTENSION_KEY];
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+  const payload = raw;
+  const required = [
+    "network",
+    "permitSignature",
+    "owner",
+    "spender",
+    "value",
+    "deadline",
+    "v",
+    "r",
+    "s"
+  ];
+  for (const field of required) {
+    if (!(field in payload)) {
+      return null;
+    }
+  }
+  return {
+    network: payload.network,
+    permitSignature: payload.permitSignature,
+    owner: payload.owner,
+    spender: payload.spender,
+    value: payload.value,
+    deadline: payload.deadline,
+    v: payload.v,
+    r: payload.r,
+    s: payload.s
+  };
+}
+function validateAndExtractPermit(extensions, extensionInfo) {
+  const payload = extractEip2612GasSponsorPayload(extensions);
+  if (!payload) {
+    return {
+      valid: false,
+      error: `Missing or invalid ${EIP2612_GAS_SPONSOR_EXTENSION_KEY} extension in payment`
+    };
+  }
+  const result = validateEip2612GasSponsorPayload(payload, extensionInfo);
+  if (!result.valid) {
+    return result;
+  }
+  return { valid: true, payload };
+}
+function buildPermitCallData(payload) {
+  return {
+    owner: payload.owner,
+    spender: payload.spender,
+    value: payload.value,
+    deadline: payload.deadline,
+    v: payload.v,
+    r: payload.r,
+    s: payload.s
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EIP2612_GAS_SPONSOR_EXTENSION_KEY,
+  EIP2612_GAS_SPONSOR_HEADER_NAME,
+  buildPermitCallData,
+  createEip2612GasSponsorPayload,
+  createPermitSignature,
+  declareEip2612GasSponsorExtension,
+  encodeEip2612GasSponsorHeader,
+  extractEip2612GasSponsorPayload,
+  parseEip2612GasSponsorHeader,
+  validateAndExtractPermit,
+  validateEip2612GasSponsorPayload
+});
+//# sourceMappingURL=index.js.map

package/dist/cjs/eip2612-gas-sponsoring/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/eip2612-gas-sponsoring/index.ts","../../../src/eip2612-gas-sponsoring/server.ts","../../../src/eip2612-gas-sponsoring/client.ts","../../../src/eip2612-gas-sponsoring/facilitator.ts"],"sourcesContent":["/**\n * @module eip2612-gas-sponsoring - t402 Payment Protocol EIP-2612 Gas Sponsoring Extension\n *\n * This module provides EIP-2612 permit-based gas sponsoring for the t402 protocol.\n * It allows facilitators to sponsor gas fees by having clients sign off-chain permits\n * instead of submitting on-chain approval transactions. The facilitator submits the\n * permit on-chain followed by settlement via Permit2.\n *\n * @example Server-side usage\n * ```typescript\n * import {\n *   declareEip2612GasSponsorExtension,\n *   parseEip2612GasSponsorHeader,\n *   validateEip2612GasSponsorPayload,\n * } from \"@t402/extensions/eip2612-gas-sponsoring\";\n *\n * // Declare extension in 402 response\n * const extension = declareEip2612GasSponsorExtension({\n *   sponsoredNetworks: [\"eip155:8453\", \"eip155:42161\"],\n *   maxAmount: \"1000000000\",\n *   sponsorAddress: \"0xFacilitator...\",\n * });\n *\n * // Parse and validate client header\n * const payload = parseEip2612GasSponsorHeader(\n *   request.headers['x-t402-eip2612-gas-sponsoring']\n * );\n * const result = validateEip2612GasSponsorPayload(payload, extension.info);\n * ```\n *\n * @example Client-side usage\n * ```typescript\n * import {\n *   createPermitSignature,\n *   createEip2612GasSponsorPayload,\n *   encodeEip2612GasSponsorHeader,\n *   EIP2612_GAS_SPONSOR_HEADER_NAME,\n * } from \"@t402/extensions/eip2612-gas-sponsoring\";\n *\n * const permit = await createPermitSignature({\n *   signer: wallet,\n *   tokenAddress: \"0xUSDT...\",\n *   tokenName: \"Tether USD\",\n *   chainId: 8453,\n *   spender: facilitatorAddress,\n *   value: \"1000000\",\n *   deadline: Math.floor(Date.now() / 1000) + 300,\n * });\n *\n * const payload = createEip2612GasSponsorPayload(permit, \"eip155:8453\");\n * fetch(url, {\n *   headers: { [EIP2612_GAS_SPONSOR_HEADER_NAME]: encodeEip2612GasSponsorHeader(payload) }\n * });\n * ```\n *\n * @example Facilitator-side usage\n * ```typescript\n * import {\n *   extractEip2612GasSponsorPayload,\n *   validateAndExtractPermit,\n *   buildPermitCallData,\n * } from \"@t402/extensions/eip2612-gas-sponsoring\";\n *\n * const result = validateAndExtractPermit(\n *   paymentPayload.extensions,\n *   extensionInfo\n * );\n * if (result.valid && result.payload) {\n *   const permitCall = buildPermitCallData(result.payload);\n *   // Submit permit() tx, then settle via Permit2\n * }\n * ```\n */\n\n// Type exports\nexport type {\n  Eip2612GasSponsorExtensionInfo,\n  Eip2612GasSponsorExtension,\n  Eip2612GasSponsorPayload,\n  DeclareEip2612GasSponsorOptions,\n  ValidateEip2612GasSponsorOptions,\n  Eip2612GasSponsorValidationResult,\n  CreatePermitParams,\n  PermitSigner,\n} from \"./types.js\";\n\n// Server exports\nexport {\n  declareEip2612GasSponsorExtension,\n  parseEip2612GasSponsorHeader,\n  validateEip2612GasSponsorPayload,\n} from \"./server.js\";\n\n// Client exports\nexport {\n  createPermitSignature,\n  createEip2612GasSponsorPayload,\n  encodeEip2612GasSponsorHeader,\n  EIP2612_GAS_SPONSOR_EXTENSION_KEY,\n  EIP2612_GAS_SPONSOR_HEADER_NAME,\n} from \"./client.js\";\n\n// Facilitator exports\nexport {\n  extractEip2612GasSponsorPayload,\n  validateAndExtractPermit,\n  buildPermitCallData,\n} from \"./facilitator.js\";\n","/**\n * EIP-2612 Gas Sponsoring Extension Server-Side Implementation\n *\n * Provides functions for servers to declare gas sponsoring requirements,\n * parse client headers, and validate permit payloads.\n */\n\nimport type {\n  Eip2612GasSponsorExtension,\n  Eip2612GasSponsorExtensionInfo,\n  Eip2612GasSponsorPayload,\n  DeclareEip2612GasSponsorOptions,\n  ValidateEip2612GasSponsorOptions,\n  Eip2612GasSponsorValidationResult,\n} from \"./types.js\";\n\n/**\n * JSON Schema for EIP-2612 gas sponsor payload validation.\n */\nconst EIP2612_GAS_SPONSOR_SCHEMA = {\n  type: \"object\",\n  required: [\"network\", \"permitSignature\", \"owner\", \"spender\", \"value\", \"deadline\", \"v\", \"r\", \"s\"],\n  properties: {\n    network: { type: \"string\" },\n    permitSignature: { type: \"string\" },\n    owner: { type: \"string\" },\n    spender: { type: \"string\" },\n    value: { type: \"string\" },\n    deadline: { type: \"number\" },\n    v: { type: \"number\" },\n    r: { type: \"string\" },\n    s: { type: \"string\" },\n  },\n};\n\n/**\n * Declares an EIP-2612 gas sponsor extension for server responses.\n *\n * @param options - Extension declaration options\n * @returns Gas sponsor extension object ready for response\n *\n * @example\n * ```typescript\n * const extension = declareEip2612GasSponsorExtension({\n *   sponsoredNetworks: [\"eip155:8453\", \"eip155:42161\"],\n *   maxAmount: \"1000000000\",\n *   sponsorAddress: \"0xFacilitator...\",\n * });\n * ```\n */\nexport function declareEip2612GasSponsorExtension(\n  options: DeclareEip2612GasSponsorOptions,\n): Eip2612GasSponsorExtension {\n  const info: Eip2612GasSponsorExtensionInfo = {\n    sponsoredNetworks: options.sponsoredNetworks,\n    maxAmount: options.maxAmount,\n    permitDeadline: options.permitDeadline ?? 300,\n    sponsorAddress: options.sponsorAddress,\n  };\n\n  return {\n    info,\n    schema: EIP2612_GAS_SPONSOR_SCHEMA,\n  };\n}\n\n/**\n * Parses an EIP-2612 gas sponsor header from client request.\n *\n * The header format is base64-encoded JSON.\n *\n * @param header - Base64-encoded gas sponsor header value\n * @returns Parsed gas sponsor payload\n * @throws Error if header is invalid\n *\n * @example\n * ```typescript\n * const payload = parseEip2612GasSponsorHeader(\n *   request.headers['x-t402-eip2612-gas-sponsoring']\n * );\n * ```\n */\nexport function parseEip2612GasSponsorHeader(header: string): Eip2612GasSponsorPayload {\n  if (!header) {\n    throw new Error(\"Missing EIP-2612 gas sponsor header\");\n  }\n\n  try {\n    const decoded = Buffer.from(header, \"base64\").toString(\"utf-8\");\n    const payload = JSON.parse(decoded) as Eip2612GasSponsorPayload;\n\n    const required = [\n      \"network\",\n      \"permitSignature\",\n      \"owner\",\n      \"spender\",\n      \"value\",\n      \"deadline\",\n      \"v\",\n      \"r\",\n      \"s\",\n    ];\n    for (const field of required) {\n      if (!(field in payload)) {\n        throw new Error(`Missing required field: ${field}`);\n      }\n    }\n\n    return payload;\n  } catch (error) {\n    if (error instanceof SyntaxError) {\n      throw new Error(\"Invalid EIP-2612 gas sponsor header: malformed JSON\");\n    }\n    throw error;\n  }\n}\n\n/**\n * Validates an EIP-2612 gas sponsor payload against server extension info.\n *\n * @param payload - The gas sponsor payload from the client\n * @param extensionInfo - The server's gas sponsor extension info\n * @param options - Validation options\n * @returns Validation result\n *\n * @example\n * ```typescript\n * const result = validateEip2612GasSponsorPayload(payload, extension.info);\n * if (!result.valid) {\n *   throw new Error(result.error);\n * }\n * ```\n */\nexport function validateEip2612GasSponsorPayload(\n  payload: Eip2612GasSponsorPayload,\n  extensionInfo: Eip2612GasSponsorExtensionInfo,\n  options: ValidateEip2612GasSponsorOptions = {},\n): Eip2612GasSponsorValidationResult {\n  const now = options.now ? options.now() : Date.now();\n  const nowSeconds = Math.floor(now / 1000);\n\n  // Validate network is in sponsoredNetworks\n  if (!extensionInfo.sponsoredNetworks.includes(payload.network)) {\n    return {\n      valid: false,\n      error: `Network ${payload.network} is not in sponsored networks: ${extensionInfo.sponsoredNetworks.join(\", \")}`,\n    };\n  }\n\n  // Validate amount does not exceed maxAmount\n  const payloadValue = BigInt(payload.value);\n  const maxAmount = BigInt(extensionInfo.maxAmount);\n  if (payloadValue > maxAmount) {\n    return {\n      valid: false,\n      error: `Value ${payload.value} exceeds maximum amount ${extensionInfo.maxAmount}`,\n    };\n  }\n\n  // Validate deadline is in the future\n  if (payload.deadline <= nowSeconds) {\n    return {\n      valid: false,\n      error: \"Permit deadline has expired\",\n    };\n  }\n\n  // Validate deadline does not exceed permitDeadline seconds from now\n  const maxDeadline = nowSeconds + extensionInfo.permitDeadline;\n  if (payload.deadline > maxDeadline) {\n    return {\n      valid: false,\n      error: `Permit deadline ${payload.deadline} exceeds maximum allowed deadline ${maxDeadline}`,\n    };\n  }\n\n  // Validate spender matches sponsorAddress\n  if (payload.spender.toLowerCase() !== extensionInfo.sponsorAddress.toLowerCase()) {\n    return {\n      valid: false,\n      error: `Spender ${payload.spender} does not match sponsor address ${extensionInfo.sponsorAddress}`,\n    };\n  }\n\n  // Validate permitSignature format (65 bytes = 130 hex chars)\n  const sigHex = payload.permitSignature.startsWith(\"0x\")\n    ? payload.permitSignature.slice(2)\n    : payload.permitSignature;\n  if (sigHex.length !== 130) {\n    return {\n      valid: false,\n      error: `Invalid permit signature length: expected 130 hex chars, got ${sigHex.length}`,\n    };\n  }\n\n  // Validate v is 27 or 28\n  if (payload.v !== 27 && payload.v !== 28) {\n    return {\n      valid: false,\n      error: `Invalid v value: expected 27 or 28, got ${payload.v}`,\n    };\n  }\n\n  // Validate r format (32 bytes = 64 hex chars)\n  const rHex = payload.r.startsWith(\"0x\") ? payload.r.slice(2) : payload.r;\n  if (rHex.length !== 64) {\n    return {\n      valid: false,\n      error: `Invalid r length: expected 64 hex chars, got ${rHex.length}`,\n    };\n  }\n\n  // Validate s format (32 bytes = 64 hex chars)\n  const sHex = payload.s.startsWith(\"0x\") ? payload.s.slice(2) : payload.s;\n  if (sHex.length !== 64) {\n    return {\n      valid: false,\n      error: `Invalid s length: expected 64 hex chars, got ${sHex.length}`,\n    };\n  }\n\n  return { valid: true };\n}\n","/**\n * EIP-2612 Gas Sponsoring Extension Client-Side Implementation\n *\n * Provides functions for clients to create EIP-2612 permit signatures\n * and encode gas sponsor payloads for transmission.\n */\n\nimport type { Eip2612GasSponsorPayload, CreatePermitParams } from \"./types.js\";\n\n/**\n * Extension key for EIP-2612 gas sponsoring in payment requirements.\n */\nexport const EIP2612_GAS_SPONSOR_EXTENSION_KEY = \"eip2612GasSponsoring\";\n\n/**\n * HTTP header name for EIP-2612 gas sponsor payload.\n */\nexport const EIP2612_GAS_SPONSOR_HEADER_NAME = \"X-T402-EIP2612-Gas-Sponsoring\";\n\n/**\n * Creates an EIP-2612 permit signature using EIP-712 typed data signing.\n *\n * @param params - Permit signing parameters\n * @returns Permit data including the signature components\n *\n * @example\n * ```typescript\n * const permit = await createPermitSignature({\n *   signer: wallet,\n *   tokenAddress: \"0xUSDT...\",\n *   tokenName: \"Tether USD\",\n *   chainId: 8453,\n *   spender: facilitatorAddress,\n *   value: \"1000000\",\n *   deadline: Math.floor(Date.now() / 1000) + 300,\n * });\n * ```\n */\nexport async function createPermitSignature(params: CreatePermitParams): Promise<{\n  owner: string;\n  spender: string;\n  value: string;\n  deadline: number;\n  v: number;\n  r: string;\n  s: string;\n  permitSignature: string;\n}> {\n  const { signer, tokenAddress, tokenName, chainId, spender, value, deadline, nonce = 0 } = params;\n\n  const domain = {\n    name: tokenName,\n    version: \"1\",\n    chainId,\n    verifyingContract: tokenAddress,\n  };\n\n  const types = {\n    Permit: [\n      { name: \"owner\", type: \"address\" },\n      { name: \"spender\", type: \"address\" },\n      { name: \"value\", type: \"uint256\" },\n      { name: \"nonce\", type: \"uint256\" },\n      { name: \"deadline\", type: \"uint256\" },\n    ],\n  };\n\n  const message = {\n    owner: signer.address,\n    spender,\n    value,\n    nonce,\n    deadline,\n  };\n\n  const signature = await signer.signTypedData({\n    domain,\n    types,\n    primaryType: \"Permit\",\n    message,\n  });\n\n  // Parse signature into components\n  const sigHex = signature.startsWith(\"0x\") ? signature.slice(2) : signature;\n\n  if (sigHex.length !== 130) {\n    throw new Error(`Invalid signature length: expected 130 hex chars, got ${sigHex.length}`);\n  }\n\n  const r = \"0x\" + sigHex.slice(0, 64);\n  const s = \"0x\" + sigHex.slice(64, 128);\n  let v = parseInt(sigHex.slice(128, 130), 16);\n\n  // Normalize v to 27 or 28\n  if (v < 27) {\n    v += 27;\n  }\n\n  return {\n    owner: signer.address,\n    spender,\n    value,\n    deadline,\n    v,\n    r,\n    s,\n    permitSignature: signature.startsWith(\"0x\") ? signature : \"0x\" + signature,\n  };\n}\n\n/**\n * Creates a gas sponsor payload from permit data and network.\n *\n * @param permit - Permit signature data from createPermitSignature\n * @param network - CAIP-2 network identifier (e.g., \"eip155:8453\")\n * @returns Gas sponsor payload ready for header encoding\n *\n * @example\n * ```typescript\n * const payload = createEip2612GasSponsorPayload(permit, \"eip155:8453\");\n * ```\n */\nexport function createEip2612GasSponsorPayload(\n  permit: {\n    owner: string;\n    spender: string;\n    value: string;\n    deadline: number;\n    v: number;\n    r: string;\n    s: string;\n    permitSignature: string;\n  },\n  network: string,\n): Eip2612GasSponsorPayload {\n  return {\n    network,\n    permitSignature: permit.permitSignature,\n    owner: permit.owner,\n    spender: permit.spender,\n    value: permit.value,\n    deadline: permit.deadline,\n    v: permit.v,\n    r: permit.r,\n    s: permit.s,\n  };\n}\n\n/**\n * Encodes a gas sponsor payload for transmission in HTTP header.\n *\n * @param payload - The gas sponsor payload to encode\n * @returns Base64-encoded JSON string\n *\n * @example\n * ```typescript\n * const header = encodeEip2612GasSponsorHeader(payload);\n * fetch(url, {\n *   headers: { [EIP2612_GAS_SPONSOR_HEADER_NAME]: header }\n * });\n * ```\n */\nexport function encodeEip2612GasSponsorHeader(payload: Eip2612GasSponsorPayload): string {\n  const json = JSON.stringify(payload);\n  if (typeof Buffer !== \"undefined\") {\n    return Buffer.from(json, \"utf-8\").toString(\"base64\");\n  }\n  return btoa(json);\n}\n","/**\n * EIP-2612 Gas Sponsoring Extension Facilitator-Side Implementation\n *\n * Provides functions for facilitators to extract permit data from payment\n * extensions, validate permits, and prepare on-chain submission.\n */\n\nimport type {\n  Eip2612GasSponsorPayload,\n  Eip2612GasSponsorExtensionInfo,\n  Eip2612GasSponsorValidationResult,\n} from \"./types.js\";\nimport { EIP2612_GAS_SPONSOR_EXTENSION_KEY } from \"./client.js\";\nimport { validateEip2612GasSponsorPayload } from \"./server.js\";\n\n/**\n * Extracts the EIP-2612 gas sponsor payload from payment extensions.\n *\n * @param extensions - The extensions map from a PaymentPayload\n * @returns The gas sponsor payload if present, or null\n *\n * @example\n * ```typescript\n * const permit = extractEip2612GasSponsorPayload(paymentPayload.extensions);\n * if (permit) {\n *   // Submit permit tx then settle via Permit2\n * }\n * ```\n */\nexport function extractEip2612GasSponsorPayload(\n  extensions: Record<string, unknown> | undefined,\n): Eip2612GasSponsorPayload | null {\n  if (!extensions) {\n    return null;\n  }\n\n  const raw = extensions[EIP2612_GAS_SPONSOR_EXTENSION_KEY];\n  if (!raw || typeof raw !== \"object\") {\n    return null;\n  }\n\n  const payload = raw as Record<string, unknown>;\n\n  // Validate required fields are present\n  const required = [\n    \"network\",\n    \"permitSignature\",\n    \"owner\",\n    \"spender\",\n    \"value\",\n    \"deadline\",\n    \"v\",\n    \"r\",\n    \"s\",\n  ];\n  for (const field of required) {\n    if (!(field in payload)) {\n      return null;\n    }\n  }\n\n  return {\n    network: payload.network as string,\n    permitSignature: payload.permitSignature as string,\n    owner: payload.owner as string,\n    spender: payload.spender as string,\n    value: payload.value as string,\n    deadline: payload.deadline as number,\n    v: payload.v as number,\n    r: payload.r as string,\n    s: payload.s as string,\n  };\n}\n\n/**\n * Validates and extracts the EIP-2612 gas sponsor payload in one step.\n *\n * This is a convenience function for facilitators that combines extraction\n * and validation against the server's extension info.\n *\n * @param extensions - The extensions map from a PaymentPayload\n * @param extensionInfo - The server's gas sponsor extension info\n * @returns Validation result with the extracted payload if valid\n *\n * @example\n * ```typescript\n * const result = validateAndExtractPermit(\n *   paymentPayload.extensions,\n *   extensionInfo\n * );\n * if (result.valid && result.payload) {\n *   // Submit permit() on token contract, then settle via Permit2\n * }\n * ```\n */\nexport function validateAndExtractPermit(\n  extensions: Record<string, unknown> | undefined,\n  extensionInfo: Eip2612GasSponsorExtensionInfo,\n): Eip2612GasSponsorValidationResult & { payload?: Eip2612GasSponsorPayload } {\n  const payload = extractEip2612GasSponsorPayload(extensions);\n\n  if (!payload) {\n    return {\n      valid: false,\n      error: `Missing or invalid ${EIP2612_GAS_SPONSOR_EXTENSION_KEY} extension in payment`,\n    };\n  }\n\n  const result = validateEip2612GasSponsorPayload(payload, extensionInfo);\n\n  if (!result.valid) {\n    return result;\n  }\n\n  return { valid: true, payload };\n}\n\n/**\n * Builds the EIP-2612 permit function call data for on-chain submission.\n *\n * Returns the ABI-encoded parameters needed to call `permit(owner, spender, value, deadline, v, r, s)`\n * on the token contract.\n *\n * @param payload - The validated gas sponsor payload\n * @returns Object with the permit call parameters\n *\n * @example\n * ```typescript\n * const permitCall = buildPermitCallData(payload);\n * // Use permitCall with your preferred web3 library to submit the tx\n * ```\n */\nexport function buildPermitCallData(payload: Eip2612GasSponsorPayload): {\n  owner: string;\n  spender: string;\n  value: string;\n  deadline: number;\n  v: number;\n  r: string;\n  s: string;\n} {\n  return {\n    owner: payload.owner,\n    spender: payload.spender,\n    value: payload.value,\n    deadline: payload.deadline,\n    v: payload.v,\n    r: payload.r,\n    s: payload.s,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACmBA,IAAM,6BAA6B;AAAA,EACjC,MAAM;AAAA,EACN,UAAU,CAAC,WAAW,mBAAmB,SAAS,WAAW,SAAS,YAAY,KAAK,KAAK,GAAG;AAAA,EAC/F,YAAY;AAAA,IACV,SAAS,EAAE,MAAM,SAAS;AAAA,IAC1B,iBAAiB,EAAE,MAAM,SAAS;AAAA,IAClC,OAAO,EAAE,MAAM,SAAS;AAAA,IACxB,SAAS,EAAE,MAAM,SAAS;AAAA,IAC1B,OAAO,EAAE,MAAM,SAAS;AAAA,IACxB,UAAU,EAAE,MAAM,SAAS;AAAA,IAC3B,GAAG,EAAE,MAAM,SAAS;AAAA,IACpB,GAAG,EAAE,MAAM,SAAS;AAAA,IACpB,GAAG,EAAE,MAAM,SAAS;AAAA,EACtB;AACF;AAiBO,SAAS,kCACd,SAC4B;AAC5B,QAAM,OAAuC;AAAA,IAC3C,mBAAmB,QAAQ;AAAA,IAC3B,WAAW,QAAQ;AAAA,IACnB,gBAAgB,QAAQ,kBAAkB;AAAA,IAC1C,gBAAgB,QAAQ;AAAA,EAC1B;AAEA,SAAO;AAAA,IACL;AAAA,IACA,QAAQ;AAAA,EACV;AACF;AAkBO,SAAS,6BAA6B,QAA0C;AACrF,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI,MAAM,qCAAqC;AAAA,EACvD;AAEA,MAAI;AACF,UAAM,UAAU,OAAO,KAAK,QAAQ,QAAQ,EAAE,SAAS,OAAO;AAC9D,UAAM,UAAU,KAAK,MAAM,OAAO;AAElC,UAAM,WAAW;AAAA,MACf;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AACA,eAAW,SAAS,UAAU;AAC5B,UAAI,EAAE,SAAS,UAAU;AACvB,cAAM,IAAI,MAAM,2BAA2B,KAAK,EAAE;AAAA,MACpD;AAAA,IACF;AAEA,WAAO;AAAA,EACT,SAAS,OAAO;AACd,QAAI,iBAAiB,aAAa;AAChC,YAAM,IAAI,MAAM,qDAAqD;AAAA,IACvE;AACA,UAAM;AAAA,EACR;AACF;AAkBO,SAAS,iCACd,SACA,eACA,UAA4C,CAAC,GACV;AACnC,QAAM,MAAM,QAAQ,MAAM,QAAQ,IAAI,IAAI,KAAK,IAAI;AACnD,QAAM,aAAa,KAAK,MAAM,MAAM,GAAI;AAGxC,MAAI,CAAC,cAAc,kBAAkB,SAAS,QAAQ,OAAO,GAAG;AAC9D,WAAO;AAAA,MACL,OAAO;AAAA,MACP,OAAO,WAAW,QAAQ,OAAO,kCAAkC,cAAc,kBAAkB,KAAK,IAAI,CAAC;AAAA,IAC/G;AAAA,EACF;AAGA,QAAM,eAAe,OAAO,QAAQ,KAAK;AACzC,QAAM,YAAY,OAAO,cAAc,SAAS;AAChD,MAAI,eAAe,WAAW;AAC5B,WAAO;AAAA,MACL,OAAO;AAAA,MACP,OAAO,SAAS,QAAQ,KAAK,2BAA2B,cAAc,SAAS;AAAA,IACjF;AAAA,EACF;AAGA,MAAI,QAAQ,YAAY,YAAY;AAClC,WAAO;AAAA,MACL,OAAO;AAAA,MACP,OAAO;AAAA,IACT;AAAA,EACF;AAGA,QAAM,cAAc,aAAa,cAAc;AAC/C,MAAI,QAAQ,WAAW,aAAa;AAClC,WAAO;AAAA,MACL,OAAO;AAAA,MACP,OAAO,mBAAmB,QAAQ,QAAQ,qCAAqC,WAAW;AAAA,IAC5F;AAAA,EACF;AAGA,MAAI,QAAQ,QAAQ,YAAY,MAAM,cAAc,eAAe,YAAY,GAAG;AAChF,WAAO;AAAA,MACL,OAAO;AAAA,MACP,OAAO,WAAW,QAAQ,OAAO,mCAAmC,cAAc,cAAc;AAAA,IAClG;AAAA,EACF;AAGA,QAAM,SAAS,QAAQ,gBAAgB,WAAW,IAAI,IAClD,QAAQ,gBAAgB,MAAM,CAAC,IAC/B,QAAQ;AACZ,MAAI,OAAO,WAAW,KAAK;AACzB,WAAO;AAAA,MACL,OAAO;AAAA,MACP,OAAO,gEAAgE,OAAO,MAAM;AAAA,IACtF;AAAA,EACF;AAGA,MAAI,QAAQ,MAAM,MAAM,QAAQ,MAAM,IAAI;AACxC,WAAO;AAAA,MACL,OAAO;AAAA,MACP,OAAO,2CAA2C,QAAQ,CAAC;AAAA,IAC7D;AAAA,EACF;AAGA,QAAM,OAAO,QAAQ,EAAE,WAAW,IAAI,IAAI,QAAQ,EAAE,MAAM,CAAC,IAAI,QAAQ;AACvE,MAAI,KAAK,WAAW,IAAI;AACtB,WAAO;AAAA,MACL,OAAO;AAAA,MACP,OAAO,gDAAgD,KAAK,MAAM;AAAA,IACpE;AAAA,EACF;AAGA,QAAM,OAAO,QAAQ,EAAE,WAAW,IAAI,IAAI,QAAQ,EAAE,MAAM,CAAC,IAAI,QAAQ;AACvE,MAAI,KAAK,WAAW,IAAI;AACtB,WAAO;AAAA,MACL,OAAO;AAAA,MACP,OAAO,gDAAgD,KAAK,MAAM;AAAA,IACpE;AAAA,EACF;AAEA,SAAO,EAAE,OAAO,KAAK;AACvB;;;AClNO,IAAM,oCAAoC;AAK1C,IAAM,kCAAkC;AAqB/C,eAAsB,sBAAsB,QASzC;AACD,QAAM,EAAE,QAAQ,cAAc,WAAW,SAAS,SAAS,OAAO,UAAU,QAAQ,EAAE,IAAI;AAE1F,QAAM,SAAS;AAAA,IACb,MAAM;AAAA,IACN,SAAS;AAAA,IACT;AAAA,IACA,mBAAmB;AAAA,EACrB;AAEA,QAAM,QAAQ;AAAA,IACZ,QAAQ;AAAA,MACN,EAAE,MAAM,SAAS,MAAM,UAAU;AAAA,MACjC,EAAE,MAAM,WAAW,MAAM,UAAU;AAAA,MACnC,EAAE,MAAM,SAAS,MAAM,UAAU;AAAA,MACjC,EAAE,MAAM,SAAS,MAAM,UAAU;AAAA,MACjC,EAAE,MAAM,YAAY,MAAM,UAAU;AAAA,IACtC;AAAA,EACF;AAEA,QAAM,UAAU;AAAA,IACd,OAAO,OAAO;AAAA,IACd;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAEA,QAAM,YAAY,MAAM,OAAO,cAAc;AAAA,IAC3C;AAAA,IACA;AAAA,IACA,aAAa;AAAA,IACb;AAAA,EACF,CAAC;AAGD,QAAM,SAAS,UAAU,WAAW,IAAI,IAAI,UAAU,MAAM,CAAC,IAAI;AAEjE,MAAI,OAAO,WAAW,KAAK;AACzB,UAAM,IAAI,MAAM,yDAAyD,OAAO,MAAM,EAAE;AAAA,EAC1F;AAEA,QAAM,IAAI,OAAO,OAAO,MAAM,GAAG,EAAE;AACnC,QAAM,IAAI,OAAO,OAAO,MAAM,IAAI,GAAG;AACrC,MAAI,IAAI,SAAS,OAAO,MAAM,KAAK,GAAG,GAAG,EAAE;AAG3C,MAAI,IAAI,IAAI;AACV,SAAK;AAAA,EACP;AAEA,SAAO;AAAA,IACL,OAAO,OAAO;AAAA,IACd;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,iBAAiB,UAAU,WAAW,IAAI,IAAI,YAAY,OAAO;AAAA,EACnE;AACF;AAcO,SAAS,+BACd,QAUA,SAC0B;AAC1B,SAAO;AAAA,IACL;AAAA,IACA,iBAAiB,OAAO;AAAA,IACxB,OAAO,OAAO;AAAA,IACd,SAAS,OAAO;AAAA,IAChB,OAAO,OAAO;AAAA,IACd,UAAU,OAAO;AAAA,IACjB,GAAG,OAAO;AAAA,IACV,GAAG,OAAO;AAAA,IACV,GAAG,OAAO;AAAA,EACZ;AACF;AAgBO,SAAS,8BAA8B,SAA2C;AACvF,QAAM,OAAO,KAAK,UAAU,OAAO;AACnC,MAAI,OAAO,WAAW,aAAa;AACjC,WAAO,OAAO,KAAK,MAAM,OAAO,EAAE,SAAS,QAAQ;AAAA,EACrD;AACA,SAAO,KAAK,IAAI;AAClB;;;AC3IO,SAAS,gCACd,YACiC;AACjC,MAAI,CAAC,YAAY;AACf,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,WAAW,iCAAiC;AACxD,MAAI,CAAC,OAAO,OAAO,QAAQ,UAAU;AACnC,WAAO;AAAA,EACT;AAEA,QAAM,UAAU;AAGhB,QAAM,WAAW;AAAA,IACf;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACA,aAAW,SAAS,UAAU;AAC5B,QAAI,EAAE,SAAS,UAAU;AACvB,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AAAA,IACL,SAAS,QAAQ;AAAA,IACjB,iBAAiB,QAAQ;AAAA,IACzB,OAAO,QAAQ;AAAA,IACf,SAAS,QAAQ;AAAA,IACjB,OAAO,QAAQ;AAAA,IACf,UAAU,QAAQ;AAAA,IAClB,GAAG,QAAQ;AAAA,IACX,GAAG,QAAQ;AAAA,IACX,GAAG,QAAQ;AAAA,EACb;AACF;AAuBO,SAAS,yBACd,YACA,eAC4E;AAC5E,QAAM,UAAU,gCAAgC,UAAU;AAE1D,MAAI,CAAC,SAAS;AACZ,WAAO;AAAA,MACL,OAAO;AAAA,MACP,OAAO,sBAAsB,iCAAiC;AAAA,IAChE;AAAA,EACF;AAEA,QAAM,SAAS,iCAAiC,SAAS,aAAa;AAEtE,MAAI,CAAC,OAAO,OAAO;AACjB,WAAO;AAAA,EACT;AAEA,SAAO,EAAE,OAAO,MAAM,QAAQ;AAChC;AAiBO,SAAS,oBAAoB,SAQlC;AACA,SAAO;AAAA,IACL,OAAO,QAAQ;AAAA,IACf,SAAS,QAAQ;AAAA,IACjB,OAAO,QAAQ;AAAA,IACf,UAAU,QAAQ;AAAA,IAClB,GAAG,QAAQ;AAAA,IACX,GAAG,QAAQ;AAAA,IACX,GAAG,QAAQ;AAAA,EACb;AACF;","names":[]}

package/dist/cjs/erc20-approval-gas-sponsoring/index.d.ts

@@ -0,0 +1,316 @@
+/**
+ * ERC-20 Approval Gas Sponsoring Extension Type Definitions
+ *
+ * ERC-20 approve()-based gas sponsoring for the t402 payment protocol.
+ * For tokens WITHOUT EIP-2612 permit support, the client signs an offline
+ * approve() transaction and the facilitator broadcasts it on their behalf.
+ */
+/**
+ * Information provided by server about ERC-20 approval gas sponsoring availability.
+ */
+interface ERC20ApprovalGasSponsorExtensionInfo {
+    /** CAIP-2 network identifiers where gas sponsoring is available */
+    sponsoredNetworks: string[];
+    /** Maximum token amount (in base units) the sponsor will cover per approval */
+    maxAmount: string;
+    /** Address of the sponsor/facilitator that will submit transactions */
+    sponsorAddress: string;
+    /** Optional Permit2 proxy address for advanced settlement flows */
+    permit2Address?: string;
+    /** Whether atomic batch execution is required (e.g., via Multicall3) */
+    requiresAtomicBatch: boolean;
+}
+/**
+ * ERC-20 approval gas sponsor extension declaration for server responses.
+ */
+interface ERC20ApprovalGasSponsorExtension {
+    /** Extension information */
+    info: ERC20ApprovalGasSponsorExtensionInfo;
+    /** JSON Schema for validation */
+    schema: object;
+}
+/**
+ * Complete ERC-20 approval gas sponsor payload from client.
+ */
+interface ERC20ApprovalGasSponsorPayload {
+    /** CAIP-2 network identifier (must be in sponsoredNetworks) */
+    network: string;
+    /** Client wallet address that signed the transaction */
+    from: string;
+    /** ERC-20 token contract address */
+    asset: string;
+    /** Approval amount in base units */
+    amount: string;
+    /** Raw signed approve() transaction (hex-encoded with 0x prefix) */
+    signedApprovalTx: string;
+    /** Chain ID for replay protection */
+    chainId: number;
+    /** Client's account nonce (if known) */
+    nonce?: number;
+}
+/**
+ * Options for declaring ERC-20 approval gas sponsor extension on server.
+ */
+interface DeclareERC20ApprovalGasSponsorOptions {
+    /** CAIP-2 network identifiers where gas sponsoring is available */
+    sponsoredNetworks: string[];
+    /** Maximum token amount (in base units) the sponsor will cover per approval */
+    maxAmount: string;
+    /** Address of the sponsor/facilitator */
+    sponsorAddress: string;
+    /** Optional Permit2 proxy address */
+    permit2Address?: string;
+    /** Whether atomic batch execution is required (defaults to false) */
+    requiresAtomicBatch?: boolean;
+}
+/**
+ * Options for validating ERC-20 approval gas sponsor payloads.
+ */
+interface ValidateERC20ApprovalGasSponsorOptions {
+    /** Expected chain IDs per CAIP-2 network (e.g., { "eip155:8453": 8453 }) */
+    expectedChainIds?: Record<string, number>;
+}
+/**
+ * Result of ERC-20 approval gas sponsor payload validation.
+ */
+interface ERC20ApprovalGasSponsorValidationResult {
+    /** Whether the payload is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+}
+/**
+ * Parameters for creating an ERC-20 approval gas sponsor payload.
+ */
+interface CreateERC20ApprovalParams {
+    /** CAIP-2 network identifier */
+    network: string;
+    /** Client wallet address */
+    from: string;
+    /** ERC-20 token contract address */
+    asset: string;
+    /** Approval amount in base units */
+    amount: string;
+    /** Raw signed approve() transaction (hex-encoded) */
+    signedApprovalTx: string;
+    /** Chain ID for replay protection */
+    chainId: number;
+    /** Client's account nonce (if known) */
+    nonce?: number;
+}
+
+/**
+ * ERC-20 Approval Gas Sponsoring Extension Server-Side Implementation
+ *
+ * Provides functions for servers to declare gas sponsoring requirements,
+ * parse client headers, and validate approval payloads.
+ */
+
+/**
+ * Declares an ERC-20 approval gas sponsor extension for server responses.
+ *
+ * @param options - Extension declaration options
+ * @returns Gas sponsor extension object ready for response
+ *
+ * @example
+ * ```typescript
+ * const extension = declareERC20ApprovalGasSponsorExtension({
+ *   sponsoredNetworks: ["eip155:8453", "eip155:42161"],
+ *   maxAmount: "1000000000",
+ *   sponsorAddress: "0xFacilitator...",
+ *   requiresAtomicBatch: true,
+ * });
+ * ```
+ */
+declare function declareERC20ApprovalGasSponsorExtension(options: DeclareERC20ApprovalGasSponsorOptions): ERC20ApprovalGasSponsorExtension;
+/**
+ * Parses an ERC-20 approval gas sponsor header from client request.
+ *
+ * The header format is base64-encoded JSON.
+ *
+ * @param header - Base64-encoded gas sponsor header value
+ * @returns Parsed gas sponsor payload
+ * @throws Error if header is invalid
+ *
+ * @example
+ * ```typescript
+ * const payload = parseERC20ApprovalGasSponsorHeader(
+ *   request.headers['x-t402-erc20-approval-gas-sponsoring']
+ * );
+ * ```
+ */
+declare function parseERC20ApprovalGasSponsorHeader(header: string): ERC20ApprovalGasSponsorPayload;
+/**
+ * Validates an ERC-20 approval gas sponsor payload against server extension info.
+ *
+ * @param payload - The gas sponsor payload from the client
+ * @param extensionInfo - The server's gas sponsor extension info
+ * @param options - Validation options
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validateERC20ApprovalGasSponsorPayload(payload, extension.info);
+ * if (!result.valid) {
+ *   throw new Error(result.error);
+ * }
+ * ```
+ */
+declare function validateERC20ApprovalGasSponsorPayload(payload: ERC20ApprovalGasSponsorPayload, extensionInfo: ERC20ApprovalGasSponsorExtensionInfo, options?: ValidateERC20ApprovalGasSponsorOptions): ERC20ApprovalGasSponsorValidationResult;
+
+/**
+ * ERC-20 Approval Gas Sponsoring Extension Client-Side Implementation
+ *
+ * Provides functions for clients to construct ERC-20 approve() calldata
+ * and encode gas sponsor payloads for transmission.
+ */
+
+/**
+ * Extension key for ERC-20 approval gas sponsoring in payment requirements.
+ */
+declare const ERC20_APPROVAL_GAS_SPONSOR_EXTENSION_KEY = "erc20ApprovalGasSponsoring";
+/**
+ * HTTP header name for ERC-20 approval gas sponsor payload.
+ */
+declare const ERC20_APPROVAL_GAS_SPONSOR_HEADER_NAME = "X-T402-ERC20-Approval-Gas-Sponsoring";
+/**
+ * ERC-20 approve(address,uint256) function selector.
+ */
+declare const APPROVE_FUNCTION_SELECTOR = "0x095ea7b3";
+/**
+ * Encodes ERC-20 approve(address spender, uint256 amount) calldata.
+ *
+ * @param spender - The spender address to approve
+ * @param amount - The approval amount in base units
+ * @returns Hex-encoded calldata with 0x prefix
+ *
+ * @example
+ * ```typescript
+ * const calldata = encodeApproveCalldata("0xFacilitator...", "1000000");
+ * // Returns "0x095ea7b3" + abi-encoded args
+ * ```
+ */
+declare function encodeApproveCalldata(spender: string, amount: string): string;
+/**
+ * Creates an ERC-20 approval gas sponsor payload from params and extension info.
+ *
+ * @param info - The server's extension info
+ * @param params - The approval parameters
+ * @returns Gas sponsor payload ready for header encoding
+ *
+ * @example
+ * ```typescript
+ * const payload = createERC20ApprovalGasSponsorPayload(extensionInfo, {
+ *   network: "eip155:8453",
+ *   from: wallet.address,
+ *   asset: "0xUSDT...",
+ *   amount: "1000000",
+ *   signedApprovalTx: signedTx,
+ *   chainId: 8453,
+ * });
+ * ```
+ */
+declare function createERC20ApprovalGasSponsorPayload(_info: ERC20ApprovalGasSponsorExtensionInfo, params: CreateERC20ApprovalParams): ERC20ApprovalGasSponsorPayload;
+/**
+ * Encodes an ERC-20 approval gas sponsor payload for transmission in HTTP header.
+ *
+ * @param payload - The gas sponsor payload to encode
+ * @returns Base64-encoded JSON string
+ *
+ * @example
+ * ```typescript
+ * const header = encodeERC20ApprovalGasSponsorHeader(payload);
+ * fetch(url, {
+ *   headers: { [ERC20_APPROVAL_GAS_SPONSOR_HEADER_NAME]: header }
+ * });
+ * ```
+ */
+declare function encodeERC20ApprovalGasSponsorHeader(payload: ERC20ApprovalGasSponsorPayload): string;
+
+/**
+ * ERC-20 Approval Gas Sponsoring Extension Facilitator-Side Implementation
+ *
+ * Provides functions for facilitators to extract approval data from payment
+ * extensions, validate the signed approve() transaction, and prepare for
+ * on-chain submission.
+ */
+
+/**
+ * Extracts the ERC-20 approval gas sponsor payload from payment extensions.
+ *
+ * @param extensions - The extensions map from a PaymentPayload
+ * @returns The gas sponsor payload if present, or null
+ *
+ * @example
+ * ```typescript
+ * const approval = extractERC20ApprovalGasSponsorPayload(paymentPayload.extensions);
+ * if (approval) {
+ *   // Validate and broadcast the approval tx, then settle
+ * }
+ * ```
+ */
+declare function extractERC20ApprovalGasSponsorPayload(extensions: Record<string, unknown> | undefined): ERC20ApprovalGasSponsorPayload | null;
+/**
+ * Processes and validates an ERC-20 approval payload for the facilitator.
+ *
+ * Combines extraction validation with approve() function selector verification.
+ * Checks that the signed transaction data contains the correct approve() selector
+ * and that the approval amount matches the declared amount.
+ *
+ * @param payload - The ERC-20 approval gas sponsor payload
+ * @param extensionInfo - The server's gas sponsor extension info
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = processERC20ApprovalPayload(payload, extensionInfo);
+ * if (result.valid) {
+ *   // Safe to broadcast the approval tx and settle
+ * }
+ * ```
+ */
+declare function processERC20ApprovalPayload(payload: ERC20ApprovalGasSponsorPayload, extensionInfo: ERC20ApprovalGasSponsorExtensionInfo): ERC20ApprovalGasSponsorValidationResult;
+/**
+ * Validates and extracts the ERC-20 approval gas sponsor payload in one step.
+ *
+ * This is a convenience function for facilitators that combines extraction
+ * and validation against the server's extension info.
+ *
+ * @param extensions - The extensions map from a PaymentPayload
+ * @param extensionInfo - The server's gas sponsor extension info
+ * @returns Validation result with the extracted payload if valid
+ *
+ * @example
+ * ```typescript
+ * const result = validateAndExtractApproval(
+ *   paymentPayload.extensions,
+ *   extensionInfo
+ * );
+ * if (result.valid && result.payload) {
+ *   // Broadcast approval tx, then settle
+ * }
+ * ```
+ */
+declare function validateAndExtractApproval(extensions: Record<string, unknown> | undefined, extensionInfo: ERC20ApprovalGasSponsorExtensionInfo): ERC20ApprovalGasSponsorValidationResult & {
+    payload?: ERC20ApprovalGasSponsorPayload;
+};
+/**
+ * Decodes the approve() calldata from a hex string to extract spender and amount.
+ *
+ * @param calldata - Hex-encoded approve() calldata (with or without 0x prefix)
+ * @returns Decoded spender and amount, or null if not valid approve() calldata
+ *
+ * @example
+ * ```typescript
+ * const decoded = decodeApproveCalldata("0x095ea7b3...");
+ * if (decoded) {
+ *   console.log(decoded.spender, decoded.amount);
+ * }
+ * ```
+ */
+declare function decodeApproveCalldata(calldata: string): {
+    spender: string;
+    amount: string;
+} | null;
+
+export { APPROVE_FUNCTION_SELECTOR, type CreateERC20ApprovalParams, type DeclareERC20ApprovalGasSponsorOptions, type ERC20ApprovalGasSponsorExtension, type ERC20ApprovalGasSponsorExtensionInfo, type ERC20ApprovalGasSponsorPayload, type ERC20ApprovalGasSponsorValidationResult, ERC20_APPROVAL_GAS_SPONSOR_EXTENSION_KEY, ERC20_APPROVAL_GAS_SPONSOR_HEADER_NAME, type ValidateERC20ApprovalGasSponsorOptions, createERC20ApprovalGasSponsorPayload, declareERC20ApprovalGasSponsorExtension, decodeApproveCalldata, encodeApproveCalldata, encodeERC20ApprovalGasSponsorHeader, extractERC20ApprovalGasSponsorPayload, parseERC20ApprovalGasSponsorHeader, processERC20ApprovalPayload, validateAndExtractApproval, validateERC20ApprovalGasSponsorPayload };