@circle-fin/adapter-ethers-v6 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @circle-fin/adapter-ethers-v6
 
+## 1.2.0
+
+### Minor Changes
+
+- Clearer ethers factory names eliminate aliasing when using multiple adapters. Prefer `createEthersAdapterFromProvider` and `createEthersAdapterFromPrivateKey` over the deprecated generic `createAdapterFromProvider` and `createAdapterFromPrivateKey`. Existing code works unchanged.
+
+### Patch Changes
+
+- Validation errors now use standardized error codes for consistent error handling. All validation failures return the same `KitError` structure as other SDK errors.
+
+  **Migration:** If you're catching validation errors, update your error handling:
+  - Check `error.code === 1098` instead of `instanceof ValidationError`
+  - Access details via `error.cause?.trace?.validationErrors` instead of `error.errors`
+
+  The legacy `ValidationError` class remains available for backward compatibility.
+
+- Fixed an issue where custom RPC URLs were not fully respected in Ethers adapter, ensuring users can now properly configure alternative RPC endpoints.
+- Fixed unnecessary chain switching in EthersAdapter that was causing redundant provider reconnections and wallet prompts. The adapter now checks the current chain ID before attempting to switch, skipping the operation when already on the target chain. This improves performance for dev-controlled wallets and reduces unnecessary wallet prompts for browser users (MetaMask, WalletConnect, etc.) when performing multiple operations on the same chain.
+
+## 1.1.1
+
+### Patch Changes
+
+- Fixed adapter `getAddress()` types to match function logic by requiring a `chain` parameter, and updated documentation accordingly.
+- Improved error handling with more informative and consistent error messages.
+
+  Errors now include:
+  - Specific error codes for programmatic handling
+  - Error type categorization (BALANCE, ONCHAIN, RPC, NETWORK)
+  - Recoverability information (FATAL vs RETRYABLE)
+  - Clearer error messages with chain context
+  - Original error details preserved for debugging
+
+- Fixed bug where tokens could be burned when bridging to unsupported chains. Bridge operations now fail immediately if the adapter doesn't support the source or destination chain, before any tokens are approved or burned. Error messages now clearly list all supported chains when an unsupported chain is used, and chain validation errors use the correct `INVALID_CHAIN` error code instead of `UNSUPPORTED_ROUTE`.
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -14,34 +14,46 @@ _Seamlessly interact with 16+ EVM networks using a single, strongly-typed interf
 
 ## Table of Contents
 
-- [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)
+- [Ethers v6 Adapter](#ethers-v6-adapter)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+    - [Why Ethers v6 Adapter?](#why-ethers-v6-adapter)
+    - [When to Use This Adapter](#when-to-use-this-adapter)
+      - [For Kit Users](#for-kit-users)
+      - [For Kit Provider Developers](#for-kit-provider-developers)
+  - [Installation](#installation)
+  - [Peer Dependencies](#peer-dependencies)
+    - [Troubleshooting Version Conflicts](#troubleshooting-version-conflicts)
+  - [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)
+  - [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)
+      - [`createEthersAdapterFromPrivateKey(params)`](#createethersadapterfromprivatekeyparams)
+      - [`createEthersAdapterFromProvider(params)`](#createethersadapterfromproviderparams)
+    - [Core Methods](#core-methods)
+      - [`prepare(params, ctx)`](#prepareparams-ctx)
+      - [`signTypedData(typedData, ctx)`](#signtypeddatatypeddata-ctx)
+      - [`waitForTransaction(txHash, config?)`](#waitfortransactiontxhash-config)
+      - [`getAddress(chain)`](#getaddresschain)
+    - [Token Operations](#token-operations)
+  - [Supported Chains \& Routes](#supported-chains--routes)
+    - [Mainnet Chains (17 chains)](#mainnet-chains-17-chains)
+    - [Testnet Chains (17 chains)](#testnet-chains-17-chains)
+  - [Development](#development)
+  - [License](#license)
 
 ## Overview
 
@@ -65,16 +77,16 @@ If you're using the Bridge Kit or other Stablecoin Kits for cross-chain operatio
 ```typescript
 // Single adapter instance for multi-chain operations
 // Note: Private keys can be provided with or without '0x' prefix
-const adapter = createAdapterFromPrivateKey({
+const adapter = createEthersAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`, // Both '0x...' and '...' work
 })
 
 // Both formats are automatically normalized:
-const adapter1 = createAdapterFromPrivateKey({
+const adapter1 = createEthersAdapterFromPrivateKey({
   privateKey: '0x1234...', // With prefix ✅
 })
 
-const adapter2 = createAdapterFromPrivateKey({
+const adapter2 = createEthersAdapterFromPrivateKey({
   privateKey: '1234...', // Without prefix ✅ (automatically normalized)
 })
 ```
@@ -119,11 +131,11 @@ If you encounter peer dependency warnings:
 The simplest way to get started with lazy initialization. Default configuration handles adapter setup automatically.
 
 ```typescript
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+import { createEthersAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
 
 // Minimal configuration with lazy initialization
 // Note: Private keys work with or without '0x' prefix
-const adapter = createAdapterFromPrivateKey({
+const adapter = createEthersAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`, // Both '0x...' and '...' work
   // Defaults applied:
   // - addressContext: 'user-controlled'
@@ -150,12 +162,12 @@ const txHash = await prepared.execute()
 For production use, provide custom RPC endpoints for better reliability and performance:
 
 ```typescript
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+import { createEthersAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
 import { JsonRpcProvider } from 'ethers'
 import { Ethereum, Base, Polygon } from '@core/chains'
 
 // Production-ready with custom RPC endpoints and lazy initialization
-const adapter = createAdapterFromPrivateKey({
+const adapter = createEthersAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
   // Custom RPC provider with explicit chain mapping
   getProvider: ({ chain }) => {
@@ -188,10 +200,10 @@ const adapter = createAdapterFromPrivateKey({
 For browser environments with MetaMask or WalletConnect:
 
 ```typescript
-import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+import { createEthersAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
 
 // Minimal browser wallet configuration
-const adapter = await createAdapterFromProvider({
+const adapter = await createEthersAdapterFromProvider({
   provider: window.ethereum,
   // Default capabilities applied automatically
 })
@@ -227,10 +239,10 @@ The OperationContext pattern is the modern approach for multi-chain operations.
 Every operation accepts an `OperationContext` parameter that specifies the chain:
 
 ```typescript
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+import { createEthersAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
 
 // Create adapter without specifying a chain - true lazy initialization
-const adapter = createAdapterFromPrivateKey({
+const adapter = createEthersAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
 })
 
@@ -255,7 +267,7 @@ Use a single adapter instance for operations across multiple chains:
 
 ```typescript
 // Create adapter once for use across multiple chains
-const adapter = createAdapterFromPrivateKey({
+const adapter = createEthersAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
 })
 
@@ -305,7 +317,7 @@ The adapter supports two address control patterns. Choose the one that fits your
 
 ```typescript
 // User-controlled adapter (default for factory functions)
-const adapter = createAdapterFromPrivateKey({
+const adapter = createEthersAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
   // addressContext: 'user-controlled' is the default
 })
@@ -373,11 +385,11 @@ const prepared = await adapter.prepare(
 **Transfer USDC** across different chains with the same adapter:
 
 ```typescript
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+import { createEthersAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
 import { parseAbi } from 'ethers'
 
 // Create adapter with lazy initialization
-const adapter = createAdapterFromPrivateKey({
+const adapter = createEthersAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
 })
 
@@ -409,9 +421,9 @@ console.log('Transaction hash:', txHash)
 **Sign permit approvals** for gasless token approvals:
 
 ```typescript
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+import { createEthersAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
 
-const adapter = createAdapterFromPrivateKey({
+const adapter = createEthersAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
 })
 
@@ -454,11 +466,11 @@ console.log('Permit signature:', signature)
 **Bridge USDC** using the Bridge Kit with OperationContext:
 
 ```typescript
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+import { createEthersAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
 import { BridgeKit } from '@circle-fin/bridge-kit'
 
 // Create adapter for multi-chain operations
-const adapter = createAdapterFromPrivateKey({
+const adapter = createEthersAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
 })
 
@@ -479,7 +491,7 @@ console.log('Bridge transaction:', result.transactionHash)
 
 ### Factory Functions
 
-#### `createAdapterFromPrivateKey(params)`
+#### `createEthersAdapterFromPrivateKey(params)`
 
 Creates an adapter from a private key for server-side use.
 
@@ -494,12 +506,12 @@ Creates an adapter from a private key for server-side use.
 **Note:** No chain required at creation time. The adapter connects to chains lazily on first operation.
 
 ```typescript
-const adapter = createAdapterFromPrivateKey({
+const adapter = createEthersAdapterFromPrivateKey({
   privateKey: '0x...',
 })
 ```
 
-#### `createAdapterFromProvider(params)`
+#### `createEthersAdapterFromProvider(params)`
 
 Creates an adapter from a browser wallet provider (MetaMask, WalletConnect, etc.).
 
@@ -512,7 +524,7 @@ Creates an adapter from a browser wallet provider (MetaMask, WalletConnect, etc.
 **Returns:** `Promise<EthersAdapter>` instance
 
 ```typescript
-const adapter = await createAdapterFromProvider({
+const adapter = await createEthersAdapterFromProvider({
   provider: window.ethereum,
 })
 ```
@@ -574,7 +586,7 @@ Waits for transaction confirmation.
 const receipt = await adapter.waitForTransaction('0x...')
 ```
 
-#### `getAddress(chain?)`
+#### `getAddress(chain)`
 
 Gets the connected wallet address. Chain parameter is provided automatically by OperationContext resolution.