@circle-fin/adapter-ethers-v6 1.0.0 → 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; }
 
@@ -268,6 +268,7 @@ exports.Blockchain = void 0;
     Blockchain["Algorand_Testnet"] = "Algorand_Testnet";
     Blockchain["Aptos"] = "Aptos";
     Blockchain["Aptos_Testnet"] = "Aptos_Testnet";
+    Blockchain["Arc_Testnet"] = "Arc_Testnet";
     Blockchain["Arbitrum"] = "Arbitrum";
     Blockchain["Arbitrum_Sepolia"] = "Arbitrum_Sepolia";
     Blockchain["Avalanche"] = "Avalanche";
@@ -488,6 +489,48 @@ const BRIDGE_CONTRACT_EVM_TESTNET = '0xC5567a5E3370d4DBfB0540025078e283e36A363d'
  */
 const BRIDGE_CONTRACT_EVM_MAINNET = '0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0';
 
+/**
+ * Arc Testnet chain definition
+ * @remarks
+ * This represents the test network for the Arc blockchain,
+ * Circle's EVM-compatible Layer-1 designed for stablecoin finance
+ * and asset tokenization. Arc uses USDC as the native gas token and
+ * features the Malachite Byzantine Fault Tolerant (BFT) consensus
+ * engine for sub-second finality.
+ */
+const ArcTestnet = defineChain({
+    type: 'evm',
+    chain: exports.Blockchain.Arc_Testnet,
+    name: 'Arc Testnet',
+    title: 'ArcTestnet',
+    nativeCurrency: {
+        name: 'Arc',
+        symbol: 'Arc',
+        decimals: 18,
+    },
+    chainId: 5042002,
+    isTestnet: true,
+    explorerUrl: 'https://testnet.arcscan.app/tx/{hash}',
+    rpcEndpoints: ['https://rpc.testnet.arc.network/'],
+    eurcAddress: '0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a',
+    usdcAddress: '0x3600000000000000000000000000000000000000',
+    cctp: {
+        domain: 26,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
 /**
  * Arbitrum Mainnet chain definition
  * @remarks
@@ -1779,26 +1822,26 @@ const Sonic = defineChain({
 });
 
 /**
- * Sonic Blaze Testnet chain definition
+ * Sonic Testnet chain definition
  * @remarks
  * This represents the official test network for the Sonic blockchain.
  */
 const SonicTestnet = defineChain({
     type: 'evm',
     chain: exports.Blockchain.Sonic_Testnet,
-    name: 'Sonic Blaze Testnet',
-    title: 'Sonic Blaze Testnet',
+    name: 'Sonic Testnet',
+    title: 'Sonic Testnet',
     nativeCurrency: {
         name: 'Sonic',
         symbol: 'S',
         decimals: 18,
     },
-    chainId: 57054,
+    chainId: 14601,
     isTestnet: true,
     explorerUrl: 'https://testnet.sonicscan.org/tx/{hash}',
-    rpcEndpoints: ['https://rpc.blaze.soniclabs.com'],
+    rpcEndpoints: ['https://rpc.testnet.soniclabs.com'],
     eurcAddress: null,
-    usdcAddress: '0xA4879Fed32Ecbef99399e5cbC247E533421C4eC6',
+    usdcAddress: '0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51',
     cctp: {
         domain: 13,
         contracts: {
@@ -2315,6 +2358,7 @@ var Blockchains = {
     AptosTestnet: AptosTestnet,
     Arbitrum: Arbitrum,
     ArbitrumSepolia: ArbitrumSepolia,
+    ArcTestnet: ArcTestnet,
     Avalanche: Avalanche,
     AvalancheFuji: AvalancheFuji,
     Base: Base,
@@ -2992,6 +3036,10 @@ class KitError extends Error {
     }
 }
 
+/**
+ * Minimum error code for INPUT type errors.
+ * INPUT errors represent validation failures and invalid parameters.
+ */
 /**
  * Standardized error definitions for INPUT type errors.
  *
@@ -8012,6 +8060,246 @@ class EvmAdapter extends Adapter {
     }
 }
 
+// --- Signature Parsing Constants ---
+const SIGNATURE_BYTE_LENGTH = 65; // Total bytes in an Ethereum signature
+const HEX_CHARS_PER_BYTE = 2;
+const SIGNATURE_HEX_LENGTH = SIGNATURE_BYTE_LENGTH * HEX_CHARS_PER_BYTE;
+const R_HEX_LENGTH = 32 * HEX_CHARS_PER_BYTE; // 32 bytes for 'r'
+const S_HEX_LENGTH = 32 * HEX_CHARS_PER_BYTE; // 32 bytes for 's'
+// --- Recovery ID Validation Constants ---
+/**
+ * Legacy recovery IDs (pre-EIP-155 format):
+ * - 0 or 1 (older clients) or 27, 28 (Ethereum before chain-id inclusion)
+ */
+const LEGACY_V_VALUES = new Set([0, 1, 27, 28]);
+/**
+ * Minimum v value indicating an EIP-155 style signature.
+ * Calculated as 35 + (2 * chainId) + recoveryId (0 or 1).
+ */
+const MIN_EIP155_V = 35;
+/**
+ * parseSignature
+ *
+ * Parse a 65-byte ECDSA signature into its r, s, and v components, expressed in hex.
+ *
+ * Ethereum signatures are structured as:
+ *   signature = r (32 bytes) || s (32 bytes) || v (1 byte)
+ *
+ * - r, s: Big-endian hex values (32 bytes each)
+ * - v: Recovery identifier, used by secp256k1 to reconstruct the signer’s public key
+ *
+ * @param signatureHex - Signature as a hex string, optionally prefixed with "0x".
+ * @returns { r, s, v }
+ *   - r: Hex string of the R component.
+ *   - s: Hex string of the S component.
+ *   - v: Numeric recovery ID.
+ *
+ * @throws Error if:
+ *   - Input is not valid hex.
+ *   - Incorrect length (must be exactly 65 bytes / 130 hex chars).
+ *   - v is outside the supported range (Legacy or EIP-155 formula).
+ *
+ * Notes on EIP-155 overload:
+ * EIP-155 repurposes the v field so that:
+ *   v = 35 + (2 * chainId) + recoveryId(0 or 1)
+ * Any v value >= 35 indicates the chain-id is encoded, preventing cross-chain replay.
+ * r and s values remain unchanged.
+ *
+ * Example:
+ * ```typescript
+ * const rawSig = '0x6c1b...f02b'
+ * try {
+ *   const { r, s, v } = parseSignature(rawSig)
+ *   console.log('R:', r)
+ *   console.log('S:', s)
+ *   console.log('Recovery ID (v):', v)
+ * } catch (err) {
+ *   console.error('Signature parse error:', err.message)
+ * }
+ * ```
+ */
+function parseSignature(signatureHex) {
+    // 1) Remove optional '0x' prefix
+    const hex = signatureHex.startsWith('0x')
+        ? signatureHex.slice(2)
+        : signatureHex;
+    // 2) Validate hex format and length
+    const VALID_HEX_REGEX = /^[0-9a-fA-F]+$/;
+    if (!VALID_HEX_REGEX.test(hex)) {
+        throw new Error('Signature must be a valid hex string (0-9, a-f, A-F).');
+    }
+    if (hex.length !== SIGNATURE_HEX_LENGTH) {
+        throw new Error(`Invalid length: expected ${SIGNATURE_HEX_LENGTH.toString()} hex chars (65 bytes), got ${hex.length.toString()}`);
+    }
+    // 3) Extract components
+    const r = `0x${hex.slice(0, R_HEX_LENGTH)}`;
+    const s = `0x${hex.slice(R_HEX_LENGTH, R_HEX_LENGTH + S_HEX_LENGTH)}`;
+    const vValue = parseInt(hex.slice(R_HEX_LENGTH + S_HEX_LENGTH), 16);
+    // 4) Ensure v is within supported values
+    const isLegacy = LEGACY_V_VALUES.has(vValue);
+    const isEIP155 = vValue >= MIN_EIP155_V;
+    if (!isLegacy && !isEIP155) {
+        throw new Error(`Unsupported v value: ${vValue.toString()}. Must be one of [${[
+            ...LEGACY_V_VALUES,
+        ].join(', ')}] or >=${MIN_EIP155_V.toString()}`);
+    }
+    return { r: r, s: s, v: vValue };
+}
+/**
+ * buildTypedData
+ *
+ * Create an EIP-712 compliant "TypedData" object, encapsulating:
+ *  - Domain separator (application/contract identity, chain ID)
+ *  - Explicit type definitions (field names and types)
+ *  - Primary type name identifying the root object
+ *  - Message payload matching the defined schema
+ *
+ * This enforces structured, non-ambiguous signing, and guards against signature replay.
+ *
+ * @typeParam Types - Map of type names to arrays of { name, type } definitions.
+ * @typeParam Msg - Object whose shape matches the primaryType fields.
+ *
+ * @param domain - EIP712Domain, e.g. { name, version, chainId, verifyingContract }.
+ * @param types - Type definitions, e.g.:
+ *   {
+ *     Mail: [ { name: 'from', type: 'string' }, { name: 'contents', type: 'string' } ],
+ *   }
+ * @param primaryType - Root key in types, e.g. 'Mail'.
+ * @param message - The actual values, e.g. { from: 'Alice', contents: 'Hello' }.
+ *
+ * @returns TypedData object ready for use with signing libraries.
+ *
+ * Example:
+ * ```typescript
+ * const typedData = buildTypedData(
+ *   { name: 'MyDApp', version: '1', chainId: 1, verifyingContract: '0xabc...' },
+ *   { Message: [{ name: 'text', type: 'string' }] },
+ *   'Message',
+ *   { text: 'Hello, EIP-712!' }
+ * )
+ * // Pass typedData to ethers.js signer._signTypedData(domain, types, message)
+ * ```
+ */
+function buildTypedData(domain, types, primaryType, message) {
+    return { domain, types, primaryType, message };
+}
+
+/**
+ * Compute default deadline for permit signatures.
+ *
+ * Returns a timestamp 1 hour (3600 seconds) from the current time,
+ * converted to Unix timestamp format as a bigint. This is commonly
+ * used as the default expiration time for EIP-2612 permit signatures.
+ *
+ * @returns Unix timestamp (in seconds) 1 hour from now as a bigint
+ *
+ * @example
+ * ```typescript
+ * import { computeDefaultDeadline } from '@core/adapter-evm'
+ *
+ * const deadline = computeDefaultDeadline()
+ * console.log(`Permit expires at: ${deadline}`)
+ * // Output: Permit expires at: 1640998800
+ * ```
+ */
+function computeDefaultDeadline() {
+    return BigInt(Math.floor(Date.now() / 1000) + 3600);
+}
+
+/**
+ * EIP-2612 permit type definition.
+ * Defines the structure for permit signatures according to EIP-2612 specification.
+ *
+ * @see {@link https://eips.ethereum.org/EIPS/eip-2612 | EIP-2612 Specification}
+ */
+const EIP2612_TYPES = {
+    Permit: [
+        { name: 'owner', type: 'address' },
+        { name: 'spender', type: 'address' },
+        { name: 'value', type: 'uint256' },
+        { name: 'nonce', type: 'uint256' },
+        { name: 'deadline', type: 'uint256' },
+    ],
+};
+
+/**
+ * Build EIP-2612 typed data for permit signing.
+ *
+ * This function creates the complete EIP-712 typed data structure required
+ * for EIP-2612 permit signatures, including automatic nonce fetching using
+ * the adapter's built-in nonce fetching capability.
+ *
+ * **Address Formatting**: All addresses are automatically formatted with proper
+ * EIP-55 checksumming using the `convertAddress` utility, ensuring compatibility
+ * with strict validation libraries like viem.
+ *
+ * **Nonce Handling**: The nonce can be provided explicitly or will be fetched
+ * automatically using the adapter's `fetchEIP2612Nonce` method, which queries
+ * the token contract's `nonces(owner)` function.
+ *
+ * **Deadline Calculation**: If no deadline is provided, it defaults to 24 hours
+ * from the current time (computed using `computeDefaultDeadline`).
+ *
+ * @param meta - Domain metadata for the token contract
+ * @param adapter - Adapter instance with nonce-fetching capability
+ * @param opts - EIP-2612 permit options including owner, spender, value
+ * @returns Complete EIP-712 typed data ready for signing
+ *
+ * @example
+ * ```typescript
+ * import { buildEIP2612TypedData } from '@core/adapter-evm'
+ *
+ * const typedData = await buildEIP2612TypedData(
+ *   {
+ *     name: 'USD Coin',
+ *     version: '2',
+ *     chainId: 1,
+ *     verifyingContract: '0xa0b86a33e6441e4d178bb0c14ce0e9ce9c83bdd8'
+ *   },
+ *   adapter,
+ *   {
+ *     owner: '0x742d35cc6639c0532fbe9002b3a2265ca4c878f8e',
+ *     spender: '0x1234567890123456789012345678901234567890',
+ *     value: 1000000n
+ *   }
+ * )
+ *
+ * const signature = await adapter.signTypedData(typedData)
+ * ```
+ */
+async function buildEIP2612TypedData(meta, adapter, opts, ctx) {
+    // Format addresses to ensure proper EIP-55 checksumming
+    const formattedOwner = convertAddress(opts.owner, 'evm');
+    const formattedSpender = convertAddress(opts.spender, 'evm');
+    const formattedContract = convertAddress(meta.verifyingContract, 'evm');
+    // Fetch nonce if not provided - adapter handles the contract interaction
+    const nonce = opts.nonce ??
+        (await adapter.fetchEIP2612Nonce(formattedContract, formattedOwner, ctx));
+    /*
+     * Calculate deadline if not provided (24 hours from now)
+     * EIP-2612 deadline is a uint256 in the permit struct, so we use bigint for full compatibility
+     * with on-chain values and to avoid overflow/precision issues with large timestamps.
+     * Most real-world deadlines are within JS safe integer range, but using bigint is safest.
+     */
+    const now = BigInt(Math.floor(Date.now() / 1000));
+    const deadline = opts.deadline !== undefined
+        ? BigInt(opts.deadline)
+        : computeDefaultDeadline();
+    if (deadline <= now) {
+        throw new Error(`EIP-2612 deadline must be in the future (got ${deadline.toString()}, now ${now.toString()})`);
+    }
+    // Build the message with properly formatted addresses
+    const message = {
+        owner: formattedOwner,
+        spender: formattedSpender,
+        value: opts.value,
+        nonce,
+        deadline,
+    };
+    // Return complete typed data structure with formatted contract address
+    return buildTypedData({ ...meta, verifyingContract: formattedContract }, EIP2612_TYPES, 'Permit', message);
+}
+
 /**
  * Checks if a function in an ABI is read-only (view or pure).
  *
@@ -9689,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);
@@ -9698,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 {
@@ -9923,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
@@ -9986,6 +10280,11 @@ class EthersAdapter extends EvmAdapter {
      * ```
      */
     async getAddress(chain) {
+        // Prevent calling getAddress on developer-controlled adapters
+        if (this.capabilities?.addressContext === 'developer-controlled') {
+            throw new Error('Cannot call getAddress() on developer-controlled adapters. ' +
+                'Address must be provided explicitly in the operation context.');
+        }
         // Chain parameter should now be provided by resolveOperationContext
         if (!chain) {
             throw new Error('Chain parameter is required for address resolution. ' +
@@ -10535,8 +10834,12 @@ const createAdapterFromProvider = async (params) => {
     }, resolvedCapabilities);
 };
 
+exports.JsonRpcProvider = ethers.JsonRpcProvider;
 exports.EthersAdapter = EthersAdapter;
+exports.buildEIP2612TypedData = buildEIP2612TypedData;
+exports.computeDefaultDeadline = computeDefaultDeadline;
 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

@@ -17,6 +17,7 @@
  */
 
 import { Provider, Signer as Signer$1, Eip1193Provider } from 'ethers';
+export { JsonRpcProvider } from 'ethers';
 import { Abi } from 'abitype';
 import { TransactionInstruction, Signer } from '@solana/web3.js';
 
@@ -409,6 +410,7 @@ declare enum Blockchain {
     Algorand_Testnet = "Algorand_Testnet",
     Aptos = "Aptos",
     Aptos_Testnet = "Aptos_Testnet",
+    Arc_Testnet = "Arc_Testnet",
     Arbitrum = "Arbitrum",
     Arbitrum_Sepolia = "Arbitrum_Sepolia",
     Avalanche = "Avalanche",
@@ -594,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.
      *
@@ -675,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>;
 }
@@ -707,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.
@@ -1965,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.
      *
@@ -2050,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.
      *
@@ -2295,6 +2311,127 @@ interface TypedData<Types extends Record<string, TypedDataField[]>, Message exte
     /** The message payload to be signed */
     message: Message;
 }
+/**
+ * Standard ECDSA signature format (r, s, v components).
+ *
+ * Used for all EIP-712 and permit/authorization signatures.
+ *
+ * @example
+ * ```typescript
+ * const sig: Signature = { v: 28, r: "0x...", s: "0x..." }
+ * ```
+ */
+interface Signature {
+    /** Recovery identifier (27 or 28) */
+    v: number;
+    /** ECDSA signature r value (32-byte hex string) */
+    r: `0x${string}`;
+    /** ECDSA signature s value (32-byte hex string) */
+    s: `0x${string}`;
+}
+declare const PERMIT_STANDARDS: readonly ["EIP-2612"];
+type KnownPermitStandard = (typeof PERMIT_STANDARDS)[number];
+/**
+ * Supported permit/authorization standards for cross-chain USDC.
+ *
+ * Extend this union as new standards are supported.
+ */
+type PermitStandardName = KnownPermitStandard
+/**
+ * Branded string type to keep this union from collapsing into plain `string`.
+ * This lets TS/your IDE still offer autocomplete for the known literals
+ * while allowing any other string without casting.
+ */
+ | (string & {
+    readonly __brand?: 'PermitStandardName';
+});
+/**
+ * Metadata required to construct an EIP-712 domain.
+ *
+ * Used as input to typed data builders for various standards.
+ *
+ * @example
+ * ```typescript
+ * const meta: DomainMeta = {
+ *   name: "USD Coin",
+ *   version: "2",
+ *   chainId: 1,
+ *   verifyingContract: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
+ * }
+ * ```
+ */
+interface DomainMeta {
+    /** Human-readable name of the signing domain */
+    name: string;
+    /** Current major version of the signing domain */
+    version: string;
+    /** EVM chain ID */
+    chainId: number | bigint;
+    /** Address of the verifying contract */
+    verifyingContract: `0x${string}`;
+}
+
+/**
+ * Utility module for handling ECDSA signatures and EIP-712 typed data.
+ *
+ * This file provides:
+ * 1. parseSignature: Take a raw hexadecimal signature and split it into its three
+ *    ECDSA components: r, s, and v (recovery identifier). Used when verifying
+ *    Ethereum transactions and signed messages.
+ *
+ * 2. buildTypedData: Assemble a data structure compliant with EIP-712, which standardizes
+ *    how structured data is formatted and hashed for secure off-chain signing.
+ *
+ * Key concepts:
+ * - Cryptographic signatures (r, s, v) ensure that only the holder of a private key can
+ *   authorize actions or sign messages. The 'v' component enables recovering the public key
+ *   from the signature, confirming the signer’s identity.
+ * - EIP-712 typed data enforces a clear schema for signing, preventing ambiguous or replayable
+ *   signatures and simplifying integration with common wallet libraries.
+ */
+
+/**
+ * parseSignature
+ *
+ * Parse a 65-byte ECDSA signature into its r, s, and v components, expressed in hex.
+ *
+ * Ethereum signatures are structured as:
+ *   signature = r (32 bytes) || s (32 bytes) || v (1 byte)
+ *
+ * - r, s: Big-endian hex values (32 bytes each)
+ * - v: Recovery identifier, used by secp256k1 to reconstruct the signer’s public key
+ *
+ * @param signatureHex - Signature as a hex string, optionally prefixed with "0x".
+ * @returns { r, s, v }
+ *   - r: Hex string of the R component.
+ *   - s: Hex string of the S component.
+ *   - v: Numeric recovery ID.
+ *
+ * @throws Error if:
+ *   - Input is not valid hex.
+ *   - Incorrect length (must be exactly 65 bytes / 130 hex chars).
+ *   - v is outside the supported range (Legacy or EIP-155 formula).
+ *
+ * Notes on EIP-155 overload:
+ * EIP-155 repurposes the v field so that:
+ *   v = 35 + (2 * chainId) + recoveryId(0 or 1)
+ * Any v value >= 35 indicates the chain-id is encoded, preventing cross-chain replay.
+ * r and s values remain unchanged.
+ *
+ * Example:
+ * ```typescript
+ * const rawSig = '0x6c1b...f02b'
+ * try {
+ *   const { r, s, v } = parseSignature(rawSig)
+ *   console.log('R:', r)
+ *   console.log('S:', s)
+ *   console.log('Recovery ID (v):', v)
+ * } catch (err) {
+ *   console.error('Signature parse error:', err.message)
+ * }
+ * ```
+ */
+declare function parseSignature(signatureHex: string): Signature;
 
 /**
  * Core type definitions for EVM-compatible blockchain transaction execution
@@ -2475,6 +2612,129 @@ declare abstract class EvmAdapter<TAdapterCapabilities extends AdapterCapabiliti
     calculateTransactionFee(baseComputeUnits: bigint, bufferBasisPoints: bigint | undefined, chain: EVMChainDefinition): Promise<EstimatedGas>;
 }
 
+/**
+ * EIP-2612 permit type definition.
+ * Defines the structure for permit signatures according to EIP-2612 specification.
+ *
+ * @see {@link https://eips.ethereum.org/EIPS/eip-2612 | EIP-2612 Specification}
+ */
+declare const EIP2612_TYPES: {
+    readonly Permit: TypedDataField[];
+};
+/**
+ * EIP-2612 permit message structure.
+ * This is the exact data that gets signed according to EIP-2612.
+ */
+interface EIP2612Message extends Record<string, unknown> {
+    /** Token owner address */
+    owner: `0x${string}`;
+    /** Address permitted to spend tokens */
+    spender: `0x${string}`;
+    /** Amount of tokens permitted */
+    value: bigint;
+    /** Current nonce for the owner */
+    nonce: bigint;
+    /** Deadline timestamp (Unix timestamp in seconds) */
+    deadline: bigint;
+}
+/**
+ * Input options for building an EIP-2612 permit.
+ * Nonce and deadline can be omitted and will be fetched/computed automatically.
+ *
+ * **Address Formatting**: Addresses are automatically formatted with proper EIP-55
+ * checksumming, so you can provide addresses in any case format.
+ */
+interface EIP2612Options extends Record<string, unknown> {
+    /** Token owner address (automatically formatted with EIP-55 checksumming) */
+    owner: `0x${string}`;
+    /** Address that will be permitted to spend tokens (automatically formatted with EIP-55 checksumming) */
+    spender: `0x${string}`;
+    /** Amount of tokens to permit */
+    value: bigint;
+    /** Optional nonce - will be fetched from token contract if not provided */
+    nonce?: bigint;
+    /** Optional deadline - will default to 1 hour from now if not provided */
+    deadline?: bigint;
+}
+/**
+ * Function type for fetching nonces from EIP-2612 compatible tokens.
+ *
+ * @param owner - Token owner address
+ * @param token - Token contract address
+ * @returns Promise resolving to current nonce
+ */
+type EIP2612NonceFetcher = (token: `0x${string}`, owner: `0x${string}`) => Promise<bigint>;
+
+interface EIP2612Adapter {
+    fetchEIP2612Nonce(tokenAddress: `0x${string}`, ownerAddress: `0x${string}`, ctx: OperationContext): Promise<bigint>;
+}
+/**
+ * Build EIP-2612 typed data for permit signing.
+ *
+ * This function creates the complete EIP-712 typed data structure required
+ * for EIP-2612 permit signatures, including automatic nonce fetching using
+ * the adapter's built-in nonce fetching capability.
+ *
+ * **Address Formatting**: All addresses are automatically formatted with proper
+ * EIP-55 checksumming using the `convertAddress` utility, ensuring compatibility
+ * with strict validation libraries like viem.
+ *
+ * **Nonce Handling**: The nonce can be provided explicitly or will be fetched
+ * automatically using the adapter's `fetchEIP2612Nonce` method, which queries
+ * the token contract's `nonces(owner)` function.
+ *
+ * **Deadline Calculation**: If no deadline is provided, it defaults to 24 hours
+ * from the current time (computed using `computeDefaultDeadline`).
+ *
+ * @param meta - Domain metadata for the token contract
+ * @param adapter - Adapter instance with nonce-fetching capability
+ * @param opts - EIP-2612 permit options including owner, spender, value
+ * @returns Complete EIP-712 typed data ready for signing
+ *
+ * @example
+ * ```typescript
+ * import { buildEIP2612TypedData } from '@core/adapter-evm'
+ *
+ * const typedData = await buildEIP2612TypedData(
+ *   {
+ *     name: 'USD Coin',
+ *     version: '2',
+ *     chainId: 1,
+ *     verifyingContract: '0xa0b86a33e6441e4d178bb0c14ce0e9ce9c83bdd8'
+ *   },
+ *   adapter,
+ *   {
+ *     owner: '0x742d35cc6639c0532fbe9002b3a2265ca4c878f8e',
+ *     spender: '0x1234567890123456789012345678901234567890',
+ *     value: 1000000n
+ *   }
+ * )
+ *
+ * const signature = await adapter.signTypedData(typedData)
+ * ```
+ */
+declare function buildEIP2612TypedData(meta: DomainMeta, adapter: EIP2612Adapter, opts: EIP2612Options, ctx: OperationContext): Promise<TypedData<typeof EIP2612_TYPES, EIP2612Message>>;
+
+/**
+ * Compute default deadline for permit signatures.
+ *
+ * Returns a timestamp 1 hour (3600 seconds) from the current time,
+ * converted to Unix timestamp format as a bigint. This is commonly
+ * used as the default expiration time for EIP-2612 permit signatures.
+ *
+ * @returns Unix timestamp (in seconds) 1 hour from now as a bigint
+ *
+ * @example
+ * ```typescript
+ * import { computeDefaultDeadline } from '@core/adapter-evm'
+ *
+ * const deadline = computeDefaultDeadline()
+ * console.log(`Permit expires at: ${deadline}`)
+ * // Output: Permit expires at: 1640998800
+ * ```
+ */
+declare function computeDefaultDeadline(): bigint;
+
 /**
  * @packageDocumentation
  * @module EthersAdapter
@@ -3404,5 +3664,5 @@ declare const createAdapterFromProvider: (params: CreateAdapterFromProviderParam
  */
 declare function validateAdapterCapabilities(capabilities: AdapterCapabilities): void;
 
-export { Blockchain, EthersAdapter, createAdapterFromPrivateKey, createAdapterFromProvider, validateAdapterCapabilities };
-export type { ChainIdentifier, CreateAdapterFromPrivateKeyParams, CreateAdapterFromProviderParams, EthersAdapterOptions };
+export { Blockchain, EthersAdapter, buildEIP2612TypedData, computeDefaultDeadline, createAdapterFromPrivateKey, createAdapterFromProvider, parseSignature, validateAdapterCapabilities };
+export type { ChainIdentifier, CreateAdapterFromPrivateKeyParams, CreateAdapterFromProviderParams, EIP2612Message, EIP2612NonceFetcher, EIP2612Options, EthersAdapterOptions, PermitStandardName, Signature, TypedData, TypedDataField };

package/index.mjs

@@ -17,11 +17,12 @@
  */
 
 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.
@@ -262,6 +263,7 @@ var Blockchain;
     Blockchain["Algorand_Testnet"] = "Algorand_Testnet";
     Blockchain["Aptos"] = "Aptos";
     Blockchain["Aptos_Testnet"] = "Aptos_Testnet";
+    Blockchain["Arc_Testnet"] = "Arc_Testnet";
     Blockchain["Arbitrum"] = "Arbitrum";
     Blockchain["Arbitrum_Sepolia"] = "Arbitrum_Sepolia";
     Blockchain["Avalanche"] = "Avalanche";
@@ -482,6 +484,48 @@ const BRIDGE_CONTRACT_EVM_TESTNET = '0xC5567a5E3370d4DBfB0540025078e283e36A363d'
  */
 const BRIDGE_CONTRACT_EVM_MAINNET = '0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0';
 
+/**
+ * Arc Testnet chain definition
+ * @remarks
+ * This represents the test network for the Arc blockchain,
+ * Circle's EVM-compatible Layer-1 designed for stablecoin finance
+ * and asset tokenization. Arc uses USDC as the native gas token and
+ * features the Malachite Byzantine Fault Tolerant (BFT) consensus
+ * engine for sub-second finality.
+ */
+const ArcTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Arc_Testnet,
+    name: 'Arc Testnet',
+    title: 'ArcTestnet',
+    nativeCurrency: {
+        name: 'Arc',
+        symbol: 'Arc',
+        decimals: 18,
+    },
+    chainId: 5042002,
+    isTestnet: true,
+    explorerUrl: 'https://testnet.arcscan.app/tx/{hash}',
+    rpcEndpoints: ['https://rpc.testnet.arc.network/'],
+    eurcAddress: '0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a',
+    usdcAddress: '0x3600000000000000000000000000000000000000',
+    cctp: {
+        domain: 26,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
 /**
  * Arbitrum Mainnet chain definition
  * @remarks
@@ -1773,26 +1817,26 @@ const Sonic = defineChain({
 });
 
 /**
- * Sonic Blaze Testnet chain definition
+ * Sonic Testnet chain definition
  * @remarks
  * This represents the official test network for the Sonic blockchain.
  */
 const SonicTestnet = defineChain({
     type: 'evm',
     chain: Blockchain.Sonic_Testnet,
-    name: 'Sonic Blaze Testnet',
-    title: 'Sonic Blaze Testnet',
+    name: 'Sonic Testnet',
+    title: 'Sonic Testnet',
     nativeCurrency: {
         name: 'Sonic',
         symbol: 'S',
         decimals: 18,
     },
-    chainId: 57054,
+    chainId: 14601,
     isTestnet: true,
     explorerUrl: 'https://testnet.sonicscan.org/tx/{hash}',
-    rpcEndpoints: ['https://rpc.blaze.soniclabs.com'],
+    rpcEndpoints: ['https://rpc.testnet.soniclabs.com'],
     eurcAddress: null,
-    usdcAddress: '0xA4879Fed32Ecbef99399e5cbC247E533421C4eC6',
+    usdcAddress: '0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51',
     cctp: {
         domain: 13,
         contracts: {
@@ -2309,6 +2353,7 @@ var Blockchains = /*#__PURE__*/Object.freeze({
     AptosTestnet: AptosTestnet,
     Arbitrum: Arbitrum,
     ArbitrumSepolia: ArbitrumSepolia,
+    ArcTestnet: ArcTestnet,
     Avalanche: Avalanche,
     AvalancheFuji: AvalancheFuji,
     Base: Base,
@@ -2986,6 +3031,10 @@ class KitError extends Error {
     }
 }
 
+/**
+ * Minimum error code for INPUT type errors.
+ * INPUT errors represent validation failures and invalid parameters.
+ */
 /**
  * Standardized error definitions for INPUT type errors.
  *
@@ -8006,6 +8055,246 @@ class EvmAdapter extends Adapter {
     }
 }
 
+// --- Signature Parsing Constants ---
+const SIGNATURE_BYTE_LENGTH = 65; // Total bytes in an Ethereum signature
+const HEX_CHARS_PER_BYTE = 2;
+const SIGNATURE_HEX_LENGTH = SIGNATURE_BYTE_LENGTH * HEX_CHARS_PER_BYTE;
+const R_HEX_LENGTH = 32 * HEX_CHARS_PER_BYTE; // 32 bytes for 'r'
+const S_HEX_LENGTH = 32 * HEX_CHARS_PER_BYTE; // 32 bytes for 's'
+// --- Recovery ID Validation Constants ---
+/**
+ * Legacy recovery IDs (pre-EIP-155 format):
+ * - 0 or 1 (older clients) or 27, 28 (Ethereum before chain-id inclusion)
+ */
+const LEGACY_V_VALUES = new Set([0, 1, 27, 28]);
+/**
+ * Minimum v value indicating an EIP-155 style signature.
+ * Calculated as 35 + (2 * chainId) + recoveryId (0 or 1).
+ */
+const MIN_EIP155_V = 35;
+/**
+ * parseSignature
+ *
+ * Parse a 65-byte ECDSA signature into its r, s, and v components, expressed in hex.
+ *
+ * Ethereum signatures are structured as:
+ *   signature = r (32 bytes) || s (32 bytes) || v (1 byte)
+ *
+ * - r, s: Big-endian hex values (32 bytes each)
+ * - v: Recovery identifier, used by secp256k1 to reconstruct the signer’s public key
+ *
+ * @param signatureHex - Signature as a hex string, optionally prefixed with "0x".
+ * @returns { r, s, v }
+ *   - r: Hex string of the R component.
+ *   - s: Hex string of the S component.
+ *   - v: Numeric recovery ID.
+ *
+ * @throws Error if:
+ *   - Input is not valid hex.
+ *   - Incorrect length (must be exactly 65 bytes / 130 hex chars).
+ *   - v is outside the supported range (Legacy or EIP-155 formula).
+ *
+ * Notes on EIP-155 overload:
+ * EIP-155 repurposes the v field so that:
+ *   v = 35 + (2 * chainId) + recoveryId(0 or 1)
+ * Any v value >= 35 indicates the chain-id is encoded, preventing cross-chain replay.
+ * r and s values remain unchanged.
+ *
+ * Example:
+ * ```typescript
+ * const rawSig = '0x6c1b...f02b'
+ * try {
+ *   const { r, s, v } = parseSignature(rawSig)
+ *   console.log('R:', r)
+ *   console.log('S:', s)
+ *   console.log('Recovery ID (v):', v)
+ * } catch (err) {
+ *   console.error('Signature parse error:', err.message)
+ * }
+ * ```
+ */
+function parseSignature(signatureHex) {
+    // 1) Remove optional '0x' prefix
+    const hex = signatureHex.startsWith('0x')
+        ? signatureHex.slice(2)
+        : signatureHex;
+    // 2) Validate hex format and length
+    const VALID_HEX_REGEX = /^[0-9a-fA-F]+$/;
+    if (!VALID_HEX_REGEX.test(hex)) {
+        throw new Error('Signature must be a valid hex string (0-9, a-f, A-F).');
+    }
+    if (hex.length !== SIGNATURE_HEX_LENGTH) {
+        throw new Error(`Invalid length: expected ${SIGNATURE_HEX_LENGTH.toString()} hex chars (65 bytes), got ${hex.length.toString()}`);
+    }
+    // 3) Extract components
+    const r = `0x${hex.slice(0, R_HEX_LENGTH)}`;
+    const s = `0x${hex.slice(R_HEX_LENGTH, R_HEX_LENGTH + S_HEX_LENGTH)}`;
+    const vValue = parseInt(hex.slice(R_HEX_LENGTH + S_HEX_LENGTH), 16);
+    // 4) Ensure v is within supported values
+    const isLegacy = LEGACY_V_VALUES.has(vValue);
+    const isEIP155 = vValue >= MIN_EIP155_V;
+    if (!isLegacy && !isEIP155) {
+        throw new Error(`Unsupported v value: ${vValue.toString()}. Must be one of [${[
+            ...LEGACY_V_VALUES,
+        ].join(', ')}] or >=${MIN_EIP155_V.toString()}`);
+    }
+    return { r: r, s: s, v: vValue };
+}
+/**
+ * buildTypedData
+ *
+ * Create an EIP-712 compliant "TypedData" object, encapsulating:
+ *  - Domain separator (application/contract identity, chain ID)
+ *  - Explicit type definitions (field names and types)
+ *  - Primary type name identifying the root object
+ *  - Message payload matching the defined schema
+ *
+ * This enforces structured, non-ambiguous signing, and guards against signature replay.
+ *
+ * @typeParam Types - Map of type names to arrays of { name, type } definitions.
+ * @typeParam Msg - Object whose shape matches the primaryType fields.
+ *
+ * @param domain - EIP712Domain, e.g. { name, version, chainId, verifyingContract }.
+ * @param types - Type definitions, e.g.:
+ *   {
+ *     Mail: [ { name: 'from', type: 'string' }, { name: 'contents', type: 'string' } ],
+ *   }
+ * @param primaryType - Root key in types, e.g. 'Mail'.
+ * @param message - The actual values, e.g. { from: 'Alice', contents: 'Hello' }.
+ *
+ * @returns TypedData object ready for use with signing libraries.
+ *
+ * Example:
+ * ```typescript
+ * const typedData = buildTypedData(
+ *   { name: 'MyDApp', version: '1', chainId: 1, verifyingContract: '0xabc...' },
+ *   { Message: [{ name: 'text', type: 'string' }] },
+ *   'Message',
+ *   { text: 'Hello, EIP-712!' }
+ * )
+ * // Pass typedData to ethers.js signer._signTypedData(domain, types, message)
+ * ```
+ */
+function buildTypedData(domain, types, primaryType, message) {
+    return { domain, types, primaryType, message };
+}
+
+/**
+ * Compute default deadline for permit signatures.
+ *
+ * Returns a timestamp 1 hour (3600 seconds) from the current time,
+ * converted to Unix timestamp format as a bigint. This is commonly
+ * used as the default expiration time for EIP-2612 permit signatures.
+ *
+ * @returns Unix timestamp (in seconds) 1 hour from now as a bigint
+ *
+ * @example
+ * ```typescript
+ * import { computeDefaultDeadline } from '@core/adapter-evm'
+ *
+ * const deadline = computeDefaultDeadline()
+ * console.log(`Permit expires at: ${deadline}`)
+ * // Output: Permit expires at: 1640998800
+ * ```
+ */
+function computeDefaultDeadline() {
+    return BigInt(Math.floor(Date.now() / 1000) + 3600);
+}
+
+/**
+ * EIP-2612 permit type definition.
+ * Defines the structure for permit signatures according to EIP-2612 specification.
+ *
+ * @see {@link https://eips.ethereum.org/EIPS/eip-2612 | EIP-2612 Specification}
+ */
+const EIP2612_TYPES = {
+    Permit: [
+        { name: 'owner', type: 'address' },
+        { name: 'spender', type: 'address' },
+        { name: 'value', type: 'uint256' },
+        { name: 'nonce', type: 'uint256' },
+        { name: 'deadline', type: 'uint256' },
+    ],
+};
+
+/**
+ * Build EIP-2612 typed data for permit signing.
+ *
+ * This function creates the complete EIP-712 typed data structure required
+ * for EIP-2612 permit signatures, including automatic nonce fetching using
+ * the adapter's built-in nonce fetching capability.
+ *
+ * **Address Formatting**: All addresses are automatically formatted with proper
+ * EIP-55 checksumming using the `convertAddress` utility, ensuring compatibility
+ * with strict validation libraries like viem.
+ *
+ * **Nonce Handling**: The nonce can be provided explicitly or will be fetched
+ * automatically using the adapter's `fetchEIP2612Nonce` method, which queries
+ * the token contract's `nonces(owner)` function.
+ *
+ * **Deadline Calculation**: If no deadline is provided, it defaults to 24 hours
+ * from the current time (computed using `computeDefaultDeadline`).
+ *
+ * @param meta - Domain metadata for the token contract
+ * @param adapter - Adapter instance with nonce-fetching capability
+ * @param opts - EIP-2612 permit options including owner, spender, value
+ * @returns Complete EIP-712 typed data ready for signing
+ *
+ * @example
+ * ```typescript
+ * import { buildEIP2612TypedData } from '@core/adapter-evm'
+ *
+ * const typedData = await buildEIP2612TypedData(
+ *   {
+ *     name: 'USD Coin',
+ *     version: '2',
+ *     chainId: 1,
+ *     verifyingContract: '0xa0b86a33e6441e4d178bb0c14ce0e9ce9c83bdd8'
+ *   },
+ *   adapter,
+ *   {
+ *     owner: '0x742d35cc6639c0532fbe9002b3a2265ca4c878f8e',
+ *     spender: '0x1234567890123456789012345678901234567890',
+ *     value: 1000000n
+ *   }
+ * )
+ *
+ * const signature = await adapter.signTypedData(typedData)
+ * ```
+ */
+async function buildEIP2612TypedData(meta, adapter, opts, ctx) {
+    // Format addresses to ensure proper EIP-55 checksumming
+    const formattedOwner = convertAddress(opts.owner, 'evm');
+    const formattedSpender = convertAddress(opts.spender, 'evm');
+    const formattedContract = convertAddress(meta.verifyingContract, 'evm');
+    // Fetch nonce if not provided - adapter handles the contract interaction
+    const nonce = opts.nonce ??
+        (await adapter.fetchEIP2612Nonce(formattedContract, formattedOwner, ctx));
+    /*
+     * Calculate deadline if not provided (24 hours from now)
+     * EIP-2612 deadline is a uint256 in the permit struct, so we use bigint for full compatibility
+     * with on-chain values and to avoid overflow/precision issues with large timestamps.
+     * Most real-world deadlines are within JS safe integer range, but using bigint is safest.
+     */
+    const now = BigInt(Math.floor(Date.now() / 1000));
+    const deadline = opts.deadline !== undefined
+        ? BigInt(opts.deadline)
+        : computeDefaultDeadline();
+    if (deadline <= now) {
+        throw new Error(`EIP-2612 deadline must be in the future (got ${deadline.toString()}, now ${now.toString()})`);
+    }
+    // Build the message with properly formatted addresses
+    const message = {
+        owner: formattedOwner,
+        spender: formattedSpender,
+        value: opts.value,
+        nonce,
+        deadline,
+    };
+    // Return complete typed data structure with formatted contract address
+    return buildTypedData({ ...meta, verifyingContract: formattedContract }, EIP2612_TYPES, 'Permit', message);
+}
+
 /**
  * Checks if a function in an ABI is read-only (view or pure).
  *
@@ -9683,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);
@@ -9692,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 {
@@ -9917,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
@@ -9980,6 +10275,11 @@ class EthersAdapter extends EvmAdapter {
      * ```
      */
     async getAddress(chain) {
+        // Prevent calling getAddress on developer-controlled adapters
+        if (this.capabilities?.addressContext === 'developer-controlled') {
+            throw new Error('Cannot call getAddress() on developer-controlled adapters. ' +
+                'Address must be provided explicitly in the operation context.');
+        }
         // Chain parameter should now be provided by resolveOperationContext
         if (!chain) {
             throw new Error('Chain parameter is required for address resolution. ' +
@@ -10529,5 +10829,5 @@ const createAdapterFromProvider = async (params) => {
     }, resolvedCapabilities);
 };
 
-export { Blockchain, EthersAdapter, createAdapterFromPrivateKey, createAdapterFromProvider, validateAdapterCapabilities };
+export { Blockchain, EthersAdapter, buildEIP2612TypedData, computeDefaultDeadline, createAdapterFromPrivateKey, createAdapterFromProvider, parseSignature, validateAdapterCapabilities };
 //# sourceMappingURL=index.mjs.map

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@circle-fin/adapter-ethers-v6",
-  "version": "1.0.0",
-  "main": "./index.cjs.js",
+  "version": "1.1.0",
+  "description": "EVM blockchain adapter powered by Ethers v6",
+  "main": "./index.cjs",
   "module": "./index.mjs",
   "types": "./index.d.ts",
   "dependencies": {
@@ -21,16 +22,19 @@
     ".": {
       "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": {
+    "access": "public",
     "directory": "../../dist/adapters/ethers.v6"
   }
 }

package/index.cjs.js.map

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