@aboutcircles/sdk-runner 0.1.0

package/dist/safe-runner.js

@@ -0,0 +1,237 @@
+import { createPublicClient, http } from 'viem';
+import { OperationType } from '@safe-global/safe-core-sdk-types';
+import { RunnerError } from './errors';
+// Use require for Safe to ensure compatibility with bun's CJS/ESM interop
+// Safe Protocol Kit v5 uses CommonJS exports, so we use require() for proper interop
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const SafeModule = require('@safe-global/protocol-kit');
+const Safe = SafeModule.default || SafeModule;
+/**
+ * Batch transaction runner for Safe
+ * Allows multiple transactions to be batched and executed together
+ */
+export class SafeBatchRun {
+    safe;
+    publicClient;
+    transactions = [];
+    constructor(safe, publicClient) {
+        this.safe = safe;
+        this.publicClient = publicClient;
+    }
+    /**
+     * Add a transaction to the batch
+     */
+    addTransaction(tx) {
+        this.transactions.push(tx);
+    }
+    /**
+     * Get the Safe transaction data for all batched transactions
+     */
+    async getSafeTransaction() {
+        const metaTransactions = this.transactions.map((tx) => ({
+            operation: OperationType.Call,
+            to: tx.to,
+            value: (tx.value?.toString() ?? '0'),
+            data: tx.data ?? '0x',
+        }));
+        const safeTransaction = await this.safe.createTransaction({
+            transactions: metaTransactions,
+        });
+        return safeTransaction;
+    }
+    /**
+     * Execute all batched transactions and wait for confirmation
+     * @throws {RunnerError} If transaction reverts or execution fails
+     */
+    async run() {
+        const safeTransaction = await this.getSafeTransaction();
+        const txResult = await this.safe.executeTransaction(safeTransaction);
+        if (!txResult.hash) {
+            throw RunnerError.executionFailed('No transaction hash returned from Safe execution');
+        }
+        // Wait for transaction receipt
+        const receipt = await this.publicClient.waitForTransactionReceipt({
+            hash: txResult.hash,
+        });
+        // Check transaction status and throw if reverted
+        if (receipt.status === 'reverted') {
+            throw RunnerError.transactionReverted(receipt.transactionHash, receipt.blockNumber, receipt.gasUsed);
+        }
+        // Return viem's TransactionReceipt directly
+        return receipt;
+    }
+}
+/**
+ * Safe contract runner implementation using Safe Protocol Kit
+ * Executes transactions through a Safe multisig wallet
+ */
+export class SafeContractRunner {
+    address;
+    publicClient;
+    privateKey;
+    rpcUrl;
+    safeAddress;
+    safe;
+    /**
+     * Creates a new SafeContractRunner
+     * @param publicClient - The viem public client for reading blockchain state
+     * @param privateKey - The private key of one of the Safe signers
+     * @param rpcUrl - The RPC URL to use for Safe operations
+     * @param safeAddress - The address of the Safe wallet (optional, can be set in init)
+     */
+    // @todo rpc might be taken from public client
+    constructor(publicClient, privateKey, rpcUrl, safeAddress) {
+        this.publicClient = publicClient;
+        this.privateKey = privateKey;
+        this.rpcUrl = rpcUrl;
+        this.safeAddress = safeAddress;
+    }
+    /**
+     * Create and initialize a SafeContractRunner in one step
+     * @param rpcUrl - The RPC URL to connect to
+     * @param privateKey - The private key of one of the Safe signers
+     * @param safeAddress - The address of the Safe wallet
+     * @param chain - The viem chain configuration (e.g., gnosis from 'viem/chains')
+     * @returns An initialized SafeContractRunner instance
+     *
+     * @example
+     * ```typescript
+     * import { gnosis } from 'viem/chains';
+     * import { SafeContractRunner } from '@aboutcircles/sdk-runner';
+     *
+     * const runner = await SafeContractRunner.create(
+     *   'https://rpc.gnosischain.com',
+     *   '0xYourPrivateKey...',
+     *   '0xYourSafeAddress...',
+     *   gnosis
+     * );
+     * ```
+     */
+    static async create(rpcUrl, privateKey, safeAddress, chain) {
+        const publicClient = createPublicClient({
+            chain,
+            transport: http(rpcUrl),
+        });
+        const runner = new SafeContractRunner(publicClient, privateKey, rpcUrl, safeAddress);
+        await runner.init();
+        return runner;
+    }
+    /**
+     * Initialize the runner with a Safe address
+     * @param safeAddress - The address of the Safe wallet (optional if provided in constructor)
+     */
+    async init(safeAddress) {
+        // Use provided address or the one from constructor
+        const targetSafeAddress = safeAddress || this.safeAddress;
+        if (!targetSafeAddress) {
+            throw new Error('Safe address must be provided either in constructor or init()');
+        }
+        this.safeAddress = targetSafeAddress;
+        this.address = targetSafeAddress;
+        // Initialize Safe Protocol Kit
+        this.safe = await Safe.init({
+            provider: this.rpcUrl,
+            signer: this.privateKey,
+            safeAddress: targetSafeAddress,
+        });
+    }
+    /**
+     * Ensures the Safe is initialized
+     */
+    ensureSafe() {
+        if (!this.safe) {
+            throw new Error('SafeContractRunner not initialized. Call init() first.');
+        }
+        return this.safe;
+    }
+    /**
+     * 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 the Safe and wait for confirmation
+     * All transactions are batched and executed atomically
+     *
+     * @throws {RunnerError} If transaction reverts or execution fails
+     */
+    sendTransaction = async (txs) => {
+        const safe = this.ensureSafe();
+        if (txs.length === 0) {
+            throw RunnerError.executionFailed('No transactions provided');
+        }
+        const metaTransactions = txs.map((tx) => ({
+            operation: OperationType.Call,
+            to: tx.to,
+            value: (tx.value?.toString() ?? '0'),
+            data: tx.data ?? '0x',
+        }));
+        // Create Safe transaction with all transactions
+        const safeTransaction = await safe.createTransaction({
+            transactions: metaTransactions,
+        });
+        // Execute the batched transaction
+        const txResult = await safe.executeTransaction(safeTransaction);
+        if (!txResult.hash) {
+            throw RunnerError.executionFailed('No transaction hash returned from Safe execution');
+        }
+        // Wait for transaction receipt
+        const receipt = await this.publicClient.waitForTransactionReceipt({
+            hash: txResult.hash,
+        });
+        // Check transaction status and throw if reverted
+        if (receipt.status === 'reverted') {
+            throw RunnerError.transactionReverted(receipt.transactionHash, receipt.blockNumber, receipt.gasUsed);
+        }
+        // Return viem's TransactionReceipt directly
+        return receipt;
+    };
+    /**
+     * Create a batch transaction runner
+     * @returns A SafeBatchRun instance for batching multiple transactions
+     */
+    sendBatchTransaction = () => {
+        const safe = this.ensureSafe();
+        return new SafeBatchRun(safe, this.publicClient);
+    };
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@aboutcircles/sdk-runner",
+  "version": "0.1.0",
+  "description": "Contract runner implementations for Circles SDK",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist  --format esm && tsc --emitDeclarationOnly",
+    "dev": "tsc --build --watch",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "circles",
+    "runner",
+    "ethereum",
+    "viem"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@aboutcircles/sdk-types": "*",
+    "@safe-global/protocol-kit": "^5.1.1",
+    "@safe-global/safe-core-sdk-types": "^5.1.0",
+    "viem": "^2.38.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.4"
+  }
+}