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

package/index.cjs.js

@@ -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).
  *
@@ -9986,6 +10274,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 +10828,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

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",
@@ -2295,6 +2297,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 +2598,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 +3650,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,6 +17,7 @@
  */
 
 import { JsonRpcProvider, Wallet, BrowserProvider, Interface, Contract } from 'ethers';
+export { JsonRpcProvider } from 'ethers';
 import { z } from 'zod';
 import { hexlify, hexZeroPad } from '@ethersproject/bytes';
 import { getAddress } from '@ethersproject/address';
@@ -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).
  *
@@ -9980,6 +10269,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 +10823,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,6 +1,7 @@
 {
   "name": "@circle-fin/adapter-ethers-v6",
-  "version": "1.0.0",
+  "version": "1.0.1",
+  "description": "EVM blockchain adapter powered by Ethers v6",
   "main": "./index.cjs.js",
   "module": "./index.mjs",
   "types": "./index.d.ts",
@@ -31,6 +32,7 @@
     "package.json"
   ],
   "publishConfig": {
+    "access": "public",
     "directory": "../../dist/adapters/ethers.v6"
   }
 }