@1llet.xyz/erc4337-gasless-sdk 0.1.1 → 0.1.4

package/README.md

@@ -114,6 +114,48 @@ npm install
 npm run build
 ```
 
-## 📄 License
+## � API Reference
+
+### Balances & Allowances
+
+```typescript
+// Get Smart Account USDC Balance
+const balance = await aa.getUsdcBalance();
+
+// Get EOA (Wallet) USDC Balance
+const eoaBalance = await aa.getEoaUsdcBalance();
+
+// Check how much USDC the Smart Account is allowed to spend from EOA
+const allowance = await aa.getAllowance();
+```
+
+### Account Management
+
+```typescript
+// Check if the Smart Account is already deployed on-chain
+const isDeployed = await aa.isAccountDeployed();
+
+// Get the Counterfactual Address (deterministic address based on owner)
+const address = await aa.getSmartAccountAddress(ownerAddress);
+
+// Manually deploy the account (if you don't want to bundle it with a tx)
+if (!isDeployed) {
+  const deployOp = await aa.buildDeployUserOperation();
+  const signed = await aa.signUserOperation(deployOp);
+  await aa.sendUserOperation(signed);
+}
+```
+
+### Utilities
+
+```typescript
+// Get current Nonce
+const nonce = await aa.getNonce();
+
+// Get UserOp Hash (for manual signing or verification)
+const hash = aa.getUserOpHash(userOp);
+```
+
+## �📄 License
 
 MIT

package/package.json

@@ -3,7 +3,7 @@
     "publishConfig": {
         "access": "public"
     },
-    "version": "0.1.1",
+    "version": "0.1.4",
     "description": "SDK for ERC-4337 Gasless Transfers",
     "main": "./dist/index.js",
     "module": "./dist/index.mjs",

package/src/AccountAbstraction.ts

@@ -23,6 +23,7 @@ import {
     type ApprovalSupportResult
 } from "./types";
 import { DEPLOYMENTS } from "./deployments";
+import { BundlerClient } from "./BundlerClient";
 
 /**
  * ERC-4337 Account Abstraction Client
@@ -32,6 +33,7 @@ export class AccountAbstraction {
     private smartAccountAddress: Address | null = null;
     private chainConfig: ChainConfig;
     private publicClient: PublicClient;
+    private bundlerClient: BundlerClient;
 
     // Resolved addresses
     private entryPointAddress: Address;
@@ -66,6 +68,8 @@ export class AccountAbstraction {
             chain: chainConfig.chain,
             transport: http(rpcUrl),
         });
+
+        this.bundlerClient = new BundlerClient(chainConfig, this.entryPointAddress);
     }
 
     /**
@@ -247,33 +251,7 @@ export class AccountAbstraction {
      * Estimate gas for a UserOperation
      */
     async estimateGas(userOp: Partial<UserOperation>): Promise<GasEstimate> {
-        const response = await fetch(this.chainConfig.bundlerUrl, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
-                jsonrpc: "2.0",
-                id: 1,
-                method: "eth_estimateUserOperationGas",
-                params: [
-                    {
-                        sender: userOp.sender,
-                        nonce: userOp.nonce ? "0x" + userOp.nonce.toString(16) : "0x0",
-                        initCode: userOp.initCode || "0x",
-                        callData: userOp.callData || "0x",
-                        paymasterAndData: userOp.paymasterAndData || "0x",
-                        signature: "0x",
-                    },
-                    this.entryPointAddress,
-                ],
-            }),
-        });
-
-        const result = await response.json();
-        if (result.error) {
-            throw new Error(result.error.message);
-        }
-
-        return result.result;
+        return this.bundlerClient.estimateGas(userOp);
     }
 
 
@@ -436,38 +414,7 @@ export class AccountAbstraction {
      * Send a signed UserOperation to the bundler
      */
     async sendUserOperation(userOp: UserOperation): Promise<Hash> {
-        const response = await fetch(this.chainConfig.bundlerUrl, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
-                jsonrpc: "2.0",
-                id: 1,
-                method: "eth_sendUserOperation",
-                params: [
-                    {
-                        sender: userOp.sender,
-                        nonce: "0x" + userOp.nonce.toString(16),
-                        initCode: userOp.initCode,
-                        callData: userOp.callData,
-                        callGasLimit: "0x" + userOp.callGasLimit.toString(16),
-                        verificationGasLimit: "0x" + userOp.verificationGasLimit.toString(16),
-                        preVerificationGas: "0x" + userOp.preVerificationGas.toString(16),
-                        maxFeePerGas: "0x" + userOp.maxFeePerGas.toString(16),
-                        maxPriorityFeePerGas: "0x" + userOp.maxPriorityFeePerGas.toString(16),
-                        paymasterAndData: userOp.paymasterAndData,
-                        signature: userOp.signature,
-                    },
-                    this.entryPointAddress,
-                ],
-            }),
-        });
-
-        const result = await response.json();
-        if (result.error) {
-            throw new Error(result.error.message);
-        }
-
-        return result.result as Hash;
+        return this.bundlerClient.sendUserOperation(userOp);
     }
 
     /**
@@ -477,30 +424,7 @@ export class AccountAbstraction {
         userOpHash: Hash,
         timeout = 60000
     ): Promise<UserOpReceipt> {
-        const startTime = Date.now();
-
-        while (Date.now() - startTime < timeout) {
-            const response = await fetch(this.chainConfig.bundlerUrl, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({
-                    jsonrpc: "2.0",
-                    id: 1,
-                    method: "eth_getUserOperationReceipt",
-                    params: [userOpHash],
-                }),
-            });
-
-            const result = await response.json();
-            if (result.result) {
-                return result.result as UserOpReceipt;
-            }
-
-            // Wait 2 seconds before polling again
-            await new Promise((resolve) => setTimeout(resolve, 2000));
-        }
-
-        throw new Error("Timeout waiting for UserOperation");
+        return this.bundlerClient.waitForUserOperation(userOpHash, timeout);
     }
 
 
@@ -515,24 +439,60 @@ export class AccountAbstraction {
         if (!this.owner) {
             throw new Error("Not connected");
         }
+        return this.bundlerClient.requestApprovalSupport(token, this.owner, spender, amount);
+    }
 
-        const response = await fetch(this.chainConfig.bundlerUrl, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
-                jsonrpc: "2.0",
-                id: 1,
-                method: "pm_requestApprovalSupport",
-                params: [token, this.owner, spender, amount.toString()],
-            }),
-        });
+    /**
+     * Deploy the Smart Account
+     */
+    async deployAccount(): Promise<UserOpReceipt> {
+        const userOp = await this.buildDeployUserOperation();
+        const signed = await this.signUserOperation(userOp);
+        const hash = await this.sendUserOperation(signed);
+        return await this.waitForUserOperation(hash);
+    }
+
+    /**
+     * Approve a token for the Smart Account (EOA -> Token -> Smart Account)
+     * Checks for gas sponsorship (Relayer funding) if needed.
+     */
+    async approveToken(
+        token: Address,
+        spender: Address,
+        amount: bigint = 115792089237316195423570985008687907853269984665640564039457584007913129639935n // maxUint256
+    ): Promise<Hash | "NOT_NEEDED"> {
+        if (!this.owner) throw new Error("Not connected");
+
+        // 1. Check if we need funding
+        const support = await this.requestApprovalSupport(token, spender, amount);
+
+        if (support.type === "approve") {
+            // 2. Encode approve data
+            const data = encodeFunctionData({
+                abi: erc20Abi,
+                functionName: "approve",
+                args: [spender, amount]
+            });
+
+            // 3. Send transaction via Wallet (MetaMask)
+            // If funding was needed, the Relayer has already sent ETH to this.owner
+            const txHash = await window.ethereum!.request({
+                method: "eth_sendTransaction",
+                params: [{
+                    from: this.owner,
+                    to: token,
+                    data,
+                }]
+            }) as Hash;
+
+            return txHash;
+        }
 
-        const result = await response.json();
-        if (result.error) {
-            throw new Error(result.error.message);
+        if (support.type === "permit") {
+            throw new Error("Permit not yet supported in this SDK version");
         }
 
-        return result.result;
+        return "NOT_NEEDED";
     }
 
     // Getters

package/src/BundlerClient.ts

@@ -0,0 +1,93 @@
+import { type Address, type Hash, type Hex } from "viem";
+import { type ChainConfig, type UserOperation, type GasEstimate, type UserOpReceipt, type ApprovalSupportResult } from "./types";
+import { entryPointAbi } from "./constants";
+
+export class BundlerClient {
+    private bundlerUrl: string;
+    private chainId: number;
+    private entryPointAddress: Address;
+
+    constructor(config: ChainConfig, entryPointAddress: Address) {
+        this.bundlerUrl = config.bundlerUrl;
+        this.chainId = config.chain.id;
+        this.entryPointAddress = entryPointAddress;
+    }
+
+    private async call(method: string, params: any[]): Promise<any> {
+        const response = await fetch(this.bundlerUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method,
+                params,
+            }),
+        });
+
+        const result = await response.json();
+        if (result.error) {
+            throw new Error(result.error.message);
+        }
+        return result.result;
+    }
+
+    async estimateGas(userOp: Partial<UserOperation>): Promise<GasEstimate> {
+        return await this.call("eth_estimateUserOperationGas", [
+            {
+                sender: userOp.sender,
+                nonce: userOp.nonce ? "0x" + userOp.nonce.toString(16) : "0x0",
+                initCode: userOp.initCode || "0x",
+                callData: userOp.callData || "0x",
+                paymasterAndData: userOp.paymasterAndData || "0x",
+                signature: "0x",
+            },
+            this.entryPointAddress,
+        ]);
+    }
+
+    async sendUserOperation(userOp: UserOperation): Promise<Hash> {
+        return await this.call("eth_sendUserOperation", [
+            {
+                sender: userOp.sender,
+                nonce: "0x" + userOp.nonce.toString(16),
+                initCode: userOp.initCode,
+                callData: userOp.callData,
+                callGasLimit: "0x" + userOp.callGasLimit.toString(16),
+                verificationGasLimit: "0x" + userOp.verificationGasLimit.toString(16),
+                preVerificationGas: "0x" + userOp.preVerificationGas.toString(16),
+                maxFeePerGas: "0x" + userOp.maxFeePerGas.toString(16),
+                maxPriorityFeePerGas: "0x" + userOp.maxPriorityFeePerGas.toString(16),
+                paymasterAndData: userOp.paymasterAndData,
+                signature: userOp.signature,
+            },
+            this.entryPointAddress,
+        ]);
+    }
+
+    async waitForUserOperation(userOpHash: Hash, timeout = 60000): Promise<UserOpReceipt> {
+        const startTime = Date.now();
+
+        while (Date.now() - startTime < timeout) {
+            const result = await this.call("eth_getUserOperationReceipt", [userOpHash]);
+
+            if (result) {
+                return result as UserOpReceipt;
+            }
+
+            // Wait 2 seconds before polling again
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+        }
+
+        throw new Error("Timeout waiting for UserOperation");
+    }
+
+    async requestApprovalSupport(token: Address, owner: Address, spender: Address, amount: bigint): Promise<ApprovalSupportResult> {
+        return await this.call("pm_requestApprovalSupport", [
+            token,
+            owner,
+            spender,
+            amount.toString()
+        ]);
+    }
+}

package/dist/index.d.mts

@@ -1,330 +0,0 @@
-import { Chain, Address, Hex, Hash } from 'viem';
-
-interface ChainConfig {
-    chain: Chain;
-    rpcUrl?: string;
-    bundlerUrl: string;
-    entryPointAddress?: Address;
-    factoryAddress?: Address;
-    paymasterAddress?: Address;
-    usdcAddress?: Address;
-}
-interface UserOperation {
-    sender: Address;
-    nonce: bigint;
-    initCode: Hex;
-    callData: Hex;
-    callGasLimit: bigint;
-    verificationGasLimit: bigint;
-    preVerificationGas: bigint;
-    maxFeePerGas: bigint;
-    maxPriorityFeePerGas: bigint;
-    paymasterAndData: Hex;
-    signature: Hex;
-}
-interface GasEstimate {
-    callGasLimit: string;
-    verificationGasLimit: string;
-    preVerificationGas: string;
-    maxFeePerGas: string;
-    maxPriorityFeePerGas: string;
-}
-interface UserOpReceipt {
-    userOpHash: Hash;
-    sender: Address;
-    success: boolean;
-    actualGasCost: string;
-    receipt: {
-        transactionHash: Hash;
-        blockNumber: string;
-    };
-}
-interface ApprovalSupportResult {
-    type: "permit" | "approve" | "none";
-    gasCost?: string;
-    fundingNeeded?: string;
-    fundedAmount?: string;
-}
-
-/**
- * ERC-4337 Account Abstraction Client
- */
-declare class AccountAbstraction {
-    private owner;
-    private smartAccountAddress;
-    private chainConfig;
-    private publicClient;
-    private entryPointAddress;
-    private factoryAddress;
-    private paymasterAddress?;
-    private usdcAddress;
-    constructor(chainConfig: ChainConfig);
-    /**
-     * Connect to MetaMask and get the owner address
-     */
-    connect(): Promise<{
-        owner: Address;
-        smartAccount: Address;
-    }>;
-    /**
-     * Get the Smart Account address for an owner (counterfactual)
-     */
-    getSmartAccountAddress(owner: Address): Promise<Address>;
-    /**
-     * Check if the Smart Account is deployed
-     */
-    isAccountDeployed(): Promise<boolean>;
-    /**
-     * Get the USDC balance of the Smart Account
-     */
-    getUsdcBalance(): Promise<bigint>;
-    /**
-     * Get the EOA's USDC balance
-     */
-    getEoaUsdcBalance(): Promise<bigint>;
-    /**
-     * Get the allowance of the Smart Account to spend the EOA's USDC
-     */
-    getAllowance(): Promise<bigint>;
-    /**
-     * Get the nonce for the Smart Account
-     */
-    getNonce(): Promise<bigint>;
-    /**
-     * Build initCode for account deployment
-     */
-    buildInitCode(): Hex;
-    /**
-     * Estimate gas for a UserOperation
-     */
-    estimateGas(userOp: Partial<UserOperation>): Promise<GasEstimate>;
-    /**
-     * Build a UserOperation for Batched Execution (e.g. USDC Transfer + Fee)
-     */
-    buildUserOperationBatch(transactions: {
-        target: Address;
-        value: bigint;
-        data: Hex;
-    }[]): Promise<UserOperation>;
-    /**
-     * Build a UserOperation to ONLY deploy the account (empty callData)
-     */
-    buildDeployUserOperation(): Promise<UserOperation>;
-    /**
-     * Calculate the UserOperation hash
-     */
-    getUserOpHash(userOp: UserOperation): Hex;
-    /**
-     * Sign a UserOperation with MetaMask
-     */
-    signUserOperation(userOp: UserOperation): Promise<UserOperation>;
-    /**
-     * Send a signed UserOperation to the bundler
-     */
-    sendUserOperation(userOp: UserOperation): Promise<Hash>;
-    /**
-     * Wait for a UserOperation to be confirmed
-     */
-    waitForUserOperation(userOpHash: Hash, timeout?: number): Promise<UserOpReceipt>;
-    /**
-     * Request support for token approval (fund if needed)
-     */
-    requestApprovalSupport(token: Address, spender: Address, amount: bigint): Promise<ApprovalSupportResult>;
-    getOwner(): Address | null;
-    getSmartAccount(): Address | null;
-}
-declare global {
-    interface Window {
-        ethereum?: {
-            request: (args: {
-                method: string;
-                params?: unknown[];
-            }) => Promise<unknown>;
-            on: (event: string, callback: (args: unknown) => void) => void;
-            removeListener: (event: string, callback: (args: unknown) => void) => void;
-        };
-    }
-}
-
-declare const DEFAULT_ENTRYPOINT = "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789";
-declare const DEFAULT_FACTORY = "0x9406Cc6185a346906296840746125a0E44976454";
-declare const factoryAbi: readonly [{
-    readonly inputs: readonly [{
-        readonly name: "owner";
-        readonly type: "address";
-    }, {
-        readonly name: "salt";
-        readonly type: "uint256";
-    }];
-    readonly name: "getAccountAddress";
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "address";
-    }];
-    readonly stateMutability: "view";
-    readonly type: "function";
-}, {
-    readonly inputs: readonly [{
-        readonly name: "owner";
-        readonly type: "address";
-    }, {
-        readonly name: "salt";
-        readonly type: "uint256";
-    }];
-    readonly name: "isAccountDeployed";
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "bool";
-    }];
-    readonly stateMutability: "view";
-    readonly type: "function";
-}, {
-    readonly inputs: readonly [{
-        readonly name: "owner";
-        readonly type: "address";
-    }, {
-        readonly name: "salt";
-        readonly type: "uint256";
-    }];
-    readonly name: "createAccount";
-    readonly outputs: readonly [{
-        readonly name: "account";
-        readonly type: "address";
-    }];
-    readonly stateMutability: "nonpayable";
-    readonly type: "function";
-}];
-declare const entryPointAbi: readonly [{
-    readonly inputs: readonly [{
-        readonly name: "sender";
-        readonly type: "address";
-    }, {
-        readonly name: "key";
-        readonly type: "uint192";
-    }];
-    readonly name: "getNonce";
-    readonly outputs: readonly [{
-        readonly name: "nonce";
-        readonly type: "uint256";
-    }];
-    readonly stateMutability: "view";
-    readonly type: "function";
-}];
-declare const smartAccountAbi: readonly [{
-    readonly inputs: readonly [{
-        readonly name: "target";
-        readonly type: "address";
-    }, {
-        readonly name: "value";
-        readonly type: "uint256";
-    }, {
-        readonly name: "data";
-        readonly type: "bytes";
-    }];
-    readonly name: "execute";
-    readonly outputs: readonly [];
-    readonly stateMutability: "nonpayable";
-    readonly type: "function";
-}, {
-    readonly inputs: readonly [{
-        readonly name: "targets";
-        readonly type: "address[]";
-    }, {
-        readonly name: "values";
-        readonly type: "uint256[]";
-    }, {
-        readonly name: "datas";
-        readonly type: "bytes[]";
-    }];
-    readonly name: "executeBatch";
-    readonly outputs: readonly [];
-    readonly stateMutability: "nonpayable";
-    readonly type: "function";
-}];
-declare const erc20Abi: readonly [{
-    readonly inputs: readonly [{
-        readonly name: "account";
-        readonly type: "address";
-    }];
-    readonly name: "balanceOf";
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "uint256";
-    }];
-    readonly stateMutability: "view";
-    readonly type: "function";
-}, {
-    readonly inputs: readonly [{
-        readonly name: "to";
-        readonly type: "address";
-    }, {
-        readonly name: "amount";
-        readonly type: "uint256";
-    }];
-    readonly name: "transfer";
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "bool";
-    }];
-    readonly stateMutability: "nonpayable";
-    readonly type: "function";
-}, {
-    readonly inputs: readonly [{
-        readonly name: "spender";
-        readonly type: "address";
-    }, {
-        readonly name: "amount";
-        readonly type: "uint256";
-    }];
-    readonly name: "approve";
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "bool";
-    }];
-    readonly stateMutability: "nonpayable";
-    readonly type: "function";
-}, {
-    readonly inputs: readonly [{
-        readonly name: "owner";
-        readonly type: "address";
-    }, {
-        readonly name: "spender";
-        readonly type: "address";
-    }];
-    readonly name: "allowance";
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "uint256";
-    }];
-    readonly stateMutability: "view";
-    readonly type: "function";
-}, {
-    readonly inputs: readonly [{
-        readonly name: "from";
-        readonly type: "address";
-    }, {
-        readonly name: "to";
-        readonly type: "address";
-    }, {
-        readonly name: "amount";
-        readonly type: "uint256";
-    }];
-    readonly name: "transferFrom";
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "bool";
-    }];
-    readonly stateMutability: "nonpayable";
-    readonly type: "function";
-}, {
-    readonly inputs: readonly [];
-    readonly name: "decimals";
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "uint8";
-    }];
-    readonly stateMutability: "view";
-    readonly type: "function";
-}];
-
-export { AccountAbstraction, type ApprovalSupportResult, type ChainConfig, DEFAULT_ENTRYPOINT, DEFAULT_FACTORY, type GasEstimate, type UserOpReceipt, type UserOperation, entryPointAbi, erc20Abi, factoryAbi, smartAccountAbi };