@gasfree-kit/evm-4337 0.2.0 → 0.3.1

package/README.md

@@ -43,17 +43,6 @@ This package gives you:
                                 └──────────────────────┘
 ```
 
-```mermaid
-flowchart TD
-  A["Your app"] --> B["@gasfree-kit/evm-4337"]
-  B --> C["WDK wallet manager"]
-  C --> D["Safe smart account"]
-  D --> E["ERC-4337 UserOperation"]
-  F["Paymaster"] -.->|sponsors or charges USDT| E
-  E --> G["Bundler"]
-  G --> H["EVM chain"]
-```
-
 ## Supported Chains
 
 | Chain    | Chain ID | Typical fallback fee estimate |
@@ -66,10 +55,21 @@ flowchart TD
 | Celo     | 42220    | `0.05` USDT                   |
 | Plasma   | 9745     | `0.05` USDT                   |
 
+## Prerequisites
+
+This package depends on [`@gasfree-kit/core`](../core/README.md) for:
+
+- **Seed phrase generation** — `generateSeedPhrase()` creates the mnemonic used to set up wallets
+- **Chain metadata** — `EVM_CHAINS` provides chain IDs, USDT addresses, and explorer URLs
+- **Address validation** — `validateEvmAddress()` catches malformed addresses before sending
+- **Error classes** — `GasfreeError`, `InsufficientBalanceError`, etc. for consistent error handling
+
+`@gasfree-kit/core` is installed automatically as a dependency.
+
 ## Installation
 
 ```bash
-npm install @gasfree-kit/evm-4337
+npm install @gasfree-kit/evm-4337 @gasfree-kit/core
 ```
 
 Required peer dependency:
@@ -237,15 +237,6 @@ Important:
                       └──────────────────────┘
 ```
 
-```mermaid
-flowchart TD
-  A["Seed phrase owner"] --> C["Safe smart account"]
-  B["Passkey (WebAuthn)"] --> C
-  C --> D["Signed UserOperation"]
-  D --> E["Bundler + Paymaster"]
-  E --> F["EVM chain"]
-```
-
 ### Link a passkey to an existing Safe
 
 ```ts

package/dist/index.d.mts

@@ -193,6 +193,11 @@ declare function waitForUserOpConfirmation(userOpHash: string, bundlerUrl: strin
  */
 declare function handleTransferError(error: unknown, chain: string): Error;
 
+declare function jsonRpcCall(rpcUrl: string, request: {
+    method: string;
+    params: unknown[];
+}): Promise<string>;
+
 /**
  * Register a new passkey via WebAuthn and link it to an existing Safe account.
  *
@@ -290,4 +295,4 @@ interface CredentialStore {
  */
 declare function createCredentialStore(): CredentialStore;
 
-export { type CredentialStore, type EVM4337ClientConfig, type EvmErc4337NetworkConfig, EvmTransfer, FCL_P256_VERIFIER, GAS_FEE_ESTIMATES, GAS_FEE_FALLBACKS, type PasskeyConfig, type PasskeyCredential, type PasskeyLinkResult, type PasskeyOptions, type PasskeyStorageMode, PasskeyTransfer, SAFE_WEBAUTHN_SIGNER_FACTORY, createCredentialStore, encodeErc20Transfer, feeToUsdt, formatTokenBalance, getErc4337ConfigForChain, handleTransferError, isPasskeyLinked, linkPasskeyToSafe, setupErc4337Wallet, toUsdtBaseUnitsEvm, unlinkPasskeyFromSafe, waitForUserOpConfirmation };
+export { type CredentialStore, type EVM4337ClientConfig, type EvmErc4337NetworkConfig, EvmTransfer, FCL_P256_VERIFIER, GAS_FEE_ESTIMATES, GAS_FEE_FALLBACKS, type PasskeyConfig, type PasskeyCredential, type PasskeyLinkResult, type PasskeyOptions, type PasskeyStorageMode, PasskeyTransfer, SAFE_WEBAUTHN_SIGNER_FACTORY, createCredentialStore, encodeErc20Transfer, feeToUsdt, formatTokenBalance, getErc4337ConfigForChain, handleTransferError, isPasskeyLinked, jsonRpcCall, linkPasskeyToSafe, setupErc4337Wallet, toUsdtBaseUnitsEvm, unlinkPasskeyFromSafe, waitForUserOpConfirmation };

package/dist/index.d.ts

@@ -193,6 +193,11 @@ declare function waitForUserOpConfirmation(userOpHash: string, bundlerUrl: strin
  */
 declare function handleTransferError(error: unknown, chain: string): Error;
 
+declare function jsonRpcCall(rpcUrl: string, request: {
+    method: string;
+    params: unknown[];
+}): Promise<string>;
+
 /**
  * Register a new passkey via WebAuthn and link it to an existing Safe account.
  *
@@ -290,4 +295,4 @@ interface CredentialStore {
  */
 declare function createCredentialStore(): CredentialStore;
 
-export { type CredentialStore, type EVM4337ClientConfig, type EvmErc4337NetworkConfig, EvmTransfer, FCL_P256_VERIFIER, GAS_FEE_ESTIMATES, GAS_FEE_FALLBACKS, type PasskeyConfig, type PasskeyCredential, type PasskeyLinkResult, type PasskeyOptions, type PasskeyStorageMode, PasskeyTransfer, SAFE_WEBAUTHN_SIGNER_FACTORY, createCredentialStore, encodeErc20Transfer, feeToUsdt, formatTokenBalance, getErc4337ConfigForChain, handleTransferError, isPasskeyLinked, linkPasskeyToSafe, setupErc4337Wallet, toUsdtBaseUnitsEvm, unlinkPasskeyFromSafe, waitForUserOpConfirmation };
+export { type CredentialStore, type EVM4337ClientConfig, type EvmErc4337NetworkConfig, EvmTransfer, FCL_P256_VERIFIER, GAS_FEE_ESTIMATES, GAS_FEE_FALLBACKS, type PasskeyConfig, type PasskeyCredential, type PasskeyLinkResult, type PasskeyOptions, type PasskeyStorageMode, PasskeyTransfer, SAFE_WEBAUTHN_SIGNER_FACTORY, createCredentialStore, encodeErc20Transfer, feeToUsdt, formatTokenBalance, getErc4337ConfigForChain, handleTransferError, isPasskeyLinked, jsonRpcCall, linkPasskeyToSafe, setupErc4337Wallet, toUsdtBaseUnitsEvm, unlinkPasskeyFromSafe, waitForUserOpConfirmation };

package/dist/index.js

@@ -43,6 +43,7 @@ __export(index_exports, {
   getErc4337ConfigForChain: () => getErc4337ConfigForChain,
   handleTransferError: () => handleTransferError,
   isPasskeyLinked: () => isPasskeyLinked,
+  jsonRpcCall: () => jsonRpcCall,
   linkPasskeyToSafe: () => linkPasskeyToSafe,
   setupErc4337Wallet: () => setupErc4337Wallet,
   toUsdtBaseUnitsEvm: () => toUsdtBaseUnitsEvm,
@@ -1178,6 +1179,7 @@ var PasskeyTransfer = class {
   getErc4337ConfigForChain,
   handleTransferError,
   isPasskeyLinked,
+  jsonRpcCall,
   linkPasskeyToSafe,
   setupErc4337Wallet,
   toUsdtBaseUnitsEvm,

package/dist/index.mjs

@@ -1128,6 +1128,7 @@ export {
   getErc4337ConfigForChain,
   handleTransferError,
   isPasskeyLinked,
+  jsonRpcCall,
   linkPasskeyToSafe,
   setupErc4337Wallet,
   toUsdtBaseUnitsEvm,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gasfree-kit/evm-4337",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "ERC-4337 gasless transactions for EVM chains — powered by WDK",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -14,8 +14,6 @@
   },
   "files": [
     "dist",
-    "patches",
-    "scripts",
     "README.md"
   ],
   "dependencies": {
@@ -36,12 +34,27 @@
       "optional": true
     }
   },
+  "keywords": [
+    "gasless",
+    "gas-free",
+    "erc-4337",
+    "account-abstraction",
+    "paymaster",
+    "bundler",
+    "user-operation",
+    "ethereum",
+    "evm",
+    "web3",
+    "sdk",
+    "meta-transactions",
+    "safe",
+    "smart-account"
+  ],
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "postinstall": "node scripts/postinstall.js",
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "vitest run",

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

@@ -1,68 +0,0 @@
-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

@@ -1,101 +0,0 @@
-#!/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 { spawnSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-const packageRoot = path.resolve(__dirname, '..');
-
-function findProjectRoot(startDir) {
-  let current = startDir;
-  while (true) {
-    const parent = path.dirname(current);
-    if (parent === current) {
-      return startDir;
-    }
-    if (fs.existsSync(path.join(parent, 'package.json'))) {
-      return parent;
-    }
-    current = parent;
-  }
-}
-
-function runOrThrow(command, args, options) {
-  const result = spawnSync(command, args, {
-    stdio: 'pipe',
-    windowsHide: true,
-    ...options,
-  });
-
-  if (result.error) {
-    throw result.error;
-  }
-
-  if (result.status !== 0) {
-    const stderr = result.stderr ? result.stderr.toString().trim() : '';
-    throw new Error(stderr || `${command} exited with code ${result.status}`);
-  }
-}
-
-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 projectRoot = findProjectRoot(packageRoot);
-const possiblePaths = [
-  path.join(projectRoot, 'node_modules', '@tetherto', 'wdk-safe-relay-kit'),
-  path.join(packageRoot, '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);
-  }
-}
-
-// Apply the patch using git apply without shell interpolation.
-try {
-  runOrThrow('git', ['apply', '--unsafe-paths', `--directory=${targetDir}`, patchFile], {
-    cwd: projectRoot,
-  });
-  console.log('@gasfree-kit/evm-4337: Applied wdk-safe-relay-kit patch (Candide paymaster fix)');
-} 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',
-  );
-}