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

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# @circle-fin/adapter-ethers-v6
+
+## 1.1.0
+
+### Minor Changes
+
+- Improves static gas estimate values for contract calls. Updates adapters' `prepare()` method so that transaction simulation is now performed only during `execute()`, not during `estimate()`. Adds an optional fallback parameter to `estimate()` for cases where gas estimation fails.
+
+### Patch Changes
+
+- Fix CommonJS compatibility by correcting file extensions and package exports. This resolves a "ReferenceError: require is not defined" error that occurred when using packages in CommonJS projects with ts-node.
+
+## 1.0.1
+
+### Patch Changes
+
+- Add support for Arc Testnet chain definition. Arc is Circle's EVM-compatible Layer-1 blockchain designed for stablecoin finance and asset
+  tokenization, featuring USDC as the native gas token and sub-second finality via the Malachite BFT consensus engine.
+- Improve error messages for developer-controlled address contexts. Calling `getAddress()` on an adapter configured with `addressContext: 'developer-controlled'` now throws a clear error explaining that addresses must be provided explicitly in the operation context.
+- Update Sonic Testnet chain definition to canonical network. The `SonicTestnet` chain definition now points to the official Sonic Testnet (chainId: 14601) instead of the deprecated Sonic Blaze Testnet (chainId: 57054). The RPC endpoint has been updated to `https://rpc.testnet.soniclabs.com`, the display name simplified to "Sonic Testnet", and the USDC contract address updated to the new deployment.
+
+  **Breaking Changes:**
+  - **Chain ID:** 57054 → 14601
+  - **RPC Endpoint:** `https://rpc.blaze.soniclabs.com` → `https://rpc.testnet.soniclabs.com`
+  - **USDC Address:** `0xA4879Fed32Ecbef99399e5cbC247E533421C4eC6` → `0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51`
+
+  **Migration:** If you were using `SonicTestnet`, your application will automatically connect to the new network upon upgrading. Any accounts, contracts, or transactions on the old Blaze testnet (chainId: 57054) will need to be recreated on the new testnet.
+
+## 1.0.0
+
+### Major Changes
+
+- # Ethers v6 Adapter 1.0.0 Release 🎉
+
+  Full-featured EVM blockchain adapter built on ethers.js v6 - providing comprehensive support for Ethereum and EVM-compatible chains with familiar ethers.js APIs.
+
+  ## 🚀 Core EVM Features
+  - **Complete EVM Support**: Full compatibility with Ethereum and EVM-compatible chains
+  - **Ethers.js v6 Integration**: Built on the latest ethers.js with improved performance
+  - **Multi-chain Support**: Seamless switching between different EVM networks
+  - **Wallet Integration**: Support for various wallet types and signing methods
+
+  ## 🔗 Supported Networks
+  - **Ethereum Mainnet & Testnets**: Full support for Ethereum ecosystem
+  - **Layer 2 Solutions**: Optimism, Arbitrum, Polygon, and other L2s
+  - **EVM Sidechains**: Base, Avalanche, and other EVM-compatible networks
+  - **Custom Networks**: Easy configuration for private or custom EVM chains
+
+  ## 💼 Address Management
+
+  **User-Controlled Adapters**
+  - Automatic address resolution from connected wallets
+  - Support for MetaMask, WalletConnect, and other wallet providers
+  - Real-time account switching and network detection
+
+  **Developer-Controlled Adapters**
+  - Private key-based signing for server-side applications
+  - Deterministic address management for automated systems
+  - Secure key handling with ethers.js security practices
+
+  ```typescript
+  // User-controlled adapter (wallet-based)
+  const adapter = createAdapterFromWallet(wallet)
+
+  // Developer-controlled adapter (private key)
+  const adapter = createAdapterFromPrivateKey({
+    privateKey: '0x...',
+  })
+  ```
+
+  ## ⛽ Gas Management
+  - **Intelligent Gas Estimation**: Automatic gas limit calculation with safety buffers
+  - **Dynamic Fee Calculation**: Real-time gas price fetching with configurable buffers
+  - **EIP-1559 Support**: Type 2 transaction support for modern fee markets
+  - **Gas Optimization**: Efficient transaction batching and optimization
+
+  ## 🔐 Security Features
+  - **Type Safety**: Full TypeScript support with strict type checking
+  - **Parameter Validation**: Runtime validation of all transaction parameters
+  - **Secure Signing**: Leverages ethers.js battle-tested signing infrastructure
+  - **Error Handling**: Comprehensive error handling with detailed error messages
+
+  ## 🛠️ Developer Experience
+  - **Rich JSDoc Documentation**: Complete API documentation with examples
+  - **TypeScript First**: Built with TypeScript for superior developer experience
+  - **Familiar APIs**: Consistent with ethers.js patterns and conventions
+  - **Comprehensive Testing**: Extensive test coverage for reliability
+
+  This adapter provides a robust foundation for EVM-based cross-chain USDC transfers, leveraging the mature ethers.js ecosystem while providing the specialized functionality needed for bridge operations.

package/{index.cjs.js → index.cjs}

@@ -20,10 +20,10 @@
 
 var ethers = require('ethers');
 var zod = require('zod');
+require('@ethersproject/units');
 var bytes = require('@ethersproject/bytes');
 var address = require('@ethersproject/address');
 var bs58 = require('bs58');
-require('@ethersproject/units');
 
 function _interopDefault (e) { return e && e.__esModule ? e.default : e; }
 
@@ -9977,7 +9977,7 @@ class EthersAdapter extends EvmAdapter {
      * @param overrides - Optional estimate overrides.
      * @returns Promise resolving to the estimated gas, gas price, and total fee.
      */
-    async estimateGasForFunction(contract, functionName, args, chain, overrides) {
+    async estimateGasForFunction(contract, functionName, args, chain, overrides, fallback) {
         let gas;
         try {
             const contractFunction = contract.getFunction(functionName);
@@ -9986,7 +9986,12 @@ class EthersAdapter extends EvmAdapter {
                 : await contractFunction.estimateGas(...args);
         }
         catch (error) {
-            throw new Error(`Gas estimation failed: ${error.message}`);
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            if (fallback &&
+                errorMessage.toLocaleLowerCase().includes('execution reverted')) {
+                return fallback;
+            }
+            throw new Error(`Gas estimation failed: ${errorMessage}`);
         }
         let gasPrice;
         try {
@@ -10211,18 +10216,19 @@ class EthersAdapter extends EvmAdapter {
         }
         // For state-changing functions, use the original logic
         const contract = this.createContractInstance(params, signer, resolvedContext.address, provider);
-        await this.simulateFunctionCall(contract, functionName, args);
         return {
             type: 'evm',
-            estimate: async (overrides) => {
+            estimate: async (overrides, fallback) => {
                 await this.ensureChain(targetChain);
                 // Reconnect the contract with the correct provider for the target chain to ensure
                 // gas estimation and fee data retrieval use the correct network.
                 const estimationProvider = await this.getProvider(targetChain);
                 const contractForEstimation = contract.connect(estimationProvider);
-                return this.estimateGasForFunction(contractForEstimation, functionName, args, targetChain, overrides);
+                return this.estimateGasForFunction(contractForEstimation, functionName, args, targetChain, overrides, fallback);
             },
             execute: async (overrides) => {
+                // Simulate the function call to catch errors before submission
+                await this.simulateFunctionCall(contract, functionName, args);
                 await this.ensureChain(targetChain);
                 // Reconnect the contract with the current signer, which is on the correct
                 // chain after `ensureChain`, to ensure the transaction is populated and
@@ -10836,4 +10842,4 @@ exports.createAdapterFromPrivateKey = createAdapterFromPrivateKey;
 exports.createAdapterFromProvider = createAdapterFromProvider;
 exports.parseSignature = parseSignature;
 exports.validateAdapterCapabilities = validateAdapterCapabilities;
-//# sourceMappingURL=index.cjs.js.map
+//# sourceMappingURL=index.cjs.map

package/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/index.d.ts

@@ -596,10 +596,11 @@ interface EvmPreparedChainRequest {
      * Estimate the gas cost for the contract execution.
      *
      * @param overrides - Optional parameters to override the default estimation behavior
+     * @param fallback - Optional fallback gas information to use if the estimation fails
      * @returns A promise that resolves to the estimated gas information
      * @throws If the estimation fails
      */
-    estimate(overrides?: EvmEstimateOverrides): Promise<EstimatedGas>;
+    estimate(overrides?: EvmEstimateOverrides, fallback?: EstimatedGas): Promise<EstimatedGas>;
     /**
      * Execute the prepared contract call.
      *
@@ -677,7 +678,7 @@ interface SolanaPreparedChainRequest {
     /** The type of the chain request. */
     type: 'solana';
     /** Estimate the compute units and fee for the transaction. */
-    estimate(overrides?: SolanaEstimateOverrides): Promise<EstimatedGas>;
+    estimate(overrides?: SolanaEstimateOverrides, fallback?: EstimatedGas): Promise<EstimatedGas>;
     /** Execute the prepared transaction. */
     execute(overrides?: SolanaExecuteOverrides): Promise<string>;
 }
@@ -709,7 +710,7 @@ interface NoopPreparedChainRequest {
      * Placeholder for the estimate method.
      * @returns The estimated gas cost.
      */
-    estimate: () => Promise<EstimatedGas>;
+    estimate: (overrides?: EvmEstimateOverrides | SolanaEstimateOverrides, fallback?: EstimatedGas) => Promise<EstimatedGas>;
     /**
      * Placeholder for the execute method.
      * @returns The transaction hash.
@@ -1967,10 +1968,23 @@ interface AdapterCapabilities {
  */
 declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
     /**
-     * The type of the chain.
-     * @example 'evm', 'solana'
+     * The type of the chain for this adapter.
+     *
+     * - For concrete adapters, this should be a real chain type (e.g., `'evm'`, `'solana'`, etc.) from the ChainType union.
+     * - For hybrid adapters (adapters that route to concrete adapters supporting multiple ecosystems),
+     *   set this property to the string literal `'hybrid'`.
+     *
+     * Note: `'hybrid'` is not a legal ChainType and should only be used as a marker for multi-ecosystem adapters.
+     * Hybrid adapters do not interact directly with any chain, but instead route requests to a concrete underlying adapter.
+     *
+     * @example
+     *   // For an EVM-only adapter:
+     *   chainType = 'evm'
+     *
+     *   // For a hybrid adapter:
+     *   chainType = 'hybrid'
      */
-    abstract chainType: ChainType;
+    abstract chainType: ChainType | 'hybrid';
     /**
      * Capabilities of this adapter, defining address control model and supported chains.
      *
@@ -2052,7 +2066,7 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * })
      * ```
      */
-    prepareAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>, ctx?: OperationContext<TAdapterCapabilities>): Promise<PreparedChainRequest>;
+    prepareAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>, ctx: OperationContext<TAdapterCapabilities>): Promise<PreparedChainRequest>;
     /**
      * Prepares a transaction for future gas estimation and execution.
      *

package/index.mjs

@@ -19,10 +19,10 @@
 import { JsonRpcProvider, Wallet, BrowserProvider, Interface, Contract } from 'ethers';
 export { JsonRpcProvider } from 'ethers';
 import { z } from 'zod';
+import '@ethersproject/units';
 import { hexlify, hexZeroPad } from '@ethersproject/bytes';
 import { getAddress } from '@ethersproject/address';
 import bs58 from 'bs58';
-import '@ethersproject/units';
 
 /**
  * Type-safe registry for managing and executing blockchain action handlers.
@@ -9972,7 +9972,7 @@ class EthersAdapter extends EvmAdapter {
      * @param overrides - Optional estimate overrides.
      * @returns Promise resolving to the estimated gas, gas price, and total fee.
      */
-    async estimateGasForFunction(contract, functionName, args, chain, overrides) {
+    async estimateGasForFunction(contract, functionName, args, chain, overrides, fallback) {
         let gas;
         try {
             const contractFunction = contract.getFunction(functionName);
@@ -9981,7 +9981,12 @@ class EthersAdapter extends EvmAdapter {
                 : await contractFunction.estimateGas(...args);
         }
         catch (error) {
-            throw new Error(`Gas estimation failed: ${error.message}`);
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            if (fallback &&
+                errorMessage.toLocaleLowerCase().includes('execution reverted')) {
+                return fallback;
+            }
+            throw new Error(`Gas estimation failed: ${errorMessage}`);
         }
         let gasPrice;
         try {
@@ -10206,18 +10211,19 @@ class EthersAdapter extends EvmAdapter {
         }
         // For state-changing functions, use the original logic
         const contract = this.createContractInstance(params, signer, resolvedContext.address, provider);
-        await this.simulateFunctionCall(contract, functionName, args);
         return {
             type: 'evm',
-            estimate: async (overrides) => {
+            estimate: async (overrides, fallback) => {
                 await this.ensureChain(targetChain);
                 // Reconnect the contract with the correct provider for the target chain to ensure
                 // gas estimation and fee data retrieval use the correct network.
                 const estimationProvider = await this.getProvider(targetChain);
                 const contractForEstimation = contract.connect(estimationProvider);
-                return this.estimateGasForFunction(contractForEstimation, functionName, args, targetChain, overrides);
+                return this.estimateGasForFunction(contractForEstimation, functionName, args, targetChain, overrides, fallback);
             },
             execute: async (overrides) => {
+                // Simulate the function call to catch errors before submission
+                await this.simulateFunctionCall(contract, functionName, args);
                 await this.ensureChain(targetChain);
                 // Reconnect the contract with the current signer, which is on the correct
                 // chain after `ensureChain`, to ensure the transaction is populated and

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@circle-fin/adapter-ethers-v6",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "EVM blockchain adapter powered by Ethers v6",
-  "main": "./index.cjs.js",
+  "main": "./index.cjs",
   "module": "./index.mjs",
   "types": "./index.d.ts",
   "dependencies": {
@@ -22,13 +22,15 @@
     ".": {
       "types": "./index.d.ts",
       "import": "./index.mjs",
-      "default": "./index.cjs.js"
+      "require": "./index.cjs",
+      "default": "./index.cjs"
     }
   },
   "files": [
     "index.*",
     "README.md",
     "LICENSE",
+    "CHANGELOG.md",
     "package.json"
   ],
   "publishConfig": {

package/index.cjs.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}