@1llet.xyz/erc4337-gasless-sdk 0.1.7 → 0.4.0

package/README.md

@@ -17,20 +17,14 @@ yarn add @1llet.xyz/erc4337-gasless-sdk viem
 Define the chain configuration (including your Bundler URL and Paymaster).
 
 ```typescript
-import { type ChainConfig } from "@1llet.xyz/erc4337-gasless-sdk";
-import { baseSepolia } from "viem/chains";
-
-const config: ChainConfig = {
-  chain: baseSepolia,
-  // Your Bundler URL (must support ERC-4337 methods)
-  bundlerUrl: "https://api.yourbundler.com/rpc", 
-  // Optional: Override RPC URL (defaults to chain.rpcUrls.default)
-  // rpcUrl: "https://sepolia.base.org",
-  
-  // Addresses are automatically resolved for supported chains (Base, Base Sepolia)
-  // You can override them if needed:
-  // factoryAddress: "0x...", 
-};
+// 1. Import Config (Chain Registry)
+import { BASE_SEPOLIA, type ChainConfig } from "@1llet.xyz/erc4337-gasless-sdk";
+import { AccountAbstraction } from "@1llet.xyz/erc4337-gasless-sdk";
+
+// 2. Initialize
+const aa = new AccountAbstraction(BASE_SEPOLIA);
+
+await aa.connect();
 ```
 
 ### 2. Initialize & Connect
@@ -143,6 +137,56 @@ const address = await aa.getSmartAccountAddress(ownerAddress);
 const receipt = await aa.deployAccount();
 ```
 
+### Simplified Transactions (v0.2.0+)
+
+Send transactions without manually building, signing, and waiting.
+
+```typescript
+// 1. Send ETH or Call Contract (Single)
+const receipt = await aa.sendTransaction({
+    target: "0x123...",
+    value: 1000000000000000000n, // 1 ETH
+    data: "0x..." // Optional callData
+});
+
+// 2. Send Multiple Transactions (Batch)
+// Great for approving + swapping, or multiple transfers
+const receipt = await aa.sendBatchTransaction([
+    { target: "0xToken...", data: encodeApproveData },
+    { target: "0xSwap...", data: encodeSwapData }
+]);
+
+// 3. Transfer ERC-20 Tokens (Helper)
+// Automatically encodes the
+// 1. Transfer ERC-20 (USDC)
+await aa.transfer("USDC", recipient, amount);
+
+// 2. Transfer Native Token (ETH)
+// The SDK detects the "ETH" symbol and sends a native transaction
+await aa.transfer("ETH", recipient, amount);
+```
+
+// 2. Transfer Native Token (ETH)
+// The SDK detects the "ETH" symbol and sends a native transaction
+await aa.transfer("ETH", recipient, amount);
+```
+
+### Funding the Account
+
+Easily deposit ETH from the connected wallet (EOA) to the Smart Account.
+
+```typescript
+// Deposit 0.1 ETH
+const txHash = await aa.deposit(100000000000000000n);
+```
+
+### High-Level Methods
+
+### Error Decoding
+The SDK now automatically tries to decode cryptic "0x..." errors from the EntryPoint into readable messages like:
+- `Smart Account Error: Transfer amount exceeds balance`
+- `Smart Account: Native transfer failed`
+
 ### Simplified Approvals
 
 ```typescript

package/package.json

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

package/src/AccountAbstraction.ts

@@ -1,29 +1,25 @@
 import {
     createPublicClient,
     http,
-    encodeFunctionData,
-    encodeAbiParameters,
-    keccak256,
     type Address,
     type Hash,
     type Hex,
-    type PublicClient
+    type PublicClient,
+    decodeErrorResult
 } from "viem";
 import {
     factoryAbi,
-    entryPointAbi,
-    smartAccountAbi,
-    erc20Abi,
 } from "./constants";
 import {
     type ChainConfig,
     type UserOperation,
-    type GasEstimate,
     type UserOpReceipt,
-    type ApprovalSupportResult
+    type ApprovalSupportResult,
+    type Token
 } from "./types";
-import { DEPLOYMENTS } from "./deployments";
 import { BundlerClient } from "./BundlerClient";
+import { TokenService } from "./TokenService";
+import { UserOpBuilder } from "./UserOpBuilder";
 
 /**
  * ERC-4337 Account Abstraction Client
@@ -35,41 +31,35 @@ export class AccountAbstraction {
     private publicClient: PublicClient;
     private bundlerClient: BundlerClient;
 
+    // Services
+    private tokenService: TokenService;
+    private userOpBuilder: UserOpBuilder;
+
     // Resolved addresses
     private entryPointAddress: Address;
     private factoryAddress: Address;
-    private paymasterAddress?: Address;
-    private usdcAddress: Address;
 
     constructor(chainConfig: ChainConfig) {
         this.chainConfig = chainConfig;
-        const chainId = chainConfig.chain.id;
-        const defaults = DEPLOYMENTS[chainId];
-
-        // Resolve addresses (Config > Defaults > Error)
-        const entryPoint = chainConfig.entryPointAddress || defaults?.entryPoint;
-        if (!entryPoint) throw new Error(`EntryPoint address not found for chain ${chainId}`);
-        this.entryPointAddress = entryPoint;
-
-        const factory = chainConfig.factoryAddress || defaults?.factory;
-        if (!factory) throw new Error(`Factory address not found for chain ${chainId}`);
-        this.factoryAddress = factory;
 
-        const usdc = chainConfig.usdcAddress || defaults?.usdc;
-        if (!usdc) throw new Error(`USDC address not found for chain ${chainId}`);
-        this.usdcAddress = usdc;
+        // Validation
+        if (!chainConfig.entryPointAddress) throw new Error("EntryPoint address required");
+        this.entryPointAddress = chainConfig.entryPointAddress;
+        if (!chainConfig.factoryAddress) throw new Error("Factory address required");
+        this.factoryAddress = chainConfig.factoryAddress;
 
-        this.paymasterAddress = chainConfig.paymasterAddress || defaults?.paymaster;
-
-        // Use provided RPC or default from chain
+        // Setup Clients
         const rpcUrl = chainConfig.rpcUrl || chainConfig.chain.rpcUrls.default.http[0];
-
         this.publicClient = createPublicClient({
             chain: chainConfig.chain,
             transport: http(rpcUrl),
         });
 
         this.bundlerClient = new BundlerClient(chainConfig, this.entryPointAddress);
+
+        // Setup Services
+        this.tokenService = new TokenService(chainConfig, this.publicClient);
+        this.userOpBuilder = new UserOpBuilder(chainConfig, this.bundlerClient, this.publicClient);
     }
 
     /**
@@ -85,19 +75,15 @@ export class AccountAbstraction {
             method: "eth_requestAccounts",
         })) as string[];
 
-        if (!accounts || accounts.length === 0) {
-            throw new Error("No accounts found");
-        }
+        if (!accounts || accounts.length === 0) throw new Error("No accounts found");
 
         // Check network
         const chainId = (await window.ethereum.request({
             method: "eth_chainId",
         })) as string;
-
         const targetChainId = this.chainConfig.chain.id;
 
         if (parseInt(chainId, 16) !== targetChainId) {
-            // Switch to configured chain
             try {
                 await window.ethereum.request({
                     method: "wallet_switchEthereumChain",
@@ -105,7 +91,6 @@ export class AccountAbstraction {
                 });
             } catch (switchError: unknown) {
                 const error = switchError as { code?: number };
-                // Chain not added, add it
                 if (error.code === 4902) {
                     await window.ethereum.request({
                         method: "wallet_addEthereumChain",
@@ -114,7 +99,7 @@ export class AccountAbstraction {
                                 chainId: "0x" + targetChainId.toString(16),
                                 chainName: this.chainConfig.chain.name,
                                 nativeCurrency: this.chainConfig.chain.nativeCurrency,
-                                rpcUrls: [this.chainConfig.rpcUrl],
+                                rpcUrls: [this.chainConfig.rpcUrl || this.chainConfig.chain.rpcUrls.default.http[0]],
                                 blockExplorerUrls: this.chainConfig.chain.blockExplorers?.default?.url
                                     ? [this.chainConfig.chain.blockExplorers.default.url]
                                     : [],
@@ -137,14 +122,14 @@ export class AccountAbstraction {
     }
 
     /**
-     * Get the Smart Account address for an owner (counterfactual)
+     * Get the Smart Account address for an owner
      */
     async getSmartAccountAddress(owner: Address): Promise<Address> {
         const address = await this.publicClient.readContract({
             address: this.factoryAddress,
             abi: factoryAbi,
             functionName: "getAccountAddress",
-            args: [owner, 0n], // salt = 0
+            args: [owner, 0n],
         }) as Address;
         return address;
     }
@@ -153,356 +138,210 @@ export class AccountAbstraction {
      * Check if the Smart Account is deployed
      */
     async isAccountDeployed(): Promise<boolean> {
-        if (!this.smartAccountAddress) {
-            throw new Error("Not connected");
-        }
-
-        const code = await this.publicClient.getCode({
-            address: this.smartAccountAddress,
-        });
-        return code !== undefined && code !== "0x";
+        if (!this.smartAccountAddress) throw new Error("Not connected");
+        return this.userOpBuilder.isAccountDeployed(this.smartAccountAddress);
     }
 
+    // --- Token Methods (Delegated) ---
 
-    /**
-     * Get the USDC balance of the Smart Account
-     */
-    async getUsdcBalance(): Promise<bigint> {
-        if (!this.smartAccountAddress) {
-            throw new Error("Not connected");
-        }
-
-        return await this.publicClient.readContract({
-            address: this.usdcAddress,
-            abi: erc20Abi,
-            functionName: "balanceOf",
-            args: [this.smartAccountAddress],
-        }) as bigint;
+    getTokenAddress(token: string | Address): Address {
+        return this.tokenService.getTokenAddress(token);
     }
 
+    async getUsdcBalance(): Promise<bigint> {
+        if (!this.smartAccountAddress) throw new Error("Not connected");
+        return this.tokenService.getBalance("USDC", this.smartAccountAddress);
+    }
 
-    /**
-     * Get the EOA's USDC balance
-     */
     async getEoaUsdcBalance(): Promise<bigint> {
-        if (!this.owner) {
-            throw new Error("Not connected");
-        }
-
-        return await this.publicClient.readContract({
-            address: this.usdcAddress,
-            abi: erc20Abi,
-            functionName: "balanceOf",
-            args: [this.owner],
-        }) as bigint;
+        if (!this.owner) throw new Error("Not connected");
+        return this.tokenService.getBalance("USDC", this.owner);
     }
 
-    /**
-     * Get the allowance of the Smart Account to spend the EOA's USDC
-     */
     async getAllowance(): Promise<bigint> {
-        if (!this.owner || !this.smartAccountAddress) {
-            throw new Error("Not connected");
-        }
-
-        return await this.publicClient.readContract({
-            address: this.usdcAddress,
-            abi: erc20Abi,
-            functionName: "allowance",
-            args: [this.owner, this.smartAccountAddress],
-        }) as bigint;
+        if (!this.owner || !this.smartAccountAddress) throw new Error("Not connected");
+        return this.tokenService.getAllowance("USDC", this.owner, this.smartAccountAddress);
     }
 
-    /**
-     * Get the nonce for the Smart Account
-     */
-    async getNonce(): Promise<bigint> {
-        if (!this.smartAccountAddress) {
-            throw new Error("Not connected");
+    // --- Transactions ---
+
+    async deployAccount(): Promise<UserOpReceipt> {
+        if (!this.owner || !this.smartAccountAddress) throw new Error("Not connected");
+
+        try {
+            const userOp = await this.userOpBuilder.buildDeployUserOp(this.owner, this.smartAccountAddress);
+            const signed = await this.signUserOperation(userOp);
+            const hash = await this.sendUserOperation(signed);
+            return await this.waitForUserOperation(hash);
+        } catch (error) {
+            throw this.decodeError(error);
         }
+    }
 
-        return await this.publicClient.readContract({
-            address: this.entryPointAddress,
-            abi: entryPointAbi,
-            functionName: "getNonce",
-            args: [this.smartAccountAddress, 0n],
-        }) as bigint;
+    async sendTransaction(
+        tx: { target: Address; value?: bigint; data?: Hex }
+    ): Promise<UserOpReceipt> {
+        return this.sendBatchTransaction([tx]);
     }
 
-    /**
-     * Build initCode for account deployment
-     */
-    buildInitCode(): Hex {
-        if (!this.owner) {
-            throw new Error("Not connected");
+    async sendBatchTransaction(
+        txs: { target: Address; value?: bigint; data?: Hex }[]
+    ): Promise<UserOpReceipt> {
+        if (!this.owner || !this.smartAccountAddress) throw new Error("Not connected");
+
+        // Normalize
+        const transactions = txs.map(tx => ({
+            target: tx.target,
+            value: tx.value ?? 0n,
+            data: tx.data ?? "0x"
+        }));
+
+        try {
+            const userOp = await this.userOpBuilder.buildUserOperationBatch(
+                this.owner,
+                this.smartAccountAddress,
+                transactions
+            );
+            const signed = await this.signUserOperation(userOp);
+            const hash = await this.sendUserOperation(signed);
+            return await this.waitForUserOperation(hash);
+        } catch (error) {
+            throw this.decodeError(error);
         }
-
-        const createAccountData = encodeFunctionData({
-            abi: factoryAbi,
-            functionName: "createAccount",
-            args: [this.owner, 0n],
-        });
-
-        return `${this.factoryAddress}${createAccountData.slice(2)}` as Hex;
     }
 
-
-    /**
-     * Estimate gas for a UserOperation
-     */
-    async estimateGas(userOp: Partial<UserOperation>): Promise<GasEstimate> {
-        return this.bundlerClient.estimateGas(userOp);
+    async deposit(amount: bigint): Promise<Hash> {
+        if (!this.owner || !this.smartAccountAddress) throw new Error("Not connected");
+
+        const txHash = await window.ethereum!.request({
+            method: "eth_sendTransaction",
+            params: [{
+                from: this.owner,
+                to: this.smartAccountAddress,
+                value: "0x" + amount.toString(16)
+            }]
+        }) as Hash;
+        return txHash;
     }
 
-
-    /**
-     * Build a UserOperation for Batched Execution (e.g. USDC Transfer + Fee)
-     */
-    async buildUserOperationBatch(
-        transactions: { target: Address; value: bigint; data: Hex }[]
-    ): Promise<UserOperation> {
-        if (!this.owner || !this.smartAccountAddress) {
-            throw new Error("Not connected");
+    async transfer(
+        token: Address | string,
+        recipient: Address,
+        amount: bigint
+    ): Promise<UserOpReceipt> {
+        const tokenAddress = this.getTokenAddress(token);
+
+        // Native Transfer check
+        if (tokenAddress === "0x0000000000000000000000000000000000000000") {
+            return this.sendTransaction({
+                target: recipient,
+                value: amount,
+                data: "0x"
+            });
         }
 
-        const isDeployed = await this.isAccountDeployed();
-        const initCode = isDeployed ? "0x" : this.buildInitCode();
-
-        // Prepare arrays for executeBatch
-        const targets = transactions.map((tx) => tx.target);
-        const values = transactions.map((tx) => tx.value);
-        const datas = transactions.map((tx) => tx.data);
-
-        // Encode callData for executeBatch
-        const callData = encodeFunctionData({
-            abi: smartAccountAbi,
-            functionName: "executeBatch",
-            args: [targets, values, datas],
-        });
-
-        const nonce = await this.getNonce();
-
-        // Estimate gas
-        const gasEstimate = await this.estimateGas({
-            sender: this.smartAccountAddress,
-            nonce,
-            initCode: initCode as Hex,
-            callData,
-            paymasterAndData: this.paymasterAddress as Hex,
+        // ERC-20
+        const data = this.tokenService.encodeTransfer(recipient, amount);
+        return this.sendTransaction({
+            target: tokenAddress,
+            value: 0n,
+            data
         });
-
-        return {
-            sender: this.smartAccountAddress,
-            nonce,
-            initCode: initCode as Hex,
-            callData,
-            callGasLimit: BigInt(gasEstimate.callGasLimit),
-            verificationGasLimit: BigInt(gasEstimate.verificationGasLimit),
-            preVerificationGas: BigInt(gasEstimate.preVerificationGas),
-            maxFeePerGas: BigInt(gasEstimate.maxFeePerGas),
-            maxPriorityFeePerGas: BigInt(gasEstimate.maxPriorityFeePerGas),
-            paymasterAndData: this.paymasterAddress as Hex,
-            signature: "0x",
-        };
     }
 
     /**
-     * Build a UserOperation to ONLY deploy the account (empty callData)
+     * Approve a token for the Smart Account
      */
-    async buildDeployUserOperation(): Promise<UserOperation> {
-        if (!this.owner || !this.smartAccountAddress) {
-            throw new Error("Not connected");
-        }
+    async approveToken(
+        token: Address,
+        spender: Address,
+        amount: bigint = 115792089237316195423570985008687907853269984665640564039457584007913129639935n // maxUint256
+    ): Promise<Hash | "NOT_NEEDED"> {
+        if (!this.owner) throw new Error("Not connected");
 
-        const isDeployed = await this.isAccountDeployed();
-        if (isDeployed) {
-            throw new Error("Account is already deployed");
-        }
+        const support = await this.requestApprovalSupport(token, spender, amount);
 
-        const initCode = this.buildInitCode();
-        const callData = "0x"; // Empty callData for deployment only
-        const nonce = await this.getNonce();
-
-        // Estimate gas
-        const gasEstimate = await this.estimateGas({
-            sender: this.smartAccountAddress,
-            nonce,
-            initCode: initCode as Hex,
-            callData,
-            paymasterAndData: this.paymasterAddress as Hex,
-        });
+        if (support.type === "approve") {
+            const data = this.tokenService.encodeApprove(spender, amount);
+            const txHash = await window.ethereum!.request({
+                method: "eth_sendTransaction",
+                params: [{
+                    from: this.owner,
+                    to: token,
+                    data,
+                }]
+            }) as Hash;
+            return txHash;
+        }
 
-        return {
-            sender: this.smartAccountAddress,
-            nonce,
-            initCode: initCode as Hex,
-            callData,
-            callGasLimit: BigInt(gasEstimate.callGasLimit),
-            verificationGasLimit: BigInt(gasEstimate.verificationGasLimit),
-            preVerificationGas: BigInt(gasEstimate.preVerificationGas),
-            maxFeePerGas: BigInt(gasEstimate.maxFeePerGas),
-            maxPriorityFeePerGas: BigInt(gasEstimate.maxPriorityFeePerGas),
-            paymasterAndData: this.paymasterAddress as Hex,
-            signature: "0x",
-        };
+        if (support.type === "permit") throw new Error("Permit not yet supported");
+        return "NOT_NEEDED";
     }
 
-    /**
-     * Calculate the UserOperation hash
-     */
-    getUserOpHash(userOp: UserOperation): Hex {
-        const packed = encodeAbiParameters(
-            [
-                { type: "address" },
-                { type: "uint256" },
-                { type: "bytes32" },
-                { type: "bytes32" },
-                { type: "uint256" },
-                { type: "uint256" },
-                { type: "uint256" },
-                { type: "uint256" },
-                { type: "uint256" },
-                { type: "bytes32" },
-            ],
-            [
-                userOp.sender,
-                userOp.nonce,
-                keccak256(userOp.initCode),
-                keccak256(userOp.callData),
-                userOp.callGasLimit,
-                userOp.verificationGasLimit,
-                userOp.preVerificationGas,
-                userOp.maxFeePerGas,
-                userOp.maxPriorityFeePerGas,
-                keccak256(userOp.paymasterAndData),
-            ]
-        );
-
-        const packedHash = keccak256(packed);
-
-        return keccak256(
-            encodeAbiParameters(
-                [{ type: "bytes32" }, { type: "address" }, { type: "uint256" }],
-                [packedHash, this.entryPointAddress, BigInt(this.chainConfig.chain.id)]
-            )
-        );
+    // --- Core Bridge to Bundler/UserOp ---
+
+    // Deprecated/Legacy but kept for compatibility or advanced usage?
+    // buildUserOperationBatch moved to internal usage mostly, but maybe exposed?
+    // If I remove them from public API, that is a BREAKING change if user used them.
+    // User requested "modularize", but usually expects same public API.
+    // I will expose them as simple delegates if needed, or assume they primarily use sendBatchTransaction.
+    // The previous implementation exposed `buildUserOperationBatch`.
+    async buildUserOperationBatch(transactions: any[]) {
+        if (!this.owner || !this.smartAccountAddress) throw new Error("Not connected");
+        return this.userOpBuilder.buildUserOperationBatch(this.owner, this.smartAccountAddress, transactions);
     }
 
-    /**
-     * Sign a UserOperation with MetaMask
-     */
     async signUserOperation(userOp: UserOperation): Promise<UserOperation> {
-        if (!this.owner) {
-            throw new Error("Not connected");
-        }
+        if (!this.owner) throw new Error("Not connected");
 
-        const userOpHash = this.getUserOpHash(userOp);
+        const userOpHash = this.userOpBuilder.getUserOpHash(userOp);
 
-        // Sign with MetaMask using personal_sign (EIP-191)
         const signature = (await window.ethereum!.request({
             method: "personal_sign",
             params: [userOpHash, this.owner],
         })) as Hex;
 
-        return {
-            ...userOp,
-            signature,
-        };
+        return { ...userOp, signature };
     }
 
-    /**
-     * Send a signed UserOperation to the bundler
-     */
     async sendUserOperation(userOp: UserOperation): Promise<Hash> {
         return this.bundlerClient.sendUserOperation(userOp);
     }
 
-    /**
-     * Wait for a UserOperation to be confirmed
-     */
-    async waitForUserOperation(
-        userOpHash: Hash,
-        timeout = 60000
-    ): Promise<UserOpReceipt> {
-        return this.bundlerClient.waitForUserOperation(userOpHash, timeout);
+    async waitForUserOperation(hash: Hash, timeout = 60000) {
+        return this.bundlerClient.waitForUserOperation(hash, timeout);
     }
 
-
-    /**
-     * Request support for token approval (fund if needed)
-     */
-    async requestApprovalSupport(
-        token: Address,
-        spender: Address,
-        amount: bigint
-    ): Promise<ApprovalSupportResult> {
-        if (!this.owner) {
-            throw new Error("Not connected");
-        }
+    // Internal but exposed via BundlerClient originally
+    async requestApprovalSupport(token: Address, spender: Address, amount: bigint): Promise<ApprovalSupportResult> {
+        if (!this.owner) throw new Error("Not connected");
         return this.bundlerClient.requestApprovalSupport(token, this.owner, spender, amount);
     }
 
-    /**
-     * 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;
+    // Error Decoding (Private)
+    private decodeError(error: any): Error {
+        const msg = error?.message || "";
+        const hexMatch = msg.match(/(0x[0-9a-fA-F]+)/);
 
-            return txHash;
+        if (hexMatch) {
+            try {
+                const decoded = decodeErrorResult({
+                    abi: [{ inputs: [{ name: "message", type: "string" }], name: "Error", type: "error" }],
+                    data: hexMatch[0] as Hex
+                });
+                if (decoded.errorName === "Error") return new Error(`Smart Account Error: ${decoded.args[0]}`);
+            } catch (e) { /* ignore */ }
         }
 
-        if (support.type === "permit") {
-            throw new Error("Permit not yet supported in this SDK version");
-        }
+        if (msg.includes("AA21")) return new Error("Smart Account: Native transfer failed (ETH missing?)");
+        if (msg.includes("AA25")) return new Error("Smart Account: Invalid account nonce");
 
-        return "NOT_NEEDED";
+        return error instanceof Error ? error : new Error(String(error));
     }
 
     // Getters
-    getOwner(): Address | null {
-        return this.owner;
-    }
-
-    getSmartAccount(): Address | null {
-        return this.smartAccountAddress;
-    }
+    getOwner() { return this.owner; }
+    getSmartAccount() { return this.smartAccountAddress; }
 }
 
 // Global window types for MetaMask

package/src/TokenService.ts

@@ -0,0 +1,92 @@
+import { type Address, type PublicClient, encodeFunctionData } from "viem";
+import { type ChainConfig, type Token } from "./types";
+import { erc20Abi } from "./constants";
+
+export class TokenService {
+    private tokens: Map<string, Token> = new Map();
+    private publicClient: PublicClient;
+
+    constructor(chainConfig: ChainConfig, publicClient: PublicClient) {
+        this.publicClient = publicClient;
+
+        // Initialize Tokens
+        chainConfig.tokens.forEach(token => {
+            this.tokens.set(token.symbol.toUpperCase(), token);
+        });
+    }
+
+    /**
+     * Resolve token address from symbol or return address if provided
+     */
+    getTokenAddress(token: string | Address): Address {
+        // Native Token (ETH)
+        if (token === "ETH") {
+            return "0x0000000000000000000000000000000000000000";
+        }
+
+        if (token.startsWith("0x")) return token as Address;
+        const info = this.tokens.get(token.toUpperCase());
+        if (!info) throw new Error(`Token ${token} not found in chain config`);
+        return info.address;
+    }
+
+    /**
+     * Get balance of a token for an account
+     */
+    async getBalance(token: string | Address, account: Address): Promise<bigint> {
+        const address = this.getTokenAddress(token);
+
+        // Native Balance
+        if (address === "0x0000000000000000000000000000000000000000") {
+            return await this.publicClient.getBalance({ address: account });
+        }
+
+        // ERC-20 Balance
+        return await this.publicClient.readContract({
+            address,
+            abi: erc20Abi,
+            functionName: "balanceOf",
+            args: [account],
+        }) as bigint;
+    }
+
+    /**
+     * Get allowance (ERC-20 only)
+     */
+    async getAllowance(token: string | Address, owner: Address, spender: Address): Promise<bigint> {
+        const address = this.getTokenAddress(token);
+
+        if (address === "0x0000000000000000000000000000000000000000") {
+            return 0n; // Native token has no allowance
+        }
+
+        return await this.publicClient.readContract({
+            address,
+            abi: erc20Abi,
+            functionName: "allowance",
+            args: [owner, spender],
+        }) as bigint;
+    }
+
+    /**
+     * Encode transfer data
+     */
+    encodeTransfer(recipient: Address, amount: bigint): `0x${string}` {
+        return encodeFunctionData({
+            abi: erc20Abi,
+            functionName: "transfer",
+            args: [recipient, amount]
+        });
+    }
+
+    /**
+     * Encode approve data
+     */
+    encodeApprove(spender: Address, amount: bigint): `0x${string}` {
+        return encodeFunctionData({
+            abi: erc20Abi,
+            functionName: "approve",
+            args: [spender, amount]
+        });
+    }
+}

package/src/UserOpBuilder.ts

@@ -0,0 +1,173 @@
+import {
+    type Address,
+    type Hash,
+    type Hex,
+    type PublicClient,
+    encodeFunctionData,
+    encodeAbiParameters,
+    keccak256
+} from "viem";
+import { type ChainConfig, type UserOperation, type GasEstimate } from "./types";
+import { BundlerClient } from "./BundlerClient";
+import { factoryAbi, smartAccountAbi, entryPointAbi } from "./constants";
+
+export class UserOpBuilder {
+    private chainConfig: ChainConfig;
+    private bundlerClient: BundlerClient;
+    private publicClient: PublicClient;
+    private entryPointAddress: Address;
+    private factoryAddress: Address;
+
+    constructor(
+        chainConfig: ChainConfig,
+        bundlerClient: BundlerClient,
+        publicClient: PublicClient
+    ) {
+        this.chainConfig = chainConfig;
+        this.bundlerClient = bundlerClient;
+        this.publicClient = publicClient;
+
+        // Resolved in AA or here? Let's assume passed valid config or resolve again
+        // Ideally we shouldn't duplicate logic. AA resolves them.
+        // Let's rely on config having them or resolving valid ones.
+        // For now take from config or defaults.
+        this.entryPointAddress = chainConfig.entryPointAddress!; // Assumed validated by AA
+        this.factoryAddress = chainConfig.factoryAddress!;
+    }
+
+    async getNonce(smartAccountAddress: Address): Promise<bigint> {
+        return await this.publicClient.readContract({
+            address: this.entryPointAddress,
+            abi: entryPointAbi,
+            functionName: "getNonce",
+            args: [smartAccountAddress, 0n],
+        }) as bigint;
+    }
+
+    buildInitCode(owner: Address): Hex {
+        const createAccountData = encodeFunctionData({
+            abi: factoryAbi,
+            functionName: "createAccount",
+            args: [owner, 0n],
+        });
+        return `${this.factoryAddress}${createAccountData.slice(2)}` as Hex;
+    }
+
+    async isAccountDeployed(smartAccountAddress: Address): Promise<boolean> {
+        const code = await this.publicClient.getCode({
+            address: smartAccountAddress,
+        });
+        return code !== undefined && code !== "0x";
+    }
+
+    async buildUserOperationBatch(
+        owner: Address,
+        smartAccountAddress: Address,
+        transactions: { target: Address; value: bigint; data: Hex }[]
+    ): Promise<UserOperation> {
+        const isDeployed = await this.isAccountDeployed(smartAccountAddress);
+        const initCode = isDeployed ? "0x" : this.buildInitCode(owner);
+
+        const targets = transactions.map((tx) => tx.target);
+        const values = transactions.map((tx) => tx.value);
+        const datas = transactions.map((tx) => tx.data);
+
+        const callData = encodeFunctionData({
+            abi: smartAccountAbi,
+            functionName: "executeBatch",
+            args: [targets, values, datas],
+        });
+
+        const nonce = await this.getNonce(smartAccountAddress);
+
+        const partialOp = {
+            sender: smartAccountAddress,
+            nonce,
+            initCode: initCode as Hex,
+            callData,
+            paymasterAndData: (this.chainConfig.paymasterAddress || "0x") as Hex,
+        };
+
+        const gasEstimate = await this.bundlerClient.estimateGas(partialOp);
+
+        return {
+            ...partialOp,
+            callGasLimit: BigInt(gasEstimate.callGasLimit),
+            verificationGasLimit: BigInt(gasEstimate.verificationGasLimit),
+            preVerificationGas: BigInt(gasEstimate.preVerificationGas),
+            maxFeePerGas: BigInt(gasEstimate.maxFeePerGas),
+            maxPriorityFeePerGas: BigInt(gasEstimate.maxPriorityFeePerGas),
+            signature: "0x",
+        };
+    }
+
+    async buildDeployUserOp(
+        owner: Address,
+        smartAccountAddress: Address
+    ): Promise<UserOperation> {
+        const isDeployed = await this.isAccountDeployed(smartAccountAddress);
+        if (isDeployed) throw new Error("Account already deployed");
+
+        const initCode = this.buildInitCode(owner);
+        const callData = "0x";
+        const nonce = await this.getNonce(smartAccountAddress);
+
+        const partialOp = {
+            sender: smartAccountAddress,
+            nonce,
+            initCode: initCode as Hex,
+            callData: callData as Hex,
+            paymasterAndData: (this.chainConfig.paymasterAddress || "0x") as Hex,
+        };
+
+        const gasEstimate = await this.bundlerClient.estimateGas(partialOp);
+
+        return {
+            ...partialOp,
+            callGasLimit: BigInt(gasEstimate.callGasLimit),
+            verificationGasLimit: BigInt(gasEstimate.verificationGasLimit),
+            preVerificationGas: BigInt(gasEstimate.preVerificationGas),
+            maxFeePerGas: BigInt(gasEstimate.maxFeePerGas),
+            maxPriorityFeePerGas: BigInt(gasEstimate.maxPriorityFeePerGas),
+            signature: "0x",
+        };
+    }
+
+    getUserOpHash(userOp: UserOperation): Hex {
+        const packed = encodeAbiParameters(
+            [
+                { type: "address" },
+                { type: "uint256" },
+                { type: "bytes32" },
+                { type: "bytes32" },
+                { type: "uint256" },
+                { type: "uint256" },
+                { type: "uint256" },
+                { type: "uint256" },
+                { type: "uint256" },
+                { type: "bytes32" },
+            ],
+            [
+                userOp.sender,
+                userOp.nonce,
+                keccak256(userOp.initCode),
+                keccak256(userOp.callData),
+                userOp.callGasLimit,
+                userOp.verificationGasLimit,
+                userOp.preVerificationGas,
+                userOp.maxFeePerGas,
+                userOp.maxPriorityFeePerGas,
+                keccak256(userOp.paymasterAndData),
+            ]
+        );
+
+        const packedHash = keccak256(packed);
+
+        return keccak256(
+            encodeAbiParameters(
+                [{ type: "bytes32" }, { type: "address" }, { type: "uint256" }],
+                [packedHash, this.entryPointAddress, BigInt(this.chainConfig.chain.id)]
+            )
+        );
+    }
+}

package/src/chains.ts

@@ -0,0 +1,54 @@
+import { type ChainConfig } from "./types";
+import { base, baseSepolia } from "viem/chains";
+
+export const BASE_MAINNET: ChainConfig = {
+    chain: base,
+    bundlerUrl: "http://localhost:3000/rpc?chain=base", // Default to local bundler pattern
+
+    // Addresses
+    entryPointAddress: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
+    factoryAddress: "0xe2584152891E4769025807DEa0cD611F135aDC68",
+    paymasterAddress: "0x1e13Eb16C565E3f3FDe49A011755e50410bb1F95",
+
+    tokens: [
+        {
+            symbol: "USDC",
+            decimals: 6,
+            address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+        },
+        {
+            symbol: "ETH",
+            decimals: 18,
+            address: "0x0000000000000000000000000000000000000000"
+        }
+    ]
+};
+
+export const BASE_SEPOLIA: ChainConfig = {
+    chain: baseSepolia,
+    bundlerUrl: "http://localhost:3000/rpc?chain=baseSepolia", // Default to local bundler pattern
+
+    // Addresses
+    entryPointAddress: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
+    factoryAddress: "0x9406Cc6185a346906296840746125a0E44976454",
+    // Paymaster not configured in deployments.ts for Sepolia?
+
+    tokens: [
+        {
+            symbol: "USDC",
+            decimals: 6,
+            address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+        },
+        {
+            symbol: "ETH",
+            decimals: 18,
+            address: "0x0000000000000000000000000000000000000000"
+        }
+    ]
+};
+
+// Map accessible by ChainID
+export const CHAIN_CONFIGS: Record<number, ChainConfig> = {
+    [base.id]: BASE_MAINNET,
+    [baseSepolia.id]: BASE_SEPOLIA
+};

package/src/index.ts

@@ -1,4 +1,12 @@
-export * from "./AccountAbstraction";
-export * from "./types";
-export * from "./constants";
-export * from "./deployments";
+// Core
+export { AccountAbstraction } from "./AccountAbstraction";
+export { BundlerClient } from "./BundlerClient";
+
+// Config & Registry
+export { BASE_MAINNET, BASE_SEPOLIA, CHAIN_CONFIGS } from "./chains";
+
+// Types
+export type { ChainConfig, Token, UserOperation, UserOpReceipt } from "./types";
+
+// Constants (ABIs)
+export { erc20Abi, smartAccountAbi, entryPointAbi } from "./constants";

package/src/types.ts

@@ -1,5 +1,11 @@
 import { type Address, type Chain, type Hash, type Hex } from "viem";
 
+export interface Token {
+    symbol: string;
+    decimals: number;
+    address: Address;
+}
+
 export interface ChainConfig {
     chain: Chain;
     rpcUrl?: string; // Optional, defaults to chain.rpcUrls.default
@@ -7,7 +13,7 @@ export interface ChainConfig {
     entryPointAddress?: Address;
     factoryAddress?: Address;
     paymasterAddress?: Address;
-    usdcAddress?: Address;
+    tokens: Token[];
 }
 
 export interface UserOperation {

package/src/deployments.ts

@@ -1,22 +0,0 @@
-import { type Address } from "viem";
-
-export const DEPLOYMENTS: Record<number, {
-    entryPoint: Address;
-    factory: Address;
-    paymaster?: Address;
-    usdc: Address;
-}> = {
-    // Base Mainnet
-    8453: {
-        entryPoint: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
-        factory: "0xe2584152891E4769025807DEa0cD611F135aDC68",
-        paymaster: "0x1e13Eb16C565E3f3FDe49A011755e50410bb1F95",
-        usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
-    },
-    // Base Sepolia
-    84532: {
-        entryPoint: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
-        factory: "0x9406Cc6185a346906296840746125a0E44976454",
-        usdc: "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
-    }
-};