@gasfree-kit/evm-4337 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,146 @@
+import * as _tetherto_wdk_wallet_evm_erc_4337 from '@tetherto/wdk-wallet-evm-erc-4337';
+import * as _gasfree_kit_core from '@gasfree-kit/core';
+import { EvmChain } from '@gasfree-kit/core';
+
+type EvmErc4337NetworkConfig = {
+    chainId: number;
+    provider: string;
+    bundlerUrl: string;
+    paymasterUrl: string;
+    paymasterAddress: string;
+    entryPointAddress: string;
+    safeModulesVersion: string;
+    transferMaxFee: number;
+    isSponsored: boolean;
+    sponsorshipPolicyId: string;
+    paymasterToken: {
+        address: string;
+    };
+};
+type EVM4337ClientConfig = {
+    chain: EvmChain;
+    rpcUrl: string;
+    bundlerUrl: string;
+    paymasterUrl: string;
+    entryPointAddress?: string;
+    safeModulesVersion?: string;
+    /** Must be explicitly set. When true, requires sponsorshipPolicyId. */
+    isSponsored: boolean;
+    sponsorshipPolicyId?: string;
+    paymasterAddress?: string;
+    paymasterTokenAddress?: string;
+};
+/**
+ * Build the full ERC-4337 network config from user-provided client config.
+ * Matches the structure expected by @tetherto/wdk-wallet-evm-erc-4337.
+ */
+declare function getErc4337ConfigForChain(config: EVM4337ClientConfig): EvmErc4337NetworkConfig;
+/** Conservative gas fee fallback estimates per chain (USDT 6 decimals). */
+declare const GAS_FEE_FALLBACKS: Record<string, bigint>;
+/** Fallback fee estimates as human-readable strings. */
+declare const GAS_FEE_ESTIMATES: Record<string, string>;
+
+/**
+ * Set up an ERC-4337 wallet via WDK.
+ *
+ * Dynamically imports @tetherto/wdk-wallet-evm-erc-4337 and builds the
+ * correct discriminated-union config:
+ * - Sponsored mode → EvmErc4337WalletSponsorshipPolicyConfig
+ * - Non-sponsored  → EvmErc4337WalletPaymasterTokenConfig
+ */
+declare function setupErc4337Wallet(seedPhrase: string, config: EVM4337ClientConfig, accountIndex?: number): Promise<{
+    wallet: _tetherto_wdk_wallet_evm_erc_4337.default;
+    account: _tetherto_wdk_wallet_evm_erc_4337.EvmAccount;
+    address: string;
+}>;
+
+declare class TetherEVMERC4337Transfer {
+    /** Default timeout for UserOp confirmation: 120 seconds. */
+    private static readonly USER_OP_TIMEOUT_MS;
+    /**
+     * Wait for a UserOperation to be included on-chain via the Candide bundler.
+     * Times out after USER_OP_TIMEOUT_MS to prevent indefinite hangs.
+     */
+    private static waitForUserOpConfirmation;
+    /**
+     * Get transaction fee estimate for a USDT transfer.
+     *
+     * Uses a minimal quote amount (gas cost is the same regardless of transfer
+     * amount). Applies a gas buffer (35% Ethereum, 30% others) for volatility.
+     */
+    static getTransactionEstimateFee(seedPhrase: string, config: EVM4337ClientConfig, recipientAddress: string, accountIndex?: number): Promise<{
+        message: string;
+        success: boolean;
+        data: {
+            fee: string;
+        };
+    }>;
+    /**
+     * Check token balance on an EVM chain.
+     */
+    static checkTokenBalance(seedPhrase: string, config: EVM4337ClientConfig, tokenAddress: string): Promise<{
+        message: string;
+        success: boolean;
+        data: {
+            tokenBalance: string;
+            decimals: number;
+            usdBalance: string;
+        };
+    }>;
+    /**
+     * Send a single USDT transfer via ERC-4337.
+     *
+     * Handles:
+     * - Balance validation
+     * - Gas fee auto-adjustment for non-sponsored mode
+     * - On-chain confirmation via Candide bundler
+     * - User-friendly error mapping
+     */
+    static sendToken(seedPhrase: string, config: EVM4337ClientConfig, tokenAddress: string, amount: string, recipientAddress: string, accountIndex?: number): Promise<{
+        success: boolean;
+        transactionHash: string;
+        chain: _gasfree_kit_core.EvmChain;
+        amount: string;
+    }>;
+    /**
+     * Send a batch USDT transfer to multiple recipients in a single UserOperation.
+     */
+    static sendBatchToken(seedPhrase: string, config: EVM4337ClientConfig, tokenAddress: string, recipients: Array<{
+        address: string;
+        amount: string;
+    }>, accountIndex?: number): Promise<{
+        success: boolean;
+        transactionHash: string;
+        chain: _gasfree_kit_core.EvmChain;
+        recipients: {
+            address: string;
+            amount: string;
+        }[];
+    }>;
+    /**
+     * Map raw errors into user-friendly messages.
+     */
+    static handleTransferError(error: unknown, chain: string): Error;
+}
+
+/**
+ * Convert USDT amount to base units (BigInt).
+ * USDT on EVM chains uses 6 decimals.
+ */
+declare function toUsdtBaseUnitsEvm(amount: number | string): bigint;
+/**
+ * Convert a raw token balance (BigInt) to a human-readable string.
+ */
+declare function formatTokenBalance(rawBalance: bigint, decimals?: number, precision?: number): string;
+/**
+ * Encode an ERC-20 transfer(address,uint256) call.
+ * Uses proper ABI encoding with validation to prevent malformed calldata.
+ */
+declare function encodeErc20Transfer(to: string, amount: bigint): string;
+/**
+ * Convert gas fee in wei to USDT value using native token price.
+ * Uses BigInt arithmetic to avoid precision loss for large wei values.
+ */
+declare function feeToUsdt(feeInWei: bigint, nativeTokenPriceUsdt: number): string;
+
+export { type EVM4337ClientConfig, type EvmErc4337NetworkConfig, GAS_FEE_ESTIMATES, GAS_FEE_FALLBACKS, TetherEVMERC4337Transfer, encodeErc20Transfer, feeToUsdt, formatTokenBalance, getErc4337ConfigForChain, setupErc4337Wallet, toUsdtBaseUnitsEvm };

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+import * as _tetherto_wdk_wallet_evm_erc_4337 from '@tetherto/wdk-wallet-evm-erc-4337';
+import * as _gasfree_kit_core from '@gasfree-kit/core';
+import { EvmChain } from '@gasfree-kit/core';
+
+type EvmErc4337NetworkConfig = {
+    chainId: number;
+    provider: string;
+    bundlerUrl: string;
+    paymasterUrl: string;
+    paymasterAddress: string;
+    entryPointAddress: string;
+    safeModulesVersion: string;
+    transferMaxFee: number;
+    isSponsored: boolean;
+    sponsorshipPolicyId: string;
+    paymasterToken: {
+        address: string;
+    };
+};
+type EVM4337ClientConfig = {
+    chain: EvmChain;
+    rpcUrl: string;
+    bundlerUrl: string;
+    paymasterUrl: string;
+    entryPointAddress?: string;
+    safeModulesVersion?: string;
+    /** Must be explicitly set. When true, requires sponsorshipPolicyId. */
+    isSponsored: boolean;
+    sponsorshipPolicyId?: string;
+    paymasterAddress?: string;
+    paymasterTokenAddress?: string;
+};
+/**
+ * Build the full ERC-4337 network config from user-provided client config.
+ * Matches the structure expected by @tetherto/wdk-wallet-evm-erc-4337.
+ */
+declare function getErc4337ConfigForChain(config: EVM4337ClientConfig): EvmErc4337NetworkConfig;
+/** Conservative gas fee fallback estimates per chain (USDT 6 decimals). */
+declare const GAS_FEE_FALLBACKS: Record<string, bigint>;
+/** Fallback fee estimates as human-readable strings. */
+declare const GAS_FEE_ESTIMATES: Record<string, string>;
+
+/**
+ * Set up an ERC-4337 wallet via WDK.
+ *
+ * Dynamically imports @tetherto/wdk-wallet-evm-erc-4337 and builds the
+ * correct discriminated-union config:
+ * - Sponsored mode → EvmErc4337WalletSponsorshipPolicyConfig
+ * - Non-sponsored  → EvmErc4337WalletPaymasterTokenConfig
+ */
+declare function setupErc4337Wallet(seedPhrase: string, config: EVM4337ClientConfig, accountIndex?: number): Promise<{
+    wallet: _tetherto_wdk_wallet_evm_erc_4337.default;
+    account: _tetherto_wdk_wallet_evm_erc_4337.EvmAccount;
+    address: string;
+}>;
+
+declare class TetherEVMERC4337Transfer {
+    /** Default timeout for UserOp confirmation: 120 seconds. */
+    private static readonly USER_OP_TIMEOUT_MS;
+    /**
+     * Wait for a UserOperation to be included on-chain via the Candide bundler.
+     * Times out after USER_OP_TIMEOUT_MS to prevent indefinite hangs.
+     */
+    private static waitForUserOpConfirmation;
+    /**
+     * Get transaction fee estimate for a USDT transfer.
+     *
+     * Uses a minimal quote amount (gas cost is the same regardless of transfer
+     * amount). Applies a gas buffer (35% Ethereum, 30% others) for volatility.
+     */
+    static getTransactionEstimateFee(seedPhrase: string, config: EVM4337ClientConfig, recipientAddress: string, accountIndex?: number): Promise<{
+        message: string;
+        success: boolean;
+        data: {
+            fee: string;
+        };
+    }>;
+    /**
+     * Check token balance on an EVM chain.
+     */
+    static checkTokenBalance(seedPhrase: string, config: EVM4337ClientConfig, tokenAddress: string): Promise<{
+        message: string;
+        success: boolean;
+        data: {
+            tokenBalance: string;
+            decimals: number;
+            usdBalance: string;
+        };
+    }>;
+    /**
+     * Send a single USDT transfer via ERC-4337.
+     *
+     * Handles:
+     * - Balance validation
+     * - Gas fee auto-adjustment for non-sponsored mode
+     * - On-chain confirmation via Candide bundler
+     * - User-friendly error mapping
+     */
+    static sendToken(seedPhrase: string, config: EVM4337ClientConfig, tokenAddress: string, amount: string, recipientAddress: string, accountIndex?: number): Promise<{
+        success: boolean;
+        transactionHash: string;
+        chain: _gasfree_kit_core.EvmChain;
+        amount: string;
+    }>;
+    /**
+     * Send a batch USDT transfer to multiple recipients in a single UserOperation.
+     */
+    static sendBatchToken(seedPhrase: string, config: EVM4337ClientConfig, tokenAddress: string, recipients: Array<{
+        address: string;
+        amount: string;
+    }>, accountIndex?: number): Promise<{
+        success: boolean;
+        transactionHash: string;
+        chain: _gasfree_kit_core.EvmChain;
+        recipients: {
+            address: string;
+            amount: string;
+        }[];
+    }>;
+    /**
+     * Map raw errors into user-friendly messages.
+     */
+    static handleTransferError(error: unknown, chain: string): Error;
+}
+
+/**
+ * Convert USDT amount to base units (BigInt).
+ * USDT on EVM chains uses 6 decimals.
+ */
+declare function toUsdtBaseUnitsEvm(amount: number | string): bigint;
+/**
+ * Convert a raw token balance (BigInt) to a human-readable string.
+ */
+declare function formatTokenBalance(rawBalance: bigint, decimals?: number, precision?: number): string;
+/**
+ * Encode an ERC-20 transfer(address,uint256) call.
+ * Uses proper ABI encoding with validation to prevent malformed calldata.
+ */
+declare function encodeErc20Transfer(to: string, amount: bigint): string;
+/**
+ * Convert gas fee in wei to USDT value using native token price.
+ * Uses BigInt arithmetic to avoid precision loss for large wei values.
+ */
+declare function feeToUsdt(feeInWei: bigint, nativeTokenPriceUsdt: number): string;
+
+export { type EVM4337ClientConfig, type EvmErc4337NetworkConfig, GAS_FEE_ESTIMATES, GAS_FEE_FALLBACKS, TetherEVMERC4337Transfer, encodeErc20Transfer, feeToUsdt, formatTokenBalance, getErc4337ConfigForChain, setupErc4337Wallet, toUsdtBaseUnitsEvm };

package/dist/index.js

@@ -0,0 +1,459 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  GAS_FEE_ESTIMATES: () => GAS_FEE_ESTIMATES,
+  GAS_FEE_FALLBACKS: () => GAS_FEE_FALLBACKS,
+  TetherEVMERC4337Transfer: () => TetherEVMERC4337Transfer,
+  encodeErc20Transfer: () => encodeErc20Transfer,
+  feeToUsdt: () => feeToUsdt,
+  formatTokenBalance: () => formatTokenBalance,
+  getErc4337ConfigForChain: () => getErc4337ConfigForChain,
+  setupErc4337Wallet: () => setupErc4337Wallet,
+  toUsdtBaseUnitsEvm: () => toUsdtBaseUnitsEvm
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/evmNetworkConfiguration.ts
+var import_core = require("@gasfree-kit/core");
+var DEFAULT_ENTRY_POINT = "0x0000000071727De22E5E9d8BAf0edAc6f37da032";
+var DEFAULT_SAFE_MODULES_VERSION = "0.3.0";
+var DEFAULT_PAYMASTER_ADDRESS = "0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba";
+var DEFAULT_TRANSFER_MAX_FEE = 1e15;
+function getErc4337ConfigForChain(config) {
+  const chainConfig = import_core.EVM_CHAINS[config.chain];
+  return {
+    chainId: chainConfig.chainId,
+    provider: config.rpcUrl,
+    bundlerUrl: config.bundlerUrl,
+    paymasterUrl: config.paymasterUrl,
+    paymasterAddress: config.paymasterAddress ?? DEFAULT_PAYMASTER_ADDRESS,
+    entryPointAddress: config.entryPointAddress ?? DEFAULT_ENTRY_POINT,
+    safeModulesVersion: config.safeModulesVersion ?? DEFAULT_SAFE_MODULES_VERSION,
+    transferMaxFee: DEFAULT_TRANSFER_MAX_FEE,
+    isSponsored: config.isSponsored,
+    sponsorshipPolicyId: config.sponsorshipPolicyId ?? "",
+    paymasterToken: {
+      address: config.paymasterTokenAddress ?? chainConfig.usdtAddress
+    }
+  };
+}
+var GAS_FEE_FALLBACKS = {
+  ethereum: 1400000n,
+  arbitrum: 100000n,
+  polygon: 100000n,
+  celo: 50000n,
+  optimism: 100000n,
+  base: 150000n
+};
+var GAS_FEE_ESTIMATES = {
+  ethereum: "1.40",
+  arbitrum: "0.10",
+  polygon: "0.10",
+  celo: "0.05",
+  optimism: "0.10",
+  base: "0.15"
+};
+
+// src/evmERC4337.ts
+async function setupErc4337Wallet(seedPhrase, config, accountIndex = 0) {
+  const networkConfig = getErc4337ConfigForChain(config);
+  const WalletManagerEvmErc4337Module = await import("@tetherto/wdk-wallet-evm-erc-4337");
+  const WalletManagerEvmErc4337 = WalletManagerEvmErc4337Module.default;
+  const wdkConfig = networkConfig.isSponsored ? {
+    chainId: networkConfig.chainId,
+    provider: networkConfig.provider,
+    bundlerUrl: networkConfig.bundlerUrl,
+    entryPointAddress: networkConfig.entryPointAddress,
+    safeModulesVersion: networkConfig.safeModulesVersion,
+    isSponsored: true,
+    paymasterUrl: networkConfig.paymasterUrl,
+    sponsorshipPolicyId: networkConfig.sponsorshipPolicyId
+  } : {
+    chainId: networkConfig.chainId,
+    provider: networkConfig.provider,
+    bundlerUrl: networkConfig.bundlerUrl,
+    entryPointAddress: networkConfig.entryPointAddress,
+    safeModulesVersion: networkConfig.safeModulesVersion,
+    paymasterUrl: networkConfig.paymasterUrl,
+    paymasterAddress: networkConfig.paymasterAddress,
+    paymasterToken: networkConfig.paymasterToken
+  };
+  const wallet = new WalletManagerEvmErc4337(
+    seedPhrase,
+    wdkConfig
+  );
+  const account = await wallet.getAccount(accountIndex);
+  const address = await account.getAddress();
+  return { wallet, account, address };
+}
+
+// src/evmERC4337TetherTransfer.ts
+var import_abstractionkit = require("abstractionkit");
+var import_core2 = require("@gasfree-kit/core");
+
+// src/evmUtility.ts
+function toUsdtBaseUnitsEvm(amount) {
+  const str = amount.toString().trim();
+  if (!/^\d+(\.\d+)?$/.test(str)) {
+    throw new Error(`Invalid USDT amount: "${str}". Must be a non-negative decimal number.`);
+  }
+  const decimals = 6;
+  const [integer, fraction = ""] = str.split(".");
+  if (fraction.length > decimals) {
+    throw new Error(
+      `USDT amount has too many decimal places (${fraction.length}). Maximum is ${decimals}.`
+    );
+  }
+  const normalizedFraction = (fraction + "0".repeat(decimals)).slice(0, decimals);
+  return BigInt(integer + normalizedFraction);
+}
+function formatTokenBalance(rawBalance, decimals = 18, precision = 6) {
+  const divisor = 10n ** BigInt(decimals);
+  const whole = rawBalance / divisor;
+  const fraction = rawBalance % divisor;
+  const fractionStr = fraction.toString().padStart(decimals, "0").slice(0, precision);
+  const result = `${whole}.${fractionStr}`.replace(/\.?0+$/, "");
+  return result || "0";
+}
+function encodeErc20Transfer(to, amount) {
+  const TRANSFER_SELECTOR = "0xa9059cbb";
+  const addr = to.startsWith("0x") ? to.slice(2) : to;
+  if (addr.length !== 40) {
+    throw new Error(`Invalid address length for ABI encoding: ${to}`);
+  }
+  const amountHex = amount.toString(16);
+  if (amountHex.length > 64) {
+    throw new Error(`Amount too large for uint256 encoding: ${amount}`);
+  }
+  const paddedAddress = addr.toLowerCase().padStart(64, "0");
+  const paddedAmount = amountHex.padStart(64, "0");
+  return `${TRANSFER_SELECTOR}${paddedAddress}${paddedAmount}`;
+}
+function feeToUsdt(feeInWei, nativeTokenPriceUsdt) {
+  const priceScale = 10n ** 18n;
+  const scaledPrice = BigInt(Math.round(nativeTokenPriceUsdt * Number(priceScale)));
+  const usdtBase = feeInWei * scaledPrice * 1000000n / (10n ** 18n * priceScale);
+  const whole = usdtBase / 1000000n;
+  const frac = (usdtBase % 1000000n).toString().padStart(6, "0");
+  return `${whole}.${frac}`;
+}
+
+// src/evmERC4337TetherTransfer.ts
+var TetherEVMERC4337Transfer = class {
+  /** Default timeout for UserOp confirmation: 120 seconds. */
+  static USER_OP_TIMEOUT_MS = 12e4;
+  /**
+   * Wait for a UserOperation to be included on-chain via the Candide bundler.
+   * Times out after USER_OP_TIMEOUT_MS to prevent indefinite hangs.
+   */
+  static async waitForUserOpConfirmation(userOpHash, bundlerUrl, entryPointAddress) {
+    const bundler = new import_abstractionkit.Bundler(bundlerUrl);
+    const response = new import_abstractionkit.SendUseroperationResponse(userOpHash, bundler, entryPointAddress);
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(
+        () => reject(
+          new import_core2.TransactionFailedError(
+            "evm",
+            `UserOperation confirmation timed out after ${this.USER_OP_TIMEOUT_MS / 1e3}s. Hash: ${userOpHash}`
+          )
+        ),
+        this.USER_OP_TIMEOUT_MS
+      );
+    });
+    const receipt = await Promise.race([response.included(), timeoutPromise]);
+    if (!receipt.success) {
+      throw new import_core2.TransactionFailedError(
+        "evm",
+        `UserOperation reverted. Tx: ${receipt.receipt.transactionHash}`
+      );
+    }
+    return receipt.receipt.transactionHash;
+  }
+  /**
+   * Get transaction fee estimate for a USDT transfer.
+   *
+   * Uses a minimal quote amount (gas cost is the same regardless of transfer
+   * amount). Applies a gas buffer (35% Ethereum, 30% others) for volatility.
+   */
+  static async getTransactionEstimateFee(seedPhrase, config, recipientAddress, accountIndex = 0) {
+    (0, import_core2.validateEvmAddress)(recipientAddress, config.chain, "recipient address");
+    const networkConfig = getErc4337ConfigForChain(config);
+    const { wallet, account } = await setupErc4337Wallet(seedPhrase, config, accountIndex);
+    const tokenAddress = networkConfig.paymasterToken.address;
+    try {
+      const quoteAmount = toUsdtBaseUnitsEvm("0.01");
+      let feeVal;
+      try {
+        const transferQuote = await account.quoteTransfer({
+          token: tokenAddress,
+          recipient: recipientAddress,
+          amount: quoteAmount
+        });
+        const bufferPercent = config.chain === "ethereum" ? 35n : 30n;
+        const bufferedFee = transferQuote.fee + transferQuote.fee * bufferPercent / 100n;
+        feeVal = formatTokenBalance(bufferedFee, 6);
+      } catch (quoteError) {
+        if (quoteError instanceof Error && (quoteError.message.includes("token allowance lower than the required") || quoteError.message.includes("token balance lower than the required"))) {
+          const estimates = {
+            ethereum: "1.40",
+            arbitrum: "0.10",
+            polygon: "0.10",
+            celo: "0.05",
+            optimism: "0.10",
+            base: "0.15"
+          };
+          feeVal = estimates[config.chain] || "0.15";
+        } else {
+          throw quoteError;
+        }
+      }
+      return {
+        message: "Transaction fee estimate retrieved successfully",
+        success: true,
+        data: { fee: feeVal }
+      };
+    } finally {
+      account.dispose();
+      wallet.dispose();
+    }
+  }
+  /**
+   * Check token balance on an EVM chain.
+   */
+  static async checkTokenBalance(seedPhrase, config, tokenAddress) {
+    (0, import_core2.validateEvmAddress)(tokenAddress, config.chain, "token address");
+    const { wallet, account } = await setupErc4337Wallet(seedPhrase, config);
+    try {
+      const balance = await account.getTokenBalance(tokenAddress);
+      const usdBalance = formatTokenBalance(balance, 6);
+      return {
+        message: `${config.chain.toUpperCase()} balances retrieved successfully`,
+        success: true,
+        data: {
+          tokenBalance: balance.toString(),
+          decimals: 6,
+          usdBalance: String(usdBalance)
+        }
+      };
+    } finally {
+      account.dispose();
+      wallet.dispose();
+    }
+  }
+  /**
+   * Send a single USDT transfer via ERC-4337.
+   *
+   * Handles:
+   * - Balance validation
+   * - Gas fee auto-adjustment for non-sponsored mode
+   * - On-chain confirmation via Candide bundler
+   * - User-friendly error mapping
+   */
+  static async sendToken(seedPhrase, config, tokenAddress, amount, recipientAddress, accountIndex = 0) {
+    const networkConfig = getErc4337ConfigForChain(config);
+    const gasSponsored = networkConfig.isSponsored;
+    (0, import_core2.validateEvmAddress)(tokenAddress, config.chain, "token address");
+    (0, import_core2.validateEvmAddress)(recipientAddress, config.chain, "recipient address");
+    const {
+      wallet,
+      account,
+      address: senderAddress
+    } = await setupErc4337Wallet(seedPhrase, config, accountIndex);
+    try {
+      if (recipientAddress.toLowerCase() === senderAddress.toLowerCase()) {
+        throw new import_core2.TransactionFailedError(config.chain, "Cannot transfer to your own address");
+      }
+      const amountInBaseUnits = toUsdtBaseUnitsEvm(amount);
+      const balance = await account.getTokenBalance(tokenAddress);
+      if (!gasSponsored) {
+        let gasFeeBaseUnits;
+        try {
+          const quote = await account.quoteTransfer({
+            token: tokenAddress,
+            recipient: recipientAddress,
+            amount: amountInBaseUnits
+          });
+          const bufferPercent = config.chain === "ethereum" ? 35n : 30n;
+          gasFeeBaseUnits = quote.fee + quote.fee * bufferPercent / 100n;
+        } catch {
+          gasFeeBaseUnits = GAS_FEE_FALLBACKS[config.chain] ?? 150000n;
+        }
+        const totalRequired = amountInBaseUnits + gasFeeBaseUnits;
+        if (BigInt(balance) < totalRequired) {
+          throw new import_core2.InsufficientBalanceError(
+            config.chain,
+            `USDT (need ${formatTokenBalance(totalRequired, 6)} but have ${formatTokenBalance(balance, 6)} \u2014 includes ${formatTokenBalance(gasFeeBaseUnits, 6)} gas fee)`
+          );
+        }
+      } else if (BigInt(balance) < amountInBaseUnits) {
+        throw new import_core2.InsufficientBalanceError(config.chain, "USDT");
+      }
+      const transferResult = await account.transfer({
+        token: tokenAddress,
+        recipient: recipientAddress,
+        amount: amountInBaseUnits
+      });
+      const transactionHash = await this.waitForUserOpConfirmation(
+        transferResult.hash,
+        networkConfig.bundlerUrl,
+        networkConfig.entryPointAddress
+      );
+      return {
+        success: true,
+        transactionHash,
+        chain: config.chain,
+        amount
+      };
+    } catch (error) {
+      throw this.handleTransferError(error, config.chain);
+    } finally {
+      account.dispose();
+      wallet.dispose();
+    }
+  }
+  /**
+   * Send a batch USDT transfer to multiple recipients in a single UserOperation.
+   */
+  static async sendBatchToken(seedPhrase, config, tokenAddress, recipients, accountIndex = 0) {
+    const networkConfig = getErc4337ConfigForChain(config);
+    const gasSponsored = networkConfig.isSponsored;
+    for (const r of recipients) {
+      (0, import_core2.validateEvmAddress)(r.address, config.chain, "recipient address");
+    }
+    const {
+      wallet,
+      account,
+      address: senderAddress
+    } = await setupErc4337Wallet(seedPhrase, config, accountIndex);
+    try {
+      for (const r of recipients) {
+        if (r.address.toLowerCase() === senderAddress.toLowerCase()) {
+          throw new import_core2.TransactionFailedError(config.chain, "Cannot transfer to your own address");
+        }
+      }
+      const totalAmount = recipients.reduce((sum, r) => sum + toUsdtBaseUnitsEvm(r.amount), 0n);
+      const balance = await account.getTokenBalance(tokenAddress);
+      if (!gasSponsored) {
+        const gasFeeReserve = GAS_FEE_FALLBACKS[config.chain] ?? 150000n;
+        const totalRequired = totalAmount + gasFeeReserve;
+        if (BigInt(balance) < totalRequired) {
+          throw new import_core2.InsufficientBalanceError(
+            config.chain,
+            `USDT (need ${formatTokenBalance(totalRequired, 6)} but have ${formatTokenBalance(balance, 6)} \u2014 includes ${formatTokenBalance(gasFeeReserve, 6)} gas fee)`
+          );
+        }
+      } else if (BigInt(balance) < totalAmount) {
+        throw new import_core2.InsufficientBalanceError(config.chain, "USDT");
+      }
+      const batchTransactions = recipients.map(({ address, amount }) => {
+        const amountBase = toUsdtBaseUnitsEvm(amount);
+        return {
+          to: tokenAddress,
+          value: 0,
+          data: encodeErc20Transfer(address, amountBase)
+        };
+      });
+      const transferResult = await account.sendTransaction(batchTransactions);
+      const transactionHash = await this.waitForUserOpConfirmation(
+        transferResult.hash,
+        networkConfig.bundlerUrl,
+        networkConfig.entryPointAddress
+      );
+      return {
+        success: true,
+        transactionHash,
+        chain: config.chain,
+        recipients
+      };
+    } catch (error) {
+      throw this.handleTransferError(error, config.chain);
+    } finally {
+      account.dispose();
+      wallet.dispose();
+    }
+  }
+  /**
+   * Map raw errors into user-friendly messages.
+   */
+  static handleTransferError(error, chain) {
+    if (!(error instanceof Error)) {
+      return new import_core2.TransactionFailedError(chain, "Unknown error");
+    }
+    const msg = error.message;
+    if (msg.includes("callData reverts")) {
+      return new import_core2.TransactionFailedError(
+        chain,
+        "Transaction reverted. Check your balance and try again."
+      );
+    }
+    if (msg.includes("not enough funds")) {
+      return new import_core2.InsufficientBalanceError(chain, "paymaster token");
+    }
+    if (msg.includes("token balance lower than the required") || msg.includes("token allowance lower than the required")) {
+      return new import_core2.InsufficientBalanceError(chain, "USDT (insufficient for transfer + gas)");
+    }
+    if (msg.includes("Insufficient") || error instanceof import_core2.InsufficientBalanceError) {
+      return error;
+    }
+    if (msg.includes("nonce too low")) {
+      return new import_core2.TransactionFailedError(chain, "Nonce conflict. Please try again.");
+    }
+    if (msg.includes("insufficient funds") || msg.includes("transfer amount exceeds balance")) {
+      return new import_core2.InsufficientBalanceError(chain, "USDT");
+    }
+    if (msg.includes("transaction underpriced") || msg.includes("max fee per gas less than block base fee")) {
+      return new import_core2.TransactionFailedError(chain, "Gas price too low. Please try again.");
+    }
+    if (msg.includes("out of gas") || msg.includes("intrinsic gas too low")) {
+      return new import_core2.TransactionFailedError(chain, "Insufficient gas limit.");
+    }
+    if (msg.includes("execution reverted")) {
+      return new import_core2.TransactionFailedError(chain, "Transaction reverted on-chain.");
+    }
+    if (msg.includes("504") || msg.includes("Gateway Time-out")) {
+      return new import_core2.TransactionFailedError(chain, "Network timeout. Please try again.");
+    }
+    return new import_core2.TransactionFailedError(chain, msg);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GAS_FEE_ESTIMATES,
+  GAS_FEE_FALLBACKS,
+  TetherEVMERC4337Transfer,
+  encodeErc20Transfer,
+  feeToUsdt,
+  formatTokenBalance,
+  getErc4337ConfigForChain,
+  setupErc4337Wallet,
+  toUsdtBaseUnitsEvm
+});

package/dist/index.mjs

@@ -0,0 +1,418 @@
+// src/evmNetworkConfiguration.ts
+import { EVM_CHAINS } from "@gasfree-kit/core";
+var DEFAULT_ENTRY_POINT = "0x0000000071727De22E5E9d8BAf0edAc6f37da032";
+var DEFAULT_SAFE_MODULES_VERSION = "0.3.0";
+var DEFAULT_PAYMASTER_ADDRESS = "0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba";
+var DEFAULT_TRANSFER_MAX_FEE = 1e15;
+function getErc4337ConfigForChain(config) {
+  const chainConfig = EVM_CHAINS[config.chain];
+  return {
+    chainId: chainConfig.chainId,
+    provider: config.rpcUrl,
+    bundlerUrl: config.bundlerUrl,
+    paymasterUrl: config.paymasterUrl,
+    paymasterAddress: config.paymasterAddress ?? DEFAULT_PAYMASTER_ADDRESS,
+    entryPointAddress: config.entryPointAddress ?? DEFAULT_ENTRY_POINT,
+    safeModulesVersion: config.safeModulesVersion ?? DEFAULT_SAFE_MODULES_VERSION,
+    transferMaxFee: DEFAULT_TRANSFER_MAX_FEE,
+    isSponsored: config.isSponsored,
+    sponsorshipPolicyId: config.sponsorshipPolicyId ?? "",
+    paymasterToken: {
+      address: config.paymasterTokenAddress ?? chainConfig.usdtAddress
+    }
+  };
+}
+var GAS_FEE_FALLBACKS = {
+  ethereum: 1400000n,
+  arbitrum: 100000n,
+  polygon: 100000n,
+  celo: 50000n,
+  optimism: 100000n,
+  base: 150000n
+};
+var GAS_FEE_ESTIMATES = {
+  ethereum: "1.40",
+  arbitrum: "0.10",
+  polygon: "0.10",
+  celo: "0.05",
+  optimism: "0.10",
+  base: "0.15"
+};
+
+// src/evmERC4337.ts
+async function setupErc4337Wallet(seedPhrase, config, accountIndex = 0) {
+  const networkConfig = getErc4337ConfigForChain(config);
+  const WalletManagerEvmErc4337Module = await import("@tetherto/wdk-wallet-evm-erc-4337");
+  const WalletManagerEvmErc4337 = WalletManagerEvmErc4337Module.default;
+  const wdkConfig = networkConfig.isSponsored ? {
+    chainId: networkConfig.chainId,
+    provider: networkConfig.provider,
+    bundlerUrl: networkConfig.bundlerUrl,
+    entryPointAddress: networkConfig.entryPointAddress,
+    safeModulesVersion: networkConfig.safeModulesVersion,
+    isSponsored: true,
+    paymasterUrl: networkConfig.paymasterUrl,
+    sponsorshipPolicyId: networkConfig.sponsorshipPolicyId
+  } : {
+    chainId: networkConfig.chainId,
+    provider: networkConfig.provider,
+    bundlerUrl: networkConfig.bundlerUrl,
+    entryPointAddress: networkConfig.entryPointAddress,
+    safeModulesVersion: networkConfig.safeModulesVersion,
+    paymasterUrl: networkConfig.paymasterUrl,
+    paymasterAddress: networkConfig.paymasterAddress,
+    paymasterToken: networkConfig.paymasterToken
+  };
+  const wallet = new WalletManagerEvmErc4337(
+    seedPhrase,
+    wdkConfig
+  );
+  const account = await wallet.getAccount(accountIndex);
+  const address = await account.getAddress();
+  return { wallet, account, address };
+}
+
+// src/evmERC4337TetherTransfer.ts
+import { Bundler, SendUseroperationResponse } from "abstractionkit";
+import {
+  InsufficientBalanceError,
+  TransactionFailedError,
+  validateEvmAddress
+} from "@gasfree-kit/core";
+
+// src/evmUtility.ts
+function toUsdtBaseUnitsEvm(amount) {
+  const str = amount.toString().trim();
+  if (!/^\d+(\.\d+)?$/.test(str)) {
+    throw new Error(`Invalid USDT amount: "${str}". Must be a non-negative decimal number.`);
+  }
+  const decimals = 6;
+  const [integer, fraction = ""] = str.split(".");
+  if (fraction.length > decimals) {
+    throw new Error(
+      `USDT amount has too many decimal places (${fraction.length}). Maximum is ${decimals}.`
+    );
+  }
+  const normalizedFraction = (fraction + "0".repeat(decimals)).slice(0, decimals);
+  return BigInt(integer + normalizedFraction);
+}
+function formatTokenBalance(rawBalance, decimals = 18, precision = 6) {
+  const divisor = 10n ** BigInt(decimals);
+  const whole = rawBalance / divisor;
+  const fraction = rawBalance % divisor;
+  const fractionStr = fraction.toString().padStart(decimals, "0").slice(0, precision);
+  const result = `${whole}.${fractionStr}`.replace(/\.?0+$/, "");
+  return result || "0";
+}
+function encodeErc20Transfer(to, amount) {
+  const TRANSFER_SELECTOR = "0xa9059cbb";
+  const addr = to.startsWith("0x") ? to.slice(2) : to;
+  if (addr.length !== 40) {
+    throw new Error(`Invalid address length for ABI encoding: ${to}`);
+  }
+  const amountHex = amount.toString(16);
+  if (amountHex.length > 64) {
+    throw new Error(`Amount too large for uint256 encoding: ${amount}`);
+  }
+  const paddedAddress = addr.toLowerCase().padStart(64, "0");
+  const paddedAmount = amountHex.padStart(64, "0");
+  return `${TRANSFER_SELECTOR}${paddedAddress}${paddedAmount}`;
+}
+function feeToUsdt(feeInWei, nativeTokenPriceUsdt) {
+  const priceScale = 10n ** 18n;
+  const scaledPrice = BigInt(Math.round(nativeTokenPriceUsdt * Number(priceScale)));
+  const usdtBase = feeInWei * scaledPrice * 1000000n / (10n ** 18n * priceScale);
+  const whole = usdtBase / 1000000n;
+  const frac = (usdtBase % 1000000n).toString().padStart(6, "0");
+  return `${whole}.${frac}`;
+}
+
+// src/evmERC4337TetherTransfer.ts
+var TetherEVMERC4337Transfer = class {
+  /** Default timeout for UserOp confirmation: 120 seconds. */
+  static USER_OP_TIMEOUT_MS = 12e4;
+  /**
+   * Wait for a UserOperation to be included on-chain via the Candide bundler.
+   * Times out after USER_OP_TIMEOUT_MS to prevent indefinite hangs.
+   */
+  static async waitForUserOpConfirmation(userOpHash, bundlerUrl, entryPointAddress) {
+    const bundler = new Bundler(bundlerUrl);
+    const response = new SendUseroperationResponse(userOpHash, bundler, entryPointAddress);
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(
+        () => reject(
+          new TransactionFailedError(
+            "evm",
+            `UserOperation confirmation timed out after ${this.USER_OP_TIMEOUT_MS / 1e3}s. Hash: ${userOpHash}`
+          )
+        ),
+        this.USER_OP_TIMEOUT_MS
+      );
+    });
+    const receipt = await Promise.race([response.included(), timeoutPromise]);
+    if (!receipt.success) {
+      throw new TransactionFailedError(
+        "evm",
+        `UserOperation reverted. Tx: ${receipt.receipt.transactionHash}`
+      );
+    }
+    return receipt.receipt.transactionHash;
+  }
+  /**
+   * Get transaction fee estimate for a USDT transfer.
+   *
+   * Uses a minimal quote amount (gas cost is the same regardless of transfer
+   * amount). Applies a gas buffer (35% Ethereum, 30% others) for volatility.
+   */
+  static async getTransactionEstimateFee(seedPhrase, config, recipientAddress, accountIndex = 0) {
+    validateEvmAddress(recipientAddress, config.chain, "recipient address");
+    const networkConfig = getErc4337ConfigForChain(config);
+    const { wallet, account } = await setupErc4337Wallet(seedPhrase, config, accountIndex);
+    const tokenAddress = networkConfig.paymasterToken.address;
+    try {
+      const quoteAmount = toUsdtBaseUnitsEvm("0.01");
+      let feeVal;
+      try {
+        const transferQuote = await account.quoteTransfer({
+          token: tokenAddress,
+          recipient: recipientAddress,
+          amount: quoteAmount
+        });
+        const bufferPercent = config.chain === "ethereum" ? 35n : 30n;
+        const bufferedFee = transferQuote.fee + transferQuote.fee * bufferPercent / 100n;
+        feeVal = formatTokenBalance(bufferedFee, 6);
+      } catch (quoteError) {
+        if (quoteError instanceof Error && (quoteError.message.includes("token allowance lower than the required") || quoteError.message.includes("token balance lower than the required"))) {
+          const estimates = {
+            ethereum: "1.40",
+            arbitrum: "0.10",
+            polygon: "0.10",
+            celo: "0.05",
+            optimism: "0.10",
+            base: "0.15"
+          };
+          feeVal = estimates[config.chain] || "0.15";
+        } else {
+          throw quoteError;
+        }
+      }
+      return {
+        message: "Transaction fee estimate retrieved successfully",
+        success: true,
+        data: { fee: feeVal }
+      };
+    } finally {
+      account.dispose();
+      wallet.dispose();
+    }
+  }
+  /**
+   * Check token balance on an EVM chain.
+   */
+  static async checkTokenBalance(seedPhrase, config, tokenAddress) {
+    validateEvmAddress(tokenAddress, config.chain, "token address");
+    const { wallet, account } = await setupErc4337Wallet(seedPhrase, config);
+    try {
+      const balance = await account.getTokenBalance(tokenAddress);
+      const usdBalance = formatTokenBalance(balance, 6);
+      return {
+        message: `${config.chain.toUpperCase()} balances retrieved successfully`,
+        success: true,
+        data: {
+          tokenBalance: balance.toString(),
+          decimals: 6,
+          usdBalance: String(usdBalance)
+        }
+      };
+    } finally {
+      account.dispose();
+      wallet.dispose();
+    }
+  }
+  /**
+   * Send a single USDT transfer via ERC-4337.
+   *
+   * Handles:
+   * - Balance validation
+   * - Gas fee auto-adjustment for non-sponsored mode
+   * - On-chain confirmation via Candide bundler
+   * - User-friendly error mapping
+   */
+  static async sendToken(seedPhrase, config, tokenAddress, amount, recipientAddress, accountIndex = 0) {
+    const networkConfig = getErc4337ConfigForChain(config);
+    const gasSponsored = networkConfig.isSponsored;
+    validateEvmAddress(tokenAddress, config.chain, "token address");
+    validateEvmAddress(recipientAddress, config.chain, "recipient address");
+    const {
+      wallet,
+      account,
+      address: senderAddress
+    } = await setupErc4337Wallet(seedPhrase, config, accountIndex);
+    try {
+      if (recipientAddress.toLowerCase() === senderAddress.toLowerCase()) {
+        throw new TransactionFailedError(config.chain, "Cannot transfer to your own address");
+      }
+      const amountInBaseUnits = toUsdtBaseUnitsEvm(amount);
+      const balance = await account.getTokenBalance(tokenAddress);
+      if (!gasSponsored) {
+        let gasFeeBaseUnits;
+        try {
+          const quote = await account.quoteTransfer({
+            token: tokenAddress,
+            recipient: recipientAddress,
+            amount: amountInBaseUnits
+          });
+          const bufferPercent = config.chain === "ethereum" ? 35n : 30n;
+          gasFeeBaseUnits = quote.fee + quote.fee * bufferPercent / 100n;
+        } catch {
+          gasFeeBaseUnits = GAS_FEE_FALLBACKS[config.chain] ?? 150000n;
+        }
+        const totalRequired = amountInBaseUnits + gasFeeBaseUnits;
+        if (BigInt(balance) < totalRequired) {
+          throw new InsufficientBalanceError(
+            config.chain,
+            `USDT (need ${formatTokenBalance(totalRequired, 6)} but have ${formatTokenBalance(balance, 6)} \u2014 includes ${formatTokenBalance(gasFeeBaseUnits, 6)} gas fee)`
+          );
+        }
+      } else if (BigInt(balance) < amountInBaseUnits) {
+        throw new InsufficientBalanceError(config.chain, "USDT");
+      }
+      const transferResult = await account.transfer({
+        token: tokenAddress,
+        recipient: recipientAddress,
+        amount: amountInBaseUnits
+      });
+      const transactionHash = await this.waitForUserOpConfirmation(
+        transferResult.hash,
+        networkConfig.bundlerUrl,
+        networkConfig.entryPointAddress
+      );
+      return {
+        success: true,
+        transactionHash,
+        chain: config.chain,
+        amount
+      };
+    } catch (error) {
+      throw this.handleTransferError(error, config.chain);
+    } finally {
+      account.dispose();
+      wallet.dispose();
+    }
+  }
+  /**
+   * Send a batch USDT transfer to multiple recipients in a single UserOperation.
+   */
+  static async sendBatchToken(seedPhrase, config, tokenAddress, recipients, accountIndex = 0) {
+    const networkConfig = getErc4337ConfigForChain(config);
+    const gasSponsored = networkConfig.isSponsored;
+    for (const r of recipients) {
+      validateEvmAddress(r.address, config.chain, "recipient address");
+    }
+    const {
+      wallet,
+      account,
+      address: senderAddress
+    } = await setupErc4337Wallet(seedPhrase, config, accountIndex);
+    try {
+      for (const r of recipients) {
+        if (r.address.toLowerCase() === senderAddress.toLowerCase()) {
+          throw new TransactionFailedError(config.chain, "Cannot transfer to your own address");
+        }
+      }
+      const totalAmount = recipients.reduce((sum, r) => sum + toUsdtBaseUnitsEvm(r.amount), 0n);
+      const balance = await account.getTokenBalance(tokenAddress);
+      if (!gasSponsored) {
+        const gasFeeReserve = GAS_FEE_FALLBACKS[config.chain] ?? 150000n;
+        const totalRequired = totalAmount + gasFeeReserve;
+        if (BigInt(balance) < totalRequired) {
+          throw new InsufficientBalanceError(
+            config.chain,
+            `USDT (need ${formatTokenBalance(totalRequired, 6)} but have ${formatTokenBalance(balance, 6)} \u2014 includes ${formatTokenBalance(gasFeeReserve, 6)} gas fee)`
+          );
+        }
+      } else if (BigInt(balance) < totalAmount) {
+        throw new InsufficientBalanceError(config.chain, "USDT");
+      }
+      const batchTransactions = recipients.map(({ address, amount }) => {
+        const amountBase = toUsdtBaseUnitsEvm(amount);
+        return {
+          to: tokenAddress,
+          value: 0,
+          data: encodeErc20Transfer(address, amountBase)
+        };
+      });
+      const transferResult = await account.sendTransaction(batchTransactions);
+      const transactionHash = await this.waitForUserOpConfirmation(
+        transferResult.hash,
+        networkConfig.bundlerUrl,
+        networkConfig.entryPointAddress
+      );
+      return {
+        success: true,
+        transactionHash,
+        chain: config.chain,
+        recipients
+      };
+    } catch (error) {
+      throw this.handleTransferError(error, config.chain);
+    } finally {
+      account.dispose();
+      wallet.dispose();
+    }
+  }
+  /**
+   * Map raw errors into user-friendly messages.
+   */
+  static handleTransferError(error, chain) {
+    if (!(error instanceof Error)) {
+      return new TransactionFailedError(chain, "Unknown error");
+    }
+    const msg = error.message;
+    if (msg.includes("callData reverts")) {
+      return new TransactionFailedError(
+        chain,
+        "Transaction reverted. Check your balance and try again."
+      );
+    }
+    if (msg.includes("not enough funds")) {
+      return new InsufficientBalanceError(chain, "paymaster token");
+    }
+    if (msg.includes("token balance lower than the required") || msg.includes("token allowance lower than the required")) {
+      return new InsufficientBalanceError(chain, "USDT (insufficient for transfer + gas)");
+    }
+    if (msg.includes("Insufficient") || error instanceof InsufficientBalanceError) {
+      return error;
+    }
+    if (msg.includes("nonce too low")) {
+      return new TransactionFailedError(chain, "Nonce conflict. Please try again.");
+    }
+    if (msg.includes("insufficient funds") || msg.includes("transfer amount exceeds balance")) {
+      return new InsufficientBalanceError(chain, "USDT");
+    }
+    if (msg.includes("transaction underpriced") || msg.includes("max fee per gas less than block base fee")) {
+      return new TransactionFailedError(chain, "Gas price too low. Please try again.");
+    }
+    if (msg.includes("out of gas") || msg.includes("intrinsic gas too low")) {
+      return new TransactionFailedError(chain, "Insufficient gas limit.");
+    }
+    if (msg.includes("execution reverted")) {
+      return new TransactionFailedError(chain, "Transaction reverted on-chain.");
+    }
+    if (msg.includes("504") || msg.includes("Gateway Time-out")) {
+      return new TransactionFailedError(chain, "Network timeout. Please try again.");
+    }
+    return new TransactionFailedError(chain, msg);
+  }
+};
+export {
+  GAS_FEE_ESTIMATES,
+  GAS_FEE_FALLBACKS,
+  TetherEVMERC4337Transfer,
+  encodeErc20Transfer,
+  feeToUsdt,
+  formatTokenBalance,
+  getErc4337ConfigForChain,
+  setupErc4337Wallet,
+  toUsdtBaseUnitsEvm
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@gasfree-kit/evm-4337",
+  "version": "0.1.0",
+  "description": "ERC-4337 gasless transactions for EVM chains — powered by WDK",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "patches",
+    "scripts"
+  ],
+  "dependencies": {
+    "abstractionkit": "^0.2.30",
+    "@gasfree-kit/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "@tetherto/wdk-wallet-evm-erc-4337": "^1.0.0-beta.5"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}

package/patches/@tetherto__wdk-safe-relay-kit@4.1.5.patch

@@ -0,0 +1,68 @@
+diff --git a/dist/cjs/src/index.cjs b/dist/cjs/src/index.cjs
+--- a/dist/cjs/src/index.cjs
++++ b/dist/cjs/src/index.cjs
+@@ -1946,6 +1946,9 @@ var GenericFeeEstimator = class {
+       const context = "paymasterTokenAddress" in paymasterOptions ? {
+         token: paymasterOptions.paymasterTokenAddress
+       } : paymasterOptions.paymasterContext ?? {};
++      if (paymasterOptions.sponsorshipPolicyId) {
++        context.sponsorshipPolicyId = paymasterOptions.sponsorshipPolicyId;
++      }
+       const [feeData, paymasterStubData] = await Promise.all([
+         this.#getUserOperationGasPrices(this.rpcUrl),
+         paymasterClient.request({
+@@ -2017,7 +2020,8 @@ var GenericFeeEstimator = class {
+       const sponsoredData = await paymasterClient.request({
+         method: "pm_getPaymasterData" /* GET_PAYMASTER_DATA */,
+         params
+       });
+-      return sponsoredData;
++      sponsoredData.callGasLimit = userOperation.callGasLimit.toString();
++      return sponsoredData;
+     }
+     const erc20PaymasterData = await paymasterClient.request({
+       method: "pm_getPaymasterData" /* GET_PAYMASTER_DATA */,
+@@ -2032,7 +2036,8 @@ var GenericFeeEstimator = class {
+       const threshold = await protocolKit.getThreshold();
+       erc20PaymasterData.verificationGasLimit = (BigInt(erc20PaymasterData.verificationGasLimit) + BigInt(threshold) * this.defaultVerificationGasLimitOverhead).toString();
+     }
+-    return erc20PaymasterData;
++    erc20PaymasterData.callGasLimit = userOperation.callGasLimit.toString();
++    return erc20PaymasterData;
+   }
+   async #getUserOperationGasPrices(rpcUrl) {
+     const client = (0, import_viem11.createPublicClient)({
+diff --git a/dist/esm/src/index.mjs b/dist/esm/src/index.mjs
+--- a/dist/esm/src/index.mjs
++++ b/dist/esm/src/index.mjs
+@@ -1923,6 +1923,9 @@ var GenericFeeEstimator = class {
+       const context = "paymasterTokenAddress" in paymasterOptions ? {
+         token: paymasterOptions.paymasterTokenAddress
+       } : paymasterOptions.paymasterContext ?? {};
++      if (paymasterOptions.sponsorshipPolicyId) {
++        context.sponsorshipPolicyId = paymasterOptions.sponsorshipPolicyId;
++      }
+       const [feeData, paymasterStubData] = await Promise.all([
+         this.#getUserOperationGasPrices(this.rpcUrl),
+         paymasterClient.request({
+@@ -1994,7 +1997,8 @@ var GenericFeeEstimator = class {
+       const sponsoredData = await paymasterClient.request({
+         method: "pm_getPaymasterData" /* GET_PAYMASTER_DATA */,
+         params
+       });
+-      return sponsoredData;
++      sponsoredData.callGasLimit = userOperation.callGasLimit.toString();
++      return sponsoredData;
+     }
+     const erc20PaymasterData = await paymasterClient.request({
+       method: "pm_getPaymasterData" /* GET_PAYMASTER_DATA */,
+@@ -2009,7 +2013,8 @@ var GenericFeeEstimator = class {
+       const threshold = await protocolKit.getThreshold();
+       erc20PaymasterData.verificationGasLimit = (BigInt(erc20PaymasterData.verificationGasLimit) + BigInt(threshold) * this.defaultVerificationGasLimitOverhead).toString();
+     }
+-    return erc20PaymasterData;
++    erc20PaymasterData.callGasLimit = userOperation.callGasLimit.toString();
++    return erc20PaymasterData;
+   }
+   async #getUserOperationGasPrices(rpcUrl) {
+     const client = createPublicClient2({

package/scripts/postinstall.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall script for @gasfree-kit/evm-4337.
+ *
+ * Applies a critical patch to @tetherto/wdk-safe-relay-kit that fixes:
+ * 1. sponsorshipPolicyId not being passed to Candide paymaster context
+ * 2. callGasLimit being dropped by paymaster response (both sponsored & ERC-20)
+ *
+ * Without this patch, gas estimation fails on Candide-sponsored transactions.
+ *
+ * Works with npm, pnpm, and yarn.
+ * pnpm users can also use patchedDependencies in package.json instead.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const patchFile = path.join(
+  __dirname,
+  '..',
+  'patches',
+  '@tetherto__wdk-safe-relay-kit@4.1.5.patch',
+);
+
+if (!fs.existsSync(patchFile)) {
+  // Patch file not found — skip (might be in a CI environment or already applied)
+  process.exit(0);
+}
+
+// Find the target package
+const possiblePaths = [
+  // npm/yarn hoisted
+  path.resolve(__dirname, '..', '..', '@tetherto', 'wdk-safe-relay-kit'),
+  // pnpm non-hoisted
+  path.resolve(__dirname, '..', 'node_modules', '@tetherto', 'wdk-safe-relay-kit'),
+  // monorepo root
+  path.resolve(__dirname, '..', '..', '..', 'node_modules', '@tetherto', 'wdk-safe-relay-kit'),
+];
+
+const targetDir = possiblePaths.find((p) => fs.existsSync(p));
+
+if (!targetDir) {
+  // @tetherto/wdk-safe-relay-kit not installed yet — skip
+  // The user's package manager will install peer deps and this runs again
+  process.exit(0);
+}
+
+// Check if patch is already applied by looking for our marker
+const cjsFile = path.join(targetDir, 'dist', 'cjs', 'src', 'index.cjs');
+if (fs.existsSync(cjsFile)) {
+  const content = fs.readFileSync(cjsFile, 'utf8');
+  if (content.includes('context.sponsorshipPolicyId')) {
+    // Patch already applied
+    process.exit(0);
+  }
+}
+
+try {
+  execSync(`npx patch-package --patch-dir "${path.dirname(patchFile)}"`, {
+    cwd: path.resolve(targetDir, '..', '..'),
+    stdio: 'pipe',
+  });
+  console.log('@gasfree-kit/evm-4337: Applied wdk-safe-relay-kit patch (Candide paymaster fix)');
+} catch {
+  // patch-package not available — try git apply
+  try {
+    execSync(`git apply --directory="${targetDir}" "${patchFile}"`, {
+      stdio: 'pipe',
+    });
+    console.log('@gasfree-kit/evm-4337: Applied wdk-safe-relay-kit patch via git apply');
+  } catch {
+    console.warn(
+      '@gasfree-kit/evm-4337: Could not auto-apply wdk-safe-relay-kit patch.\n' +
+        'Please apply manually: patches/@tetherto__wdk-safe-relay-kit@4.1.5.patch\n' +
+        'See: https://github.com/gasfree-kit/evm-4337#patch',
+    );
+  }
+}