@aboutcircles/sdk-runner 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# @aboutcircles/sdk-runner
+
+Safe multisig wallet integration for executing blockchain operations with the Circles SDK.
+
+## Overview
+
+This package provides the `SafeContractRunner` implementation for executing transactions through Safe multisig wallets. It handles transaction batching, signing, and confirmation, making it easy to interact with Circles protocol using Safe wallets.
+
+## Installation
+
+```bash
+npm install @aboutcircles/sdk-runner
+```
+
+## Usage
+
+### SafeContractRunner
+
+The `SafeContractRunner` executes transactions through a Safe multisig wallet.
+
+```typescript
+import { createPublicClient, http } from 'viem';
+import { gnosis } from 'viem/chains';
+import { SafeContractRunner } from '@aboutcircles/sdk-runner';
+
+// Create a public client
+const publicClient = createPublicClient({
+  chain: gnosis,
+  transport: http('https://rpc.gnosischain.com'),
+});
+
+// Create the runner
+const runner = new SafeContractRunner(
+  publicClient,
+  '0x...', // private key of Safe signer
+  'https://rpc.gnosischain.com',
+  '0x...' // Safe address
+);
+
+// Initialize the runner
+await runner.init();
+
+// Send a single transaction
+const receipt = await runner.sendTransaction([{
+  to: '0x...',
+  data: '0x...',
+  value: 0n,
+}]);
+
+console.log('Transaction hash:', receipt.transactionHash);
+console.log('Status:', receipt.status);
+console.log('Gas used:', receipt.gasUsed);
+
+// Batch multiple transactions atomically
+const batchReceipt = await runner.sendTransaction([
+  { to: '0x...', data: '0x...', value: 0n },
+  { to: '0x...', data: '0x...', value: 0n },
+  { to: '0x...', data: '0x...', value: 0n },
+]);
+```
+
+## Features
+
+- **Transaction Confirmation**: Automatically waits for transactions to be mined
+- **Status Checking**: Throws errors if transactions revert
+- **Atomic Batching**: Execute multiple transactions in a single Safe transaction
+- **Full Receipt Data**: Returns complete viem TransactionReceipt with gas, logs, etc.
+
+## API
+
+### ContractRunner Interface
+
+```typescript
+interface ContractRunner {
+  address?: Address;
+  publicClient: PublicClient;
+
+  init(): Promise<void>;
+  estimateGas?(tx: TransactionRequest): Promise<bigint>;
+  call?(tx: TransactionRequest): Promise<string>;
+  resolveName?(name: string): Promise<string | null>;
+  sendTransaction?(txs: TransactionRequest[]): Promise<TransactionResponse>;
+  sendBatchTransaction?(): BatchRun;
+}
+```
+
+### SafeContractRunner
+
+```typescript
+class SafeContractRunner implements ContractRunner {
+  constructor(
+    publicClient: PublicClient,
+    privateKey: Hex,
+    rpcUrl: string,
+    safeAddress?: Address
+  );
+
+  init(safeAddress?: Address): Promise<void>;
+  sendTransaction(txs: TransactionRequest[]): Promise<TransactionResponse>;
+  sendBatchTransaction(): SafeBatchRun;
+}
+```
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Runner Package Error Types
+ */
+import { CirclesError } from '@aboutcircles/sdk-utils';
+/**
+ * Runner-specific error sources
+ */
+export type RunnerErrorSource = 'RUNNER' | 'RUNNER_INITIALIZATION' | 'TRANSACTION_EXECUTION' | 'WALLET' | 'SAFE';
+/**
+ * Runner and transaction execution errors
+ */
+export declare class RunnerError extends CirclesError<RunnerErrorSource> {
+    constructor(message: string, options?: {
+        code?: string | number;
+        source?: RunnerErrorSource;
+        cause?: unknown;
+        context?: Record<string, any>;
+    });
+    /**
+     * Create error for initialization failures
+     */
+    static initializationFailed(runnerType: string, cause?: unknown): RunnerError;
+    /**
+     * Create error for transaction execution failures
+     */
+    static executionFailed(reason: string, cause?: unknown): RunnerError;
+    /**
+     * Create error for wallet-related issues
+     */
+    static walletError(message: string, cause?: unknown): RunnerError;
+    /**
+     * Create error for Safe-specific issues
+     */
+    static safeError(message: string, safeAddress: string, cause?: unknown): RunnerError;
+    /**
+     * Create error for missing signer
+     */
+    static missingSigner(): RunnerError;
+    /**
+     * Create error for transaction timeout
+     */
+    static timeout(txHash: string, timeout: number): RunnerError;
+    /**
+     * Create error for reverted transactions
+     */
+    static transactionReverted(txHash: string, blockNumber: bigint, gasUsed: bigint, cause?: unknown): RunnerError;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,uBAAuB,GACvB,uBAAuB,GACvB,QAAQ,GACR,MAAM,CAAC;AAEX;;GAEG;AACH,qBAAa,WAAY,SAAQ,YAAY,CAAC,iBAAiB,CAAC;gBAE5D,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,iBAAiB,CAAC;QAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAC/B;IAKH;;OAEG;IACH,MAAM,CAAC,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW;IAS7E;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW;IASpE;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW;IAQjE;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW;IASpF;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,WAAW;IAOnC;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW;IAQ5D;;OAEG;IACH,MAAM,CAAC,mBAAmB,CACxB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO,GACd,WAAW;CAYf"}

package/dist/errors.js

@@ -0,0 +1,89 @@
+/**
+ * Runner Package Error Types
+ */
+import { CirclesError } from '@aboutcircles/sdk-utils';
+/**
+ * Runner and transaction execution errors
+ */
+export class RunnerError extends CirclesError {
+    constructor(message, options) {
+        super('RunnerError', message, { ...options, source: options?.source ?? 'RUNNER' });
+    }
+    /**
+     * Create error for initialization failures
+     */
+    static initializationFailed(runnerType, cause) {
+        return new RunnerError(`Failed to initialize ${runnerType}`, {
+            code: 'RUNNER_INIT_FAILED',
+            source: 'RUNNER_INITIALIZATION',
+            cause,
+            context: { runnerType },
+        });
+    }
+    /**
+     * Create error for transaction execution failures
+     */
+    static executionFailed(reason, cause) {
+        return new RunnerError(`Transaction execution failed: ${reason}`, {
+            code: 'RUNNER_EXECUTION_FAILED',
+            source: 'TRANSACTION_EXECUTION',
+            cause,
+            context: { reason },
+        });
+    }
+    /**
+     * Create error for wallet-related issues
+     */
+    static walletError(message, cause) {
+        return new RunnerError(message, {
+            code: 'RUNNER_WALLET_ERROR',
+            source: 'WALLET',
+            cause,
+        });
+    }
+    /**
+     * Create error for Safe-specific issues
+     */
+    static safeError(message, safeAddress, cause) {
+        return new RunnerError(message, {
+            code: 'RUNNER_SAFE_ERROR',
+            source: 'SAFE',
+            cause,
+            context: { safeAddress },
+        });
+    }
+    /**
+     * Create error for missing signer
+     */
+    static missingSigner() {
+        return new RunnerError('Signer is required for this operation', {
+            code: 'RUNNER_MISSING_SIGNER',
+            source: 'WALLET',
+        });
+    }
+    /**
+     * Create error for transaction timeout
+     */
+    static timeout(txHash, timeout) {
+        return new RunnerError('Transaction timed out', {
+            code: 'RUNNER_TX_TIMEOUT',
+            source: 'TRANSACTION_EXECUTION',
+            context: { txHash, timeout },
+        });
+    }
+    /**
+     * Create error for reverted transactions
+     */
+    static transactionReverted(txHash, blockNumber, gasUsed, cause) {
+        return new RunnerError('Transaction reverted', {
+            code: 'RUNNER_TX_REVERTED',
+            source: 'TRANSACTION_EXECUTION',
+            cause,
+            context: {
+                transactionHash: txHash,
+                blockNumber: blockNumber.toString(),
+                gasUsed: gasUsed.toString(),
+            },
+        });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @aboutcircles/sdk-runner
+ *
+ * Contract runner implementations for executing blockchain operations.
+ * Provides Safe multisig wallet integration for transaction execution.
+ */
+export type { ContractRunner, BatchRun } from './runner';
+export { SafeContractRunner, SafeBatchRun } from './safe-runner';
+export { SafeBrowserRunner, SafeBrowserBatchRun } from './safe-browser-runner';
+export { RunnerError } from './errors';
+export type { RunnerErrorSource } from './errors';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGzD,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGjE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAG/E,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC"}