Merge pull request #4 from etherspot/ft-simple-7702-eg

minor fixes for types, added example for simple 7702 account

Author: nikhilkumar1612

.gitignore

@@ -1 +1,2 @@
 node_modules
+dist

bun.lockb

@@ -0,0 +1,97 @@
+# Free Bundler Usage Examples
+
+This guide provides example commands for running user operations (userops) using the Free Bundler client.
+
+## Prerequisites
+
+- Node.js >= 18.0.0 or Bun >= 1.0.0
+- A private key for the smart account
+- RPC URL for the target chain (optional, defaults to free bundler endpoints)
+
+## Command Line Arguments
+
+The example script accepts the following command line arguments:
+
+- `--chain-id` (required): Chain ID for the userop
+- `--account-type` (required): Type of smart account implementation
+- `--private-key` (required): Private key that controls the smart account
+- `--rpc-url` (optional): RPC URL for the chain
+- `--paymaster-url` (optional): Paymaster URL to sponsor user ops
+- `--paymaster-context` (optional): JSON string for paymaster context
+
+## Example Commands
+
+### 1. Basic UserOp on Ethereum Mainnet
+
+```bash
+bun run ./examples/index.ts \
+  --chain-id 1 \
+  --account-type simple7702 \
+  --private-key "0x..."
+```
+
+### 2. UserOp on Optimism with Custom RPC
+
+```bash
+bun run ./examples/index.ts \
+  --chain-id 10 \
+  --account-type simple7702 \
+  --private-key "0x..." \
+  --rpc-url "https://optimism-mainnet.infura.io/v3/YOUR_INFURA_KEY"
+```
+
+### 3. UserOp on Optimism with Paymaster
+
+```bash
+bun run ./examples/index.ts \
+  --chain-id 10 \
+  --account-type simple7702 \
+  --private-key "0x..." \
+  --paymaster-url "https://api.stackup.sh/v1/paymaster/YOUR_STACKUP_KEY" \
+  --paymaster-context '{"sponsor": true}'
+```
+
+## Supported Networks
+
+The following networks are supported by the free bundler:
+
+- **Ethereum Mainnet**: Chain ID `1`
+- **Optimism**: Chain ID `10`
+- **Arbitrum One**: Chain ID `42161`
+
+## Account Types
+
+Currently supported smart account implementations:
+
+- **simple7702**: EIP-7702 compatible smart account
+
+## What the Example Does
+
+The example script demonstrates:
+
+1. **Smart Account Creation**: Creates a Simple7702 smart account from a private key
+2. **Authorization Check**: Automatically handles EIP-7702 authorization if needed
+3. **UserOp Execution**: Sends a user operation that transfers 0.0000001 ETH to a test address
+4. **Paymaster Integration**: Optional paymaster support for sponsored transactions
+
+### Getting Help
+
+```bash
+bun run ./examples/index.ts --help
+```
+
+This will display all available options and their descriptions.
+
+## Development
+
+To run in development mode with auto-reload:
+
+```bash
+bun run dev
+```
+
+To build the project:
+
+```bash
+bun run build
+```

examples/USAGE.md

@@ -0,0 +1,84 @@
+import {
+    createPaymasterClient,
+    toSimple7702SmartAccount,
+    ToSimple7702SmartAccountReturnType
+} from "viem/account-abstraction";
+import { createFreeBundler } from "../../src/client.js"
+import { privateKeyToAccount } from "viem/accounts";
+import {
+    http,
+    parseUnits,
+    createClient,
+    publicActions,
+    walletActions,
+    SignAuthorizationReturnType,
+    Hex,
+    Chain
+} from "viem";
+import { FREE_BUNDLER_URLS } from "../../src/config.js";
+
+
+export default async (
+    {
+        chain,
+        paymasterContext,
+        paymasterUrl,
+        privateKey,
+        rpcUrl
+    }:
+    {
+        chain: Chain,
+        privateKey: Hex,
+        rpcUrl?: string,
+        paymasterUrl?: string,
+        paymasterContext?: string
+    }
+) => {
+    const owner = privateKeyToAccount(privateKey);
+
+    const client = createClient({
+        account: owner,
+        transport: http(rpcUrl || FREE_BUNDLER_URLS[chain.id]),
+        chain
+    }).extend(publicActions).extend(walletActions);
+
+    const smartAccount: ToSimple7702SmartAccountReturnType = await toSimple7702SmartAccount({
+        client,
+        owner,
+    });
+
+    console.log("wallet:: ", smartAccount.address);
+
+    const bundlerClient = createFreeBundler(
+        chain.id,
+        {account: smartAccount, chain}
+    );
+
+    // check sender's code to decide if eip7702Auth tuple is necessary for userOp.
+    const senderCode = await client.getCode({
+        address: smartAccount.address
+    });
+
+    let authorization: SignAuthorizationReturnType | undefined;
+    const { address: delegateAddress } = smartAccount.authorization;
+
+    if(senderCode !== `0xef0100${delegateAddress.toLowerCase().substring(2)}`) {
+        authorization = await client.signAuthorization(smartAccount.authorization)
+    }
+
+    const paymasterClient = paymasterUrl ? createPaymasterClient({
+        transport: http(paymasterUrl)
+    }) : undefined;
+
+    const userOpHash = await bundlerClient.sendUserOperation({
+        authorization,
+        calls: [
+            {to: "0x09FD4F6088f2025427AB1e89257A44747081Ed59", value: parseUnits('0.0000001', 18)}
+        ],
+        paymaster: paymasterClient,
+        paymasterContext: paymasterContext ? JSON.parse(paymasterContext) : undefined,
+    });
+
+    console.log("userOpHash:: ", userOpHash);
+    return userOpHash;
+}

examples/accounts/simple7702.ts

@@ -0,0 +1,34 @@
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+export const argv = await yargs(hideBin(process.argv))
+  .option('chain-id', {
+    description: 'chain id for the userop, supported networks - (ethereum(1), optimism(10), arbitrum(42161))',
+    type: 'number',
+    demandOption: true
+  })
+  .option('account-type', {
+    description: 'type of smart account implementation, available:\n1. simple7702',
+    type: 'string',
+    demandOption: true
+  })
+  .option('private-key', {
+    description: 'private key which controls the smart account',
+    type: 'string',
+    demandOption: true
+  })
+  .option('rpc-url', {
+    description: 'rpc url for the chain on which userop needs to execute',
+    type: 'string'
+  })
+  .option('paymaster-url', {
+    description: 'paymaster url to sponsor user ops',
+    type: 'string'
+  })
+  .option('paymaster-context', {
+    description: 'stringified json to be used as context for paymaster',
+    type: 'string'
+  })
+  .help()
+  .alias('help', 'h')
+  .argv;

examples/args.ts

@@ -0,0 +1,31 @@
+import {argv} from "./args.js";
+import { getChainById } from "./utils.js";
+import sendSimple7702UserOp from "./accounts/simple7702.js";
+import { Hex } from "viem";
+
+export const main = async () => {
+    const {
+        chainId,
+        rpcUrl,
+        accountType,
+        paymasterContext,
+        paymasterUrl,
+        privateKey
+    } = argv;
+
+    const chain = getChainById(chainId);
+
+    switch(accountType) {
+        case "simple7702":
+            return sendSimple7702UserOp({
+                chain,
+                privateKey: privateKey as Hex,
+                paymasterContext,
+                paymasterUrl,
+                rpcUrl
+            })
+        default:
+            throw new Error(`Unsupported account type: ${accountType}`);
+    }
+}
+main();

examples/index.ts

@@ -0,0 +1,10 @@
+import * as chains from "viem/chains"
+
+export const getChainById = (id: number): chains.Chain => {
+    for (const chain of Object.values(chains)) {
+        if ('id' in chain && chain.id === id) {
+            return chain;
+        }
+    }
+    throw new Error(`Chain with id ${id} not found`);
+}

examples/utils.ts

@@ -1,6 +1,7 @@
 {
   "name": "@etherspot/free-bundler",
-  "version": "1.0.0",
+  "version": "1.0.1-alpha.0",
+  "type": "module",
   "description": "Free bundler client for ERC-4337 account abstraction with preconfigured endpoints",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -67,11 +68,13 @@
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^6.0.0",
     "@typescript-eslint/parser": "^6.0.0",
     "eslint": "^8.0.0",
     "tsup": "^8.5.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "yargs": "^18.0.0"
   },
   "engines": {
     "node": ">=18.0.0",

package.json

@@ -1,6 +1,6 @@
 import type { Account, Chain, Transport } from 'viem'
 import { createClient, http } from 'viem'
-import { bundlerActions } from 'viem/account-abstraction'
+import { bundlerActions, SmartAccount } from 'viem/account-abstraction'
 
 import type { FreeBundlerClient, CreateFreeBundlerOptions } from './types'
 import { DEFAULT_TRANSPORT_OPTIONS, DEFAULT_CLIENT_OPTIONS } from './config.js'
@@ -17,32 +17,32 @@ import { getFreeBundlerUrl, validateChainId } from './utils.js'
  * ```typescript
  * import { createFreeBundler } from '@etherspot/free-bundler'
  * 
- * // Create bundler client for Ethereum Sepolia
+ * Create bundler client for Ethereum Sepolia
  * const bundlerClient = createFreeBundler(11155111)
  * 
- * // Create bundler client for Polygon with custom transport options
+ * Create bundler client for Polygon with custom transport options
  * const bundlerClient = createFreeBundler(137, {
  *   transport: {
  *     timeout: 10000,
  *     retryCount: 3
  *   }
  * })
  * 
- * // Use the bundler client
+ * Use the bundler client
  * const userOperation = await bundlerClient.sendUserOperation({
  *   userOperation: {
  *     sender: '0x...',
  *     nonce: 0n,
  *     callData: '0x...',
- *     // ... other fields
+ *     ... other fields
  *   },
  *   entryPoint: '0x...'
  * })
  * ```
  */
 export function createFreeBundler<
   chain extends Chain | undefined = undefined,
-  account extends Account | undefined = undefined,
+  account extends SmartAccount | undefined = undefined,
 >(
   chainId: number,
   options: CreateFreeBundlerOptions<chain, account> = {}
@@ -71,6 +71,5 @@ export function createFreeBundler<
   })
 
   // Extend with bundler actions
-  // @ts-ignore - bundlerActions type compatibility issue
   return client.extend(bundlerActions) as FreeBundlerClient<Transport, chain, account>
 }

src/client.ts

@@ -5,23 +5,23 @@ import type { BundlerConfig } from './types'
  */
 export const FREE_BUNDLER_URLS: Record<number, string> = {
   // Ethereum Mainnet
-  1: 'https://bundler.etherspot.io/1/',
+  1: 'https://bundler.etherspot.io/1',
 
   // Ethereum Sepolia
-  11155111: 'https://bundler.etherspot.io/11155111/',
+  11155111: 'https://bundler.etherspot.io/11155111',
 
 
   // Arbitrum One
-  42161: 'https://bundler.etherspot.io/42161/',
+  42161: 'https://bundler.etherspot.io/42161',
 
   // Arbitrum Sepolia
-  421614: 'https://bundler.etherspot.io/421614/',
+  421614: 'https://bundler.etherspot.io/421614',
 
   // Optimism Mainnet
-  10: 'https://bundler.etherspot.io/10/',
+  10: 'https://bundler.etherspot.io/10',
 
   // Optimism Sepolia
-  11155420: 'https://bundler.etherspot.io/11155420/',
+  11155420: 'https://bundler.etherspot.io/11155420',
 
 } as const