@circle-fin/adapter-ethers-v6 0.0.2-alpha.7 → 1.0.1

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",
@@ -1168,6 +1170,14 @@ interface CCTPv2ActionMap {
          * Destination chain definition where tokens will be minted.
          */
         readonly toChain: ChainDefinitionWithCCTPv2;
+        /**
+         * Optional destination wallet address on the destination chain to receive minted USDC.
+         *
+         * When provided (e.g., for Solana), the mint instruction will derive the
+         * recipient's Associated Token Account (ATA) from this address instead of
+         * the adapter's default address.
+         */
+        readonly destinationAddress?: string;
     };
     /**
      * Initiate a cross-chain USDC transfer using a custom bridge contract with preapproval funnel.
@@ -1525,7 +1535,7 @@ interface USDCActionMap {
 /**
  * Central registry of all available action namespaces and their operations.
  *
- * Define the complete action map structure used throughout the bridging kit.
+ * Define the complete action map structure used throughout the bridge kit.
  * Each top-level key represents a namespace (e.g., 'token', 'usdc') containing
  * related operations. The structure supports arbitrary nesting depth through
  * the recursive utility types provided in this module.
@@ -1618,7 +1628,7 @@ type NestedValue<T, K extends string> = K extends `${infer First}.${infer Rest}`
  *
  * @remarks
  * This type serves as the canonical source for all valid action identifiers
- * in the bridging kit. It ensures compile-time validation of action keys
+ * in the bridge kit. It ensures compile-time validation of action keys
  * and enables type-safe action dispatching throughout the application.
  *
  * @see {@link ActionPayload} for extracting parameter types
@@ -1987,26 +1997,6 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * ```
      */
     capabilities?: TAdapterCapabilities;
-    /**
-     * Default chain for operations when none is explicitly provided.
-     *
-     * This allows adapters to have sensible defaults for chain operations,
-     * reducing the need for explicit chain specification in every call.
-     *
-     * @remarks
-     * This is optional for backward compatibility and because some adapter types
-     * (like developer-controlled adapters) may not have meaningful defaults.
-     *
-     * @example
-     * ```typescript
-     * // User-controlled adapter with default chain
-     * defaultChain = Ethereum
-     *
-     * // Developer-controlled adapter (no default)
-     * defaultChain = undefined
-     * ```
-     */
-    defaultChain?: ChainDefinition;
     /**
      * Registry of available actions for this adapter.
      *
@@ -2120,16 +2110,6 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * @returns A promise that resolves to the blockchain address as a string.
      */
     abstract getAddress(chain?: ChainDefinition): Promise<string>;
-    /**
-     * Retrieves the {@link ChainDefinition} object that describes the blockchain
-     * this adapter is configured to interact with.
-     *
-     * This includes information such as the chain ID, name, native currency, etc.,
-     * as defined by the `ChainDefinition` type.
-     *
-     * @returns A promise that resolves to the {@link ChainDefinition} for the current chain.
-     */
-    abstract getChain(): Promise<ChainDefinition>;
     /**
      * Switches the adapter to operate on the specified chain.
      *
@@ -2174,17 +2154,14 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * - **Browser wallet adapters**: Request chain switch via EIP-1193 or equivalent
      * - **Multi-entity adapters**: Validate chain support (operations are contextual)
      *
-     * @param chain - The target chain for operations. If not provided, uses the adapter's defaultChain.
+     * @param chain - The target chain for operations.
      * @returns A promise that resolves when the adapter is operating on the specified chain.
      * @throws When the target chain is not supported or chain switching fails.
      *
      * @remarks
-     * This method replaces the pattern of calling `getChain()` to check current chain and then
-     * manually switching. It provides a declarative "ensure this chain" interface for operations.
-     *
-     * **Backward Compatibility**: The default implementation provides basic validation but
-     * doesn't perform actual chain switching. Concrete adapter implementations should override
-     * this method to provide proper chain switching logic.
+     * This method always calls `switchToChain()` to ensure consistency across all adapter types.
+     * The underlying implementations handle idempotent switching efficiently (e.g., browser wallets
+     * gracefully handle switching to the current chain, private key adapters recreate lightweight clients).
      *
      * @example
      * ```typescript
@@ -2198,7 +2175,7 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * await circleWalletsAdapter.ensureChain(Ethereum)
      * ```
      */
-    ensureChain(chain?: ChainDefinition): Promise<void>;
+    ensureChain(targetChain: ChainDefinition): Promise<void>;
     /**
      * Validate that the target chain is supported by this adapter.
      *
@@ -2320,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
@@ -2386,19 +2484,6 @@ declare abstract class EvmAdapter<TAdapterCapabilities extends AdapterCapabiliti
      * The type of chain this adapter is for.
      */
     chainType: ChainType;
-    /**
-     * Cached EVM chain definition.
-     *
-     * This property holds the most recently synchronized EVM chain definition for the adapter.
-     * It is automatically set by `getChain()` and updated via `syncChain()` when provider events
-     * (such as wallet chain changes) are detected. Setting this property to `undefined` clears
-     * the cached chain, which is useful when resetting adapter state or handling disconnects.
-     *
-     * @remarks
-     * This property narrows the base Adapter's `cachedChain` to the EVM-specific type,
-     * ensuring type safety for EVM operations and consumers.
-     */
-    cachedChain?: EVMChainDefinition;
     /**
      * Cached gas price for the current network.
      */
@@ -2513,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
@@ -2858,37 +3066,6 @@ declare class EthersAdapter<TAdapterCapabilities extends AdapterCapabilities = A
      * ```
      */
     getAddress(chain?: EVMChainDefinition): Promise<string>;
-    /**
-     * Gets the current chain definition.
-     *
-     * TEMP This method is temporary and will be removed once all adapters migrate to the OperationContext pattern.
-     *
-     * **Migration Guide:**
-     *
-     * With the OperationContext pattern, chain information is provided explicitly in each operation
-     * rather than queried from the adapter. This eliminates ambiguity and enables seamless multi-chain
-     * operations with a single adapter instance.
-     *
-     * **Before (Deprecated):**
-     * ```typescript
-     * const chain = await adapter.getChain()
-     * const prepared = await adapter.prepare(params) // Uses cached chain
-     * ```
-     *
-     * **After (OperationContext):**
-     * ```typescript
-     * // Chain specified explicitly per operation
-     * const prepared = await adapter.prepare(params, { chain: 'Ethereum' })
-     *
-     * // Multi-chain operations with same adapter
-     * const ethPrepared = await adapter.prepare(params, { chain: 'Ethereum' })
-     * const basePrepared = await adapter.prepare(params, { chain: 'Base' })
-     * ```
-     *
-     * @returns A promise that resolves to the first supported chain from capabilities
-     * @throws Error when no supported chains are configured
-     */
-    getChain(): Promise<ChainDefinition>;
     /**
      * Waits for a transaction to be mined and confirmed on the blockchain.
      *
@@ -3040,9 +3217,10 @@ declare class EthersAdapter<TAdapterCapabilities extends AdapterCapabilities = A
 interface CreateAdapterFromPrivateKeyParams<TCapabilities extends Partial<AdapterCapabilities> = AdapterCapabilities> {
     /**
      * The private key to use for wallet derivation.
-     * Must be a valid 32-byte hex string prefixed with '0x'.
+     * Must be a valid 32-byte hex string, with or without '0x' prefix.
+     * If the prefix is omitted, it will be added automatically during validation.
      */
-    privateKey: `0x${string}`;
+    privateKey: string;
     /**
      * Optional function to create providers for different chains.
      * If not provided, a default implementation using JsonRpcProvider will be used.
@@ -3115,16 +3293,17 @@ interface CreateAdapterFromPrivateKeyParams<TCapabilities extends Partial<Adapte
  * ```typescript
  * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
  *
- * // Minimal configuration with lazy initialization
- * const adapter = createAdapterFromPrivateKey({
- *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
- *   // Defaults applied:
- *   // - addressContext: 'user-controlled'
- *   // - supportedChains: all EVM chains (~29 networks)
+ * // Both private key formats are supported (with or without '0x' prefix):
+ * const adapter1 = createAdapterFromPrivateKey({
+ *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' // With prefix
+ * })
+ *
+ * const adapter2 = createAdapterFromPrivateKey({
+ *   privateKey: '1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' // Without prefix (automatically normalized)
  * })
  *
  * // Chain specified per-operation via OperationContext
- * const prepared = await adapter.prepare({
+ * const prepared = await adapter1.prepare({
  *   address: '0x...',
  *   abi: contractAbi,
  *   functionName: 'transfer',
@@ -3397,13 +3576,13 @@ interface CreateAdapterFromProviderParams {
  * ```typescript
  * // Cross-chain transfer using a single adapter
  * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
- * import { BridgingKit } from '@circle-fin/bridging-kit'
+ * import { BridgeKit } from '@circle-fin/bridge-kit'
  *
  * const adapter = await createAdapterFromProvider({
  *   provider: window.ethereum
  * })
  *
- * const kit = new BridgingKit()
+ * const kit = new BridgeKit()
  *
  * // Use the same adapter for both source and destination
  * const result = await kit.bridge({
@@ -3471,5 +3650,5 @@ declare const createAdapterFromProvider: (params: CreateAdapterFromProviderParam
  */
 declare function validateAdapterCapabilities(capabilities: AdapterCapabilities): void;
 
-export { 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 };