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

package/index.d.ts

@@ -423,6 +423,10 @@ declare enum Blockchain {
     Ethereum_Sepolia = "Ethereum_Sepolia",
     Hedera = "Hedera",
     Hedera_Testnet = "Hedera_Testnet",
+    HyperEVM = "HyperEVM",
+    HyperEVM_Testnet = "HyperEVM_Testnet",
+    Ink = "Ink",
+    Ink_Testnet = "Ink_Testnet",
     Linea = "Linea",
     Linea_Sepolia = "Linea_Sepolia",
     NEAR = "NEAR",
@@ -433,6 +437,8 @@ declare enum Blockchain {
     Optimism_Sepolia = "Optimism_Sepolia",
     Polkadot_Asset_Hub = "Polkadot_Asset_Hub",
     Polkadot_Westmint = "Polkadot_Westmint",
+    Plume = "Plume",
+    Plume_Testnet = "Plume_Testnet",
     Polygon = "Polygon",
     Polygon_Amoy_Testnet = "Polygon_Amoy_Testnet",
     Sei = "Sei",
@@ -449,6 +455,8 @@ declare enum Blockchain {
     Unichain_Sepolia = "Unichain_Sepolia",
     World_Chain = "World_Chain",
     World_Chain_Sepolia = "World_Chain_Sepolia",
+    XDC = "XDC",
+    XDC_Apothem = "XDC_Apothem",
     ZKSync_Era = "ZKSync_Era",
     ZKSync_Sepolia = "ZKSync_Sepolia"
 }
@@ -618,10 +626,6 @@ type EvmPreparedChainRequestParams = {
     functionName: string;
     /** The arguments to pass to the function. */
     args: unknown[];
-    /**
-     * The chain the prepared request should be executed on.
-     */
-    chain: EVMChainDefinition;
 } & Partial<EvmEstimateOverrides>;
 /**
  * Solana-specific parameters for preparing a transaction.
@@ -787,6 +791,147 @@ interface WaitForTransactionConfig {
      */
     maxSupportedTransactionVersion?: number;
 }
+/**
+ * Type utility to extract the address context from adapter capabilities.
+ *
+ * @typeParam TAdapterCapabilities - The adapter capabilities type
+ * @returns The address context type or never if capabilities are undefined
+ */
+type ExtractAddressContext<TAdapterCapabilities extends AdapterCapabilities> = TAdapterCapabilities extends {
+    addressContext: infer TContext;
+} ? TContext : never;
+type AddressField<TAddressContext> = TAddressContext extends 'user-controlled' ? {
+    /**
+     * ℹ️ Address is forbidden for user-controlled adapters.
+     *
+     * User-controlled adapters (like browser wallets or private key adapters)
+     * automatically resolve the address from the connected wallet or signer.
+     * Providing an explicit address would conflict with this behavior.
+     *
+     * @example
+     * ```typescript
+     * // ℹ️ This will cause a TypeScript error:
+     * const context: AdapterContext<{ addressContext: 'user-controlled' }> = {
+     *   adapter: userAdapter,
+     *   chain: 'Ethereum',
+     *   address: '0x123...' // Error: Address is forbidden for user-controlled adapters
+     * }
+     * ```
+     */
+    address?: never;
+} : TAddressContext extends 'developer-controlled' ? {
+    /**
+     * ℹ️ Address is required for developer-controlled adapters.
+     *
+     * Developer-controlled adapters (like enterprise providers or server-side adapters)
+     * require an explicit address for each operation since they don't have a single
+     * connected wallet. The address must be provided for every operation.
+     *
+     * @example
+     * ```typescript
+     * // ℹ️ This is required:
+     * const context: AdapterContext<{ addressContext: 'developer-controlled' }> = {
+     *   adapter: devAdapter,
+     *   chain: 'Ethereum',
+     *   address: '0x123...' // Required for developer-controlled adapters
+     * }
+     *
+     * // ℹ️ This will cause a TypeScript error:
+     * const context: AdapterContext<{ addressContext: 'developer-controlled' }> = {
+     *   adapter: devAdapter,
+     *   chain: 'Ethereum'
+     *   // Error: Address is required for developer-controlled adapters
+     * }
+     * ```
+     */
+    address: string;
+} : {
+    /**
+     * Address is optional for legacy adapters.
+     *
+     * Legacy adapters without defined capabilities maintain backward compatibility
+     * by allowing optional address specification.
+     */
+    address?: string;
+};
+/**
+ * Generic operation context for adapter methods with compile-time address validation.
+ *
+ * This type provides compile-time enforcement of address requirements based on the
+ * adapter's capabilities. The address field behavior is determined by the adapter's
+ * address control model:
+ *
+ * - **User-controlled adapters** (default): The `address` field is forbidden (never) because
+ *   the address is automatically resolved from the connected wallet or signer.
+ * - **Developer-controlled adapters**: The `address` field is required (string) because
+ *   each operation must explicitly specify which address to use.
+ * - **Legacy adapters**: The `address` field remains optional for backward compatibility.
+ *
+ * @typeParam TAdapterCapabilities - The adapter capabilities type to derive address requirements from
+ *
+ * @example
+ * ```typescript
+ * import { OperationContext } from '@core/adapter'
+ *
+ * // User-controlled adapter context (default - address forbidden)
+ * type UserContext = OperationContext<{ addressContext: 'user-controlled', supportedChains: [] }>
+ * const userCtx: UserContext = {
+ *   chain: 'Ethereum'
+ *   // address: '0x123...' // ❌ TypeScript error: address not allowed
+ * }
+ *
+ * // Developer-controlled adapter context (explicit - address required)
+ * type DevContext = OperationContext<{ addressContext: 'developer-controlled', supportedChains: [] }>
+ * const devCtx: DevContext = {
+ *   chain: 'Ethereum',
+ *   address: '0x123...' // ✅ Required for developer-controlled
+ * }
+ * ```
+ */
+type OperationContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> = {
+    /**
+     * The blockchain network to use for this operation.
+     */
+    chain: ChainIdentifier;
+} & AddressField<ExtractAddressContext<TAdapterCapabilities>>;
+/**
+ * Fully resolved context for an adapter operation, with concrete chain and address.
+ *
+ * This interface guarantees that both the blockchain network (`chain`) and the account
+ * address (`address`) are present and valid. It is produced by resolving an {@link OperationContext},
+ * which may have optional or conditional fields, into a form suitable for internal logic and action handlers.
+ *
+ * - `chain`: A fully resolved {@link ChainDefinition}, either explicitly provided or inferred from the adapter.
+ * - `address`: A string representing the resolved account address, determined by the context or adapter,
+ *   depending on the address control model (developer- or user-controlled).
+ *
+ * Use this type when an operation requires both the chain and address to be unambiguous and available.
+ *
+ * @example
+ * ```ts
+ * import { ResolvedOperationContext} from "@core/adapter"
+ * import { Solana, ChainDefinition } from '@core/chains';
+ *
+ * const context: ResolvedOperationContext = {
+ *   chain: Solana,
+ *   address: '7Gk1v...abc123', // a valid Solana address
+ * };
+ *
+ * // Use context.chain and context.address in adapter operations
+ * ```
+ */
+interface ResolvedOperationContext {
+    /**
+     * The chain identifier for this operation.
+     * Guaranteed to be defined - either from context or adapter default.
+     */
+    chain: ChainDefinition;
+    /**
+     * The address for this operation.
+     * Guaranteed to be defined - either specified (developer-controlled) or resolved (user-controlled).
+     */
+    address: string;
+}
 
 /**
  * Base interface for all action parameter objects.
@@ -1023,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.
@@ -1116,7 +1269,7 @@ interface CCTPv2ActionMap {
          *
          * @defaultValue 0n - no protocol fee for basic usage
          */
-        protocolFee?: bigint;
+        protocolFee?: bigint | undefined;
         /**
          * Address to receive the protocol fee.
          *
@@ -1126,7 +1279,7 @@ interface CCTPv2ActionMap {
          *
          * @defaultValue bridge contract address - safe fallback for zero fees
          */
-        feeRecipient?: string;
+        feeRecipient?: string | undefined;
         /**
          * Source chain definition where tokens will be burned.
          */
@@ -1380,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.
@@ -1473,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
@@ -1515,18 +1668,23 @@ type ActionPayload<T extends ActionKeys> = Omit<NestedValue<ActionMap, T>, '__is
  *
  * @typeParam TActionKey - The specific action key this handler processes.
  * @param params - The action payload matching the specified action key.
+ * @param context - The resolved operation context with concrete chain and address values.
  * @returns A promise resolving to a prepared chain request.
  *
  * @example
  * ```typescript
  * import type { ActionHandler } from '@core/adapter'
  *
- * const depositHandler: ActionHandler<'cctp.v2.depositForBurn'> = async (params) => {
- *   // Handler logic here
+ * const depositHandler: ActionHandler<'cctp.v2.depositForBurn'> = async (params, context) => {
+ *   // context is always defined and has concrete chain and address values
+ *   console.log(context.chain.name);
+ *   console.log(context.address);
+ *   // ... handler logic ...
+ *   return preparedRequest;
  * }
  * ```
  */
-type ActionHandler<TActionKey extends ActionKeys> = (params: ActionPayload<TActionKey>) => Promise<PreparedChainRequest>;
+type ActionHandler<TActionKey extends ActionKeys> = (params: ActionPayload<TActionKey>, context: ResolvedOperationContext) => Promise<PreparedChainRequest>;
 /**
  * Type-safe mapping of all available action keys to their corresponding handlers.
  *
@@ -1536,7 +1694,7 @@ type ActionHandler<TActionKey extends ActionKeys> = (params: ActionPayload<TActi
  * handler registration and lookup for all supported actions in the Stablecoin Kits.
  *
  * @remarks
- * Each handler is typed as {@link ActionHandler<ActionKeys>}, which means the handler
+ * Each handler is typed as {@link ActionHandler}, which means the handler
  * must accept the payload type for the specific action key it is registered under.
  * This provides type safety for handler registration and execution, but does not
  * enforce per-key handler parameterization at the type level. For stricter per-key
@@ -1548,12 +1706,14 @@ type ActionHandler<TActionKey extends ActionKeys> = (params: ActionPayload<TActi
  * import type { ActionHandler } from '@core/adapter'
  *
  * const handlers: ActionHandlers = {
- *   'cctp.v2.depositForBurn': async (params) => {
+ *   'cctp.v2.depositForBurn': async (params, resolved) => {
  *     // params is correctly typed for 'cctp.v2.depositForBurn'
+ *     // resolved has concrete chain and address values
  *     // ...handler logic...
  *   },
- *   'usdc.approve': async (params) => {
+ *   'usdc.approve': async (params, resolved) => {
  *     // params is correctly typed for 'usdc.approve'
+ *     // resolved has concrete chain and address values
  *     // ...handler logic...
  *   }
  * }
@@ -1591,8 +1751,8 @@ declare class ActionRegistry {
      * @param handler - The handler function for processing this action type.
      * @returns Void.
      *
-     * @throws {Error} When action parameter is not a valid string.
-     * @throws {TypeError} When handler parameter is not a function.
+     * @throws Error When action parameter is not a valid string.
+     * @throws TypeError When handler parameter is not a function.
      *
      * @example
      * ```typescript
@@ -1602,7 +1762,7 @@ declare class ActionRegistry {
      * const registry = new ActionRegistry()
      *
      * // Register a CCTP deposit handler
-     * const depositHandler: ActionHandler<'cctp.v2.depositForBurn'> = async (params) => {
+     * const depositHandler: ActionHandler<'cctp.v2.depositForBurn'> = async (params, resolved) => {
      *   console.log('Processing deposit:', params.amount)
      *   return {
      *     chainId: params.chainId,
@@ -1639,14 +1799,14 @@ declare class ActionRegistry {
      *
      * // Register multiple handlers at once
      * const tokenHandlers: ActionHandlers = {
-     *   'token.approve': async (params) => ({
-     *     chainId: params.chainId,
+     *   'token.approve': async (params, resolved) => ({
+     *     chainId: resolved.chain,
      *     data: '0x095ea7b3...',
      *     to: params.tokenAddress,
      *     value: '0'
      *   }),
-     *   'token.transfer': async (params) => ({
-     *     chainId: params.chainId,
+     *   'token.transfer': async (params, resolved) => ({
+     *     chainId: resolved.chain,
      *     data: '0xa9059cbb...',
      *     to: params.tokenAddress,
      *     value: '0'
@@ -1698,13 +1858,14 @@ declare class ActionRegistry {
      * Execute a registered action handler with type-safe parameters.
      *
      * Look up and execute the handler associated with the given action key,
-     * passing the provided parameters and returning the resulting prepared
+     * passing the provided parameters and context, returning the resulting prepared
      * chain request. TypeScript ensures the parameters match the expected
      * structure for the specified action.
      *
      * @typeParam TActionKey - The specific action key being executed.
      * @param action - The action key identifying which handler to execute.
      * @param params - The parameters to pass to the action handler.
+     * @param context - The resolved operation context with concrete chain and address values.
      * @returns A promise resolving to the prepared chain request.
      *
      * @throws {Error} When action parameter is not a valid string.
@@ -1719,78 +1880,76 @@ declare class ActionRegistry {
      * const registry = new ActionRegistry()
      *
      * // First register a handler
-     * registry.registerHandler('token.approve', async (params) => ({
-     *   chainId: params.chainId,
+     * registry.registerHandler('token.approve', async (params, context) => ({
+     *   chainId: context.chain, // Always defined
      *   data: '0x095ea7b3...',
      *   to: params.tokenAddress,
      *   value: '0'
      * }))
      *
-     * // Execute the action with type-safe parameters
+     * // Execute the action with resolved context (typically called from adapter.prepareAction)
+     * const resolvedContext = { chain: 'Base', address: '0x123...' }
      * const result = await registry.executeAction('token.approve', {
      *   chainId: ChainEnum.Ethereum,
      *   tokenAddress: '0xA0b86a33E6441c8C1c7C16e4c5e3e5b5e4c5e3e5b5e4c5e',
      *   delegate: '0x1234567890123456789012345678901234567890',
      *   amount: '1000000'
-     * })
+     * }, resolvedContext)
      *
      * console.log('Transaction prepared:', result.data)
      * ```
      */
-    executeAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>): Promise<PreparedChainRequest>;
+    executeAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>, context: ResolvedOperationContext): Promise<PreparedChainRequest>;
 }
 
 /**
  * Defines the capabilities of an adapter, including address handling patterns and supported chains.
  *
- * @interface AdapterCapabilities
+ * @interface TAdapterCapabilities
  * @category Types
  * @description
- * This interface helps determine the behavior of an adapter, especially how it handles
- * address resolution and chain operations. Different adapter types have different
- * requirements for explicit context in operations.
+ * This interface specifies how an adapter manages address control and which blockchain networks it supports.
+ * It is used for capability discovery, validation, and to inform consumers about the adapter's operational model.
+ *
+ * The `addressContext` property determines both address selection behavior and bridge API requirements:
+ * - `'user-controlled'`: User controls addresses through wallet UI, address optional in operations
+ * - `'developer-controlled'`: Service manages addresses programmatically, address required in operations
  *
  * @example
  * ```typescript
- * // Single address adapter (private key)
+ * // Browser wallet adapter (user-controlled)
  * const capabilities: AdapterCapabilities = {
- *   addressContext: 'single',
- *   supportedChains: [Ethereum, Base, Polygon],
- *   availableAddresses: ['0x123...']
+ *   addressContext: 'user-controlled', // User selects address in wallet UI
+ *   supportedChains: [Ethereum, Base, Polygon]
  * }
  *
- * // Multi-entity adapter (institutional)
+ * // Enterprise provider adapter (developer-controlled)
  * const capabilities: AdapterCapabilities = {
- *   addressContext: 'multi-entity',
- *   supportedChains: [Ethereum, Base, Solana],
- *   availableAddresses: undefined // Too many to fetch
+ *   addressContext: 'developer-controlled', // Address must be specified per operation
+ *   supportedChains: [Ethereum, Base, Solana]
  * }
  * ```
  */
 interface AdapterCapabilities {
     /**
-     * Defines how the adapter handles addresses.
+     * Defines who controls address selection for wallet operations.
      *
-     * - `'single'`: Adapter controls exactly one address (e.g., private key adapter)
-     * - `'user-accounts'`: Adapter controls user's personal addresses (e.g., MetaMask)
-     * - `'multi-entity'`: Adapter manages addresses for multiple entities (e.g., Circle Wallets)
+     * - `'user-controlled'`: User controls addresses through wallet UI (browser wallets, hardware wallets)
+     *   - Address is implicit in bridge operations (uses wallet's current address)
+     *   - Adapter may listen for accountsChanged/chainChanged events
+     *   - Suitable for MetaMask, Coinbase Wallet, WalletConnect, private keys, etc.
+     *
+     * - `'developer-controlled'`: Service manages addresses programmatically (enterprise providers)
+     *   - Address must be explicitly provided in bridge operations
+     *   - No event listening (addresses controlled programmatically)
+     *   - Suitable for Fireblocks, Circle Wallets, institutional custody, etc.
      */
-    addressContext: 'single' | 'user-accounts' | 'multi-entity';
+    addressContext: 'user-controlled' | 'developer-controlled';
     /**
-     * List of blockchain networks that this adapter can interact with.
-     * Used for validation and capability discovery.
+     * The set of blockchain networks this adapter supports.
+     * Used for validation, capability discovery, and to restrict operations to supported chains.
      */
     supportedChains: ChainDefinition[];
-    /**
-     * Available addresses for single and user-accounts adapters.
-     *
-     * - For `single` adapters: Contains exactly one address
-     * - For `user-accounts` adapters: Contains user's available addresses
-     * - For `multi-entity` adapters: Should be undefined (too many addresses to list)
-     *
-     * This is populated during adapter creation to avoid repeated network calls.
-     */
-    availableAddresses?: string[];
 }
 /**
  * Abstract class defining the standard interface for an adapter that interacts with a specific blockchain.
@@ -1801,63 +1960,41 @@ interface AdapterCapabilities {
  *
  * This abstraction allows the Stablecoin Kits to work with multiple blockchains in a uniform way.
  *
+ * @typeParam TAdapterCapabilities - The adapter capabilities type for compile-time address validation.
+ * When provided, enables strict typing of operation context based on the adapter's address control model.
  */
-declare abstract class Adapter {
+declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
     /**
      * The type of the chain.
      * @example 'evm', 'solana'
      */
     abstract chainType: ChainType;
     /**
-     * Capabilities of this adapter, defining address handling patterns and supported chains.
+     * Capabilities of this adapter, defining address control model and supported chains.
      *
-     * This property helps determine how the adapter behaves, especially for address resolution
-     * and chain operations. Different adapter types have different requirements for explicit
-     * context in operations.
+     * This property determines how the adapter behaves, especially for address selection
+     * and bridge API requirements. The `addressContext` must match the adapter's type parameter.
      *
      * @remarks
-     * This is optional for backward compatibility during the migration period.
-     * New adapters should always define this property.
+     * The `addressContext` value must align with the adapter's generic type parameter for proper
+     * type safety in bridge operations.
      *
      * @example
      * ```typescript
-     * // Private key adapter
+     * // User-controlled adapter (private key, browser wallet)
      * capabilities = {
-     *   addressContext: 'single',
-     *   supportedChains: [Ethereum, Base],
-     *   availableAddresses: ['0x123...']
+     *   addressContext: 'user-controlled', // Address implicit in bridge operations
+     *   supportedChains: [Ethereum, Base, Polygon]
      * }
      *
-     * // Browser wallet adapter
+     * // Developer-controlled adapter (enterprise provider)
      * capabilities = {
-     *   addressContext: 'user-accounts',
-     *   supportedChains: [Ethereum, Base, Polygon],
-     *   availableAddresses: ['0x123...', '0x456...']
+     *   addressContext: 'developer-controlled', // Address required in bridge operations
+     *   supportedChains: [Ethereum, Base, Solana]
      * }
      * ```
      */
-    capabilities?: AdapterCapabilities;
-    /**
-     * 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.
-     * Multi-entity adapters typically don't have a default chain.
-     *
-     * @remarks
-     * This is optional for backward compatibility and because some adapter types
-     * (like multi-entity adapters) may not have meaningful defaults.
-     *
-     * @example
-     * ```typescript
-     * // Private key adapter with default chain
-     * defaultChain = Ethereum
-     *
-     * // Multi-entity adapter (no default)
-     * defaultChain = undefined
-     * ```
-     */
-    defaultChain?: ChainDefinition;
+    capabilities?: TAdapterCapabilities;
     /**
      * Registry of available actions for this adapter.
      *
@@ -1877,6 +2014,12 @@ declare abstract class Adapter {
      * {@link PreparedChainRequest} allows developers to estimate gas costs and execute
      * the transaction at a later time, enabling pre-flight simulation and deferred execution.
      *
+     * **Compile-time Address Validation**: When used with typed adapters that have capabilities,
+     * this method enforces address requirements at compile time:
+     * - **User-controlled adapters**: The `address` field is forbidden in the context
+     * - **Developer-controlled adapters**: The `address` field is required in the context
+     * - **Legacy adapters**: The `address` field remains optional for backward compatibility
+     *
      * @remarks
      * This method does not send any transaction to the network. Instead, it returns a
      * prepared request object with `estimate()` and `execute()` methods, allowing
@@ -1884,9 +2027,30 @@ declare abstract class Adapter {
      *
      * @param action - The action key identifying which handler to use for preparation.
      * @param params - The parameters to pass to the action handler.
+     * @param ctx - Operation context with compile-time validated address requirements based on adapter capabilities.
      * @returns A promise that resolves to a {@link PreparedChainRequest} for estimation and execution.
+     * @throws Error If the specified action key does not correspond to a registered handler.
+     * @throws Error If the provided parameters are invalid for the action.
+     * @throws Error If the operation context cannot be resolved.
+     *
+     * @example
+     * ```typescript
+     * // User-controlled adapter (address forbidden)
+     * const userAdapter: Adapter<{ addressContext: 'user-controlled', supportedChains: [] }>
+     * await userAdapter.prepareAction('token.approve', params, {
+     *   chain: 'Ethereum'
+     *   // address: '0x123...' // ❌ TypeScript error: address not allowed
+     * })
+     *
+     * // Developer-controlled adapter (address required)
+     * const devAdapter: Adapter<{ addressContext: 'developer-controlled', supportedChains: [] }>
+     * await devAdapter.prepareAction('token.approve', params, {
+     *   chain: 'Ethereum',
+     *   address: '0x123...' // ✅ Required for developer-controlled
+     * })
+     * ```
      */
-    prepareAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>): 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.
      *
@@ -1899,6 +2063,12 @@ declare abstract class Adapter {
      *  - `execute()`: Asynchronously executes the prepared transaction and returns a promise that resolves
      *                 with the transaction result (e.g., a transaction hash, receipt, or other chain-specific response).
      *
+     * **Compile-time Address Validation**: When used with typed adapters that have capabilities,
+     * this method enforces address requirements at compile time:
+     * - **User-controlled adapters**: The `address` field is forbidden in the context
+     * - **Developer-controlled adapters**: The `address` field is required in the context
+     * - **Legacy adapters**: The `address` field remains optional for backward compatibility
+     *
      * @remarks
      * The specific parameters for `prepare` might vary greatly between chain implementations.
      * Consider defining a generic type or a base type for `transactionRequest` if common patterns emerge,
@@ -1906,28 +2076,38 @@ declare abstract class Adapter {
      * For this abstract definition, we keep it parameter-less, assuming implementations will add specific
      * parameters as needed for their `prepare` method (e.g. `prepare(txDetails: MyChainTxDetails)`).
      *
+     * @param params - The prepared chain request parameters for the specific blockchain.
+     * @param ctx - Operation context with compile-time validated address requirements based on adapter capabilities.
      * @returns An object containing `estimate` and `execute` methods for the prepared transaction.
+     *
+     * @example
+     * ```typescript
+     * // User-controlled adapter (address forbidden)
+     * const userAdapter: Adapter<{ addressContext: 'user-controlled', supportedChains: [] }>
+     * await userAdapter.prepare(params, {
+     *   chain: 'Ethereum'
+     *   // address: '0x123...' // ❌ TypeScript error: address not allowed
+     * })
+     *
+     * // Developer-controlled adapter (address required)
+     * const devAdapter: Adapter<{ addressContext: 'developer-controlled', supportedChains: [] }>
+     * await devAdapter.prepare(params, {
+     *   chain: 'Ethereum',
+     *   address: '0x123...' // ✅ Required for developer-controlled
+     * })
+     * ```
      */
-    abstract prepare(params: PreparedChainRequestParams): Promise<PreparedChainRequest>;
+    abstract prepare(params: PreparedChainRequestParams, ctx: OperationContext<TAdapterCapabilities>): Promise<PreparedChainRequest>;
     /**
      * Retrieves the public address of the connected wallet.
      *
      * This address is used as the default sender for transactions
      * and interactions initiated by this adapter.
      *
+     * @param chain - Optional chain definition for chain-specific address resolution (used by EVM adapters)
      * @returns A promise that resolves to the blockchain address as a string.
      */
-    abstract getAddress(): 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>;
+    abstract getAddress(chain?: ChainDefinition): Promise<string>;
     /**
      * Switches the adapter to operate on the specified chain.
      *
@@ -1972,17 +2152,14 @@ declare abstract class Adapter {
      * - **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
@@ -1996,7 +2173,7 @@ declare abstract class Adapter {
      * await circleWalletsAdapter.ensureChain(Ethereum)
      * ```
      */
-    ensureChain(chain?: ChainDefinition): Promise<void>;
+    ensureChain(targetChain: ChainDefinition): Promise<void>;
     /**
      * Validate that the target chain is supported by this adapter.
      *
@@ -2012,9 +2189,10 @@ declare abstract class Adapter {
      *
      * @param txHash - The hash of the transaction to wait for.
      * @param config - Optional configuration for waiting behavior including timeout and confirmations.
+     * @param chain - The chain definition where the transaction was submitted.
      * @returns Promise resolving to comprehensive transaction details.
      */
-    abstract waitForTransaction(txHash: string, config?: WaitForTransactionConfig): Promise<WaitForTransactionResponse>;
+    abstract waitForTransaction(txHash: string, config: WaitForTransactionConfig | undefined, chain: ChainDefinition): Promise<WaitForTransactionResponse>;
     /**
      * Calculate the total transaction fee including compute cost and buffer for the configured chain.
      *
@@ -2024,11 +2202,25 @@ declare abstract class Adapter {
      *
      * @param baseComputeUnits - The base compute units for the transaction (gas for EVM, compute units for Solana, etc.).
      * @param bufferBasisPoints - The buffer to add as basis points (e.g., 500 = 5%). Defaults to implementation-specific value.
+     * @param chain - The chain definition to calculate fees for.
      * @returns A promise that resolves to the total transaction fee as a bigint.
      */
-    abstract calculateTransactionFee(baseComputeUnits: bigint, bufferBasisPoints?: bigint): Promise<EstimatedGas>;
+    abstract calculateTransactionFee(baseComputeUnits: bigint, bufferBasisPoints: bigint | undefined, chain: ChainDefinition): Promise<EstimatedGas>;
 }
 
+/**
+ * Type utility that infers the final adapter capabilities from partial overrides.
+ * This provides clean type inference without complex conditional types.
+ */
+type InferAdapterCapabilities<T extends Partial<AdapterCapabilities>> = T & {
+    addressContext: T extends {
+        addressContext: infer A;
+    } ? A : 'user-controlled';
+    supportedChains: T extends {
+        supportedChains: infer S;
+    } ? S : ChainDefinition[];
+};
+
 /**
  * EIP-712 domain structure for typed data signing.
  *
@@ -2160,12 +2352,19 @@ interface ReadContractParams {
  * The signTypedData method uses a generic TypedData interface from the signTypedData module,
  * making it compatible with any EIP-712 standard (EIP-2612, EIP-7597, ERC-3009, etc.) while
  * maintaining type safety throughout the signing process.
+ *
+ * Includes caching and synchronization capabilities for provider-based adapters that need
+ * to respond to account and chain changes from external wallets (e.g., MetaMask).
  */
-declare abstract class EvmAdapter extends Adapter {
+declare abstract class EvmAdapter<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> extends Adapter<TAdapterCapabilities> {
     /**
      * The type of chain this adapter is for.
      */
     chainType: ChainType;
+    /**
+     * Cached gas price for the current network.
+     */
+    cachedGasPrice?: bigint;
     /**
      * The constructor for the EVM adapter.
      *
@@ -2183,8 +2382,10 @@ declare abstract class EvmAdapter extends Adapter {
      * @typeParam Types - The EIP-712 types definition for the standard being signed
      * @typeParam Message - The message structure for the standard being signed
      * @param typedData - The EIP-712 typed data to sign with full type safety
+     * @param ctx - Required operation context specifying the chain and address for this operation
      * @returns Promise resolving to the signature as a hex string
      * @throws Error when the wallet client is not available or signing fails
+     * @throws Error when OperationContext resolution fails
      *
      * @example
      * ```typescript
@@ -2192,10 +2393,12 @@ declare abstract class EvmAdapter extends Adapter {
      * import { buildEIP2612TypedData } from '@core/adapter-evm'
      *
      * const typedData = await buildEIP2612TypedData(meta, adapter, options)
-     * const signature = await adapter.signTypedData(typedData)
+     * const signature = await adapter.signTypedData(typedData, {
+     *   chain: 'Base' // Chain specified in context
+     * })
      * ```
      */
-    abstract signTypedData<Types extends Record<string, TypedDataField[]>, Message extends Record<string, unknown>>(typedData: TypedData<Types, Message>): Promise<`0x${string}`>;
+    abstract signTypedData<Types extends Record<string, TypedDataField[]>, Message extends Record<string, unknown>>(typedData: TypedData<Types, Message>, ctx: OperationContext<TAdapterCapabilities>): Promise<`0x${string}`>;
     /**
      * Fetches the current EIP-2612 nonce for a token owner.
      *
@@ -2217,15 +2420,59 @@ declare abstract class EvmAdapter extends Adapter {
      * )
      * ```
      */
-    fetchEIP2612Nonce(tokenAddress: `0x${string}`, ownerAddress: `0x${string}`): Promise<bigint>;
+    fetchEIP2612Nonce(tokenAddress: `0x${string}`, ownerAddress: `0x${string}`, ctx: OperationContext<TAdapterCapabilities>): Promise<bigint>;
     /**
      * Read a contract function.
      *
      * @typeParam TReturnType - The expected return type of the contract function.
      * @param params - The parameters for the contract function read.
+     * @param chain - The chain definition where the contract is deployed.
      * @returns A promise that resolves to the result of the contract function read.
      */
-    abstract readContract<TReturnType = unknown>(params: ReadContractParams): Promise<TReturnType>;
+    abstract readContract<TReturnType = unknown>(params: ReadContractParams, chain: EVMChainDefinition): Promise<TReturnType>;
+    /**
+     * Fetches the current gas price from the network, bypassing cache.
+     *
+     * This abstract method must be implemented by concrete adapters to fetch
+     * the current gas price using their specific client libraries. This method
+     * should not implement caching - caching is handled by the base class.
+     *
+     * @param chain - The chain definition to fetch gas price for.
+     * @returns Promise resolving to the current gas price in wei
+     * @throws Error when gas price retrieval fails
+     */
+    abstract fetchGasPrice(chain: EVMChainDefinition): Promise<bigint>;
+    /**
+     * Calculate the total transaction fee including compute cost and buffer for the configured chain.
+     *
+     * This method computes the fee by multiplying the estimated compute units by the
+     * current gas price, then adds a configurable buffer to account for fee fluctuations
+     * and ensure transaction success. The buffer is specified in basis points (1 basis
+     * point = 0.01%).
+     *
+     * @param baseComputeUnits - The base compute units for the transaction.
+     * @param bufferBasisPoints - The buffer to add as basis points (e.g., 500 = 5%). Defaults to DEFAULT_BUFFER_BASIS_POINTS (5%).
+     * @param chain - The chain definition to fetch gas price for.
+     * @returns A promise that resolves to the estimated gas cost including buffer.
+     * @throws Error when gas price retrieval fails.
+     *
+     * @example
+     * ```typescript
+     * import { ViemAdapter } from '@circle-fin/adapter-viem-v2'
+     * import { Ethereum } from '@core/chains'
+     *
+     * const adapter = new ViemAdapter({ publicClient, walletClient })
+     *
+     * // Calculate transaction fee with default 5% buffer
+     * const fee = await adapter.calculateTransactionFee(1000000000n, undefined, Ethereum)
+     * console.log('Transaction fee:', fee.toString(), 'wei')
+     *
+     * // Calculate transaction fee with custom 10% buffer
+     * const feeWithCustomBuffer = await adapter.calculateTransactionFee(1000000000n, 1000n, Ethereum)
+     * console.log('Transaction fee with custom buffer:', feeWithCustomBuffer.toString(), 'wei')
+     * ```
+     */
+    calculateTransactionFee(baseComputeUnits: bigint, bufferBasisPoints: bigint | undefined, chain: EVMChainDefinition): Promise<EstimatedGas>;
 }
 
 /**
@@ -2234,7 +2481,7 @@ declare abstract class EvmAdapter extends Adapter {
  *
  * A concrete EVM adapter implementation backed by the `ethers` library.
  * It provides functionality for gas estimation, contract interaction,
- * and transaction execution.
+ * and transaction execution with explicit capabilities and OperationContext support.
  */
 /**
  * Direct client configuration for EthersAdapter using pre-configured Ethers.js clients.
@@ -2262,31 +2509,81 @@ interface EthersAdapterOptions {
     signer: Signer$1;
 }
 /**
- * Creates a new EthersAdapter instance.
+ * Creates a new EthersAdapter instance with explicit capabilities and OperationContext support.
  *
- * @param options - Configuration options for the adapter.
+ * This constructor is typically not called directly. Instead, use the factory functions
+ * {@link createAdapterFromPrivateKey} or {@link createAdapterFromProvider} which provide
+ * smart defaults and better developer experience.
+ *
+ * @remarks
+ * The constructor requires both configuration options and explicit capabilities to ensure
+ * consistent behavior across all EVM adapters following the OperationContext pattern.
+ *
+ * **Capabilities Configuration:**
+ * - `addressContext`: Defines address control model (`'user-controlled'` or `'developer-controlled'`)
+ * - `supportedChains`: Array of EVM chains this adapter can operate on
+ *
+ * **Factory Functions (Recommended):**
+ * - {@link createAdapterFromPrivateKey} - For server-side/programmatic use with private keys
+ * - {@link createAdapterFromProvider} - For browser wallets (MetaMask, WalletConnect, etc.)
+ *
+ * @param options - Configuration options including provider getter and signer
+ * @param capabilities - Adapter capabilities defining address control and supported chains
+ *
+ * @example
+ * ```typescript
+ * import { EthersAdapter } from '@circle-fin/adapter-ethers-v6'
+ * import { Wallet, JsonRpcProvider } from 'ethers'
+ * import { Ethereum, Base } from '@core/chains'
+ *
+ * // Direct construction (advanced usage)
+ * const adapter = new EthersAdapter({
+ *   getProvider: ({ chain }) => new JsonRpcProvider('https://...'),
+ *   signer: new Wallet('0x...', new JsonRpcProvider('https://...'))
+ * }, {
+ *   addressContext: 'user-controlled',
+ *   supportedChains: [Ethereum, Base]
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Recommended: Use factory functions instead
+ * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+ *
+ * // Minimal configuration with default capabilities
+ * const adapter = createAdapterFromPrivateKey({
+ *   privateKey: '0x...'
+ *   // Defaults: user-controlled + all EVM chains
+ * })
+ * ```
  */
-declare class EthersAdapter extends EvmAdapter {
+declare class EthersAdapter<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> extends EvmAdapter<TAdapterCapabilities> {
     /** The configuration options for this adapter instance. */
     options: EthersAdapterOptions;
     /** Cached Ethers Signer instance. */
     private _signer;
-    /** Cached address of the connected wallet. */
-    private cachedAddress?;
     /** Cached providers for different chains. */
     private readonly cachedProviders;
-    /** Cached gas price for the current network. */
-    private cachedGasPrice?;
-    /** Cached chain definition for the connected provider. */
-    private cachedChain;
-    /** The resolved chain definition that this adapter was created for. */
-    private resolvedChain;
-    constructor(options: EthersAdapterOptions);
+    constructor(options: EthersAdapterOptions, capabilities: TAdapterCapabilities);
     /**
-     * Sets the resolved chain for this adapter.
-     * @internal
+     * Resets all cached state in the adapter, including Ethers-specific caches.
+     *
+     * This method extends the base class resetState() to also clear Ethers-specific
+     * caches like providers and gas prices. It ensures a clean state when
+     * the adapter needs to be reinitialized (e.g., after chain or account changes).
+     *
+     * @override
+     * @example
+     * ```typescript
+     * // Called automatically during chain switches or account changes
+     * adapter.resetState()
+     *
+     * // Or called manually to clear all caches
+     * adapter.resetState()
+     * ```
      */
-    setResolvedChain(chain: EVMChainDefinition): void;
+    resetState(): void;
     /**
      * Switches the adapter to operate on the specified chain.
      *
@@ -2300,8 +2597,21 @@ declare class EthersAdapter extends EvmAdapter {
     switchToChain(chain: ChainDefinition): Promise<void>;
     /**
      * Gets the cached Provider or initializes it from options if not already cached.
+     *
+     * @param chain - The chain definition for which to get the Provider (required).
+     * @returns The Ethers Provider instance.
+     * @remarks
+     * This method ensures we only store one instance of the Provider per chain.
+     * The chain parameter is required to prevent accidentally using the wrong chain,
+     * which could lead to serious issues and real costs for users.
+     * @example
+     * ```typescript
+     * const adapter = new EthersAdapter(options, capabilities);
+     * const provider = await adapter.getProvider(Ethereum);
+     * const blockNumber = await provider.getBlockNumber();
+     * ```
      */
-    getProvider(chain?: EVMChainDefinition): Promise<Provider>;
+    getProvider(chain: EVMChainDefinition): Promise<Provider>;
     /** Gets the current Signer instance used by the adapter. */
     getSigner(): Signer$1;
     /**
@@ -2314,225 +2624,498 @@ declare class EthersAdapter extends EvmAdapter {
     private simulateFunctionCall;
     /**
      * Estimates the gas required for executing a contract function call.
+     *
+     * @param contract - The contract instance to estimate gas for.
+     * @param functionName - The name of the contract function.
+     * @param args - The arguments to pass to the contract function.
+     * @param chain - The chain definition to use for gas price retrieval (prevents race conditions).
+     * @param overrides - Optional estimate overrides.
+     * @returns Promise resolving to the estimated gas, gas price, and total fee.
      */
     private estimateGasForFunction;
     /**
      * Executes a contract function as a transaction on the blockchain.
+     *
+     * @remarks
+     * This method executes a transaction on the blockchain.
+     * - If `overrides.nonce` is provided, it is used verbatim and local allocation is skipped.
+     * - Otherwise, allocates the next process-local nonce for (chainId, fromAddress) to avoid
+     *   collisions under concurrent sends.
+     * - On common nonce errors (e.g., "nonce too low", "already known", "replacement fee too low"),
+     *   re-syncs from provider pending nonce and retries once with a freshly allocated nonce.
+     *
+     * @param contract - The contract instance to execute the function on.
+     * @param functionName - The name of the contract function to execute.
+     * @param args - The arguments to pass to the contract function.
+     * @param fromAddress - The address to send the transaction from (prevents race conditions).
+     * @param chain - The chain definition to use for this operation (prevents race conditions).
+     * @param overrides - Optional transaction overrides including nonce, gas settings, etc.
+     * @returns The transaction hash as a hex string.
+     *
+     * @throws When the contract function is not found or callable.
+     * @throws When transaction population fails.
+     * @throws When transaction execution fails after retry attempts.
      */
     private executeTransaction;
     /**
-     * Prepares a chain request for execution.
+     * Prepares a contract function call for gas estimation and execution with OperationContext.
+     *
+     * This method follows the OperationContext approach, requiring explicit chain specification
+     * for every operation. The chain is provided via the required OperationContext parameter,
+     * enabling seamless multi-chain operations with a single adapter instance.
+     *
+     * @remarks
+     * **Operation Flow:**
+     * 1. Validates parameters and resolves chain from OperationContext
+     * 2. Switches adapter to target chain if necessary
+     * 3. Resolves address based on adapter's addressContext capability
+     * 4. Creates contract instance and simulates the function call
+     * 5. Returns prepared request with `estimate()` and `execute()` methods
+     *
+     * **Address Resolution:**
+     * - `'user-controlled'`: Address automatically resolved from connected signer
+     * - `'developer-controlled'`: Address must be provided explicitly in OperationContext
+     *
+     * **Read-Only Functions:**
+     * View and pure functions are automatically detected and handled with noop gas estimation.
+     *
+     * @param params - The EVM contract function call parameters
+     * @param ctx - Required operation context specifying the chain for this operation
+     * @returns A promise that resolves to a prepared chain request for estimation and execution
+     * @throws Error when parameters are invalid or function simulation fails
+     * @throws Error when OperationContext resolution fails
+     *
+     * @example
+     * ```typescript
+     * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+     * import { parseAbi } from 'ethers'
+     *
+     * const adapter = createAdapterFromPrivateKey({
+     *   privateKey: process.env.PRIVATE_KEY
+     * })
+     *
+     * // Basic usage - OperationContext specifies the chain
+     * const prepared = await adapter.prepare({
+     *   address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC on Ethereum
+     *   abi: parseAbi(['function transfer(address to, uint256 amount) returns (bool)']),
+     *   functionName: 'transfer',
+     *   args: ['0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb', '1000000']
+     * }, { chain: 'Ethereum' }) // Chain specified in context
+     *
+     * // Estimate gas
+     * const gasEstimate = await prepared.estimate()
+     * console.log('Estimated gas:', gasEstimate.gas)
+     *
+     * // Execute transaction
+     * const txHash = await prepared.execute()
+     * console.log('Transaction hash:', txHash)
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Multi-chain usage with same adapter instance
+     * const adapter = createAdapterFromPrivateKey({
+     *   privateKey: process.env.PRIVATE_KEY
+     * })
+     *
+     * // Transfer USDC on Ethereum
+     * const preparedEthereum = await adapter.prepare({
+     *   address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+     *   abi: usdcAbi,
+     *   functionName: 'transfer',
+     *   args: ['0xrecipient', '1000000']
+     * }, { chain: 'Ethereum' })
+     *
+     * // Transfer USDC on Base using the same adapter
+     * const preparedBase = await adapter.prepare({
+     *   address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+     *   abi: usdcAbi,
+     *   functionName: 'transfer',
+     *   args: ['0xrecipient', '1000000']
+     * }, { chain: 'Base' })
+     *
+     * // Execute both transfers
+     * await preparedEthereum.execute()
+     * await preparedBase.execute()
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Address resolution patterns
+     * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+     *
+     * const adapter = await createAdapterFromProvider({
+     *   provider: window.ethereum
+     *   // Defaults to user-controlled address context
+     * })
+     *
+     * // Address is automatically resolved from the signer
+     * const prepared = await adapter.prepare({
+     *   address: '0xcontract',
+     *   abi: contractAbi,
+     *   functionName: 'approve',
+     *   args: ['0xspender', '1000000']
+     * }, {
+     *   chain: 'Polygon'
+     *   // No need to specify 'address' - comes from signer automatically
+     * })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Read-only functions (view/pure) - automatic noop estimation
+     * const prepared = await adapter.prepare({
+     *   address: '0xcontract',
+     *   abi: parseAbi(['function balanceOf(address account) view returns (uint256)']),
+     *   functionName: 'balanceOf',
+     *   args: ['0xaccount']
+     * }, { chain: 'Ethereum' })
+     *
+     * // estimate() returns noop for read-only functions
+     * const estimate = await prepared.estimate() // { gas: 0n, fee: '0', gasPrice: 0n }
+     *
+     * // execute() returns the result as a string
+     * const balance = await prepared.execute() // '1000000'
+     * ```
+     */
+    prepare(params: EvmPreparedChainRequestParams, ctx: OperationContext<TAdapterCapabilities>): Promise<EvmPreparedChainRequest>;
+    /**
+     * Gets the address associated with this adapter.
+     *
+     * @remarks
+     * This method is primarily used internally by the OperationContext resolution system.
+     * In user-facing code, addresses are typically resolved automatically based on the
+     * adapter's addressContext capability.
+     *
+     * **With OperationContext Pattern:**
+     * - The chain parameter is provided automatically by `resolveOperationContext()`
+     * - For `'user-controlled'` adapters: address is derived from the signer/wallet
+     * - For `'developer-controlled'` adapters: address must be provided explicitly in context
+     *
+     * **Implementation Note:**
+     * While the chain parameter is typed as optional for compatibility with the base
+     * adapter interface, it is effectively required and enforced at runtime. This ensures
+     * the adapter is connected to the correct chain before querying the signer.
+     *
+     * @param chain - The chain to use for address resolution (provided by OperationContext)
+     * @returns A promise that resolves to the signer's address
+     * @throws Error when no chain is provided
+     *
+     * @example
+     * ```typescript
+     * import { Ethereum } from '@core/chains'
+     *
+     * // Typically called internally by resolveOperationContext
+     * const address = await adapter.getAddress(Ethereum)
+     * console.log('Wallet address:', address)
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // In practice, address resolution happens automatically
+     * const prepared = await adapter.prepare(params, {
+     *   chain: 'Ethereum'
+     *   // Address automatically resolved via getAddress() internally
+     * })
+     * ```
      */
-    prepare(params: EvmPreparedChainRequestParams): Promise<EvmPreparedChainRequest>;
-    /** Gets the address of the connected wallet. */
-    getAddress(): Promise<string>;
-    /** Gets the current chain definition. */
-    getChain(): Promise<ChainDefinition>;
+    getAddress(chain?: EVMChainDefinition): Promise<string>;
     /**
      * Waits for a transaction to be mined and confirmed on the blockchain.
+     *
+     * @param txHash - The transaction hash to wait for.
+     * @param config - Optional configuration for confirmations and timeout.
+     * @param chain - The chain definition where the transaction was submitted.
+     * @returns Promise resolving to the transaction receipt details.
+     * @throws Error when transaction is not found or times out.
      */
-    waitForTransaction(txHash: string, config?: WaitForTransactionConfig): Promise<WaitForTransactionResponse>;
+    waitForTransaction(txHash: string, config: WaitForTransactionConfig | undefined, chain: EVMChainDefinition): Promise<WaitForTransactionResponse>;
     /**
-     * Calculate the total transaction fee including compute cost and buffer for the configured chain.
+     * Fetches the current gas price from the network.
+     *
+     * @param chain - The chain definition to fetch gas price for.
+     * @returns Promise resolving to the current gas price in wei
+     * @throws Error when gas price retrieval fails
+     */
+    fetchGasPrice(chain: EVMChainDefinition): Promise<bigint>;
+    /**
+     * Signs EIP-712 typed data using the configured signer with OperationContext.
+     *
+     * This method signs structured typed data following the EIP-712 standard, enabling
+     * secure off-chain signatures for permit approvals, meta-transactions, and other
+     * gasless operations. The chain must be specified via the required OperationContext
+     * parameter to ensure signatures are valid for the correct network.
+     *
+     * @remarks
+     * **Operation Flow:**
+     * 1. Validates the typed data structure
+     * 2. Resolves chain from OperationContext and switches if necessary
+     * 3. Resolves signer address based on adapter's addressContext
+     * 4. Signs the typed data using the configured signer
+     * 5. Returns the signature as a hex string
+     *
+     * **Use Cases:**
+     * - ERC-2612 permit approvals (gasless token approvals)
+     * - Meta-transactions and gasless operations
+     * - Off-chain order signing for DEX protocols
+     * - DAO voting signatures
+     *
+     * @typeParam Types - The EIP-712 types definition for the data being signed
+     * @typeParam Message - The message structure being signed
+     * @param typedData - The EIP-712 typed data to sign with full type safety
+     * @param ctx - Required operation context specifying the chain for this operation
+     * @returns Promise resolving to the signature as a hex string
+     * @throws Error when typedData validation fails
+     * @throws Error when no signer is configured
+     * @throws Error when OperationContext resolution fails
+     *
+     * @example
+     * ```typescript
+     * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+     *
+     * const adapter = createAdapterFromPrivateKey({
+     *   privateKey: process.env.PRIVATE_KEY
+     * })
+     *
+     * // Sign ERC-2612 permit (gasless token approval)
+     * const signature = await adapter.signTypedData({
+     *   domain: {
+     *     name: 'USD Coin',
+     *     version: '2',
+     *     chainId: 1,
+     *     verifyingContract: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
+     *   },
+     *   types: {
+     *     Permit: [
+     *       { name: 'owner', type: 'address' },
+     *       { name: 'spender', type: 'address' },
+     *       { name: 'value', type: 'uint256' },
+     *       { name: 'nonce', type: 'uint256' },
+     *       { name: 'deadline', type: 'uint256' }
+     *     ]
+     *   },
+     *   primaryType: 'Permit',
+     *   message: {
+     *     owner: '0xowner',
+     *     spender: '0xspender',
+     *     value: '1000000',
+     *     nonce: '0',
+     *     deadline: '1735689600'
+     *   }
+     * }, { chain: 'Ethereum' }) // Chain must be specified
+     *
+     * console.log('Signature:', signature)
+     * // '0x...' - can be used for permit approval
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Multi-chain permit signing with same adapter
+     * const adapter = createAdapterFromPrivateKey({
+     *   privateKey: process.env.PRIVATE_KEY
+     * })
+     *
+     * // Sign permit for USDC on Ethereum
+     * const ethSignature = await adapter.signTypedData(permitData, {
+     *   chain: 'Ethereum'
+     * })
+     *
+     * // Sign permit for USDC on Base - same adapter!
+     * const baseSignature = await adapter.signTypedData(permitData, {
+     *   chain: 'Base'
+     * })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Browser wallet usage
+     * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+     *
+     * const adapter = await createAdapterFromProvider({
+     *   provider: window.ethereum
+     * })
+     *
+     * // User will see signature request in wallet
+     * const signature = await adapter.signTypedData(typedData, {
+     *   chain: 'Polygon'
+     * })
+     * ```
      */
-    calculateTransactionFee(baseComputeUnits: bigint, bufferBasisPoints?: bigint): Promise<EstimatedGas>;
+    signTypedData<Types extends Record<string, TypedDataField[]>, Message extends Record<string, unknown>>(typedData: TypedData<Types, Message>, ctx: OperationContext<TAdapterCapabilities>): Promise<`0x${string}`>;
     /**
-     * Signs EIP-712 typed data using the configured signer.
+     * Handle read-only function execution with noop estimation.
+     *
+     * @param params - The EVM prepared chain request parameters.
+     * @param signer - The Ethers signer instance.
+     * @param provider - The Ethers provider instance.
+     * @param walletAddress - The wallet address (prevents race conditions in concurrent requests).
+     * @returns A prepared chain request for read-only function execution.
+     */
+    private handleReadOnlyFunction;
+    /**
+     * Reads a contract function using Ethers v6.
+     *
+     * @param params - The read contract parameters including address, ABI, function name, and args.
+     * @param chain - The chain definition where the contract is deployed.
+     * @returns Promise resolving to the contract function return value.
+     * @throws Error when contract read fails.
      */
-    signTypedData<Types extends Record<string, TypedDataField[]>, Message extends Record<string, unknown>>(typedData: TypedData<Types, Message>): Promise<`0x${string}`>;
-    /** Reads a contract function using Ethers v6. */
-    readContract<TReturnType = unknown>(params: ReadContractParams): Promise<TReturnType>;
+    readContract<TReturnType = unknown>(params: ReadContractParams, chain: EVMChainDefinition): Promise<TReturnType>;
 }
 
 /**
  * Parameters for creating an {@link EthersAdapter} from a private key.
  *
- * @interface CreateAdapterFromPrivateKeyParams
- * @category Types
- * @description
- * Defines the configuration required to instantiate an {@link EthersAdapter}
- * using a raw private key for server-side or programmatic wallet operations.
- *
- * This is intended for secure, backend, or automated environments where direct
- * control of the private key is possible and safe. Do not use this pattern in
- * browser or client-side code.
- *
- * @example
- * ```typescript
- * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
- * import { Blockchain } from '@core/chains'
- *
- * // Using a chain identifier (enum, string, or ChainDefinition)
- * const adapter = createAdapterFromPrivateKey({
- *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
- *   defaultChain: Blockchain.Ethereum,
- * })
- *
- * // Advanced: custom provider logic (e.g., for custom endpoints or retry logic)
- * const adapter2 = createAdapterFromPrivateKey({
- *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
- *   defaultChain: 'Ethereum',
- *   getProvider: ({ chain }) => new JsonRpcProvider('https://...'),
- * })
- * ```
- *
- * @remarks
- * Supported parameter combinations:
- * - Provide `privateKey` and `defaultChain` (uses default provider logic).
- * - Optionally provide a custom `getProvider` function for advanced provider instantiation.
- *
- * The `privateKey` must be a valid 32-byte hex string prefixed with `0x`.
- * The `defaultChain` can be a {@link ChainDefinition}, a supported chain enum, or a string literal.
- * The `getProvider` function, if supplied, receives an object with a `chain` parameter.
+ * @typeParam TCapabilities - The adapter capabilities type for compile-time address validation
  */
-interface CreateAdapterFromPrivateKeyParams {
-    /**
-     * The private key for wallet operations.
-     * @remarks
-     * Must be a valid 32-byte hex string prefixed with '0x'. This should be:
-     * - A securely generated private key
-     * - Kept confidential and never exposed in client-side code
-     * - Used only in server-side or secure environments
-     *
-     * The private key will be used to sign transactions and authenticate
-     * with the blockchain network.
-     */
-    privateKey: `0x${string}`;
+interface CreateAdapterFromPrivateKeyParams<TCapabilities extends Partial<AdapterCapabilities> = AdapterCapabilities> {
     /**
-     * The default blockchain network to connect to.
-     * @remarks
-     * Accepts a {@link ChainDefinition}, a supported chain enum, or a string literal representing the chain.
-     * This determines which EVM-compatible network the adapter will operate on by default.
-     * The adapter will use the canonical RPC URL for the specified chain unless a custom provider is supplied.
-     * Examples: `Blockchain.Ethereum`, `'Ethereum'`, or a `ChainDefinition` object.
+     * The private key to use for wallet derivation.
+     * 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.
      */
-    defaultChain: ChainIdentifier;
+    privateKey: string;
     /**
-     * Optional function to provide a custom Ethers Provider instance.
-     * @remarks
-     * If not provided, a default Provider will be created using the chain's RPC endpoints.
-     * Use this to inject custom provider logic, such as:
-     * - Custom retry or caching strategies
-     * - Enhanced logging or monitoring
-     * - Support for non-standard transports
-     *
-     * @param chain - The chain definition for which to create the provider.
-     * @returns A configured Provider instance.
+     * Optional function to create providers for different chains.
+     * If not provided, a default implementation using JsonRpcProvider will be used.
      */
     getProvider?: (params: {
         chain: ChainDefinition;
     }) => Provider;
+    /**
+     * Optional adapter capabilities configuration.
+     * Defines address control model and supported chains.
+     * If not provided, defaults to user-controlled with all EVM chains supported.
+     *
+     * @example
+     * ```typescript
+     * // Minimal configuration with default capabilities
+     * createAdapterFromPrivateKey({
+     *   privateKey: '0x...'
+     *   // Capabilities default to:
+     *   // { addressContext: 'user-controlled', supportedChains: [all EVM chains] }
+     * })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Custom supported chains
+     * createAdapterFromPrivateKey({
+     *   privateKey: '0x...',
+     *   capabilities: {
+     *     supportedChains: [Ethereum, Base, Polygon]
+     *   }
+     * })
+     * ```
+     */
+    capabilities?: TCapabilities;
 }
 /**
- * Creates an EthersAdapter instance from a private key.
+ * Creates an EthersAdapter instance from a private key with automatic type inference.
  *
  * This function creates an EthersAdapter for server-side or programmatic use
- * by deriving a wallet from the provided private key and connecting it to the specified chain.
- * It's ideal for automated systems, backend services, or scenarios where you have direct
- * control over the private key.
+ * by deriving a wallet from the provided private key. It uses lazy initialization
+ * where the wallet is created without a provider and is connected to chain-specific
+ * providers on-demand during operations. This matches the Viem adapter pattern and
+ * enables seamless multi-chain operations with a single adapter instance.
  *
  * @remarks
  * The function performs the following operations:
  * 1. Validates the input parameters at runtime
- * 2. Resolves the chain identifier to a ChainDefinition
- * 3. Determines the canonical RPC URL for the specified chain
- * 4. Creates a JsonRpcProvider using the resolved RPC URL (or a custom provider if getProvider is supplied)
- * 5. Instantiates a Wallet with the private key and provider
- * 6. Returns a configured EthersAdapter instance
+ * 2. Creates a Wallet from the private key (without provider - lazy initialization)
+ * 3. Applies smart defaults for capabilities (user-controlled + all EVM chains)
+ * 4. Returns a configured EthersAdapter instance
  *
- * The adapter will be ready to use immediately after creation with the
- * specified provider and wallet active. If a custom provider factory is provided,
- * those settings will be respected for all operations.
+ * Chain context is provided through OperationContext during individual operations.
+ * The wallet will be connected to a provider when ensureChain() is called in prepare().
+ *
+ * **Default Configuration:**
+ * - `addressContext`: `'user-controlled'` (address derived from private key automatically)
+ * - `supportedChains`: All EVM-compatible chains (~29 networks)
+ * - Lazy initialization: Chain connection deferred until first operation
  *
  * **Security Warning:** Never use this function in client-side code or expose
  * private keys in any way. This function is intended for server-side use only.
+ * Store private keys securely using environment variables or secret management systems.
  *
+ * @typeParam TCapabilities - The adapter capabilities type for compile-time address validation
  * @param params - Configuration parameters for creating the adapter
- * @returns A configured EthersAdapter instance
- * @throws Error when validation fails or wallet creation fails
+ * @returns A configured EthersAdapter instance with automatically inferred capabilities
+ * @throws Error when validation fails or wallet derivation fails
  *
  * @example
  * ```typescript
  * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
- * import { Blockchain, Ethereum } from '@core/chains'
  *
- * // Using ChainDefinition object
+ * // Both private key formats are supported (with or without '0x' prefix):
  * const adapter1 = createAdapterFromPrivateKey({
- *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
- *   defaultChain: Ethereum,
+ *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' // With prefix
  * })
  *
- * // Using Blockchain enum
  * const adapter2 = createAdapterFromPrivateKey({
- *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
- *   defaultChain: Blockchain.Ethereum,
+ *   privateKey: '1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' // Without prefix (automatically normalized)
  * })
  *
- * // Using string literal
- * const adapter3 = createAdapterFromPrivateKey({
- *   privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
- *   defaultChain: 'Ethereum',
- * })
+ * // Chain specified per-operation via OperationContext
+ * const prepared = await adapter1.prepare({
+ *   address: '0x...',
+ *   abi: contractAbi,
+ *   functionName: 'transfer',
+ *   args: ['0xto', '1000']
+ * }, { chain: 'Ethereum' })
  * ```
  *
  * @example
  * ```typescript
  * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
- * import { JsonRpcProvider } from 'ethers'
  *
- * // Advanced usage with custom provider logic
+ * // Multi-chain usage with same adapter instance
  * const adapter = createAdapterFromPrivateKey({
- *   privateKey: process.env.PRIVATE_KEY,
- *   defaultChain: 'Ethereum',
- *   getProvider: ({ chain }) => new JsonRpcProvider('https://...'),
+ *   privateKey: process.env.PRIVATE_KEY as `0x${string}`
  * })
+ *
+ * // Transfer USDC on Ethereum
+ * await adapter.prepare(params, { chain: 'Ethereum' })
+ *
+ * // Transfer USDC on Base using the same adapter
+ * await adapter.prepare(params, { chain: 'Base' })
  * ```
  *
  * @example
  * ```typescript
- * // Cross-chain transfer using a single adapter
  * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
- * import { BridgingKit } from '@circle-fin/bridging-kit'
+ * import { Ethereum, Base, Polygon } from '@core/chains'
  *
+ * // Custom capabilities configuration
  * const adapter = createAdapterFromPrivateKey({
- *   privateKey: process.env.PRIVATE_KEY,
- *   defaultChain: 'Ethereum',
- * })
- *
- * const kit = new BridgingKit()
- *
- * // Use the same adapter for both source and destination
- * const result = await kit.bridge({
- *   from: { adapter, chain: 'Ethereum' },
- *   to: { adapter, chain: 'Base' },
- *   amount: '100.50'
+ *   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+ *   capabilities: {
+ *     supportedChains: [Ethereum, Base, Polygon]
+ *   }
  * })
  * ```
  *
  * @example
  * ```typescript
  * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-ethers-v6'
+ * import { JsonRpcProvider } from 'ethers'
  *
- * // Error handling example
- * try {
- *   const adapter = createAdapterFromPrivateKey({
- *     privateKey: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
- *     defaultChain: 'Polygon',
- *   })
- *
- *   // Adapter is ready to use immediately
- *   const balance = await adapter.getBalance()
- *   console.log('Balance:', balance)
- * } catch (error) {
- *   if (error.message.includes('Private key')) {
- *     console.error('Invalid private key format')
- *   } else {
- *     console.error('Failed to create adapter:', error.message)
+ * // Custom provider configuration with explicit chain mapping
+ * const adapter = createAdapterFromPrivateKey({
+ *   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+ *   getProvider: ({ chain }) => {
+ *     const rpcEndpoints: Record<string, string> = {
+ *       'Ethereum': `https://eth-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
+ *       'Base': `https://base-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`
+ *     }
+ *     const endpoint = rpcEndpoints[chain.name]
+ *     if (!endpoint) throw new Error(`RPC not configured for ${chain.name}`)
+ *     return new JsonRpcProvider(endpoint, chain.chainId)
  *   }
- * }
+ * })
  * ```
  */
-declare const createAdapterFromPrivateKey: (params: CreateAdapterFromPrivateKeyParams) => EthersAdapter;
+declare function createAdapterFromPrivateKey<const TCapabilities extends Partial<AdapterCapabilities> = object>(params: CreateAdapterFromPrivateKeyParams<TCapabilities>): EthersAdapter<InferAdapterCapabilities<TCapabilities>>;
 
 /**
  * Parameters for creating an {@link EthersAdapter} from an EIP-1193 provider.
@@ -2541,43 +3124,46 @@ declare const createAdapterFromPrivateKey: (params: CreateAdapterFromPrivateKeyP
  * @category Types
  * @description
  * Defines the parameters required to instantiate an {@link EthersAdapter} using an EIP-1193-compatible provider
- * (such as MetaMask, WalletConnect, or any injected browser wallet), and to specify the intended blockchain network.
+ * (such as MetaMask, WalletConnect, or any injected browser wallet).
  *
  * @example
  * ```typescript
  * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
  *
- * // Basic usage with injected provider and explicit chain
+ * // Basic browser wallet setup
  * const adapter = await createAdapterFromProvider({
- *   provider: window.ethereum,
- *   chain: 'Ethereum_Sepolia',
+ *   provider: window.ethereum
+ *   // Smart defaults applied:
+ *   // - addressContext: 'user-controlled'
+ *   // - supportedChains: all EVM chains
  * })
  * ```
  *
  * @example
  * ```typescript
  * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
- * import { JsonRpcProvider } from 'ethers'
+ * import { Ethereum, Base, Polygon } from '@core/chains'
  *
- * // Advanced: custom provider logic for a specific chain
+ * // Advanced: custom capabilities
  * const adapter = await createAdapterFromProvider({
  *   provider: window.ethereum,
- *   chain: 'Base_Sepolia',
- *   getProvider: ({ chain }) => new JsonRpcProvider('https://...'),
+ *   capabilities: {
+ *     supportedChains: [Ethereum, Base, Polygon]
+ *   }
  * })
  * ```
  *
  * @remarks
  * Required parameters:
  * - `provider`: A valid EIP-1193 provider (e.g., MetaMask, WalletConnect, etc.).
- * - `chain`: The blockchain network to use for the adapter. Accepts a chain identifier string, enum, or chain definition.
  *
  * Optional:
  * - `getProvider`: A custom function to instantiate an Ethers Provider for the specified chain.
  *   Receives an object with a `chain` property of type {@link EVMChainDefinition}.
+ * - `capabilities`: Adapter capabilities defining address control and supported chains.
  *
- * The `chain` parameter determines which network the adapter will operate on, regardless of the wallet's current network.
- * This enables cross-chain workflows and explicit network targeting.
+ * With OperationContext pattern, chain is specified per-operation rather than at factory creation.
+ * This enables cross-chain workflows with a single adapter instance.
  */
 interface CreateAdapterFromProviderParams {
     /**
@@ -2593,13 +3179,6 @@ interface CreateAdapterFromProviderParams {
      * - `enable()` or equivalent for requesting account access
      */
     provider: Eip1193Provider;
-    /**
-     * The blockchain network to use for the adapter.
-     * @remarks
-     * This chain will be used as the intended chain for the adapter.
-     * The adapter will use this chain instead of the wallet's current network.
-     */
-    chain: ChainIdentifier;
     /**
      * Optional function to provide a custom Ethers Provider instance.
      * @remarks
@@ -2615,48 +3194,115 @@ interface CreateAdapterFromProviderParams {
     getProvider?: (params: {
         chain: EVMChainDefinition;
     }) => Provider;
+    /**
+     * Optional capabilities configuration for the adapter.
+     * @remarks
+     * Defines the adapter's address control model and supported chains.
+     * If not provided, defaults to user-controlled address context with all EVM chains supported.
+     *
+     * - `addressContext`: Determines address control model ('user-controlled' or 'developer-controlled')
+     * - `supportedChains`: Array of supported blockchain networks
+     *
+     * For EIP-1193 provider adapters, typically uses 'user-controlled' since addresses are managed
+     * through the wallet UI and user interaction.
+     *
+     * @example
+     * ```typescript
+     * // Minimal configuration with smart defaults
+     * createAdapterFromProvider({
+     *   provider: window.ethereum
+     *   // Capabilities default to:
+     *   // { addressContext: 'user-controlled', supportedChains: [all EVM chains] }
+     * })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Override supported chains only
+     * createAdapterFromProvider({
+     *   provider: window.ethereum,
+     *   capabilities: {
+     *     supportedChains: [Ethereum, Base, Polygon]
+     *     // addressContext still defaults to 'user-controlled'
+     *   }
+     * })
+     * ```
+     */
+    capabilities?: Partial<AdapterCapabilities>;
 }
 /**
- * Creates an EthersAdapter instance from an EIP-1193 provider.
+ * Creates an EthersAdapter instance from an EIP-1193 provider with smart default capabilities.
  *
  * This function creates an EthersAdapter for browser or injected wallet use
- * by connecting to the provided EIP-1193-compatible provider.
- * It's ideal for dApps, browser-based integrations, or scenarios where the user controls the wallet.
+ * by connecting to the provided EIP-1193-compatible provider (such as MetaMask,
+ * WalletConnect, or any browser wallet). The adapter is automatically configured
+ * with user-controlled address context and support for all EVM-compatible chains.
  *
  * @remarks
  * The function performs the following operations:
  * 1. Validates the input parameters at runtime
- * 2. Creates a cached provider factory (or uses a custom one if provided)
- * 3. Instantiates a BrowserProvider for the injected provider
- * 4. Requests account access and retrieves the signer
- * 5. Returns a configured EthersAdapter instance
+ * 2. Creates a BrowserProvider for the injected provider
+ * 3. Requests account access from the user (wallet prompt appears here)
+ * 4. Retrieves the signer from the connected wallet
+ * 5. Applies smart defaults for capabilities (user-controlled + all EVM chains)
+ * 6. Returns a configured EthersAdapter instance ready for immediate use
  *
  * The adapter will be ready to use immediately after creation with the
- * specified provider and signer active. If a custom provider factory is provided,
- * those settings will be respected for all operations.
+ * specified provider and signer active. Chain context is provided through
+ * OperationContext during individual operations.
+ *
+ * **Smart Defaults:**
+ * - `addressContext`: `'user-controlled'` (addresses managed through wallet UI)
+ * - `supportedChains`: All EVM-compatible chains (~29 networks) for maximum flexibility
+ * - OperationContext support for per-operation chain specification
  *
- * **Supported parameter combinations:**
- * - Provide `provider` and `chain` (uses default provider logic).
- * - Provide `provider`, `chain`, and a custom `getProvider` function (for advanced provider instantiation).
+ * **Account Access:**
+ * Note: Unlike Viem, Ethers requires eager signer initialization because:
+ * - Ethers Signer objects are chain-specific and must be recreated during chain switches
+ * - The switchChain utility requires an initialized Signer as input
+ * - This is an architectural difference between Ethers and Viem, not a limitation
+ * The user will be prompted for account access when this factory is called (before adapter is returned).
  *
  * **Security Note:** This function is intended for use with injected/browser wallets.
  * Do not use in server-side code with private keys.
  *
- * @param params - Configuration parameters for creating the adapter. Must include:
- *   - `provider`: An EIP-1193-compatible provider (e.g., MetaMask, WalletConnect, etc.)
- *   - `chain`: The blockchain network identifier (string, enum, or ChainDefinition)
- *   - `getProvider` (optional): A custom function to create a JsonRpcProvider
+ * @param params - Configuration parameters for creating the adapter
  * @returns A configured EthersAdapter instance
- * @throws Error when validation fails or provider/signing fails
+ * @throws Error when validation fails, user rejects connection, or provider initialization fails
+ *
+ * @example
+ * ```typescript
+ * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+ *
+ * // Minimal browser wallet configuration
+ * const adapter = await createAdapterFromProvider({
+ *   provider: window.ethereum
+ *   // Smart defaults applied:
+ *   // - addressContext: 'user-controlled'
+ *   // - supportedChains: all EVM chains (~29 networks)
+ * })
+ *
+ * // Use with OperationContext pattern
+ * const prepared = await adapter.prepare({
+ *   address: '0x...',
+ *   abi: contractAbi,
+ *   functionName: 'transfer',
+ *   args: ['0xto', '1000']
+ * }, { chain: 'Ethereum' }) // Chain specified in context
+ * ```
  *
  * @example
  * ```typescript
  * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+ * import { Ethereum, Base, Polygon } from '@core/chains'
  *
- * // Basic usage with default provider
+ * // Advanced: custom capabilities for production use
  * const adapter = await createAdapterFromProvider({
  *   provider: window.ethereum,
- *   chain: 'Ethereum'
+ *   capabilities: {
+ *     supportedChains: [Ethereum, Base, Polygon] // Restrict to specific chains
+ *     // addressContext still defaults to 'user-controlled'
+ *   }
  * })
  * ```
  *
@@ -2665,15 +3311,98 @@ interface CreateAdapterFromProviderParams {
  * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
  * import { JsonRpcProvider } from 'ethers'
  *
- * // Advanced usage with custom provider logic
+ * // Advanced usage with custom provider logic for production
  * const adapter = await createAdapterFromProvider({
  *   provider: window.ethereum,
- *   chain: 'Ethereum',
- *   getProvider: ({ chain }) => new JsonRpcProvider('https://...')
+ *   getProvider: ({ chain }) => new JsonRpcProvider(
+ *     `https://eth-mainnet.alchemyapi.io/v2/${process.env.ALCHEMY_KEY}`,
+ *     { name: chain.name, chainId: chain.chainId }
+ *   )
+ * })
+ *
+ * // Address is automatically resolved from connected wallet
+ * const prepared = await adapter.prepare(params, {
+ *   chain: 'Polygon' // Address comes from wallet UI
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Cross-chain transfer using a single adapter
+ * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+ * import { BridgeKit } from '@circle-fin/bridge-kit'
+ *
+ * const adapter = await createAdapterFromProvider({
+ *   provider: window.ethereum
+ * })
+ *
+ * const kit = new BridgeKit()
+ *
+ * // Use the same adapter for both source and destination
+ * const result = await kit.bridge({
+ *   from: { adapter, chain: 'Ethereum' },
+ *   to: { adapter, chain: 'Base' },
+ *   amount: '100.50'
  * })
  * ```
+ *
+ * @example
+ * ```typescript
+ * import { createAdapterFromProvider } from '@circle-fin/adapter-ethers-v6'
+ *
+ * // Error handling example - wallet prompt occurs during factory creation
+ * try {
+ *   const adapter = await createAdapterFromProvider({
+ *     provider: window.ethereum
+ *   })
+ *
+ *   // Adapter is ready to use immediately
+ *   console.log('Adapter connected successfully')
+ * } catch (error) {
+ *   if (error.message.includes('User rejected')) {
+ *     console.error('User rejected connection request')
+ *   } else if (error.message.includes('Failed to initialize')) {
+ *     console.error('Could not initialize wallet connection')
+ *   } else {
+ *     console.error('Failed to create adapter:', error.message)
+ *   }
+ * }
+ * ```
  */
 declare const createAdapterFromProvider: (params: CreateAdapterFromProviderParams) => Promise<EthersAdapter>;
 
-export { EthersAdapter, createAdapterFromPrivateKey, createAdapterFromProvider };
+/**
+ * Validates adapter capabilities for EthersAdapter.
+ *
+ * This function ensures that the adapter capabilities meet the requirements for the
+ * OperationContext pattern by validating the addressContext property and optionally
+ * checking the supportedChains property for EVM compatibility.
+ *
+ * @param capabilities - The adapter capabilities to validate
+ * @throws ValidationError when capabilities validation fails
+ *
+ * @example
+ * ```typescript
+ * import { validateAdapterCapabilities } from '@circle-fin/adapter-ethers-v6/validation'
+ * import { Ethereum, Base } from '@core/chains'
+ *
+ * // Valid capabilities for user-controlled adapter
+ * const userCapabilities = {
+ *   addressContext: 'user-controlled',
+ *   supportedChains: [Ethereum, Base]
+ * }
+ *
+ * // Valid capabilities for developer-controlled adapter
+ * const devCapabilities = {
+ *   addressContext: 'developer-controlled',
+ *   supportedChains: [Ethereum]
+ * }
+ *
+ * validateAdapterCapabilities(userCapabilities) // passes validation
+ * validateAdapterCapabilities(devCapabilities) // passes validation
+ * ```
+ */
+declare function validateAdapterCapabilities(capabilities: AdapterCapabilities): void;
+
+export { Blockchain, EthersAdapter, createAdapterFromPrivateKey, createAdapterFromProvider, validateAdapterCapabilities };
 export type { ChainIdentifier, CreateAdapterFromPrivateKeyParams, CreateAdapterFromProviderParams, EthersAdapterOptions };