Ethers Adapter

This package provides Ethers-compatible contract runners for the Circles SDK. It enables interaction with smart contracts using Ethers v6 providers, wallets, and browser environments like MetaMask.

---

Installation

npm install @circles-sdk/adapter-ethers

---

Overview

This package implements the SdkContractRunner interface from @circles-sdk/adapter, making it usable with any part of the Circles SDK that expects a contract runner.

---

Supported Runners

1. PrivateKeyContractRunner

For backend/server usage with a private key and a JSON-RPC provider.

import { PrivateKeyContractRunner } from '@circles-sdk/adapter-ethers';
import { JsonRpcProvider } from 'ethers';

const provider = new JsonRpcProvider('https://rpc.gnosischain.com');
const runner = new PrivateKeyContractRunner(provider, '0xYOUR_PRIVATE_KEY');

await runner.init();
await runner.sendTransaction?.({
  to: '0xRecipientAddress',
  value: BigInt(0),
  data: '0x',
});

---

2. BrowserProviderContractRunner

For browser-based wallets such as MetaMask using window.ethereum.

import { BrowserProviderContractRunner } from '@circles-sdk/adapter-ethers';

const runner = new BrowserProviderContractRunner();
await runner.init();

await runner.sendTransaction?.({
  to: '0xRecipientAddress',
  value: BigInt(0),
  data: '0x',
});

---

3. SdkContractRunnerWrapper

Wraps any SdkContractRunner to be used with Ethers contract factory or TypeChain-generated wrappers.

import { SdkContractRunnerWrapper } from '@circles-sdk/adapter-ethers';

const wrapper = new SdkContractRunnerWrapper(provider, address, sdkRunner);
await wrapper.sendTransaction?.({
  to: '0xRecipient',
  value: BigInt(0),
  data: '0x...',
});

---

Batch Execution

PrivateKeyBatchRun and BrowserProviderBatchRun

All runners support batching multiple transactions and executing them in sequence.

const batch = runner.sendBatchTransaction?.();
batch?.addTransaction({
  to: '0x...',
  value: BigInt(0),
  data: '0x...',
});
await batch?.run();