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

package/index.d.ts

@@ -1168,6 +1168,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 +1533,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 +1626,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 +1995,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 +2108,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 +2152,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 +2173,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.
      *
@@ -2386,19 +2361,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.
      */
@@ -2858,37 +2820,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 +2971,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 +3047,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 +3330,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 +3404,5 @@ declare const createAdapterFromProvider: (params: CreateAdapterFromProviderParam
  */
 declare function validateAdapterCapabilities(capabilities: AdapterCapabilities): void;
 
-export { EthersAdapter, createAdapterFromPrivateKey, createAdapterFromProvider, validateAdapterCapabilities };
+export { Blockchain, EthersAdapter, createAdapterFromPrivateKey, createAdapterFromProvider, validateAdapterCapabilities };
 export type { ChainIdentifier, CreateAdapterFromPrivateKeyParams, CreateAdapterFromProviderParams, EthersAdapterOptions };