@circle-fin/adapter-ethers-v6 0.0.2-alpha.6 → 1.0.0

package/README.md

@@ -8,31 +8,44 @@
 
 **Type-safe EVM blockchain adapter powered by Ethers v6**
 
-_Seamlessly interact with 12+ EVM networks using a single, strongly-typed interface_
+_Seamlessly interact with 16+ EVM networks using a single, strongly-typed interface_
 
 </div>
 
 ## Table of Contents
 
-- [Ethers v6 Adapter](#ethers-v6-adapter)
-  - [Overview](#overview)
-    - [Why Ethers v6 Adapter?](#why-ethers-v6-adapter)
-  - [Installation](#installation)
-  - [Quick Start](#quick-start)
-    - [🚀 Easy Setup with Factory Methods (Recommended)](#-easy-setup-with-factory-methods-recommended)
-    - [🏭 Production Considerations](#-production-considerations)
-  - [Usage Examples](#usage-examples)
-    - [Basic Usage with Factory Methods](#basic-usage-with-factory-methods)
-    - [Manual Setup with Ethers Clients](#manual-setup-with-ethers-clients)
-    - [Multi-Chain Setup](#multi-chain-setup)
-    - [Methods](#methods)
-  - [Development](#development)
-  - [Contributing](#contributing)
-  - [License](#license)
+- [Overview](#overview)
+  - [Why Ethers v6 Adapter?](#why-ethers-v6-adapter)
+  - [When to Use This Adapter](#when-to-use-this-adapter)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [Zero-Config Setup (Recommended)](#zero-config-setup-recommended)
+  - [Production Setup](#production-setup)
+  - [Browser Wallet Setup](#browser-wallet-setup)
+- [OperationContext Pattern](#operationcontext-pattern)
+  - [Why OperationContext?](#why-operationcontext)
+  - [Basic Usage](#basic-usage)
+  - [Multi-Chain Operations](#multi-chain-operations)
+- [Address Context Guide](#address-context-guide)
+  - [User-Controlled (Recommended)](#user-controlled-recommended)
+  - [Developer-Controlled (Advanced)](#developer-controlled-advanced)
+  - [Decision Matrix](#decision-matrix)
+- [Usage Examples](#usage-examples)
+  - [Contract Interactions](#contract-interactions)
+  - [EIP-712 Signatures](#eip-712-signatures)
+  - [Cross-Chain Bridging](#cross-chain-bridging)
+- [API Reference](#api-reference)
+  - [Factory Functions](#factory-functions)
+  - [Core Methods](#core-methods)
+  - [Token Operations](#token-operations)
+- [Migration Guide](#migration-guide)
+- [Supported Chains](#supported-chains)
+- [Development](#development)
+- [License](#license)
 
 ## Overview
 
-The Ethers v6 Adapter is a strongly-typed implementation of the [`Adapter`](https://github.com/circlefin/stablecoin-kits-private/blob/main/core/adapter/README.md) interface for **EVM-compatible blockchains**. Built on top of the popular [Ethers v6](https://docs.ethers.org/v6/) library, it provides type-safe blockchain interactions through a unified interface that's designed to work seamlessly with the [Bridging Kit](https://github.com/circlefin/stablecoin-kits-private/tree/main/kits/bridging-kit) for cross-chain USDC transfers between Solana and EVM networks, as well as any future kits for additional stablecoin operations. It can be used by any Kit built using the Stablecoin Kits architecture and/or any providers plugged into those kits.
+The Ethers v6 Adapter is a strongly-typed implementation of the `Adapter` interface for **EVM-compatible blockchains**. Built on top of the popular [Ethers v6](https://docs.ethers.org/v6/) library, it provides type-safe blockchain interactions through a unified interface that's designed to work seamlessly with the [Bridge Kit](https://www.npmjs.com/package/@circle-fin/bridge-kit) for cross-chain USDC transfers between Solana and EVM networks, as well as any future kits for additional stablecoin operations. It can be used by any Kit built using the Stablecoin Kits architecture and/or any providers plugged into those kits.
 
 ### Why Ethers v6 Adapter?
 
@@ -43,24 +56,32 @@ The Ethers v6 Adapter is a strongly-typed implementation of the [`Adapter`](http
 - **🔄 Transaction lifecycle** - Complete prepare/estimate/execute workflow
 - **🌉 Cross-chain ready** - Seamlessly bridge USDC between EVM chains and Solana
 
-### When and How Should I Use The Ethers v6 Adapter?
+### When to Use This Adapter
 
-#### I'm a developer using a kit
+#### For Kit Users
 
-If you're using one of the kits to perform actions such as bridging from chain 'A' to chain 'B', you only need to instantiate the adapter for your chain and pass it to the kit.
-
-##### Example
+If you're using the Bridge Kit or other Stablecoin Kits for cross-chain operations, you only need to instantiate one adapter and pass it to the kit. The same adapter works across all supported chains.
 
 ```typescript
+// Single adapter instance for multi-chain operations
+// Note: Private keys can be provided with or without '0x' prefix
 const adapter = createAdapterFromPrivateKey({
-  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
-  defaultChain: 'Ethereum',
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`, // Both '0x...' and '...' work
+})
+
+// Both formats are automatically normalized:
+const adapter1 = createAdapterFromPrivateKey({
+  privateKey: '0x1234...', // With prefix ✅
+})
+
+const adapter2 = createAdapterFromPrivateKey({
+  privateKey: '1234...', // Without prefix ✅ (automatically normalized)
 })
 ```
 
-#### I'm a developer making a Kit Provider
+#### For Kit Provider Developers
 
-If you are making a provider for other Kit users to plug in to the kit, e.g. a `BridgingProvider`, and you'll need to interact with diff chains, then you'll need to use the abstracted `Adapter` methods to execute on chain.
+If you're building a provider (e.g., a custom `BridgingProvider` implementation), you'll use the adapter's abstracted methods to interact with different chains. The OperationContext pattern makes multi-chain operations seamless.
 
 ## Installation
 
@@ -70,240 +91,526 @@ npm install @circle-fin/adapter-ethers-v6 ethers
 yarn add @circle-fin/adapter-ethers-v6 ethers
 ```
 
+## Peer Dependencies
+
+This adapter requires `ethers` (v6) as a peer dependency. Install it alongside the adapter:
+
+```bash
+npm install @circle-fin/adapter-ethers-v6 ethers
+# or
+yarn add @circle-fin/adapter-ethers-v6 ethers
+```
+
+**Supported Versions:** `^6.11.0` (6.11.x through 6.x.x, excluding 7.x.x)
+
+### Troubleshooting Version Conflicts
+
+If you encounter peer dependency warnings:
+
+- Check your `ethers` version: `npm ls ethers`
+- Ensure ethers v6 is between 6.11.0 and 7.0.0 (exclusive)
+- Use `npm install ethers@^6.11.0` to install a compatible version
+- Note: This adapter is **not** compatible with ethers v5 or v7
+
 ## Quick Start
 
-### 🚀 Easy Setup with Factory Methods (Recommended)
+### Zero-Config Setup (Recommended)
 
-The simplest way to get started is with our factory methods. You can create just **one adapter** and use it across different chains!
+The simplest way to get started with lazy initialization. Default configuration handles adapter setup automatically.
 
 ```typescript
 import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
 
-// Create ONE adapter that can work across chains!
+// Minimal configuration with lazy initialization
+// Note: Private keys work with or without '0x' prefix
 const adapter = createAdapterFromPrivateKey({
-  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
-  defaultChain: 'Ethereum',
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`, // Both '0x...' and '...' work
+  // Defaults applied:
+  // - addressContext: 'user-controlled'
+  // - supportedChains: all EVM chains (~34 networks)
+  // - Lazy initialization: wallet connects to chain on first operation
 })
 
-// Ready to use with Bridging Kit!
-const address = await adapter.getAddress()
-console.log('Connected address:', address)
+// Chain specified per operation via OperationContext
+const prepared = await adapter.prepare(
+  {
+    address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC on Ethereum
+    abi: usdcAbi,
+    functionName: 'transfer',
+    args: ['0xrecipient', '1000000'],
+  },
+  { chain: 'Ethereum' }, // Chain specified in context
+)
+
+const txHash = await prepared.execute()
 ```
 
-### 🏭 Production Considerations
+### Production Setup
 
-> **⚠️ Important for Production**: The factory methods use Ethers's default public RPC endpoints, which may have rate limits and lower reliability. For production applications, we strongly recommend using dedicated RPC providers like Alchemy, Infura, or QuickNode.
+For production use, provide custom RPC endpoints for better reliability and performance:
 
 ```typescript
 import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
 import { JsonRpcProvider } from 'ethers'
+import { Ethereum, Base, Polygon } from '@core/chains'
 
-// Production-ready setup with custom RPC endpoints
+// Production-ready with custom RPC endpoints and lazy initialization
 const adapter = createAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
-  defaultChain: 'Ethereum',
-  getProvider: ({ chain }) =>
-    new JsonRpcProvider(
-      `https://eth-mainnet.alchemyapi.io/v2/${process.env.ALCHEMY_KEY}`,
-    ),
+  // Custom RPC provider with explicit chain mapping
+  getProvider: ({ chain }) => {
+    // Map chain names to RPC endpoints
+    // Customize this mapping based on your RPC provider
+    const rpcEndpoints: Record<string, string> = {
+      Ethereum: `https://eth-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
+      Base: `https://base-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
+      Polygon: `https://polygon-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
+    }
+
+    const endpoint = rpcEndpoints[chain.name]
+    if (!endpoint) {
+      throw new Error(`RPC endpoint not configured for chain: ${chain.name}`)
+    }
+
+    return new JsonRpcProvider(endpoint, chain.chainId)
+  },
+  // Optionally restrict to specific chains
+  capabilities: {
+    supportedChains: [Ethereum, Base, Polygon],
+  },
 })
 ```
 
-### 🌐 Browser Support with Wallet Providers
+> **⚠️ Production Note**: Default factory methods use public RPC endpoints which may have rate limits. For production, use dedicated providers like Alchemy, Infura, or QuickNode.
 
-For browser environments with wallet providers like MetaMask:
+### Browser Wallet Setup
+
+For browser environments with MetaMask or WalletConnect:
 
 ```typescript
 import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
 
-// Create an adapter from a browser wallet
+// Minimal browser wallet configuration
 const adapter = await createAdapterFromProvider({
   provider: window.ethereum,
-  chain: 'Ethereum', // Required: specify the intended chain
-  getProvider: ({ chain }) =>
-    new JsonRpcProvider(
-      `https://eth-mainnet.alchemyapi.io/v2/${process.env.ALCHEMY_KEY}`,
-    ),
+  // Default capabilities applied automatically
 })
+
+// User will be prompted to connect wallet
+// Address is automatically resolved from connected wallet
+const prepared = await adapter.prepare(
+  {
+    address: '0xcontract',
+    abi: contractAbi,
+    functionName: 'approve',
+    args: ['0xspender', '1000000'],
+  },
+  { chain: 'Polygon' },
+)
 ```
 
-### 🔧 Advanced Manual Setup
+## OperationContext Pattern
+
+### Why OperationContext?
+
+The OperationContext pattern is the modern approach for multi-chain operations. Instead of locking an adapter to a single chain, you specify the chain per operation. This enables powerful patterns like using a single adapter for cross-chain bridging.
 
-For advanced use cases requiring custom RPC endpoints:
+**Benefits:**
+
+- ✅ **One adapter, many chains** - No need to create separate adapters for each network
+- ✅ **Explicit is better** - Chain is always clear in your code
+- ✅ **Type-safe** - Full TypeScript support with compile-time checks
+- ✅ **Eliminates ambiguity** - No confusion about which chain is being used
+
+### Basic Usage
+
+Every operation accepts an `OperationContext` parameter that specifies the chain:
 
 ```typescript
-import { EthersAdapter } from '@circle-fin/adapter-ethers-v6'
-import { JsonRpcProvider, Wallet } from 'ethers'
+import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+
+// Create adapter without specifying a chain - true lazy initialization
+const adapter = createAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+})
+
+// Chain specified explicitly in every operation
+const prepared = await adapter.prepare(
+  {
+    address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+    abi: usdcAbi,
+    functionName: 'transfer',
+    args: ['0xrecipient', '1000000'],
+  },
+  { chain: 'Ethereum' },
+)
+
+const gas = await prepared.estimate()
+const txHash = await prepared.execute()
+```
 
-// Use your existing Ethers setup
-const provider = new JsonRpcProvider('https://your-custom-rpc.com')
-const wallet = new Wallet(process.env.PRIVATE_KEY, provider)
+### Multi-Chain Operations
 
-// Create the adapter
-const adapter = new EthersAdapter({
-  provider,
-  wallet,
+Use a single adapter instance for operations across multiple chains:
+
+```typescript
+// Create adapter once for use across multiple chains
+const adapter = createAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
 })
+
+// Transfer USDC on Ethereum
+const ethPrepared = await adapter.prepare(
+  {
+    address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC on Ethereum
+    abi: usdcAbi,
+    functionName: 'transfer',
+    args: ['0xrecipient', '1000000'],
+  },
+  { chain: 'Ethereum' },
+)
+
+// Transfer USDC on Base using the same adapter
+const basePrepared = await adapter.prepare(
+  {
+    address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
+    abi: usdcAbi,
+    functionName: 'transfer',
+    args: ['0xrecipient', '1000000'],
+  },
+  { chain: 'Base' },
+)
+
+// Execute both transfers
+await ethPrepared.execute()
+await basePrepared.execute()
 ```
 
-## Features
+## Address Context Guide
 
-- ✅ **Full EVM compatibility** - Works with any Ethereum-compatible blockchain
-- ✅ **Ethers v6 integration** - Uses your existing `JsonRpcProvider` and `Wallet`
-- ✅ **Transaction lifecycle** - Complete prepare/estimate/execute workflow
-- ✅ **Type safety** - Full TypeScript support with strict mode
-- ✅ **Cross-chain ready** - Seamlessly bridge USDC between Solana and EVM chains
+The adapter supports two address control patterns. Choose the one that fits your use case.
 
-## Usage Examples
+### User-Controlled (Recommended)
 
-### Basic Usage with Factory Methods
+**Best for:** Private key wallets, browser wallets (MetaMask), hardware wallets
 
-```typescript
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
-import { BridgingKit } from '@circle-fin/bridging-kit'
+**How it works:** Address is automatically resolved from the connected signer/wallet. You don't need to specify it in the OperationContext.
 
-// Create ONE adapter that can work across chains - so simple!
+**When to use:**
+
+- ✅ Building a dApp where users connect their wallets
+- ✅ Using a private key for backend automation
+- ✅ Single wallet signing all transactions
+- ✅ Server-side scripts with one identity
+
+```typescript
+// User-controlled adapter (default for factory functions)
 const adapter = createAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
-  defaultChain: 'Ethereum',
+  // addressContext: 'user-controlled' is the default
 })
 
-// Use directly with Bridging Kit - same adapter, different chains!
-const kit = new BridgingKit()
-const result = await kit.bridge({
-  from: { adapter }, // Uses default chain (Ethereum)
-  to: { adapter, chain: 'Base' }, // Same adapter, different chain
-  amount: '10.50',
-})
+// Address automatically resolved from private key/wallet
+const prepared = await adapter.prepare(
+  {
+    address: '0xcontract',
+    abi: contractAbi,
+    functionName: 'approve',
+    args: ['0xspender', '1000000'],
+  },
+  { chain: 'Polygon' }, // No address needed in context for user-controlled
+)
 ```
 
-### Manual Setup with Ethers
+### Developer-Controlled (Advanced)
+
+**Best for:** Custody solutions, multi-entity systems, enterprise applications
+
+**How it works:** Address must be explicitly provided in the OperationContext for each operation.
+
+**When to use:**
+
+- ✅ Building a custody solution managing multiple client wallets
+- ✅ Enterprise system where different users have different signing keys
+- ✅ Multi-sig or delegated signing infrastructure
+- ✅ Systems where address varies per transaction
 
 ```typescript
 import { EthersAdapter } from '@circle-fin/adapter-ethers-v6'
-import { BridgingKit } from '@circle-fin/bridging-kit'
-import { JsonRpcProvider, Wallet } from 'ethers'
+import { Ethereum, Base } from '@core/chains'
+
+// Developer-controlled adapter (manual constructor)
+const adapter = new EthersAdapter(
+  {
+    getProvider: ({ chain }) => new JsonRpcProvider('https://...'),
+    signer: wallet,
+  },
+  {
+    addressContext: 'developer-controlled', // ← Explicit address required
+    supportedChains: [Ethereum, Base],
+  },
+)
+
+// Address must be provided in context for developer-controlled adapters
+const prepared = await adapter.prepare(
+  {
+    address: '0xcontract',
+    abi: contractAbi,
+    functionName: 'approve',
+    args: ['0xspender', '1000000'],
+  },
+  {
+    chain: 'Ethereum',
+    address: '0x1234...', // Required for developer-controlled
+  },
+)
+```
 
-const provider = new JsonRpcProvider('https://your-custom-rpc.com')
-const wallet = new Wallet(process.env.PRIVATE_KEY!, provider)
+## Usage Examples
 
-const adapter = new EthersAdapter({ provider, wallet })
+### Contract Interactions
 
-const destinationAdapter = new EthersAdapter({
-  provider: new JsonRpcProvider('https://another-rpc.com'),
-  wallet: new Wallet(
-    process.env.PRIVATE_KEY!,
-    new JsonRpcProvider('https://another-rpc.com'),
-  ),
-})
+**Transfer USDC** across different chains with the same adapter:
 
-const kit = new BridgingKit()
-const result = await kit.bridge({
-  from: { adapter },
-  to: { adapter: destinationAdapter },
-  amount: '10.50',
+```typescript
+import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+import { parseAbi } from 'ethers'
+
+// Create adapter with lazy initialization
+const adapter = createAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
 })
+
+const usdcAbi = parseAbi([
+  'function transfer(address to, uint256 amount) returns (bool)',
+])
+
+// Transfer on Ethereum - chain specified in operation
+const ethPrepared = await adapter.prepare(
+  {
+    address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC on Ethereum
+    abi: usdcAbi,
+    functionName: 'transfer',
+    args: ['0xrecipient', '1000000'], // 1 USDC (6 decimals)
+  },
+  { chain: 'Ethereum' },
+)
+
+// Estimate and execute
+const gas = await ethPrepared.estimate()
+console.log('Estimated gas:', gas.gas)
+
+const txHash = await ethPrepared.execute()
+console.log('Transaction hash:', txHash)
 ```
 
-### Multi-Chain Setup
+### EIP-712 Signatures
+
+**Sign permit approvals** for gasless token approvals:
 
 ```typescript
 import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
-import { BridgingKit } from '@circle-fin/bridging-kit'
 
-const kit = new BridgingKit()
+const adapter = createAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+})
+
+// Sign ERC-2612 permit (gasless USDC approval)
+const signature = await adapter.signTypedData(
+  {
+    domain: {
+      name: 'USD Coin',
+      version: '2',
+      chainId: 1,
+      verifyingContract: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+    },
+    types: {
+      Permit: [
+        { name: 'owner', type: 'address' },
+        { name: 'spender', type: 'address' },
+        { name: 'value', type: 'uint256' },
+        { name: 'nonce', type: 'uint256' },
+        { name: 'deadline', type: 'uint256' },
+      ],
+    },
+    primaryType: 'Permit',
+    message: {
+      owner: '0xowner',
+      spender: '0xspender',
+      value: '1000000',
+      nonce: '0',
+      deadline: '1735689600',
+    },
+  },
+  { chain: 'Ethereum' }, // Chain must be specified
+)
+
+console.log('Permit signature:', signature)
+// Use signature for gasless approval
+```
+
+### Cross-Chain Bridging
 
-// Create ONE adapter that can work across ANY supported chain
+**Bridge USDC** using the Bridge Kit with OperationContext:
+
+```typescript
+import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+import { BridgeKit } from '@circle-fin/bridge-kit'
+
+// Create adapter for multi-chain operations
 const adapter = createAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
-  defaultChain: 'Ethereum', // This is just the default
 })
 
-// Use for cross-chain bridging by specifying different chains
+const kit = new BridgeKit()
+
+// Bridge from Ethereum to Base using the same adapter
 const result = await kit.bridge({
-  from: { adapter }, // Ethereum (from defaultChain)
-  to: { adapter, chain: 'Base' }, // Base (explicitly specified)
-  amount: '10.50',
+  from: { adapter, chain: 'Ethereum' },
+  to: { adapter, chain: 'Base' },
+  amount: '100.50',
   token: 'USDC',
 })
 
-// Or bridge between any other supported chains
-const anotherResult = await kit.bridge({
-  from: { adapter, chain: 'Arbitrum' },
-  to: { adapter, chain: 'Polygon' },
-  amount: '25.00',
-  token: 'USDC',
+console.log('Bridge transaction:', result.transactionHash)
+```
+
+## API Reference
+
+### Factory Functions
+
+#### `createAdapterFromPrivateKey(params)`
+
+Creates an adapter from a private key for server-side use.
+
+**Parameters:**
+
+- `privateKey` - 32-byte hex string with `0x` prefix
+- `getProvider?` - Optional custom provider function
+- `capabilities?` - Optional partial capabilities (defaults: user-controlled + all EVM chains)
+
+**Returns:** `EthersAdapter` instance with lazy initialization
+
+**Note:** No chain required at creation time. The adapter connects to chains lazily on first operation.
+
+```typescript
+const adapter = createAdapterFromPrivateKey({
+  privateKey: '0x...',
 })
 ```
 
-> **💡 Pro Tip**: With the single adapter pattern, you create one adapter and can use it for bridging between any supported EVM chains. Just specify the desired chain in the bridge parameters!
+#### `createAdapterFromProvider(params)`
 
-## Supported Chains
+Creates an adapter from a browser wallet provider (MetaMask, WalletConnect, etc.).
 
-Works with all EVM-compatible chains supported by Ethers v6 and the Bridging Kit:
+**Parameters:**
 
-**Ethereum**, **Base**, **Arbitrum**, **Avalanche**, **Polygon**, **Optimism**, **Linea**, **Sonic**, **Unichain**, **World Chain**, **Codex**, and their respective testnets.
+- `provider` - EIP-1193 compatible provider
+- `getProvider?` - Optional custom provider function
+- `capabilities?` - Optional partial capabilities (defaults: user-controlled + all EVM chains)
 
-## API Reference
+**Returns:** `Promise<EthersAdapter>` instance
+
+```typescript
+const adapter = await createAdapterFromProvider({
+  provider: window.ethereum,
+})
+```
+
+### Core Methods
+
+#### `prepare(params, ctx)`
+
+Prepares a contract function call for estimation and execution.
+
+**Parameters:**
 
-### Constructor Options
+- `params` - Contract call parameters (address, abi, functionName, args)
+- `ctx` - **Required** OperationContext with chain specification
+
+**Returns:** `Promise<PreparedChainRequest>` with `estimate()` and `execute()` methods
 
 ```typescript
-interface EthersAdapterOptions {
-  getProvider: (params: { chain: ChainDefinition }) => Provider
-  signer: Signer
-}
+const prepared = await adapter.prepare(
+  {
+    address: '0xcontract',
+    abi: contractAbi,
+    functionName: 'transfer',
+    args: ['0xto', '1000000'],
+  },
+  { chain: 'Ethereum' }, // Required
+)
 ```
 
-### Methods
+#### `signTypedData(typedData, ctx)`
 
-- `getAddress()` - Get the connected wallet address
-- `getChain()` - Get chain information
-- `prepare()` - Prepare transactions for execution
-- `estimate()` - Estimate transaction costs
-- `execute()` - Execute prepared transactions
-- `waitForTransaction()` - Wait for transaction confirmation
-- `calculateTransactionFee()` - Calculate transaction fees with optional buffer
-- `readContract()` - Read contract functions with comprehensive validation
+Signs EIP-712 typed data for permits, meta-transactions, etc.
 
-You can see the implementation of each of these methods in the Ethers v6 Adapter's [main implementation file](./src/adapter/adapter.ts).
+**Parameters:**
 
-### Token Operations via Actions
+- `typedData` - EIP-712 structured data
+- `ctx` - **Required** OperationContext with chain specification
 
-For token balance and allowance operations, this adapter uses the standardized action-based system inherited from `EvmAdapter`:
+**Returns:** `Promise<string>` - Signature as hex string
 
-- **`token.balanceOf`** - Get balance for any ERC-20 token
-- **`token.allowance`** - Get allowance for any ERC-20 token
-- **`usdc.balanceOf`** - Get USDC balance (uses `token.balanceOf` with USDC address)
-- **`usdc.allowance`** - Get USDC allowance (uses `token.allowance` with USDC address)
+```typescript
+const signature = await adapter.signTypedData(permitData, {
+  chain: 'Ethereum',
+})
+```
 
-These actions provide type-safe, validated interfaces and use the adapter's `readContract()` method internally.
+#### `waitForTransaction(txHash, config?)`
 
-## Integration with Stablecoin Kits
+Waits for transaction confirmation.
 
-This adapter is designed to work seamlessly across the Stablecoin Kits ecosystem. Here's an example with the [Bridging Kit](https://github.com/circlefin/stablecoin-kits-private/tree/main/kits/bridging-kit):
+**Parameters:**
+
+- `txHash` - Transaction hash to wait for
+- `config?` - Optional wait configuration (confirmations, timeout)
+
+**Returns:** `Promise<TransactionReceipt>`
 
 ```typescript
-import { BridgingKit } from '@circle-fin/bridging-kit'
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+const receipt = await adapter.waitForTransaction('0x...')
+```
 
-const kit = new BridgingKit()
+#### `getAddress(chain?)`
 
-// Create ONE adapter that works across all EVM chains - incredibly simple!
-const adapter = createAdapterFromPrivateKey({
-  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
-  defaultChain: 'Ethereum',
+Gets the connected wallet address. Chain parameter is provided automatically by OperationContext resolution.
+
+**Returns:** `Promise<string>` - Wallet address
+
+### Token Operations
+
+Built-in token operations using the action system:
+
+```typescript
+// Get USDC balance
+const balance = await adapter.actions.usdc.balanceOf({
+  address: '0xwallet',
+  chain: 'Ethereum',
 })
 
-// Ready for cross-chain bridging between any supported chains!
-await kit.bridge({
-  from: { adapter }, // Uses default chain (Ethereum)
-  to: { adapter, chain: 'Base' }, // Same adapter, different chain
-  amount: '50.0',
+// Get token allowance
+const allowance = await adapter.actions.token.allowance({
+  tokenAddress: '0xtoken',
+  owner: '0xowner',
+  spender: '0xspender',
+  chain: 'Base',
 })
 ```
 
-**For Production Use**: Remember to provide custom RPC endpoints using the `getProvider` parameter for better reliability and performance!
+## Supported Chains & Routes
+
+The Ethers v6 adapter supports **34 EVM-compatible chains** across mainnet and testnet environments through Circle's CCTP v2 protocol:
+
+### Mainnet Chains (17 chains)
+
+**Arbitrum**, **Avalanche**, **Base**, **Celo**, **Codex**, **Ethereum**, **HyperEVM**, **Ink**, **Linea**, **OP Mainnet**, **Plume**, **Polygon PoS**, **Sonic**, **Unichain**, **World Chain**, **XDC**, **ZKSync Era**
+
+### Testnet Chains (17 chains)
+
+**Arbitrum Sepolia**, **Avalanche Fuji**, **Base Sepolia**, **Celo Alfajores**, **Codex Testnet**, **Ethereum Sepolia**, **HyperEVM Testnet**, **Ink Testnet**, **Linea Sepolia**, **OP Sepolia**, **Plume Testnet**, **Polygon PoS Amoy**, **Sonic Testnet**, **Unichain Sepolia**, **World Chain Sepolia**, **XDC Apothem**, **ZKSync Era Sepolia**
 
 ## Development
 
@@ -317,13 +624,9 @@ nx build @circle-fin/adapter-ethers-v6
 nx test @circle-fin/adapter-ethers-v6
 ```
 
-## Contributing
-
-We welcome contributions! Please see our [Contributing Guide](https://github.com/circlefin/stablecoin-kits-private/blob/main/CONTRIBUTING.md) for details.
-
 ## License
 
-This project is licensed under the Apache 2.0 License - see the [LICENSE](https://github.com/circlefin/stablecoin-kits-private/blob/main/LICENSE) file for details.
+This project is licensed under the Apache 2.0 License. Contact [support](https://help.circle.com/s/submit-ticket) for details.
 
 ---
 
@@ -331,7 +634,8 @@ This project is licensed under the Apache 2.0 License - see the [LICENSE](https:
 
 **Ready to integrate?**
 
-[View Stablecoin Kits](https://github.com/circlefin/stablecoin-kits-private) • [Join Discord](https://discord.com/invite/buildoncircle) • [Report Issues](https://github.com/circlefin/stablecoin-kits-private/issues)
+[Join Discord](https://discord.com/invite/buildoncircle) •
+[Visit our Help-Desk](https://help.circle.com/s/submit-ticket)
 
 _Built with ❤️ by Circle_