@aboutcircles/sdk-runner 0.1.24 → 0.1.25

package/dist/safe-4337-runner.d.ts

@@ -0,0 +1,183 @@
+import type { Address, TransactionRequest } from '@aboutcircles/sdk-types';
+import type { ContractRunner, BatchRun } from './runner';
+import type { PublicClient, TransactionReceipt, Chain } from 'viem';
+import type { EIP1193Provider } from 'viem';
+/**
+ * Configuration options for Safe 4337 paymaster
+ */
+export interface Safe4337PaymasterOptions {
+    /**
+     * Whether transactions should be sponsored (gasless)
+     */
+    isSponsored: boolean;
+    /**
+     * Pimlico paymaster URL for sponsored transactions
+     * @example 'https://api.pimlico.io/v2/100/rpc?apikey=YOUR_API_KEY'
+     */
+    paymasterUrl: string;
+}
+/**
+ * Configuration options for Safe 4337 custom contracts
+ */
+export interface Safe4337CustomContracts {
+    /**
+     * Address of the Safe 4337 module contract
+     * @example '0x75cf11467937ce3F2f357CE24ffc3DBF8fD5c226'
+     */
+    safe4337ModuleAddress: string;
+    /**
+     * Optional entry point address (defaults to standard ERC-4337 entry point)
+     */
+    entryPointAddress?: string;
+}
+/**
+ * Safe 4337 browser contract runner implementation using Safe4337Pack from relay-kit
+ * Executes account abstraction transactions with optional paymaster sponsorship
+ *
+ * This runner enables gasless transactions through ERC-4337 account abstraction
+ * and Pimlico bundler/paymaster infrastructure.
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient, http } from 'viem';
+ * import { gnosis } from 'viem/chains';
+ * import { Safe4337Runner } from '@aboutcircles/sdk-runner';
+ *
+ * const publicClient = createPublicClient({
+ *   chain: gnosis,
+ *   transport: http('https://rpc.gnosischain.com')
+ * });
+ *
+ * const runner = new Safe4337Runner(
+ *   publicClient,
+ *   window.ethereum,
+ *   '0xYourSafeAddress...',
+ *   'https://api.pimlico.io/v2/100/rpc?apikey=YOUR_API_KEY',
+ *   {
+ *     isSponsored: true,
+ *     paymasterUrl: 'https://api.pimlico.io/v2/100/rpc?apikey=YOUR_API_KEY'
+ *   },
+ *   {
+ *     safe4337ModuleAddress: '0x75cf11467937ce3F2f357CE24ffc3DBF8fD5c226'
+ *   }
+ * );
+ *
+ * await runner.init();
+ * ```
+ */
+export declare class Safe4337Runner implements ContractRunner {
+    address?: Address;
+    publicClient: PublicClient;
+    private eip1193Provider;
+    private safeAddress?;
+    private bundlerUrl;
+    private paymasterOptions?;
+    private customContracts?;
+    private safe4337?;
+    private safeModulesVersion;
+    /**
+     * Creates a new Safe4337Runner
+     * @param publicClient - The viem public client for reading blockchain state
+     * @param eip1193Provider - The EIP-1193 provider from the browser (e.g., window.ethereum)
+     * @param safeAddress - The address of the Safe wallet (optional, can be set in init)
+     * @param bundlerUrl - Pimlico bundler URL for ERC-4337 transactions
+     * @param paymasterOptions - Optional paymaster configuration for sponsored transactions
+     * @param customContracts - Optional custom contract addresses
+     * @param safeModulesVersion - Version of Safe modules (default: '0.3.0')
+     */
+    constructor(publicClient: PublicClient, eip1193Provider: EIP1193Provider, safeAddress: Address | undefined, bundlerUrl: string, paymasterOptions?: Safe4337PaymasterOptions, customContracts?: Safe4337CustomContracts, safeModulesVersion?: string);
+    /**
+     * Create and initialize a Safe4337Runner in one step
+     * @param rpcUrl - The RPC URL to connect to
+     * @param eip1193Provider - The EIP-1193 provider from the browser (e.g., window.ethereum)
+     * @param safeAddress - The address of the Safe wallet
+     * @param chain - The viem chain configuration (e.g., gnosis from 'viem/chains')
+     * @param bundlerUrl - Pimlico bundler URL for ERC-4337 transactions
+     * @param paymasterOptions - Optional paymaster configuration for sponsored transactions
+     * @param customContracts - Optional custom contract addresses
+     * @param safeModulesVersion - Version of Safe modules (default: '0.3.0')
+     * @returns An initialized Safe4337Runner instance
+     *
+     * @example
+     * ```typescript
+     * import { gnosis } from 'viem/chains';
+     * import { Safe4337Runner } from '@aboutcircles/sdk-runner';
+     *
+     * const runner = await Safe4337Runner.create(
+     *   'https://rpc.gnosischain.com',
+     *   window.ethereum,
+     *   '0xYourSafeAddress...',
+     *   gnosis,
+     *   'https://api.pimlico.io/v2/100/rpc?apikey=YOUR_API_KEY',
+     *   {
+     *     isSponsored: true,
+     *     paymasterUrl: 'https://api.pimlico.io/v2/100/rpc?apikey=YOUR_API_KEY'
+     *   },
+     *   {
+     *     safe4337ModuleAddress: '0x75cf11467937ce3F2f357CE24ffc3DBF8fD5c226'
+     *   }
+     * );
+     * ```
+     */
+    static create(rpcUrl: string, eip1193Provider: EIP1193Provider, safeAddress: Address, chain: Chain, bundlerUrl: string, paymasterOptions?: Safe4337PaymasterOptions, customContracts?: Safe4337CustomContracts, safeModulesVersion?: string): Promise<Safe4337Runner>;
+    /**
+     * Initialize the runner with a Safe address
+     * Sets up the Safe4337Pack with bundler and optional paymaster
+     * @param safeAddress - The address of the Safe wallet (optional if provided in constructor)
+     * @throws {RunnerError} If no Safe address is provided or initialization fails
+     */
+    init(safeAddress?: Address): Promise<void>;
+    /**
+     * Ensures the Safe4337Pack is initialized
+     * @private
+     */
+    private ensureSafe4337;
+    /**
+     * Estimate gas for a transaction
+     */
+    estimateGas: (tx: TransactionRequest) => Promise<bigint>;
+    /**
+     * Call a contract (read-only operation)
+     */
+    call: (tx: TransactionRequest) => Promise<string>;
+    /**
+     * Resolve an ENS name to an address
+     */
+    resolveName: (name: string) => Promise<string | null>;
+    /**
+     * Send one or more transactions through Safe 4337 and wait for confirmation
+     * All transactions are batched and executed atomically as a UserOperation
+     *
+     * The transaction will be sponsored if paymaster options were configured
+     *
+     * @throws {RunnerError} If transaction reverts or execution fails
+     */
+    sendTransaction: (txs: TransactionRequest[]) => Promise<TransactionReceipt>;
+    /**
+     * Create a batch transaction runner
+     * @returns A Safe4337BatchRun instance for batching multiple transactions
+     */
+    sendBatchTransaction: () => Safe4337BatchRun;
+}
+/**
+ * Batch transaction runner for Safe 4337 operations
+ * Allows multiple transactions to be batched and executed together as a UserOperation
+ */
+export declare class Safe4337BatchRun implements BatchRun {
+    private readonly safe4337;
+    private readonly publicClient;
+    private readonly transactions;
+    constructor(safe4337: any, publicClient: PublicClient);
+    /**
+     * Add a transaction to the batch
+     */
+    addTransaction(tx: TransactionRequest): void;
+    /**
+     * Execute all batched transactions as a sponsored UserOperation
+     * Waits for the UserOperation to be included and confirmed on-chain
+     *
+     * @throws {RunnerError} If transaction reverts or execution fails
+     */
+    run(): Promise<TransactionReceipt>;
+}
+//# sourceMappingURL=safe-4337-runner.d.ts.map

package/dist/safe-4337-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-4337-runner.d.ts","sourceRoot":"","sources":["../src/safe-4337-runner.ts"],"names":[],"mappings":"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"}

package/dist/safe-4337-runner.js

@@ -0,0 +1,378 @@
+import { createPublicClient, http } from 'viem';
+import { RunnerError } from './errors';
+// Use require for Safe to ensure compatibility with bun's CJS/ESM interop
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const Safe4337PackModule = require('@safe-global/relay-kit');
+const Safe4337Pack = Safe4337PackModule.Safe4337Pack || Safe4337PackModule.default || Safe4337PackModule;
+/**
+ * Safe 4337 browser contract runner implementation using Safe4337Pack from relay-kit
+ * Executes account abstraction transactions with optional paymaster sponsorship
+ *
+ * This runner enables gasless transactions through ERC-4337 account abstraction
+ * and Pimlico bundler/paymaster infrastructure.
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient, http } from 'viem';
+ * import { gnosis } from 'viem/chains';
+ * import { Safe4337Runner } from '@aboutcircles/sdk-runner';
+ *
+ * const publicClient = createPublicClient({
+ *   chain: gnosis,
+ *   transport: http('https://rpc.gnosischain.com')
+ * });
+ *
+ * const runner = new Safe4337Runner(
+ *   publicClient,
+ *   window.ethereum,
+ *   '0xYourSafeAddress...',
+ *   'https://api.pimlico.io/v2/100/rpc?apikey=YOUR_API_KEY',
+ *   {
+ *     isSponsored: true,
+ *     paymasterUrl: 'https://api.pimlico.io/v2/100/rpc?apikey=YOUR_API_KEY'
+ *   },
+ *   {
+ *     safe4337ModuleAddress: '0x75cf11467937ce3F2f357CE24ffc3DBF8fD5c226'
+ *   }
+ * );
+ *
+ * await runner.init();
+ * ```
+ */
+export class Safe4337Runner {
+    address;
+    publicClient;
+    eip1193Provider;
+    safeAddress;
+    bundlerUrl;
+    paymasterOptions;
+    customContracts;
+    safe4337;
+    safeModulesVersion;
+    /**
+     * Creates a new Safe4337Runner
+     * @param publicClient - The viem public client for reading blockchain state
+     * @param eip1193Provider - The EIP-1193 provider from the browser (e.g., window.ethereum)
+     * @param safeAddress - The address of the Safe wallet (optional, can be set in init)
+     * @param bundlerUrl - Pimlico bundler URL for ERC-4337 transactions
+     * @param paymasterOptions - Optional paymaster configuration for sponsored transactions
+     * @param customContracts - Optional custom contract addresses
+     * @param safeModulesVersion - Version of Safe modules (default: '0.3.0')
+     */
+    constructor(publicClient, eip1193Provider, safeAddress, bundlerUrl, paymasterOptions, customContracts, safeModulesVersion = '0.3.0') {
+        this.publicClient = publicClient;
+        this.eip1193Provider = eip1193Provider;
+        this.safeAddress = safeAddress;
+        this.bundlerUrl = bundlerUrl;
+        this.paymasterOptions = paymasterOptions;
+        this.customContracts = customContracts;
+        this.safeModulesVersion = safeModulesVersion;
+    }
+    /**
+     * Create and initialize a Safe4337Runner in one step
+     * @param rpcUrl - The RPC URL to connect to
+     * @param eip1193Provider - The EIP-1193 provider from the browser (e.g., window.ethereum)
+     * @param safeAddress - The address of the Safe wallet
+     * @param chain - The viem chain configuration (e.g., gnosis from 'viem/chains')
+     * @param bundlerUrl - Pimlico bundler URL for ERC-4337 transactions
+     * @param paymasterOptions - Optional paymaster configuration for sponsored transactions
+     * @param customContracts - Optional custom contract addresses
+     * @param safeModulesVersion - Version of Safe modules (default: '0.3.0')
+     * @returns An initialized Safe4337Runner instance
+     *
+     * @example
+     * ```typescript
+     * import { gnosis } from 'viem/chains';
+     * import { Safe4337Runner } from '@aboutcircles/sdk-runner';
+     *
+     * const runner = await Safe4337Runner.create(
+     *   'https://rpc.gnosischain.com',
+     *   window.ethereum,
+     *   '0xYourSafeAddress...',
+     *   gnosis,
+     *   'https://api.pimlico.io/v2/100/rpc?apikey=YOUR_API_KEY',
+     *   {
+     *     isSponsored: true,
+     *     paymasterUrl: 'https://api.pimlico.io/v2/100/rpc?apikey=YOUR_API_KEY'
+     *   },
+     *   {
+     *     safe4337ModuleAddress: '0x75cf11467937ce3F2f357CE24ffc3DBF8fD5c226'
+     *   }
+     * );
+     * ```
+     */
+    static async create(rpcUrl, eip1193Provider, safeAddress, chain, bundlerUrl, paymasterOptions, customContracts, safeModulesVersion = '0.3.0') {
+        const publicClient = createPublicClient({
+            chain,
+            transport: http(rpcUrl),
+        });
+        const runner = new Safe4337Runner(publicClient, eip1193Provider, safeAddress, bundlerUrl, paymasterOptions, customContracts, safeModulesVersion);
+        await runner.init();
+        return runner;
+    }
+    /**
+     * Initialize the runner with a Safe address
+     * Sets up the Safe4337Pack with bundler and optional paymaster
+     * @param safeAddress - The address of the Safe wallet (optional if provided in constructor)
+     * @throws {RunnerError} If no Safe address is provided or initialization fails
+     */
+    async init(safeAddress) {
+        // Use provided address or the one from constructor
+        const targetSafeAddress = safeAddress || this.safeAddress;
+        if (!targetSafeAddress) {
+            throw RunnerError.initializationFailed('Safe4337Runner', new Error('Safe address must be provided either in constructor or init()'));
+        }
+        if (!this.eip1193Provider) {
+            throw RunnerError.initializationFailed('Safe4337Runner', new Error('No EIP-1193 provider available. Make sure you are in a browser environment with a Web3 wallet extension.'));
+        }
+        try {
+            // Get the current signer address from the provider
+            const accounts = await this.eip1193Provider.request({
+                method: 'eth_requestAccounts'
+            });
+            const signerAddress = accounts[0];
+            if (!signerAddress) {
+                throw RunnerError.missingSigner();
+            }
+            this.safeAddress = targetSafeAddress;
+            this.address = targetSafeAddress;
+            // Build initialization options
+            const initOptions = {
+                provider: this.eip1193Provider,
+                signer: signerAddress,
+                safeModulesVersion: this.safeModulesVersion,
+                bundlerUrl: this.bundlerUrl,
+                options: {
+                    safeAddress: targetSafeAddress,
+                },
+            };
+            // Add custom contracts if provided
+            if (this.customContracts) {
+                initOptions.customContracts = this.customContracts;
+            }
+            // Add paymaster options if provided
+            if (this.paymasterOptions) {
+                initOptions.paymasterOptions = this.paymasterOptions;
+            }
+            // Initialize Safe4337Pack
+            this.safe4337 = await Safe4337Pack.init(initOptions);
+        }
+        catch (error) {
+            throw RunnerError.initializationFailed('Safe4337Runner', error);
+        }
+    }
+    /**
+     * Ensures the Safe4337Pack is initialized
+     * @private
+     */
+    ensureSafe4337() {
+        if (!this.safe4337) {
+            throw RunnerError.initializationFailed('Safe4337Runner', new Error('Safe4337Runner not initialized. Call init() first.'));
+        }
+        return this.safe4337;
+    }
+    /**
+     * Estimate gas for a transaction
+     */
+    estimateGas = async (tx) => {
+        const estimate = await this.publicClient.estimateGas({
+            // @ts-expect-error - Address type is compatible with viem's 0x${string}
+            account: this.address,
+            // @ts-expect-error - Address type is compatible with viem's 0x${string}
+            to: tx.to,
+            data: tx.data,
+            value: tx.value,
+        });
+        return estimate;
+    };
+    /**
+     * Call a contract (read-only operation)
+     */
+    call = async (tx) => {
+        const result = await this.publicClient.call({
+            // @ts-expect-error - Address type is compatible with viem's 0x${string}
+            account: tx.from || this.address,
+            // @ts-expect-error - Address type is compatible with viem's 0x${string}
+            to: tx.to,
+            data: tx.data,
+            value: tx.value,
+            gas: tx.gas,
+            gasPrice: tx.gasPrice,
+        });
+        return result.data || '0x';
+    };
+    /**
+     * Resolve an ENS name to an address
+     */
+    resolveName = async (name) => {
+        try {
+            const address = await this.publicClient.getEnsAddress({
+                name,
+            });
+            return address;
+        }
+        catch (error) {
+            // ENS resolution failed or not supported
+            return null;
+        }
+    };
+    /**
+     * Send one or more transactions through Safe 4337 and wait for confirmation
+     * All transactions are batched and executed atomically as a UserOperation
+     *
+     * The transaction will be sponsored if paymaster options were configured
+     *
+     * @throws {RunnerError} If transaction reverts or execution fails
+     */
+    sendTransaction = async (txs) => {
+        const safe4337 = this.ensureSafe4337();
+        if (txs.length === 0) {
+            throw RunnerError.executionFailed('No transactions provided');
+        }
+        try {
+            // Convert to Safe4337 transaction format
+            const transactions = txs.map((tx) => ({
+                to: tx.to,
+                data: tx.data ?? '0x',
+                value: (tx.value?.toString() ?? '0'),
+            }));
+            // Create the SafeOperation with all the transactions
+            const safeOperation = await safe4337.createTransaction({
+                transactions,
+            });
+            // Sign the SafeOperation
+            const signedSafeOperation = await safe4337.signSafeOperation(safeOperation);
+            // Execute and submit to bundler
+            const userOperationHash = await safe4337.executeTransaction({
+                executable: signedSafeOperation,
+            });
+            if (!userOperationHash) {
+                throw RunnerError.executionFailed('No UserOperation hash returned from Safe 4337 execution');
+            }
+            // Poll for the user operation receipt
+            let userOperationReceipt = null;
+            const maxAttempts = 60; // 2 minutes max wait (60 * 2 seconds)
+            let attempts = 0;
+            while (!userOperationReceipt && attempts < maxAttempts) {
+                // Wait 2 seconds before checking the status again
+                await new Promise((resolve) => setTimeout(resolve, 2000));
+                userOperationReceipt = await safe4337.getUserOperationReceipt(userOperationHash);
+                attempts++;
+            }
+            if (!userOperationReceipt) {
+                throw RunnerError.timeout(userOperationHash, maxAttempts * 2000);
+            }
+            // Extract transaction hash from UserOperation receipt
+            const txHash = userOperationReceipt.receipt?.transactionHash;
+            if (!txHash) {
+                throw RunnerError.executionFailed('No transaction hash in UserOperation receipt');
+            }
+            // Get the full transaction receipt
+            const receipt = await this.publicClient.waitForTransactionReceipt({
+                hash: txHash,
+            });
+            // Check transaction status and throw if reverted
+            if (receipt.status === 'reverted') {
+                throw RunnerError.transactionReverted(receipt.transactionHash, receipt.blockNumber, receipt.gasUsed);
+            }
+            return receipt;
+        }
+        catch (error) {
+            if (error instanceof RunnerError) {
+                throw error;
+            }
+            throw RunnerError.executionFailed('Safe 4337 transaction failed', error);
+        }
+    };
+    /**
+     * Create a batch transaction runner
+     * @returns A Safe4337BatchRun instance for batching multiple transactions
+     */
+    sendBatchTransaction = () => {
+        const safe4337 = this.ensureSafe4337();
+        return new Safe4337BatchRun(safe4337, this.publicClient);
+    };
+}
+/**
+ * Batch transaction runner for Safe 4337 operations
+ * Allows multiple transactions to be batched and executed together as a UserOperation
+ */
+export class Safe4337BatchRun {
+    safe4337;
+    publicClient;
+    transactions = [];
+    constructor(safe4337, publicClient) {
+        this.safe4337 = safe4337;
+        this.publicClient = publicClient;
+    }
+    /**
+     * Add a transaction to the batch
+     */
+    addTransaction(tx) {
+        this.transactions.push(tx);
+    }
+    /**
+     * Execute all batched transactions as a sponsored UserOperation
+     * Waits for the UserOperation to be included and confirmed on-chain
+     *
+     * @throws {RunnerError} If transaction reverts or execution fails
+     */
+    async run() {
+        if (this.transactions.length === 0) {
+            throw RunnerError.executionFailed('No transactions in batch');
+        }
+        try {
+            // Convert to Safe4337 transaction format
+            const transactions = this.transactions.map((tx) => ({
+                to: tx.to,
+                data: tx.data ?? '0x',
+                value: (tx.value?.toString() ?? '0'),
+            }));
+            // Create the SafeOperation with all the transactions
+            const safeOperation = await this.safe4337.createTransaction({
+                transactions,
+            });
+            // Sign the SafeOperation
+            const signedSafeOperation = await this.safe4337.signSafeOperation(safeOperation);
+            // Execute and submit to bundler
+            const userOperationHash = await this.safe4337.executeTransaction({
+                executable: signedSafeOperation,
+            });
+            if (!userOperationHash) {
+                throw RunnerError.executionFailed('No UserOperation hash returned from Safe 4337 execution');
+            }
+            // Poll for the user operation receipt
+            let userOperationReceipt = null;
+            const maxAttempts = 60; // 2 minutes max wait
+            let attempts = 0;
+            while (!userOperationReceipt && attempts < maxAttempts) {
+                await new Promise((resolve) => setTimeout(resolve, 2000));
+                userOperationReceipt = await this.safe4337.getUserOperationReceipt(userOperationHash);
+                attempts++;
+            }
+            if (!userOperationReceipt) {
+                throw RunnerError.timeout(userOperationHash, maxAttempts * 2000);
+            }
+            // Extract transaction hash from UserOperation receipt
+            const txHash = userOperationReceipt.receipt?.transactionHash;
+            if (!txHash) {
+                throw RunnerError.executionFailed('No transaction hash in UserOperation receipt');
+            }
+            // Get the full transaction receipt
+            const receipt = await this.publicClient.waitForTransactionReceipt({
+                hash: txHash,
+            });
+            // Check transaction status and throw if reverted
+            if (receipt.status === 'reverted') {
+                throw RunnerError.transactionReverted(receipt.transactionHash, receipt.blockNumber, receipt.gasUsed);
+            }
+            return receipt;
+        }
+        catch (error) {
+            if (error instanceof RunnerError) {
+                throw error;
+            }
+            throw RunnerError.executionFailed('Safe 4337 batch transaction failed', error);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aboutcircles/sdk-runner",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "Contract runner implementations for Circles SDK",
   "type": "module",
   "main": "./dist/index.js",