@x402/evm 2.6.0 → 2.7.0

package/dist/esm/exact/facilitator/index.mjs

@@ -2,34 +2,98 @@ import {
   isPermit2Payload
 } from "../../chunk-TKN5V2BV.mjs";
 import {
+  ERC20_APPROVAL_GAS_SPONSORING_KEY,
+  extractEip2612GasSponsoringInfo,
+  extractErc20ApprovalGasSponsoringInfo,
+  resolveErc20ApprovalExtensionSigner,
+  validateEip2612GasSponsoringInfo,
+  validateErc20ApprovalGasSponsoringInfo
+} from "../../chunk-GD4MKCN7.mjs";
+import {
+  DEFAULT_MAX_FEE_PER_GAS,
+  ERC20_APPROVE_GAS_LIMIT,
+  ErrEip2612AssetMismatch,
+  ErrEip2612DeadlineExpired,
+  ErrEip2612FromMismatch,
+  ErrEip2612SpenderNotPermit2,
+  ErrErc20ApprovalAssetMismatch,
+  ErrErc20ApprovalFromMismatch,
+  ErrErc20ApprovalInsufficientEthForGas,
+  ErrErc20ApprovalInvalidFormat,
+  ErrErc20ApprovalSpenderNotPermit2,
+  ErrErc20ApprovalTxFailed,
+  ErrErc20ApprovalTxInvalidCalldata,
+  ErrErc20ApprovalTxInvalidSignature,
+  ErrErc20ApprovalTxParseFailed,
+  ErrErc20ApprovalTxSignerMismatch,
+  ErrErc20ApprovalTxWrongSelector,
+  ErrErc20ApprovalTxWrongSpender,
+  ErrErc20ApprovalTxWrongTarget,
+  ErrInvalidAuthorizationValue,
+  ErrInvalidEip2612ExtensionFormat,
+  ErrInvalidScheme,
+  ErrInvalidSignature,
+  ErrInvalidTransactionState,
+  ErrMissingEip712Domain,
+  ErrNetworkMismatch,
+  ErrPermit2612AmountMismatch,
+  ErrPermit2AllowanceRequired,
+  ErrPermit2AmountMismatch,
+  ErrPermit2DeadlineExpired,
+  ErrPermit2InsufficientBalance,
+  ErrPermit2InvalidAmount,
+  ErrPermit2InvalidDestination,
+  ErrPermit2InvalidNonce,
+  ErrPermit2InvalidOwner,
+  ErrPermit2InvalidSignature,
+  ErrPermit2InvalidSpender,
+  ErrPermit2NotYetValid,
+  ErrPermit2PaymentTooEarly,
+  ErrPermit2ProxyNotDeployed,
+  ErrPermit2RecipientMismatch,
+  ErrPermit2SimulationFailed,
+  ErrPermit2TokenMismatch,
+  ErrRecipientMismatch,
+  ErrTransactionFailed,
+  ErrUndeployedSmartWallet,
+  ErrUnsupportedPayloadType,
+  ErrValidAfterInFuture,
+  ErrValidBeforeExpired,
   ExactEvmSchemeV1,
+  MULTICALL3_ADDRESS,
   NETWORKS,
   PERMIT2_ADDRESS,
   authorizationTypes,
+  diagnoseEip3009SimulationFailure,
   eip3009ABI,
   erc20AllowanceAbi,
   erc20ApproveAbi,
+  executeTransferWithAuthorization,
   getEvmChainId,
+  multicall,
+  multicall3GetEthBalanceAbi,
   permit2WitnessTypes,
+  simulateEip3009Transfer,
   x402ExactPermit2ProxyABI,
   x402ExactPermit2ProxyAddress
-} from "../../chunk-XL6IFXCP.mjs";
+} from "../../chunk-IZEI7JTG.mjs";
 
 // src/exact/facilitator/eip3009.ts
-import { getAddress, isAddressEqual, parseErc6492Signature, parseSignature } from "viem";
-async function verifyEIP3009(signer, payload, requirements, eip3009Payload) {
+import { getAddress, isAddressEqual, parseErc6492Signature } from "viem";
+async function verifyEIP3009(signer, payload, requirements, eip3009Payload, options) {
   const payer = eip3009Payload.authorization.from;
+  let eip6492Deployment;
   if (payload.accepted.scheme !== "exact" || requirements.scheme !== "exact") {
     return {
       isValid: false,
-      invalidReason: "unsupported_scheme",
+      invalidReason: ErrInvalidScheme,
       payer
     };
   }
   if (!requirements.extra?.name || !requirements.extra?.version) {
     return {
       isValid: false,
-      invalidReason: "missing_eip712_domain",
+      invalidReason: ErrMissingEip712Domain,
       payer
     };
   }
@@ -38,7 +102,7 @@ async function verifyEIP3009(signer, payload, requirements, eip3009Payload) {
   if (payload.accepted.network !== requirements.network) {
     return {
       isValid: false,
-      invalidReason: "network_mismatch",
+      invalidReason: ErrNetworkMismatch,
       payer
     };
   }
@@ -60,47 +124,41 @@ async function verifyEIP3009(signer, payload, requirements, eip3009Payload) {
       nonce: eip3009Payload.authorization.nonce
     }
   };
+  let isValid = false;
   try {
-    const recoveredAddress = await signer.verifyTypedData({
+    isValid = await signer.verifyTypedData({
       address: eip3009Payload.authorization.from,
       ...permitTypedData,
       signature: eip3009Payload.signature
     });
-    if (!recoveredAddress) {
+  } catch {
+    isValid = false;
+  }
+  const signature = eip3009Payload.signature;
+  const sigLen = signature.startsWith("0x") ? signature.length - 2 : signature.length;
+  const erc6492Data = parseErc6492Signature(signature);
+  const hasDeploymentInfo = erc6492Data.address && erc6492Data.data && !isAddressEqual(erc6492Data.address, "0x0000000000000000000000000000000000000000");
+  if (hasDeploymentInfo) {
+    eip6492Deployment = {
+      factoryAddress: erc6492Data.address,
+      factoryCalldata: erc6492Data.data
+    };
+  }
+  if (!isValid) {
+    const isSmartWallet = sigLen > 130;
+    if (!isSmartWallet) {
       return {
         isValid: false,
-        invalidReason: "invalid_exact_evm_payload_signature",
+        invalidReason: ErrInvalidSignature,
         payer
       };
     }
-  } catch {
-    const signature = eip3009Payload.signature;
-    const signatureLength = signature.startsWith("0x") ? signature.length - 2 : signature.length;
-    const isSmartWallet = signatureLength > 130;
-    if (isSmartWallet) {
-      const payerAddress = eip3009Payload.authorization.from;
-      const bytecode = await signer.getCode({ address: payerAddress });
-      if (!bytecode || bytecode === "0x") {
-        const erc6492Data = parseErc6492Signature(signature);
-        const hasDeploymentInfo = erc6492Data.address && erc6492Data.data && !isAddressEqual(erc6492Data.address, "0x0000000000000000000000000000000000000000");
-        if (!hasDeploymentInfo) {
-          return {
-            isValid: false,
-            invalidReason: "invalid_exact_evm_payload_undeployed_smart_wallet",
-            payer: payerAddress
-          };
-        }
-      } else {
-        return {
-          isValid: false,
-          invalidReason: "invalid_exact_evm_payload_signature",
-          payer
-        };
-      }
-    } else {
+    const bytecode = await signer.getCode({ address: payer });
+    const isDeployed = bytecode && bytecode !== "0x";
+    if (!isDeployed && !hasDeploymentInfo) {
       return {
         isValid: false,
-        invalidReason: "invalid_exact_evm_payload_signature",
+        invalidReason: ErrUndeployedSmartWallet,
         payer
       };
     }
@@ -108,7 +166,7 @@ async function verifyEIP3009(signer, payload, requirements, eip3009Payload) {
   if (getAddress(eip3009Payload.authorization.to) !== getAddress(requirements.payTo)) {
     return {
       isValid: false,
-      invalidReason: "invalid_exact_evm_payload_recipient_mismatch",
+      invalidReason: ErrRecipientMismatch,
       payer
     };
   }
@@ -116,41 +174,41 @@ async function verifyEIP3009(signer, payload, requirements, eip3009Payload) {
   if (BigInt(eip3009Payload.authorization.validBefore) < BigInt(now + 6)) {
     return {
       isValid: false,
-      invalidReason: "invalid_exact_evm_payload_authorization_valid_before",
+      invalidReason: ErrValidBeforeExpired,
       payer
     };
   }
   if (BigInt(eip3009Payload.authorization.validAfter) > BigInt(now)) {
     return {
       isValid: false,
-      invalidReason: "invalid_exact_evm_payload_authorization_valid_after",
+      invalidReason: ErrValidAfterInFuture,
       payer
     };
   }
-  try {
-    const balance = await signer.readContract({
-      address: erc20Address,
-      abi: eip3009ABI,
-      functionName: "balanceOf",
-      args: [eip3009Payload.authorization.from]
-    });
-    if (BigInt(balance) < BigInt(requirements.amount)) {
-      return {
-        isValid: false,
-        invalidReason: "insufficient_funds",
-        invalidMessage: `Insufficient funds to complete the payment. Required: ${requirements.amount} ${requirements.asset}, Available: ${balance.toString()} ${requirements.asset}. Please add funds to your wallet and try again.`,
-        payer
-      };
-    }
-  } catch {
-  }
   if (BigInt(eip3009Payload.authorization.value) !== BigInt(requirements.amount)) {
     return {
       isValid: false,
-      invalidReason: "invalid_exact_evm_payload_authorization_value_mismatch",
+      invalidReason: ErrInvalidAuthorizationValue,
       payer
     };
   }
+  if (options?.simulate !== false) {
+    const simulationSucceeded = await simulateEip3009Transfer(
+      signer,
+      erc20Address,
+      eip3009Payload,
+      eip6492Deployment
+    );
+    if (!simulationSucceeded) {
+      return diagnoseEip3009SimulationFailure(
+        signer,
+        erc20Address,
+        eip3009Payload,
+        requirements,
+        requirements.amount
+      );
+    }
+  }
   return {
     isValid: true,
     invalidReason: void 0,
@@ -159,19 +217,22 @@ async function verifyEIP3009(signer, payload, requirements, eip3009Payload) {
 }
 async function settleEIP3009(signer, payload, requirements, eip3009Payload, config) {
   const payer = eip3009Payload.authorization.from;
-  const valid = await verifyEIP3009(signer, payload, requirements, eip3009Payload);
+  const valid = await verifyEIP3009(signer, payload, requirements, eip3009Payload, {
+    simulate: config.simulateInSettle ?? false
+  });
   if (!valid.isValid) {
     return {
       success: false,
       network: payload.accepted.network,
       transaction: "",
-      errorReason: valid.invalidReason ?? "invalid_scheme",
+      errorReason: valid.invalidReason ?? ErrInvalidScheme,
       payer
     };
   }
   try {
-    const parseResult = parseErc6492Signature(eip3009Payload.signature);
-    const { signature, address: factoryAddress, data: factoryCalldata } = parseResult;
+    const { address: factoryAddress, data: factoryCalldata } = parseErc6492Signature(
+      eip3009Payload.signature
+    );
     if (config.deployERC4337WithEIP6492 && factoryAddress && factoryCalldata && !isAddressEqual(factoryAddress, "0x0000000000000000000000000000000000000000")) {
       const bytecode = await signer.getCode({ address: payer });
       if (!bytecode || bytecode === "0x") {
@@ -182,48 +243,16 @@ async function settleEIP3009(signer, payload, requirements, eip3009Payload, conf
         await signer.waitForTransactionReceipt({ hash: deployTx });
       }
     }
-    const signatureLength = signature.startsWith("0x") ? signature.length - 2 : signature.length;
-    const isECDSA = signatureLength === 130;
-    let tx;
-    if (isECDSA) {
-      const parsedSig = parseSignature(signature);
-      tx = await signer.writeContract({
-        address: getAddress(requirements.asset),
-        abi: eip3009ABI,
-        functionName: "transferWithAuthorization",
-        args: [
-          getAddress(eip3009Payload.authorization.from),
-          getAddress(eip3009Payload.authorization.to),
-          BigInt(eip3009Payload.authorization.value),
-          BigInt(eip3009Payload.authorization.validAfter),
-          BigInt(eip3009Payload.authorization.validBefore),
-          eip3009Payload.authorization.nonce,
-          parsedSig.v || parsedSig.yParity,
-          parsedSig.r,
-          parsedSig.s
-        ]
-      });
-    } else {
-      tx = await signer.writeContract({
-        address: getAddress(requirements.asset),
-        abi: eip3009ABI,
-        functionName: "transferWithAuthorization",
-        args: [
-          getAddress(eip3009Payload.authorization.from),
-          getAddress(eip3009Payload.authorization.to),
-          BigInt(eip3009Payload.authorization.value),
-          BigInt(eip3009Payload.authorization.validAfter),
-          BigInt(eip3009Payload.authorization.validBefore),
-          eip3009Payload.authorization.nonce,
-          signature
-        ]
-      });
-    }
+    const tx = await executeTransferWithAuthorization(
+      signer,
+      getAddress(requirements.asset),
+      eip3009Payload
+    );
     const receipt = await signer.waitForTransactionReceipt({ hash: tx });
     if (receipt.status !== "success") {
       return {
         success: false,
-        errorReason: "invalid_transaction_state",
+        errorReason: ErrTransactionFailed,
         transaction: tx,
         network: payload.accepted.network,
         payer
@@ -238,7 +267,7 @@ async function settleEIP3009(signer, payload, requirements, eip3009Payload, conf
   } catch {
     return {
       success: false,
-      errorReason: "transaction_failed",
+      errorReason: ErrTransactionFailed,
       transaction: "",
       network: payload.accepted.network,
       payer
@@ -247,33 +276,7 @@ async function settleEIP3009(signer, payload, requirements, eip3009Payload, conf
 }
 
 // src/exact/facilitator/permit2.ts
-import {
-  extractEip2612GasSponsoringInfo,
-  validateEip2612GasSponsoringInfo,
-  extractErc20ApprovalGasSponsoringInfo,
-  ERC20_APPROVAL_GAS_SPONSORING
-} from "@x402/extensions";
-import { getAddress as getAddress3 } from "viem";
-
-// src/exact/facilitator/errors.ts
-var ErrPermit2InvalidSignature = "invalid_permit2_signature";
-var ErrPermit2InvalidAmount = "permit2_invalid_amount";
-var ErrPermit2InvalidDestination = "permit2_invalid_destination";
-var ErrPermit2InvalidOwner = "permit2_invalid_owner";
-var ErrPermit2PaymentTooEarly = "permit2_payment_too_early";
-var ErrPermit2InvalidNonce = "permit2_invalid_nonce";
-var ErrPermit2612AmountMismatch = "permit2_2612_amount_mismatch";
-var ErrErc20ApprovalInvalidFormat = "invalid_erc20_approval_extension_format";
-var ErrErc20ApprovalFromMismatch = "erc20_approval_from_mismatch";
-var ErrErc20ApprovalAssetMismatch = "erc20_approval_asset_mismatch";
-var ErrErc20ApprovalSpenderNotPermit2 = "erc20_approval_spender_not_permit2";
-var ErrErc20ApprovalTxWrongTarget = "erc20_approval_tx_wrong_target";
-var ErrErc20ApprovalTxWrongSelector = "erc20_approval_tx_wrong_selector";
-var ErrErc20ApprovalTxWrongSpender = "erc20_approval_tx_wrong_spender";
-var ErrErc20ApprovalTxInvalidCalldata = "erc20_approval_tx_invalid_calldata";
-var ErrErc20ApprovalTxSignerMismatch = "erc20_approval_tx_signer_mismatch";
-var ErrErc20ApprovalTxInvalidSignature = "erc20_approval_tx_invalid_signature";
-var ErrErc20ApprovalTxParseFailed = "erc20_approval_tx_parse_failed";
+import { getAddress as getAddress4 } from "viem";
 
 // src/exact/facilitator/erc20approval.ts
 import {
@@ -282,9 +285,6 @@ import {
   decodeFunctionData,
   recoverTransactionAddress
 } from "viem";
-import {
-  validateErc20ApprovalGasSponsoringInfo
-} from "@x402/extensions";
 var APPROVE_SELECTOR = "0x095ea7b3";
 async function validateErc20ApprovalForPayment(info, payer, tokenAddress) {
   if (!validateErc20ApprovalGasSponsoringInfo(info)) {
@@ -381,36 +381,285 @@ async function validateErc20ApprovalForPayment(info, payer, tokenAddress) {
   return { isValid: true };
 }
 
+// src/exact/facilitator/permit2-utils.ts
+import { encodeFunctionData, getAddress as getAddress3 } from "viem";
+async function simulatePermit2Settle(signer, permit2Payload) {
+  try {
+    await signer.readContract({
+      address: x402ExactPermit2ProxyAddress,
+      abi: x402ExactPermit2ProxyABI,
+      functionName: "settle",
+      args: buildPermit2SettleArgs(permit2Payload)
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function splitEip2612Signature(signature) {
+  const sig = signature.startsWith("0x") ? signature.slice(2) : signature;
+  if (sig.length !== 130) {
+    throw new Error(
+      `invalid EIP-2612 signature length: expected 65 bytes (130 hex chars), got ${sig.length / 2} bytes`
+    );
+  }
+  const r = `0x${sig.slice(0, 64)}`;
+  const s = `0x${sig.slice(64, 128)}`;
+  const v = parseInt(sig.slice(128, 130), 16);
+  return { v, r, s };
+}
+function buildPermit2SettleArgs(permit2Payload) {
+  return [
+    {
+      permitted: {
+        token: getAddress3(permit2Payload.permit2Authorization.permitted.token),
+        amount: BigInt(permit2Payload.permit2Authorization.permitted.amount)
+      },
+      nonce: BigInt(permit2Payload.permit2Authorization.nonce),
+      deadline: BigInt(permit2Payload.permit2Authorization.deadline)
+    },
+    getAddress3(permit2Payload.permit2Authorization.from),
+    {
+      to: getAddress3(permit2Payload.permit2Authorization.witness.to),
+      validAfter: BigInt(permit2Payload.permit2Authorization.witness.validAfter)
+    },
+    permit2Payload.signature
+  ];
+}
+function encodePermit2SettleCalldata(permit2Payload) {
+  return encodeFunctionData({
+    abi: x402ExactPermit2ProxyABI,
+    functionName: "settle",
+    args: buildPermit2SettleArgs(permit2Payload)
+  });
+}
+async function simulatePermit2SettleWithPermit(signer, permit2Payload, eip2612Info) {
+  try {
+    const { v, r, s } = splitEip2612Signature(eip2612Info.signature);
+    await signer.readContract({
+      address: x402ExactPermit2ProxyAddress,
+      abi: x402ExactPermit2ProxyABI,
+      functionName: "settleWithPermit",
+      args: [
+        {
+          value: BigInt(eip2612Info.amount),
+          deadline: BigInt(eip2612Info.deadline),
+          r,
+          s,
+          v
+        },
+        ...buildPermit2SettleArgs(permit2Payload)
+      ]
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function diagnosePermit2SimulationFailure(signer, tokenAddress, permit2Payload, amountRequired) {
+  const payer = permit2Payload.permit2Authorization.from;
+  const diagnosticCalls = [
+    {
+      address: x402ExactPermit2ProxyAddress,
+      abi: x402ExactPermit2ProxyABI,
+      functionName: "PERMIT2"
+    },
+    {
+      address: tokenAddress,
+      abi: eip3009ABI,
+      functionName: "balanceOf",
+      args: [payer]
+    },
+    {
+      address: tokenAddress,
+      abi: erc20AllowanceAbi,
+      functionName: "allowance",
+      args: [payer, PERMIT2_ADDRESS]
+    }
+  ];
+  try {
+    const results = await multicall(signer.readContract.bind(signer), diagnosticCalls);
+    const [proxyResult, balanceResult, allowanceResult] = results;
+    if (proxyResult.status === "failure") {
+      return { isValid: false, invalidReason: ErrPermit2ProxyNotDeployed, payer };
+    }
+    if (balanceResult.status === "success") {
+      const balance = balanceResult.result;
+      if (balance < BigInt(amountRequired)) {
+        return { isValid: false, invalidReason: ErrPermit2InsufficientBalance, payer };
+      }
+    }
+    if (allowanceResult.status === "success") {
+      const allowance = allowanceResult.result;
+      if (allowance < BigInt(amountRequired)) {
+        return { isValid: false, invalidReason: ErrPermit2AllowanceRequired, payer };
+      }
+    }
+  } catch {
+  }
+  return { isValid: false, invalidReason: ErrPermit2SimulationFailed, payer };
+}
+async function checkPermit2Prerequisites(signer, tokenAddress, payer, amountRequired) {
+  const diagnosticCalls = [
+    {
+      address: x402ExactPermit2ProxyAddress,
+      abi: x402ExactPermit2ProxyABI,
+      functionName: "PERMIT2"
+    },
+    {
+      address: tokenAddress,
+      abi: eip3009ABI,
+      functionName: "balanceOf",
+      args: [payer]
+    },
+    {
+      address: MULTICALL3_ADDRESS,
+      abi: multicall3GetEthBalanceAbi,
+      functionName: "getEthBalance",
+      args: [payer]
+    }
+  ];
+  try {
+    const results = await multicall(signer.readContract.bind(signer), diagnosticCalls);
+    const [proxyResult, balanceResult, ethBalanceResult] = results;
+    if (proxyResult.status === "failure") {
+      return { isValid: false, invalidReason: ErrPermit2ProxyNotDeployed, payer };
+    }
+    if (balanceResult.status === "success") {
+      const balance = balanceResult.result;
+      if (balance < BigInt(amountRequired)) {
+        return { isValid: false, invalidReason: ErrPermit2InsufficientBalance, payer };
+      }
+    }
+    if (ethBalanceResult.status === "success") {
+      const minEthForApprovalGas = ERC20_APPROVE_GAS_LIMIT * DEFAULT_MAX_FEE_PER_GAS;
+      const ethBalance = ethBalanceResult.result;
+      if (ethBalance < minEthForApprovalGas) {
+        return {
+          isValid: false,
+          invalidReason: ErrErc20ApprovalInsufficientEthForGas,
+          payer
+        };
+      }
+    }
+  } catch {
+  }
+  return { isValid: true, invalidReason: void 0, payer };
+}
+async function simulatePermit2SettleWithErc20Approval(extensionSigner, permit2Payload, erc20Info) {
+  if (!extensionSigner.simulateTransactions) {
+    return false;
+  }
+  try {
+    const settleData = encodePermit2SettleCalldata(permit2Payload);
+    return await extensionSigner.simulateTransactions([
+      erc20Info.signedTransaction,
+      { to: x402ExactPermit2ProxyAddress, data: settleData, gas: BigInt(3e5) }
+    ]);
+  } catch {
+    return false;
+  }
+}
+async function waitAndReturn(signer, tx, payload, payer) {
+  const receipt = await signer.waitForTransactionReceipt({ hash: tx });
+  if (receipt.status !== "success") {
+    return {
+      success: false,
+      errorReason: ErrInvalidTransactionState,
+      transaction: tx,
+      network: payload.accepted.network,
+      payer
+    };
+  }
+  return {
+    success: true,
+    transaction: tx,
+    network: payload.accepted.network,
+    payer
+  };
+}
+function mapSettleError(error, payload, payer) {
+  let errorReason = ErrTransactionFailed;
+  if (error instanceof Error) {
+    const message = error.message;
+    if (message.includes("Permit2612AmountMismatch")) {
+      errorReason = ErrPermit2612AmountMismatch;
+    } else if (message.includes("InvalidAmount")) {
+      errorReason = ErrPermit2InvalidAmount;
+    } else if (message.includes("InvalidDestination")) {
+      errorReason = ErrPermit2InvalidDestination;
+    } else if (message.includes("InvalidOwner")) {
+      errorReason = ErrPermit2InvalidOwner;
+    } else if (message.includes("PaymentTooEarly")) {
+      errorReason = ErrPermit2PaymentTooEarly;
+    } else if (message.includes("InvalidSignature") || message.includes("SignatureExpired")) {
+      errorReason = ErrPermit2InvalidSignature;
+    } else if (message.includes("InvalidNonce")) {
+      errorReason = ErrPermit2InvalidNonce;
+    } else if (message.includes("erc20_approval_tx_failed")) {
+      errorReason = ErrErc20ApprovalTxFailed;
+    } else {
+      errorReason = `${ErrTransactionFailed}: ${message.slice(0, 500)}`;
+    }
+  }
+  return {
+    success: false,
+    errorReason,
+    transaction: "",
+    network: payload.accepted.network,
+    payer
+  };
+}
+function validateEip2612PermitForPayment(info, payer, tokenAddress) {
+  if (!validateEip2612GasSponsoringInfo(info)) {
+    return { isValid: false, invalidReason: ErrInvalidEip2612ExtensionFormat };
+  }
+  if (getAddress3(info.from) !== getAddress3(payer)) {
+    return { isValid: false, invalidReason: ErrEip2612FromMismatch };
+  }
+  if (getAddress3(info.asset) !== tokenAddress) {
+    return { isValid: false, invalidReason: ErrEip2612AssetMismatch };
+  }
+  if (getAddress3(info.spender) !== getAddress3(PERMIT2_ADDRESS)) {
+    return { isValid: false, invalidReason: ErrEip2612SpenderNotPermit2 };
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  if (BigInt(info.deadline) < BigInt(now + 6)) {
+    return { isValid: false, invalidReason: ErrEip2612DeadlineExpired };
+  }
+  return { isValid: true };
+}
+
 // src/exact/facilitator/permit2.ts
-async function verifyPermit2(signer, payload, requirements, permit2Payload, context) {
+async function verifyPermit2(signer, payload, requirements, permit2Payload, context, options) {
   const payer = permit2Payload.permit2Authorization.from;
   if (payload.accepted.scheme !== "exact" || requirements.scheme !== "exact") {
     return {
       isValid: false,
-      invalidReason: "unsupported_scheme",
+      invalidReason: ErrUnsupportedPayloadType,
       payer
     };
   }
   if (payload.accepted.network !== requirements.network) {
     return {
       isValid: false,
-      invalidReason: "network_mismatch",
+      invalidReason: ErrNetworkMismatch,
       payer
     };
   }
   const chainId = getEvmChainId(requirements.network);
-  const tokenAddress = getAddress3(requirements.asset);
-  if (getAddress3(permit2Payload.permit2Authorization.spender) !== getAddress3(x402ExactPermit2ProxyAddress)) {
+  const tokenAddress = getAddress4(requirements.asset);
+  if (getAddress4(permit2Payload.permit2Authorization.spender) !== getAddress4(x402ExactPermit2ProxyAddress)) {
     return {
       isValid: false,
-      invalidReason: "invalid_permit2_spender",
+      invalidReason: ErrPermit2InvalidSpender,
       payer
     };
   }
-  if (getAddress3(permit2Payload.permit2Authorization.witness.to) !== getAddress3(requirements.payTo)) {
+  if (getAddress4(permit2Payload.permit2Authorization.witness.to) !== getAddress4(requirements.payTo)) {
     return {
       isValid: false,
-      invalidReason: "invalid_permit2_recipient_mismatch",
+      invalidReason: ErrPermit2RecipientMismatch,
       payer
     };
   }
@@ -418,28 +667,28 @@ async function verifyPermit2(signer, payload, requirements, permit2Payload, cont
   if (BigInt(permit2Payload.permit2Authorization.deadline) < BigInt(now + 6)) {
     return {
       isValid: false,
-      invalidReason: "permit2_deadline_expired",
+      invalidReason: ErrPermit2DeadlineExpired,
       payer
     };
   }
   if (BigInt(permit2Payload.permit2Authorization.witness.validAfter) > BigInt(now)) {
     return {
       isValid: false,
-      invalidReason: "permit2_not_yet_valid",
+      invalidReason: ErrPermit2NotYetValid,
       payer
     };
   }
   if (BigInt(permit2Payload.permit2Authorization.permitted.amount) !== BigInt(requirements.amount)) {
     return {
       isValid: false,
-      invalidReason: "permit2_amount_mismatch",
+      invalidReason: ErrPermit2AmountMismatch,
       payer
     };
   }
-  if (getAddress3(permit2Payload.permit2Authorization.permitted.token) !== tokenAddress) {
+  if (getAddress4(permit2Payload.permit2Authorization.permitted.token) !== tokenAddress) {
     return {
       isValid: false,
-      invalidReason: "permit2_token_mismatch",
+      invalidReason: ErrPermit2TokenMismatch,
       payer
     };
   }
@@ -453,125 +702,114 @@ async function verifyPermit2(signer, payload, requirements, permit2Payload, cont
     },
     message: {
       permitted: {
-        token: getAddress3(permit2Payload.permit2Authorization.permitted.token),
+        token: getAddress4(permit2Payload.permit2Authorization.permitted.token),
         amount: BigInt(permit2Payload.permit2Authorization.permitted.amount)
       },
-      spender: getAddress3(permit2Payload.permit2Authorization.spender),
+      spender: getAddress4(permit2Payload.permit2Authorization.spender),
       nonce: BigInt(permit2Payload.permit2Authorization.nonce),
       deadline: BigInt(permit2Payload.permit2Authorization.deadline),
       witness: {
-        to: getAddress3(permit2Payload.permit2Authorization.witness.to),
+        to: getAddress4(permit2Payload.permit2Authorization.witness.to),
         validAfter: BigInt(permit2Payload.permit2Authorization.witness.validAfter)
       }
     }
   };
+  let signatureValid = false;
   try {
-    const isValid = await signer.verifyTypedData({
+    signatureValid = await signer.verifyTypedData({
       address: payer,
       ...permit2TypedData,
       signature: permit2Payload.signature
     });
-    if (!isValid) {
-      return {
-        isValid: false,
-        invalidReason: "invalid_permit2_signature",
-        payer
-      };
-    }
   } catch {
-    return {
-      isValid: false,
-      invalidReason: "invalid_permit2_signature",
-      payer
-    };
+    signatureValid = false;
   }
-  const allowanceResult = await _verifyPermit2Allowance(
-    signer,
-    payload,
-    requirements,
-    payer,
-    tokenAddress,
-    context
-  );
-  if (allowanceResult) {
-    return allowanceResult;
-  }
-  try {
-    const balance = await signer.readContract({
-      address: tokenAddress,
-      abi: eip3009ABI,
-      functionName: "balanceOf",
-      args: [payer]
-    });
-    if (balance < BigInt(requirements.amount)) {
+  if (!signatureValid) {
+    const bytecode = await signer.getCode({ address: payer });
+    const isDeployedContract = bytecode && bytecode !== "0x";
+    if (!isDeployedContract) {
       return {
         isValid: false,
-        invalidReason: "insufficient_funds",
-        invalidMessage: `Insufficient funds to complete the payment. Required: ${requirements.amount} ${requirements.asset}, Available: ${balance.toString()} ${requirements.asset}. Please add funds to your wallet and try again.`,
+        invalidReason: ErrPermit2InvalidSignature,
         payer
       };
     }
-  } catch {
   }
-  return {
-    isValid: true,
-    invalidReason: void 0,
-    payer
-  };
-}
-async function _verifyPermit2Allowance(signer, payload, requirements, payer, tokenAddress, context) {
-  try {
-    const allowance = await signer.readContract({
-      address: tokenAddress,
-      abi: erc20AllowanceAbi,
-      functionName: "allowance",
-      args: [payer, PERMIT2_ADDRESS]
-    });
-    if (allowance >= BigInt(requirements.amount)) {
-      return null;
+  if (options?.simulate === false) {
+    return { isValid: true, invalidReason: void 0, payer };
+  }
+  const eip2612Info = extractEip2612GasSponsoringInfo(payload);
+  if (eip2612Info) {
+    const fieldResult = validateEip2612PermitForPayment(eip2612Info, payer, tokenAddress);
+    if (!fieldResult.isValid) {
+      return { isValid: false, invalidReason: fieldResult.invalidReason, payer };
     }
-    const eip2612Info = extractEip2612GasSponsoringInfo(payload);
-    if (eip2612Info) {
-      const result = validateEip2612PermitForPayment(eip2612Info, payer, tokenAddress);
-      if (!result.isValid) {
-        return { isValid: false, invalidReason: result.invalidReason, payer };
-      }
-      return null;
+    const simOk2 = await simulatePermit2SettleWithPermit(signer, permit2Payload, eip2612Info);
+    if (!simOk2) {
+      return diagnosePermit2SimulationFailure(
+        signer,
+        tokenAddress,
+        permit2Payload,
+        requirements.amount
+      );
     }
-    const erc20GasSponsorshipExtension = context?.getExtension(
-      ERC20_APPROVAL_GAS_SPONSORING.key
-    );
-    if (erc20GasSponsorshipExtension) {
-      const erc20Info = extractErc20ApprovalGasSponsoringInfo(payload);
-      if (erc20Info) {
-        const result = await validateErc20ApprovalForPayment(erc20Info, payer, tokenAddress);
-        if (!result.isValid) {
-          return { isValid: false, invalidReason: result.invalidReason, payer };
-        }
-        return null;
+    return { isValid: true, invalidReason: void 0, payer };
+  }
+  const erc20GasSponsorshipExtension = context?.getExtension(
+    ERC20_APPROVAL_GAS_SPONSORING_KEY
+  );
+  if (erc20GasSponsorshipExtension) {
+    const erc20Info = extractErc20ApprovalGasSponsoringInfo(payload);
+    if (erc20Info) {
+      const fieldResult = await validateErc20ApprovalForPayment(erc20Info, payer, tokenAddress);
+      if (!fieldResult.isValid) {
+        return { isValid: false, invalidReason: fieldResult.invalidReason, payer };
       }
-    }
-    return { isValid: false, invalidReason: "permit2_allowance_required", payer };
-  } catch {
-    const eip2612Info = extractEip2612GasSponsoringInfo(payload);
-    if (eip2612Info) {
-      const result = validateEip2612PermitForPayment(eip2612Info, payer, tokenAddress);
-      if (!result.isValid) {
-        return { isValid: false, invalidReason: result.invalidReason, payer };
+      const extensionSigner = resolveErc20ApprovalExtensionSigner(
+        erc20GasSponsorshipExtension,
+        requirements.network
+      );
+      if (extensionSigner?.simulateTransactions) {
+        const simOk2 = await simulatePermit2SettleWithErc20Approval(
+          extensionSigner,
+          permit2Payload,
+          erc20Info
+        );
+        if (!simOk2) {
+          return diagnosePermit2SimulationFailure(
+            signer,
+            tokenAddress,
+            permit2Payload,
+            requirements.amount
+          );
+        }
+        return { isValid: true, invalidReason: void 0, payer };
       }
+      return checkPermit2Prerequisites(signer, tokenAddress, payer, requirements.amount);
     }
-    return null;
   }
+  const simOk = await simulatePermit2Settle(signer, permit2Payload);
+  if (!simOk) {
+    return diagnosePermit2SimulationFailure(
+      signer,
+      tokenAddress,
+      permit2Payload,
+      requirements.amount
+    );
+  }
+  return { isValid: true, invalidReason: void 0, payer };
 }
-async function settlePermit2(signer, payload, requirements, permit2Payload, context) {
+async function settlePermit2(signer, payload, requirements, permit2Payload, context, config) {
   const payer = permit2Payload.permit2Authorization.from;
-  const valid = await verifyPermit2(signer, payload, requirements, permit2Payload, context);
+  const valid = await verifyPermit2(signer, payload, requirements, permit2Payload, context, {
+    simulate: config?.simulateInSettle ?? false
+  });
   if (!valid.isValid) {
     return {
       success: false,
       network: payload.accepted.network,
       transaction: "",
-      errorReason: valid.invalidReason ?? "invalid_scheme",
+      errorReason: valid.invalidReason ?? ErrInvalidScheme,
       payer
     };
   }
@@ -582,15 +820,14 @@ async function settlePermit2(signer, payload, requirements, permit2Payload, cont
   const erc20Info = extractErc20ApprovalGasSponsoringInfo(payload);
   if (erc20Info) {
     const erc20GasSponsorshipExtension = context?.getExtension(
-      ERC20_APPROVAL_GAS_SPONSORING.key
+      ERC20_APPROVAL_GAS_SPONSORING_KEY
     );
-    if (erc20GasSponsorshipExtension?.signer) {
-      return _settlePermit2WithERC20Approval(
-        erc20GasSponsorshipExtension.signer,
-        payload,
-        permit2Payload,
-        erc20Info
-      );
+    const extensionSigner = resolveErc20ApprovalExtensionSigner(
+      erc20GasSponsorshipExtension,
+      payload.accepted.network
+    );
+    if (extensionSigner) {
+      return _settlePermit2WithERC20Approval(extensionSigner, payload, permit2Payload, erc20Info);
     }
   }
   return _settlePermit2Direct(signer, payload, permit2Payload);
@@ -611,69 +848,26 @@ async function _settlePermit2WithEIP2612(signer, payload, permit2Payload, eip261
           s,
           v
         },
-        {
-          permitted: {
-            token: getAddress3(permit2Payload.permit2Authorization.permitted.token),
-            amount: BigInt(permit2Payload.permit2Authorization.permitted.amount)
-          },
-          nonce: BigInt(permit2Payload.permit2Authorization.nonce),
-          deadline: BigInt(permit2Payload.permit2Authorization.deadline)
-        },
-        getAddress3(payer),
-        {
-          to: getAddress3(permit2Payload.permit2Authorization.witness.to),
-          validAfter: BigInt(permit2Payload.permit2Authorization.witness.validAfter)
-        },
-        permit2Payload.signature
+        ...buildPermit2SettleArgs(permit2Payload)
       ]
     });
-    return _waitAndReturn(signer, tx, payload, payer);
+    return waitAndReturn(signer, tx, payload, payer);
   } catch (error) {
-    return _mapSettleError(error, payload, payer);
+    return mapSettleError(error, payload, payer);
   }
 }
 async function _settlePermit2WithERC20Approval(extensionSigner, payload, permit2Payload, erc20Info) {
   const payer = permit2Payload.permit2Authorization.from;
   try {
-    const approvalTxHash = await extensionSigner.sendRawTransaction({
-      serializedTransaction: erc20Info.signedTransaction
-    });
-    const approvalReceipt = await extensionSigner.waitForTransactionReceipt({
-      hash: approvalTxHash
-    });
-    if (approvalReceipt.status !== "success") {
-      return {
-        success: false,
-        errorReason: "erc20_approval_tx_failed",
-        transaction: approvalTxHash,
-        network: payload.accepted.network,
-        payer
-      };
-    }
-    const tx = await extensionSigner.writeContract({
-      address: x402ExactPermit2ProxyAddress,
-      abi: x402ExactPermit2ProxyABI,
-      functionName: "settle",
-      args: [
-        {
-          permitted: {
-            token: getAddress3(permit2Payload.permit2Authorization.permitted.token),
-            amount: BigInt(permit2Payload.permit2Authorization.permitted.amount)
-          },
-          nonce: BigInt(permit2Payload.permit2Authorization.nonce),
-          deadline: BigInt(permit2Payload.permit2Authorization.deadline)
-        },
-        getAddress3(payer),
-        {
-          to: getAddress3(permit2Payload.permit2Authorization.witness.to),
-          validAfter: BigInt(permit2Payload.permit2Authorization.witness.validAfter)
-        },
-        permit2Payload.signature
-      ]
-    });
-    return _waitAndReturn(extensionSigner, tx, payload, payer);
+    const settleData = encodePermit2SettleCalldata(permit2Payload);
+    const txHashes = await extensionSigner.sendTransactions([
+      erc20Info.signedTransaction,
+      { to: x402ExactPermit2ProxyAddress, data: settleData, gas: BigInt(3e5) }
+    ]);
+    const settleTxHash = txHashes[txHashes.length - 1];
+    return waitAndReturn(extensionSigner, settleTxHash, payload, payer);
   } catch (error) {
-    return _mapSettleError(error, payload, payer);
+    return mapSettleError(error, payload, payer);
   }
 }
 async function _settlePermit2Direct(signer, payload, permit2Payload) {
@@ -683,106 +877,12 @@ async function _settlePermit2Direct(signer, payload, permit2Payload) {
       address: x402ExactPermit2ProxyAddress,
       abi: x402ExactPermit2ProxyABI,
       functionName: "settle",
-      args: [
-        {
-          permitted: {
-            token: getAddress3(permit2Payload.permit2Authorization.permitted.token),
-            amount: BigInt(permit2Payload.permit2Authorization.permitted.amount)
-          },
-          nonce: BigInt(permit2Payload.permit2Authorization.nonce),
-          deadline: BigInt(permit2Payload.permit2Authorization.deadline)
-        },
-        getAddress3(payer),
-        {
-          to: getAddress3(permit2Payload.permit2Authorization.witness.to),
-          validAfter: BigInt(permit2Payload.permit2Authorization.witness.validAfter)
-        },
-        permit2Payload.signature
-      ]
+      args: buildPermit2SettleArgs(permit2Payload)
     });
-    return _waitAndReturn(signer, tx, payload, payer);
+    return waitAndReturn(signer, tx, payload, payer);
   } catch (error) {
-    return _mapSettleError(error, payload, payer);
-  }
-}
-async function _waitAndReturn(signer, tx, payload, payer) {
-  const receipt = await signer.waitForTransactionReceipt({ hash: tx });
-  if (receipt.status !== "success") {
-    return {
-      success: false,
-      errorReason: "invalid_transaction_state",
-      transaction: tx,
-      network: payload.accepted.network,
-      payer
-    };
+    return mapSettleError(error, payload, payer);
   }
-  return {
-    success: true,
-    transaction: tx,
-    network: payload.accepted.network,
-    payer
-  };
-}
-function _mapSettleError(error, payload, payer) {
-  let errorReason = "transaction_failed";
-  if (error instanceof Error) {
-    const message = error.message;
-    if (message.includes("Permit2612AmountMismatch")) {
-      errorReason = ErrPermit2612AmountMismatch;
-    } else if (message.includes("InvalidAmount")) {
-      errorReason = ErrPermit2InvalidAmount;
-    } else if (message.includes("InvalidDestination")) {
-      errorReason = ErrPermit2InvalidDestination;
-    } else if (message.includes("InvalidOwner")) {
-      errorReason = ErrPermit2InvalidOwner;
-    } else if (message.includes("PaymentTooEarly")) {
-      errorReason = ErrPermit2PaymentTooEarly;
-    } else if (message.includes("InvalidSignature") || message.includes("SignatureExpired")) {
-      errorReason = ErrPermit2InvalidSignature;
-    } else if (message.includes("InvalidNonce")) {
-      errorReason = ErrPermit2InvalidNonce;
-    } else {
-      errorReason = `transaction_failed: ${message.slice(0, 500)}`;
-    }
-  }
-  return {
-    success: false,
-    errorReason,
-    transaction: "",
-    network: payload.accepted.network,
-    payer
-  };
-}
-function validateEip2612PermitForPayment(info, payer, tokenAddress) {
-  if (!validateEip2612GasSponsoringInfo(info)) {
-    return { isValid: false, invalidReason: "invalid_eip2612_extension_format" };
-  }
-  if (getAddress3(info.from) !== getAddress3(payer)) {
-    return { isValid: false, invalidReason: "eip2612_from_mismatch" };
-  }
-  if (getAddress3(info.asset) !== tokenAddress) {
-    return { isValid: false, invalidReason: "eip2612_asset_mismatch" };
-  }
-  if (getAddress3(info.spender) !== getAddress3(PERMIT2_ADDRESS)) {
-    return { isValid: false, invalidReason: "eip2612_spender_not_permit2" };
-  }
-  const now = Math.floor(Date.now() / 1e3);
-  if (BigInt(info.deadline) < BigInt(now + 6)) {
-    return { isValid: false, invalidReason: "eip2612_deadline_expired" };
-  }
-  return { isValid: true };
-}
-function splitEip2612Signature(signature) {
-  const sig = signature.startsWith("0x") ? signature.slice(2) : signature;
-  if (sig.length !== 130) {
-    throw new Error(
-      `invalid EIP-2612 signature length: expected 65 bytes (130 hex chars), got ${sig.length / 2} bytes`
-    );
-  }
-  const r = `0x${sig.slice(0, 64)}`;
-  const s = `0x${sig.slice(64, 128)}`;
-  const v = parseInt(sig.slice(128, 130), 16);
-  return { v, r, s };
 }
 
 // src/exact/facilitator/scheme.ts
@@ -798,7 +898,8 @@ var ExactEvmScheme = class {
     this.scheme = "exact";
     this.caipFamily = "eip155:*";
     this.config = {
-      deployERC4337WithEIP6492: config?.deployERC4337WithEIP6492 ?? false
+      deployERC4337WithEIP6492: config?.deployERC4337WithEIP6492 ?? false,
+      simulateInSettle: config?.simulateInSettle ?? false
     };
   }
   /**
@@ -829,7 +930,8 @@ var ExactEvmScheme = class {
    */
   async verify(payload, requirements, context) {
     const rawPayload = payload.payload;
-    if (isPermit2Payload(rawPayload)) {
+    const isPermit2 = isPermit2Payload(rawPayload);
+    if (isPermit2) {
       return verifyPermit2(this.signer, payload, requirements, rawPayload, context);
     }
     const eip3009Payload = rawPayload;
@@ -845,8 +947,11 @@ var ExactEvmScheme = class {
    */
   async settle(payload, requirements, context) {
     const rawPayload = payload.payload;
-    if (isPermit2Payload(rawPayload)) {
-      return settlePermit2(this.signer, payload, requirements, rawPayload, context);
+    const isPermit2 = isPermit2Payload(rawPayload);
+    if (isPermit2) {
+      return settlePermit2(this.signer, payload, requirements, rawPayload, context, {
+        simulateInSettle: this.config.simulateInSettle
+      });
     }
     const eip3009Payload = rawPayload;
     return settleEIP3009(this.signer, payload, requirements, eip3009Payload, this.config);
@@ -858,13 +963,15 @@ function registerExactEvmScheme(facilitator, config) {
   facilitator.register(
     config.networks,
     new ExactEvmScheme(config.signer, {
-      deployERC4337WithEIP6492: config.deployERC4337WithEIP6492
+      deployERC4337WithEIP6492: config.deployERC4337WithEIP6492,
+      simulateInSettle: config.simulateInSettle
     })
   );
   facilitator.registerV1(
     NETWORKS,
     new ExactEvmSchemeV1(config.signer, {
-      deployERC4337WithEIP6492: config.deployERC4337WithEIP6492
+      deployERC4337WithEIP6492: config.deployERC4337WithEIP6492,
+      simulateInSettle: config.simulateInSettle
     })
   );
   return facilitator;