@circle-fin/adapter-ethers-v6 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @circle-fin/adapter-ethers-v6
 
+## 1.3.0
+
+### Minor Changes
+
+- Add `native.balanceOf` action to query native token balances (ETH, SOL, etc.)
+  - Added `NativeActionMap` with `balanceOf` action to check native token balance for any wallet address
+  - Added abstract `readNativeBalance(address, chain)` method to base adapters
+  - Implemented `readNativeBalance` in all concrete adapters (Viem, Ethers, Solana, SolanaKit)
+  - Registered `native.balanceOf` action handlers for EVM and Solana chains
+  - Balance reads are gas-free operations returning balance as string (wei for EVM, lamports for Solana)
+
+### Patch Changes
+
+- **Faster balance and allowance checks**: Read-only operations like checking token balances or allowances no longer require wallet network switching. This means no wallet popups asking for permission to switch networks, resulting in quicker responses and a smoother user experience.
+
+## 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

package/README.md

@@ -41,8 +41,8 @@ _Seamlessly interact with 16+ EVM networks using a single, strongly-typed interf
     - [Cross-Chain Bridging](#cross-chain-bridging)
   - [API Reference](#api-reference)
     - [Factory Functions](#factory-functions)
-      - [`createAdapterFromPrivateKey(params)`](#createadapterfromprivatekeyparams)
-      - [`createAdapterFromProvider(params)`](#createadapterfromproviderparams)
+      - [`createEthersAdapterFromPrivateKey(params)`](#createethersadapterfromprivatekeyparams)
+      - [`createEthersAdapterFromProvider(params)`](#createethersadapterfromproviderparams)
     - [Core Methods](#core-methods)
       - [`prepare(params, ctx)`](#prepareparams-ctx)
       - [`signTypedData(typedData, ctx)`](#signtypeddatatypeddata-ctx)
@@ -77,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)
 })
 ```
@@ -131,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'
@@ -162,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 }) => {
@@ -200,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
 })
@@ -239,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}`,
 })
 
@@ -267,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}`,
 })
 
@@ -317,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
 })
@@ -385,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}`,
 })
 
@@ -421,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}`,
 })
 
@@ -466,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}`,
 })
 
@@ -491,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.
 
@@ -506,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.).
 
@@ -524,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,
 })
 ```