@circle-fin/provider-cctp-v2 1.3.0 → 1.4.0

package/index.d.ts

@@ -313,7 +313,7 @@ type ChainDefinitionWithCCTPv2 = ChainDefinition & {
  * - A Blockchain enum value (e.g., Blockchain.Ethereum)
  * - A string literal of the blockchain value (e.g., "Ethereum")
  */
-type ChainIdentifier = ChainDefinition | Blockchain | `${Blockchain}`;
+type ChainIdentifier$1 = ChainDefinition | Blockchain | `${Blockchain}`;
 interface CCTPSplitConfig {
     type: 'split';
     tokenMessenger: string;
@@ -357,6 +357,22 @@ interface CCTPConfig {
      * The contracts required for CCTP.
      */
     contracts: CCTPContracts;
+    /**
+     * Indicates whether the chain supports forwarder for source and destination.
+     * @example
+     * ```typescript
+     * const chainWithForwarderSupported: ChainDefinition = {
+     *   forwarderSupported: {
+     *     source: true,
+     *     destination: true,
+     *   },
+     * }
+     * ```
+     */
+    forwarderSupported: {
+        source: boolean;
+        destination: boolean;
+    };
 }
 /**
  * Available kit contract types for enhanced chain functionality.
@@ -913,7 +929,7 @@ type OperationContext<TAdapterCapabilities extends AdapterCapabilities = Adapter
     /**
      * The blockchain network to use for this operation.
      */
-    chain: ChainIdentifier;
+    chain: ChainIdentifier$1;
 } & AddressField<ExtractAddressContext<TAdapterCapabilities>>;
 /**
  * Fully resolved context for an adapter operation, with concrete chain and address.
@@ -1322,6 +1338,99 @@ interface CCTPv2ActionMap {
          */
         permitParams?: PermitParams;
     };
+    /**
+     * Initiate a cross-chain USDC transfer using a custom bridge contract with hook data for CCTP forwarding.
+     *
+     * This action combines the custom bridge functionality with CCTP forwarding hookData.
+     * It uses either `bridgeWithPreapprovalAndHook` or `bridgeWithPermitAndHook` contract
+     * functions depending on whether permit parameters are provided.
+     *
+     * @remarks
+     * When CCTP forwarding is enabled with custom burn, Circle's relay infrastructure will:
+     * 1. Watch for the burn transaction with forwarding hookData
+     * 2. Fetch the attestation automatically
+     * 3. Submit the destination mint transaction on behalf of the user
+     * 4. Deduct the relay fee from the minted USDC
+     *
+     * The hookData must be formatted with the CCTP forwarding magic bytes prefix
+     * followed by version and length fields. Use the `buildForwardingHookData`
+     * utility to construct properly formatted hookData.
+     *
+     * @example
+     * ```typescript
+     * import { buildForwardingHookData } from '@core/utils'
+     * import { hasCustomContractSupport } from '@core/chains'
+     *
+     * if (hasCustomContractSupport(sourceChain, 'bridge')) {
+     *   await adapter.action('cctp.v2.customBurnWithHook', {
+     *     amount: BigInt('1000000'),
+     *     mintRecipient: '0x...',
+     *     maxFee: BigInt('50000'),
+     *     minFinalityThreshold: 1000,
+     *     fromChain: ethereum,
+     *     toChain: base,
+     *     hookData: buildForwardingHookData()
+     *   })
+     * }
+     * ```
+     */
+    customBurnWithHook: CCTPv2ActionMap['customBurn'] & {
+        /**
+         * Hex-encoded hook data for CCTP forwarding.
+         *
+         * The hookData signals to Circle's Orbit relayer that forwarding is requested.
+         * Must be formatted with the CCTP forwarding magic bytes prefix ("cctp-forward"
+         * right-padded to 24 bytes) followed by uint32 version and uint32 length fields.
+         *
+         * Use the `buildForwardingHookData` utility to construct properly formatted hookData.
+         */
+        hookData: string;
+    };
+    /**
+     * Initiate a cross-chain USDC transfer with hook data for CCTP forwarding.
+     *
+     * This action extends the standard `depositForBurn` with an additional `hookData`
+     * parameter that signals to Circle's Orbit relayer that the user wants automated
+     * attestation fetching and destination mint execution.
+     *
+     * @remarks
+     * When CCTP forwarding is enabled, Circle's relay infrastructure will:
+     * 1. Watch for the burn transaction with forwarding hookData
+     * 2. Fetch the attestation automatically
+     * 3. Submit the destination mint transaction on behalf of the user
+     * 4. Deduct the relay fee from the minted USDC
+     *
+     * The hookData must be formatted with the CCTP forwarding magic bytes prefix
+     * followed by version and length fields. Use the `buildForwardingHookData`
+     * utility to construct properly formatted hookData.
+     *
+     * @example
+     * ```typescript
+     * import { buildForwardingHookData } from '@core/utils'
+     *
+     * await adapter.action('cctp.v2.depositForBurnWithHook', {
+     *   amount: BigInt('1000000'),
+     *   mintRecipient: '0x...',
+     *   maxFee: BigInt('50000'), // Must cover burn fee + forwarding fee
+     *   minFinalityThreshold: 1000,
+     *   fromChain: ethereum,
+     *   toChain: base,
+     *   hookData: buildForwardingHookData()
+     * })
+     * ```
+     */
+    depositForBurnWithHook: CCTPv2ActionMap['depositForBurn'] & {
+        /**
+         * Hex-encoded hook data for CCTP forwarding.
+         *
+         * The hookData signals to Circle's Orbit relayer that forwarding is requested.
+         * Must be formatted with the CCTP forwarding magic bytes prefix ("cctp-forward"
+         * right-padded to 24 bytes) followed by uint32 version and uint32 length fields.
+         *
+         * Use the `buildForwardingHookData` utility to construct properly formatted hookData.
+         */
+        hookData: string;
+    };
 }
 
 /**
@@ -2441,238 +2550,1328 @@ declare class Actionable<AllActions> {
 }
 
 /**
- * Transfer speed options for cross-chain operations.
+ * Module augmentation to register known token symbols.
  *
- * Defines the available speed modes for CCTPv2 transfers, affecting
- * both transfer time and potential fee implications.
- */
-declare enum TransferSpeed {
-    /** Fast burn mode - reduces transfer time but may have different fee implications */
-    FAST = "FAST",
-    /** Standard burn mode - normal transfer time with standard fees */
-    SLOW = "SLOW"
-}
-/**
- * Context object representing a wallet and signing authority on a specific blockchain network.
+ * @remarks
+ * This file augments the `TokenSymbolRegistry` interface to provide
+ * type-safe autocomplete for built-in tokens.
  *
- * Combines a wallet or contract address, the blockchain it resides on, and the adapter (signer)
- * responsible for authorizing transactions. Used to specify the source or destination in cross-chain
- * transfer operations.
+ * When imported, TypeScript will recognize 'USDC' as a valid
+ * `TokenSymbol` value with autocomplete support.
  *
- * @remarks
- * The `adapter` (signer) and `address` do not always have to belong to the same entity. For example,
- * in minting or withdrawal scenarios, the signing adapter may authorize a transaction that credits
- * funds to a different recipient address. This context is essential for cross-chain operations,
- * ensuring that both the address and the associated adapter are correctly paired with the intended
- * blockchain, but not necessarily with each other.
+ * Other packages or applications can create their own augmentations
+ * to add additional tokens.
  *
  * @example
  * ```typescript
- * import type { WalletContext } from '@core/provider'
- * import { adapter, blockchain } from './setup'
+ * import '@core/tokens' // Automatically includes this augmentation
  *
- * const wallet: WalletContext = {
- *   adapter,
- *   address: '0x1234...abcd',
- *   chain: blockchain,
- * }
+ * const symbol: TokenSymbol = 'USDC' // ✓ Autocomplete shows USDC
  * ```
  */
-interface WalletContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, 
-/**
- * The chain definition type to use for the wallet context.
- *
- * @defaultValue ChainDefinition
- */
-TChainDefinition extends ChainDefinition = ChainDefinition> {
+declare module './types' {
     /**
-     * The adapter (signer) for the wallet on the specified chain.
-     *
-     * Responsible for authorizing transactions and signing messages on behalf of the wallet or
-     * for a different recipient, depending on the use case.
-     */
-    adapter: Adapter<TAdapterCapabilities>;
-    /**
-     * The wallet or contract address.
+     * Module augmentation: Adds known token symbols as valid keys
+     * to the TokenSymbolRegistry interface.
      *
-     * Must be a valid address format for the specified blockchain. May differ from the adapter's
-     * own address in scenarios such as relayed transactions or third-party minting.
-     */
-    address: string;
-    /**
-     * The blockchain network where the wallet or contract address resides.
-     *
-     * Determines the context and format for the address and adapter.
+     * Keys are explicitly listed to ensure IDE autocomplete works properly.
      */
-    chain: TChainDefinition;
+    interface TokenSymbolRegistry {
+        USDC: true;
+    }
 }
+
 /**
- * Wallet context for bridge destinations with optional custom recipient.
+ * Module augmentation to register Blockchain enum values as ChainIdentifiers.
  *
- * Extends WalletContext to support scenarios where the recipient address
- * differs from the signer address (e.g., bridging to a third-party wallet).
- * The signer address is used for transaction authorization, while the
- * recipient address specifies where the minted funds should be sent.
+ * @remarks
+ * This file augments the `ChainRegistry` interface to provide type-safe
+ * autocomplete for all `Blockchain` enum values from `@core/chains`.
  *
- * @typeParam TAdapterCapabilities - The adapter capabilities type to use for the wallet context.
- * @typeParam TChainDefinition - The chain definition type to use for the wallet context.
+ * When this augmentation is imported (via `@core/tokens`), TypeScript will
+ * recognize all blockchain identifiers as valid `ChainIdentifier` values
+ * with IDE autocomplete support.
+ *
+ * The `Blockchain` enum values are converted to their string representations,
+ * enabling both enum values and string literals to be accepted as chain identifiers.
  *
  * @example
  * ```typescript
- * import type { DestinationWalletContext } from '@core/provider'
- * import { adapter, blockchain } from './setup'
+ * import { Blockchain } from '@core/chains'
+ * import type { ChainIdentifier } from '@core/tokens'
  *
- * // Bridge to a custom recipient address
- * const destination: DestinationWalletContext = {
- *   adapter,
- *   address: '0x1234...abcd', // Signer address
- *   chain: blockchain,
- *   recipientAddress: '0x9876...fedc' // Custom recipient
- * }
- * ```
- */
-interface DestinationWalletContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, 
-/**
- * The chain definition type to use for the wallet context.
+ * // Using enum value
+ * const chain1: ChainIdentifier = Blockchain.Ethereum
  *
- * @defaultValue ChainDefinition
+ * // Using string literal (with autocomplete!)
+ * const chain2: ChainIdentifier = 'Base'
+ *
+ * // Arbitrary strings also work (escape hatch for custom chains)
+ * const chain3: ChainIdentifier = 'my-custom-chain'
+ * ```
  */
-TChainDefinition extends ChainDefinition = ChainDefinition> extends WalletContext<TAdapterCapabilities, TChainDefinition> {
+
+declare module './types' {
     /**
-     * Optional custom recipient address for minted funds.
+     * Module augmentation: Adds all Blockchain enum values as valid keys
+     * to the ChainRegistry interface for type-safe chain identifier support.
      *
-     * When provided, minted tokens will be sent to this address instead of
-     * the address specified in the wallet context. The wallet context address
-     * is still used for transaction signing and authorization.
+     * This ensures both enum property access (e.g., Blockchain.Ethereum) and plain
+     * string literals (e.g., 'Ethereum') are accepted by TypeScript as chain keys,
+     * providing robust autocomplete and error checking.
      *
-     * Must be a valid address format for the specified blockchain.
+     * NOTE:
+     * - This interface intentionally has no body. It merges a mapped Record type
+     *   into ChainRegistry solely for type augmentation.
+     * - This empty-body construct is a necessary TypeScript idiom for module
+     *   augmentation with Record types—directly listing mapped keys is not
+     *   feasible in interface extensions.
+     *
+     * eslint-disable-next-line directives below suppress linter complaints about
+     * the empty interface/mapping, which are benign and required for this pattern.
      */
-    recipientAddress?: string;
+    interface ChainRegistry extends Record<`${Blockchain}`, true> {
+    }
 }
+
 /**
- * Parameters for executing a cross-chain bridge operation.
+ * Creates a union type that preserves IDE autocomplete for known literals
+ * while still accepting any string at runtime.
+ *
+ * @remarks
+ * This pattern uses `Record<never, never>` (an empty record type) to prevent
+ * TypeScript from widening string literals to just `string`. This gives us
+ * the best of both worlds: autocomplete for known values and flexibility
+ * for arbitrary strings.
+ *
+ * @typeParam T - The known string literal union to preserve.
  */
-interface BridgeParams<TFromCapabilities extends AdapterCapabilities = AdapterCapabilities, TToCapabilities extends AdapterCapabilities = AdapterCapabilities, 
+type LiteralUnion<T extends string> = T | (string & Record<never, never>);
 /**
- * The chain definition type to use for the wallet context.
+ * Registry for known chain identifiers (augmentation target).
  *
- * @defaultValue ChainDefinition
+ * @remarks
+ * This empty interface exists solely for module augmentation. Extend it to
+ * register chain identifiers for type-safe token definitions.
+ *
+ * **Why an interface?** TypeScript only allows module augmentation on
+ * interfaces, not type aliases.
+ *
+ * **Note:** This is NOT the EVM "chain ID" (numeric like 1 for Ethereum).
+ * It's a human-readable identifier like "Ethereum", "Solana", "Base".
+ *
+ * **Usage**
+ *
+ * Without augmentation, `ChainIdentifier` defaults to `string`.
+ * With `@core/chains` imported, you get autocomplete for all `Blockchain` values.
+ *
+ * **Custom Chains**
+ *
+ * ```typescript
+ * declare module '@core/tokens' {
+ *   interface ChainRegistry {
+ *     MyChain: true
+ *     MyTestnet: true
+ *   }
+ * }
+ * // Now ChainIdentifier includes 'MyChain' | 'MyTestnet' | ...
+ * ```
+ *
+ * The value (`true`) is a placeholder—only the keys matter.
+ *
+ * NOTE: The eslint-disable below suppresses warnings about empty interfaces.
+ * This is intentional—the interface exists solely as an augmentation target.
  */
-TChainDefinition extends ChainDefinition = ChainDefinition> {
-    /** The source adapter containing wallet and chain information */
-    source: WalletContext<TFromCapabilities, TChainDefinition>;
-    /** The destination adapter containing wallet and chain information */
-    destination: DestinationWalletContext<TToCapabilities, TChainDefinition>;
-    /** The amount to transfer (as a string to avoid precision issues) */
-    amount: string;
-    /** The token to transfer (currently only USDC is supported) */
-    token: 'USDC';
-    /** Bridge configuration (e.g., fast burn settings) */
-    config: BridgeConfig;
+interface ChainRegistry {
 }
 /**
- * A step in the bridge process.
+ * Union of all registered chain identifiers.
  *
  * @remarks
- * This interface represents a single step in the bridge process,
- * such as approval, burn, or mint.
+ * Derived from `ChainRegistry` keys:
+ * - Without augmentation: `string`
+ * - With `@core/chains`: `'Ethereum' | 'Solana' | ...` plus any string
+ *
+ * Uses `LiteralUnion` to preserve IDE autocomplete while allowing
+ * arbitrary strings at runtime.
  *
  * @example
  * ```typescript
- * const step: BridgeStep = {
- *   name: 'Approve',
- *   state: 'success',
- *   txHash: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
- *   explorerUrl: 'https://etherscan.io/tx/0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
- * }
+ * const chain: ChainIdentifier = 'Ethereum'  // Autocomplete works
+ * const custom: ChainIdentifier = 'my-chain' // Also valid
  * ```
  */
-interface BridgeStep {
-    /** Human-readable name of the step (e.g., "Approve", "Burn", "Mint") */
-    name: string;
-    /** The state of the step */
-    state: 'pending' | 'success' | 'error' | 'noop';
-    /** Optional transaction hash for this step (if applicable) */
-    txHash?: string;
-    /** Optional explorer URL for viewing this transaction on a block explorer */
-    explorerUrl?: string;
-    /** Optional data for the step */
-    data?: unknown;
-    /** Optional human-readable error message */
-    errorMessage?: string;
-    /** Optional raw error object (can be Viem/Ethers/Chain error) */
-    error?: unknown;
-}
+type ChainIdentifier = keyof ChainRegistry extends never ? string : LiteralUnion<Extract<keyof ChainRegistry, string>>;
 /**
- * Result object returned after a successful cross-chain bridge operation.
+ * Maps chain identifiers to their token locators.
  *
- * This interface contains all the details about a completed bridge, including
- * the bridge parameters, source and destination information,
- * and the sequence of steps that were executed.
+ * @remarks
+ * The key is a chain identifier (type-safe when `KnownChainIdentifiers` is
+ * augmented). This enables a single token definition to work across chains.
+ *
+ * When `@core/chains` is imported, you get autocomplete for known chains
+ * like `Ethereum`, `Base`, `Solana`, etc.
  *
  * @example
  * ```typescript
- * const result: BridgeResult = await provider.bridge(source, dest, '100')
- * console.log(`Transferred ${result.amount} ${result.token}`)
- * console.log(`Steps executed: ${result.steps.length}`)
+ * import { Blockchain } from '@core/chains'
+ *
+ * const usdcLocators: ChainLocatorMap = {
+ *   [Blockchain.Ethereum]: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+ *   [Blockchain.Solana]: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   [Blockchain.Base]: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+ * }
+ *
+ * // Or with string keys (always works)
+ * const locators: ChainLocatorMap = {
+ *   'ethereum': '0xa0b86991...',
+ *   'my-custom-chain': '0x1234...',
+ * }
  * ```
  */
-interface BridgeResult {
-    /** The amount that was transferred (as a string to avoid precision issues) */
-    amount: string;
-    /** The token that was transferred (currently only USDC is supported) */
-    token: 'USDC';
-    /** The state of the transfer */
-    state: 'pending' | 'success' | 'error';
-    /** The bridge configuration that was used for this operation */
-    config?: BridgeConfig;
-    /** The provider that was used for this operation */
-    provider: string;
-    /** Information about the source chain and address */
-    source: {
-        /** The source wallet/contract address */
-        address: string;
-        /** The source blockchain network */
-        chain: ChainDefinition;
-    };
-    /** Information about the destination chain and address */
-    destination: {
-        /** The destination wallet/contract address */
-        address: string;
-        /** The destination blockchain network */
-        chain: ChainDefinition;
-        /**
-         * Optional custom recipient address for minted funds.
-         *
-         * When provided during the bridge operation, minted tokens are sent to this
-         * address instead of the destination address. This field is preserved in the
-         * result for retry operations to maintain consistency with the original burn.
-         */
-        recipientAddress?: string;
-    };
-    /** Array of steps that were executed during the bridge process */
-    steps: BridgeStep[];
-}
+type ChainLocatorMap = Record<ChainIdentifier, string>;
 /**
- * Cost estimation result for a cross-chain transfer operation.
+ * Complete definition of a token including metadata and chain locators.
  *
- * This interface provides detailed information about the expected costs
- * for a transfer, including gas fees on different chains and protocol fees.
- * It also includes the input context (token, amount, source, destination) to
- * provide a complete view of the transfer being estimated.
+ * @remarks
+ * This is the canonical representation of a token in the registry.
+ * It includes the symbol, decimals, and chain-specific locators.
  *
  * @example
  * ```typescript
- * const estimate: EstimateResult = await provider.estimate(source, dest, '100')
- * console.log('Estimating transfer of', estimate.amount, estimate.token)
- * console.log('From', estimate.source.chain.name, 'to', estimate.destination.chain.name)
- * console.log('Total gas fees:', estimate.gasFees.length)
- * console.log('Protocol fees:', estimate.fees.length)
+ * const usdc: TokenDefinition = {
+ *   symbol: 'USDC',
+ *   decimals: 6,
+ *   locators: {
+ *     [Blockchain.Ethereum]: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+ *     [Blockchain.Solana]: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   },
+ * }
  * ```
  */
-interface EstimateResult {
-    /** The token being transferred */
-    token: 'USDC';
+interface TokenDefinition {
+    /**
+     * The token symbol (e.g., "USDC", "EURC").
+     */
+    readonly symbol: string;
+    /**
+     * The number of decimal places for the token.
+     * @example 6 for USDC, 18 for most ERC20 tokens
+     */
+    readonly decimals: number;
+    /**
+     * Chain-specific locators for the token.
+     * Keys are chain identifiers, values are the token address/locator on that chain.
+     * Not all chains need to be present - tokens may only exist on a subset of chains.
+     */
+    readonly locators: Partial<ChainLocatorMap>;
+}
+/**
+ * A raw token locator selector with explicit decimals.
+ *
+ * @remarks
+ * Use this form when working with arbitrary tokens not in the registry.
+ * The `locator` is the chain-specific address, and `decimals` is required
+ * unless using lenient mode.
+ *
+ * @example
+ * ```typescript
+ * // Selecting a custom token by address
+ * const selector: RawTokenSelector = {
+ *   locator: '0x1234567890abcdef1234567890abcdef12345678',
+ *   decimals: 18,
+ * }
+ * ```
+ */
+interface RawTokenSelector {
+    /**
+     * The chain-specific token locator (address, program ID, etc.).
+     */
+    readonly locator: string;
+    /**
+     * The number of decimal places.
+     * Required in strict mode, optional in lenient mode.
+     */
+    readonly decimals?: number;
+}
+/**
+ * Registry for known token symbols (augmentation target).
+ *
+ * @remarks
+ * This empty interface exists solely for module augmentation. Extend it to
+ * register token symbols for type-safe selection.
+ *
+ * **Why an interface?** TypeScript only allows module augmentation on
+ * interfaces, not type aliases.
+ *
+ * **Usage**
+ *
+ * Without augmentation, `TokenSymbol` defaults to `string`.
+ *
+ * ```typescript
+ * declare module '@core/tokens' {
+ *   interface TokenSymbolRegistry {
+ *     USDC: true
+ *     EURC: true
+ *   }
+ * }
+ * // Now TokenSymbol includes 'USDC' | 'EURC' | ...
+ * ```
+ *
+ * NOTE: The eslint-disable below suppresses warnings about empty interfaces.
+ * This is intentional—the interface exists solely as an augmentation target.
+ */
+interface TokenSymbolRegistry {
+}
+/**
+ * Union type of all registered token symbols.
+ *
+ * @remarks
+ * This type is derived from the keys of `TokenSymbolRegistry`:
+ * - **Without augmentation** — Simply `string` (any value)
+ * - **With augmentation** — `'USDC' | 'USDT' | ...` plus any string
+ *
+ * Uses `LiteralUnion` to preserve autocomplete for known values while
+ * still accepting any string at runtime.
+ *
+ * @example
+ * ```typescript
+ * // With symbols.augment imported - autocomplete works
+ * const symbol: TokenSymbol = 'USDC'
+ *
+ * // Custom strings still accepted
+ * const symbol: TokenSymbol = 'MY_TOKEN'
+ * ```
+ */
+type TokenSymbol = keyof TokenSymbolRegistry extends never ? string : LiteralUnion<Extract<keyof TokenSymbolRegistry, string>>;
+/**
+ * Selector for identifying a token.
+ *
+ * @remarks
+ * Can be one of:
+ * - A symbol string (e.g., "USDC") - resolves from registry
+ * - A raw locator object with explicit decimals - for arbitrary tokens
+ *
+ * Using a symbol is preferred when the token is in the registry, as it
+ * automatically resolves decimals and the correct chain address.
+ *
+ * @example
+ * ```typescript
+ * // By symbol (preferred for known tokens)
+ * const selector1: TokenSelector = 'USDC'
+ *
+ * // By raw locator (for arbitrary tokens)
+ * const selector2: TokenSelector = {
+ *   locator: '0x1234...',
+ *   decimals: 18,
+ * }
+ * ```
+ */
+type TokenSelector = TokenSymbol | RawTokenSelector;
+/**
+ * The resolved token information after registry lookup.
+ *
+ * @remarks
+ * This is the result of resolving a `TokenSelector` against a chain.
+ * It always contains the locator and decimals, and optionally the symbol
+ * if the token was resolved from the registry.
+ */
+interface ResolvedToken {
+    /**
+     * The token symbol, if known.
+     * Present when resolved from registry, absent for raw locators.
+     */
+    readonly symbol?: string;
+    /**
+     * The number of decimal places for the token.
+     */
+    readonly decimals: number;
+    /**
+     * The chain-specific token locator (address, program ID, etc.).
+     */
+    readonly locator: string;
+}
+/**
+ * Interface for the token registry.
+ *
+ * @remarks
+ * The registry is the sole source of truth for token information.
+ * It supports both symbol-based and raw locator-based token selection.
+ *
+ * @example
+ * ```typescript
+ * import { createTokenRegistry } from '@core/tokens'
+ *
+ * // Create registry (includes built-in tokens like USDC)
+ * const registry = createTokenRegistry()
+ *
+ * // Resolve by symbol
+ * const usdc = registry.resolve('USDC', 'Ethereum')
+ * console.log(usdc.locator) // '0xa0b86991...'
+ *
+ * // Resolve raw locator
+ * const custom = registry.resolve({ locator: '0x...', decimals: 18 }, 'Ethereum')
+ * ```
+ */
+interface TokenRegistry {
+    /**
+     * Resolve a token selector to concrete token information for a chain.
+     *
+     * @param selector - The token to resolve (symbol or raw locator).
+     * @param chainId - The chain identifier to resolve for.
+     * @returns The resolved token information.
+     * @throws When the token cannot be resolved (unknown symbol, missing decimals, etc.).
+     */
+    resolve(selector: TokenSelector, chainId: ChainIdentifier): ResolvedToken;
+    /**
+     * Get a token definition by symbol.
+     *
+     * @param symbol - The token symbol (e.g., "USDC").
+     * @returns The token definition, or undefined if not found.
+     */
+    get(symbol: string): TokenDefinition | undefined;
+    /**
+     * Check if a symbol is registered.
+     *
+     * @param symbol - The token symbol to check.
+     * @returns True if the symbol is in the registry.
+     */
+    has(symbol: string): boolean;
+    /**
+     * Get all registered token symbols.
+     *
+     * @returns An array of registered symbol strings.
+     */
+    symbols(): string[];
+    /**
+     * Get all registered token definitions.
+     *
+     * @returns An array of all TokenDefinition objects in the registry.
+     */
+    entries(): TokenDefinition[];
+}
+
+/**
+ * Structured fields that can be attached to log entries.
+ */
+type LogFields = Record<string, unknown>;
+/**
+ * Logger interface providing structured logging with child scoping.
+ *
+ * @remarks
+ * This interface defines a minimal, framework-agnostic logging contract.
+ * The underlying implementation uses pino for transport handling (console,
+ * file, remote, JSON, pretty, etc.) but consumers only interact with this
+ * stable interface.
+ *
+ * @example
+ * ```typescript
+ * import { createLogger } from '@core/runtime'
+ *
+ * const logger = createLogger({ level: 'debug' })
+ *
+ * // Simple message
+ * logger.info('Server started')
+ *
+ * // Message with structured fields
+ * logger.info('Request received', { method: 'POST', path: '/api/transfer' })
+ *
+ * // Create child logger with context
+ * const requestLogger = logger.child({ requestId: 'abc-123' })
+ * requestLogger.debug('Processing transfer')
+ * // Output includes: requestId in all subsequent logs
+ * ```
+ */
+interface Logger {
+    /**
+     * Log a debug-level message.
+     * @param message - The log message.
+     * @param fields - Optional structured fields.
+     * @returns void
+     */
+    debug(message: string, fields?: LogFields): void;
+    /**
+     * Log an info-level message.
+     * @param message - The log message.
+     * @param fields - Optional structured fields.
+     * @returns void
+     */
+    info(message: string, fields?: LogFields): void;
+    /**
+     * Log a warning-level message.
+     * @param message - The log message.
+     * @param fields - Optional structured fields.
+     * @returns void
+     */
+    warn(message: string, fields?: LogFields): void;
+    /**
+     * Log an error-level message.
+     * @param message - The log message.
+     * @param fields - Optional structured fields.
+     * @returns void
+     */
+    error(message: string, fields?: LogFields): void;
+    /**
+     * Create a child logger with additional contextual bindings.
+     *
+     * @param tags - Key-value pairs to add to the child logger's context.
+     *   Undefined values are filtered out automatically.
+     * @returns A new Logger instance with merged bindings.
+     *
+     * @example
+     * ```typescript
+     * const requestLogger = logger.child({ requestId: 'req-123' })
+     * const userLogger = requestLogger.child({ userId: 'user-456' })
+     * // All logs from userLogger include both requestId and userId
+     * ```
+     */
+    child(tags: LogFields): Logger;
+}
+
+/**
+ * Handler function for event subscriptions.
+ */
+type EventHandler = (event: Event) => void | Promise<void>;
+/**
+ * Event bus for publishing and subscribing to events.
+ *
+ * @remarks
+ * Supports wildcard topic subscriptions:
+ * - `*` matches exactly one segment
+ * - `**` matches zero or more segments
+ *
+ * @example
+ * ```typescript
+ * const bus = createEventBus()
+ *
+ * // Subscribe to all events
+ * bus.on((event) => console.log(event))
+ *
+ * // Subscribe to specific topic
+ * bus.on('tx.wait.started', (event) => console.log(event))
+ *
+ * // Subscribe with wildcard
+ * bus.on('tx.wait.*', (event) => console.log(event))
+ * bus.on('tx.**', (event) => console.log(event))
+ *
+ * // Emit events
+ * bus.emit({ name: 'tx.wait.started', data: { txId: '0x123' } })
+ * ```
+ */
+interface EventBus {
+    /**
+     * Emit an event to all matching subscribers.
+     *
+     * @param event - The event to emit.
+     * @remarks
+     * Synchronous and never throws. Handler errors are isolated.
+     */
+    emit(event: Event): void;
+    /**
+     * Create a child event bus with scoped tags.
+     *
+     * @param tags - Tags to merge into all emitted events.
+     * @returns A new EventBus with merged tags.
+     */
+    child(tags: Tags): EventBus;
+    /**
+     * Subscribe to all events.
+     *
+     * @param handler - Function called for every event.
+     * @returns Unsubscribe function.
+     */
+    on(handler: EventHandler): () => void;
+    /**
+     * Subscribe to events matching a pattern.
+     *
+     * @param pattern - Topic pattern (supports `*` and `**` wildcards).
+     * @param handler - Function called for matching events.
+     * @returns Unsubscribe function.
+     *
+     * @remarks
+     * Wildcard semantics:
+     * - `*` matches exactly one segment (no dots)
+     * - `**` matches zero or more segments (only valid at end)
+     *
+     * @example
+     * ```typescript
+     * bus.on('*', handler)             // matches 'tx', 'user' (single segment only)
+     * bus.on('tx.wait.*', handler)     // matches tx.wait.started, tx.wait.failed
+     * bus.on('tx.wait.**', handler)    // matches tx.wait, tx.wait.started, tx.wait.foo.bar
+     * bus.on('**', handler)            // matches all events
+     * ```
+     */
+    on(pattern: string, handler: EventHandler): () => void;
+}
+
+/**
+ * Metrics type definitions for the Runtime module.
+ *
+ * @remarks
+ * Define a minimal, pluggable metrics interface that can be backed by any
+ * metrics library (hot-shots, dd-trace, prom-client, etc.).
+ *
+ * The interface supports:
+ * - Counters for monotonically increasing values
+ * - Histograms for distributions (latencies, sizes)
+ * - Timers as a convenience wrapper for timing operations
+ * - Label scoping via `child()` for dimensional metrics
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * metrics.counter('requests.total').inc({ method: 'POST' })
+ * metrics.histogram('request.duration').observe({ status: 200 }, 42.5)
+ *
+ * // Timer convenience
+ * const stop = metrics.timer('db.query').start({ table: 'users' })
+ * await query()
+ * stop() // Records duration automatically
+ *
+ * // Scoping adds base labels to all metrics
+ * const scoped = metrics.child({ service: 'bridge', env: 'prod' })
+ * scoped.counter('transfers').inc() // Includes service + env labels
+ * ```
+ */
+/**
+ * Labels for dimensional metrics.
+ *
+ * @remarks
+ * Labels (also called tags in some systems) are key-value pairs that
+ * provide dimensions for metric aggregation and filtering.
+ * Values must be primitives for serialization compatibility.
+ *
+ * @example
+ * ```typescript
+ * const labels: MetricLabels = {
+ *   chain: 'Ethereum',
+ *   status: 'success',
+ *   retries: 3,
+ *   cached: true,
+ * }
+ * ```
+ */
+type MetricLabels = Record<string, string | number | boolean>;
+/**
+ * A counter metric for monotonically increasing values.
+ *
+ * @remarks
+ * Use counters for values that only go up: request counts, error counts,
+ * bytes processed, etc. The value resets only on process restart.
+ *
+ * @see {@link Metrics.counter} to obtain a Counter instance.
+ *
+ * @example
+ * ```typescript
+ * const counter = metrics.counter('http.requests')
+ *
+ * // Increment by 1
+ * counter.inc()
+ * counter.inc({ method: 'GET' })
+ *
+ * // Increment by specific value
+ * counter.inc(5)
+ * counter.inc({ method: 'POST' }, 3)
+ * ```
+ */
+interface Counter {
+    /**
+     * Increment the counter value.
+     *
+     * @param labelsOrValue - The labels object or increment value.
+     *   When a number, increments by that amount with no labels.
+     *   When an object, uses as labels with optional value in second param.
+     * @param value - The increment value when first arg is labels. Default: 1.
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * counter.inc()                          // +1, no labels
+     * counter.inc(5)                         // +5, no labels
+     * counter.inc({ method: 'GET' })         // +1, with labels
+     * counter.inc({ method: 'POST' }, 3)     // +3, with labels
+     * ```
+     */
+    inc(labelsOrValue?: MetricLabels | number, value?: number): void;
+}
+/**
+ * A histogram metric for recording value distributions.
+ *
+ * @remarks
+ * Use histograms for values that vary and need percentile analysis:
+ * request durations, response sizes, queue depths, etc.
+ *
+ * @see {@link Metrics.histogram} to obtain a Histogram instance.
+ *
+ * @example
+ * ```typescript
+ * const histogram = metrics.histogram('http.duration')
+ *
+ * // Record a value
+ * histogram.observe(42.5)
+ * histogram.observe({ status: 200 }, 42.5)
+ * ```
+ */
+interface Histogram {
+    /**
+     * Record an observation value.
+     *
+     * @param labelsOrValue - The labels object or observed value.
+     *   When a number, records that value with no labels.
+     *   When an object, uses as labels with value in second param.
+     * @param value - The observed value when first arg is labels. Default: 0.
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * histogram.observe(42.5)                    // Value only
+     * histogram.observe({ status: 200 }, 42.5)  // With labels
+     * ```
+     */
+    observe(labelsOrValue?: MetricLabels | number, value?: number): void;
+}
+/**
+ * A timer metric for measuring operation durations.
+ *
+ * @remarks
+ * Timers provide a convenience wrapper that automatically records durations
+ * to an underlying histogram. Call `start()` to begin timing and the
+ * returned function to stop and record the elapsed time in milliseconds.
+ *
+ * @see {@link Metrics.timer} to obtain a Timer instance.
+ *
+ * @example
+ * ```typescript
+ * const timer = metrics.timer('db.query')
+ *
+ * // Start timing
+ * const stop = timer.start({ table: 'users' })
+ * await performQuery()
+ * stop() // Records duration in milliseconds
+ * ```
+ */
+interface Timer {
+    /**
+     * Start timing an operation.
+     *
+     * @param labels - The optional labels for the timing observation.
+     * @returns A stop function that records the duration when called.
+     *
+     * @example
+     * ```typescript
+     * const stop = timer.start({ operation: 'fetch' })
+     * await fetchData()
+     * stop() // Records elapsed time
+     * ```
+     */
+    start(labels?: MetricLabels): () => void;
+}
+/**
+ * Main metrics interface for instrumentation.
+ *
+ * @remarks
+ * This interface is designed to be thin and pluggable. Implementations
+ * can delegate to any metrics library:
+ *
+ * - **hot-shots**: StatsD/DogStatsD client
+ * - **dd-trace**: Datadog APM
+ * - **prom-client**: Prometheus
+ * - **opentelemetry-js**: OpenTelemetry
+ *
+ * The `child()` method creates a scoped metrics instance that automatically
+ * includes base labels on all metric operations.
+ *
+ * @see {@link createMockMetrics} for testing.
+ * @see {@link noopMetrics} for a no-op implementation.
+ *
+ * @example
+ * ```typescript
+ * // Create a scoped metrics instance
+ * const appMetrics = metrics.child({
+ *   service: 'stablecoin-kit',
+ *   version: '1.0.0',
+ * })
+ *
+ * // All metrics include service + version labels
+ * appMetrics.counter('transfers.initiated').inc({ chain: 'ethereum' })
+ * ```
+ */
+interface Metrics {
+    /**
+     * Get or create a counter metric by name.
+     *
+     * @param name - The metric name (e.g., 'http.requests.total').
+     * @returns A Counter instance for the given name.
+     *
+     * @example
+     * ```typescript
+     * const counter = metrics.counter('requests.total')
+     * counter.inc({ method: 'GET' })
+     * ```
+     */
+    counter(name: string): Counter;
+    /**
+     * Get or create a histogram metric by name.
+     *
+     * @param name - The metric name (e.g., 'http.request.duration').
+     * @returns A Histogram instance for the given name.
+     *
+     * @example
+     * ```typescript
+     * const histogram = metrics.histogram('request.duration')
+     * histogram.observe({ status: 200 }, 42.5)
+     * ```
+     */
+    histogram(name: string): Histogram;
+    /**
+     * Get or create a timer metric by name.
+     *
+     * @param name - The metric name (e.g., 'db.query.duration').
+     * @returns A Timer instance for the given name.
+     *
+     * @example
+     * ```typescript
+     * const stop = metrics.timer('db.query').start()
+     * await query()
+     * stop()
+     * ```
+     */
+    timer(name: string): Timer;
+    /**
+     * Create a child metrics instance with scoped labels.
+     *
+     * @param labels - The base labels to include on all metric operations.
+     * @returns A new Metrics instance with merged labels.
+     *
+     * @remarks
+     * Labels from the child are merged with any labels passed to individual
+     * metric operations. Call-site labels take precedence for the same key.
+     *
+     * @example
+     * ```typescript
+     * const scoped = metrics.child({ chain: 'Ethereum' })
+     * scoped.counter('transfers').inc({ status: 'success' })
+     * // Labels: { chain: 'Ethereum', status: 'success' }
+     * ```
+     */
+    child(labels: MetricLabels): Metrics;
+}
+
+/**
+ * Core type definitions for the runtime package.
+ *
+ * @remarks
+ * This module defines the foundational types used throughout the SDK:
+ *
+ * - {@link Runtime} - Complete runtime with all services (clock, logger, metrics, events)
+ * - {@link ExecutionContext} - Context for middleware with observability surface
+ * - {@link Clock}, {@link Tags}, {@link Event} - Supporting types
+ *
+ * **Naming Convention**
+ *
+ * | Input Type | Resolved Type | Description |
+ * |------------|---------------|-------------|
+ * | `Partial<Runtime>` | `Runtime` | Runtime services |
+ * | `OperationMeta` | `OperationContext` | WHAT - operation target |
+ * | `InvocationMeta` | `InvocationContext` | WHO/HOW - call chain |
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Clock interface for time operations.
+ *
+ * @remarks
+ * Abstracting time allows tests to control timing without real delays.
+ * Production code uses {@link defaultClock}, tests use mock implementations.
+ *
+ * @example
+ * ```typescript
+ * import { defaultClock, type Clock } from '@core/runtime'
+ *
+ * const start = defaultClock.now()
+ * // ... do work ...
+ * const elapsed = defaultClock.since(start)
+ * ```
+ */
+interface Clock {
+    /**
+     * Return the current timestamp in milliseconds since Unix epoch.
+     *
+     * @returns Current time in milliseconds.
+     */
+    now(): number;
+    /**
+     * Calculate elapsed time since a given timestamp.
+     *
+     * @param start - The start timestamp in milliseconds.
+     * @returns Elapsed time in milliseconds (`now() - start`).
+     */
+    since: (start: number) => number;
+}
+/**
+ * Contextual metadata tags for logging and metrics.
+ *
+ * @remarks
+ * Tags are key-value pairs attached to log entries and metrics.
+ * Values can be primitives or undefined (undefined values are filtered out).
+ *
+ * Common tags include:
+ * - `opId` - Operation identifier for correlation
+ * - `chain` - Blockchain network name
+ * - `phase` - Current pipeline phase
+ *
+ * @example
+ * ```typescript
+ * import type { Tags } from '@core/runtime'
+ *
+ * const tags: Tags = {
+ *   opId: 'op-abc123',
+ *   chain: 'Ethereum',
+ *   phase: 'validate',
+ *   optional: undefined, // Will be filtered out
+ * }
+ * ```
+ */
+type Tags = Record<string, string | number | boolean | undefined>;
+/**
+ * A structured event emitted by the runtime.
+ *
+ * @remarks
+ * Events provide a standardized way to capture lifecycle moments,
+ * actions, and state changes throughout the SDK.
+ */
+interface Event {
+    /** The event name/identifier. */
+    name: string;
+    /** Log level for the event. */
+    level?: 'debug' | 'info' | 'warn' | 'error';
+    /** Timestamp (epoch ms) when the event occurred. */
+    at?: number;
+    /** Contextual tags for filtering/categorization. */
+    tags?: Tags;
+    /** Arbitrary payload data associated with the event. */
+    data?: unknown;
+}
+/**
+ * Complete runtime with all services guaranteed present.
+ *
+ * @remarks
+ * The runtime is the container for all cross-cutting concerns: logging,
+ * timing, events, and metrics. All services are guaranteed to be available.
+ *
+ * **Creating a Runtime**
+ *
+ * Use {@link createRuntime} to create a fully-configured runtime:
+ * ```typescript
+ * import { createRuntime } from '@core/runtime'
+ *
+ * const runtime = createRuntime()
+ * runtime.logger.info('Hello')
+ * runtime.metrics.counter('requests').inc()
+ * ```
+ *
+ * **Partial Runtime Input**
+ *
+ * When accepting runtime configuration as input, use `Partial<Runtime>`:
+ * ```typescript
+ * function myFunction(options: { runtime?: Partial<Runtime> }) {
+ *   const runtime = createRuntime(options.runtime)
+ *   // ...
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createRuntime, type Runtime } from '@core/runtime'
+ *
+ * const runtime: Runtime = createRuntime()
+ *
+ * // All services are guaranteed present
+ * runtime.logger.info('Processing request')
+ * runtime.metrics.counter('requests').inc()
+ * runtime.events.emit({ name: 'request.received' })
+ * const now = runtime.clock.now()
+ * ```
+ */
+interface Runtime {
+    /**
+     * Clock for time operations.
+     *
+     * @remarks
+     * Provides the current timestamp. Use {@link defaultClock} for production
+     * or custom clocks for deterministic testing.
+     */
+    clock: Clock;
+    /**
+     * Logger for structured logging.
+     *
+     * @remarks
+     * Provides debug, info, warn, error methods with structured data support.
+     */
+    logger: Logger;
+    /**
+     * Metrics collector for observability.
+     *
+     * @remarks
+     * Provides counters, histograms, and timers for application metrics.
+     */
+    metrics: Metrics;
+    /**
+     * Event bus for pub/sub events.
+     *
+     * @remarks
+     * Enables decoupled event emission and subscription across the SDK.
+     */
+    events: EventBus;
+}
+/**
+ * A component in the call chain.
+ *
+ * @remarks
+ * Each caller identifies itself with a type (app, kit, provider, adapter)
+ * and a name/version. This enables proper attribution in logs, metrics, and traces.
+ *
+ * @example
+ * ```typescript
+ * import type { Caller } from '@core/runtime'
+ *
+ * const appCaller: Caller = { type: 'app', name: 'MyDApp', version: '1.0.0' }
+ * const kitCaller: Caller = { type: 'kit', name: 'BridgeKit', version: '2.0.0' }
+ * ```
+ */
+interface Caller {
+    /**
+     * Type of component in the call hierarchy.
+     *
+     * @remarks
+     * Common types: `app`, `kit`, `provider`, `adapter`
+     */
+    readonly type: string;
+    /** Name of the component (e.g., 'BridgeKit', 'cctp-v2'). */
+    readonly name: string;
+    /** Version of the component (e.g., '1.0.0'). */
+    readonly version?: string | undefined;
+}
+/**
+ * User input for invocation metadata.
+ *
+ * @remarks
+ * Defines **WHO** called and **HOW** to observe: trace correlation, runtime override,
+ * and caller chain. This is the user-facing input type, resolved to `InvocationContext`.
+ *
+ * Passed as the optional invocation argument to actions and primitives.
+ *
+ * @example
+ * ```typescript
+ * import type { InvocationMeta } from '@core/runtime'
+ *
+ * // Minimal - just traceId
+ * const meta: InvocationMeta = { traceId: 'abc-123' }
+ *
+ * // Full - with runtime override and caller chain
+ * const meta: InvocationMeta = {
+ *   traceId: 'abc-123',
+ *   runtime: myRuntime,
+ *   callers: [
+ *     { type: 'app', name: 'MyDApp', version: '1.0.0' },
+ *   ],
+ * }
+ * ```
+ */
+interface InvocationMeta {
+    /**
+     * Trace ID for distributed tracing correlation.
+     *
+     * @remarks
+     * If not provided, generated automatically.
+     */
+    readonly traceId?: string | undefined;
+    /**
+     * Runtime override (complete replacement).
+     *
+     * @remarks
+     * When provided, this runtime completely replaces the default runtime.
+     * Must be a complete Runtime instance (e.g., from `createRuntime()`).
+     * If not provided, the default runtime is used.
+     */
+    readonly runtime?: Runtime | undefined;
+    /**
+     * Token registry override (complete replacement).
+     *
+     * @remarks
+     * When provided, this registry completely replaces the default token registry.
+     * Enables kits to pass their token registry to adapters.
+     * If not provided, the default token registry is used.
+     */
+    readonly tokens?: TokenRegistry | undefined;
+    /**
+     * Call chain - each caller appends itself.
+     *
+     * @remarks
+     * Ordered from outermost (first) to innermost (last).
+     * Example: [app, kit, provider]
+     */
+    readonly callers?: readonly Caller[] | undefined;
+}
+
+/**
+ * Transfer speed options for cross-chain operations.
+ *
+ * Defines the available speed modes for CCTPv2 transfers, affecting
+ * both transfer time and potential fee implications.
+ */
+declare enum TransferSpeed {
+    /** Fast burn mode - reduces transfer time but may have different fee implications */
+    FAST = "FAST",
+    /** Standard burn mode - normal transfer time with standard fees */
+    SLOW = "SLOW"
+}
+/**
+ * Context object representing a wallet and signing authority on a specific blockchain network.
+ *
+ * Combines a wallet or contract address, the blockchain it resides on, and the adapter (signer)
+ * responsible for authorizing transactions. Used to specify the source or destination in cross-chain
+ * transfer operations.
+ *
+ * @remarks
+ * The `adapter` (signer) and `address` do not always have to belong to the same entity. For example,
+ * in minting or withdrawal scenarios, the signing adapter may authorize a transaction that credits
+ * funds to a different recipient address. This context is essential for cross-chain operations,
+ * ensuring that both the address and the associated adapter are correctly paired with the intended
+ * blockchain, but not necessarily with each other.
+ *
+ * @example
+ * ```typescript
+ * import type { WalletContext } from '@core/provider'
+ * import { adapter, blockchain } from './setup'
+ *
+ * const wallet: WalletContext = {
+ *   adapter,
+ *   address: '0x1234...abcd',
+ *   chain: blockchain,
+ * }
+ * ```
+ */
+interface WalletContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, 
+/**
+ * The chain definition type to use for the wallet context.
+ *
+ * @defaultValue ChainDefinition
+ */
+TChainDefinition extends ChainDefinition = ChainDefinition> {
+    /**
+     * The adapter (signer) for the wallet on the specified chain.
+     *
+     * Responsible for authorizing transactions and signing messages on behalf of the wallet or
+     * for a different recipient, depending on the use case.
+     */
+    adapter: Adapter<TAdapterCapabilities>;
+    /**
+     * The wallet or contract address.
+     *
+     * Must be a valid address format for the specified blockchain. May differ from the adapter's
+     * own address in scenarios such as relayed transactions or third-party minting.
+     */
+    address: string;
+    /**
+     * The blockchain network where the wallet or contract address resides.
+     *
+     * Determines the context and format for the address and adapter.
+     */
+    chain: TChainDefinition;
+}
+/**
+ * Wallet context for bridge destinations with optional custom recipient.
+ *
+ * Extends WalletContext to support scenarios where the recipient address
+ * differs from the signer address (e.g., bridging to a third-party wallet).
+ * The signer address is used for transaction authorization, while the
+ * recipient address specifies where the minted funds should be sent.
+ *
+ * @typeParam TAdapterCapabilities - The adapter capabilities type to use for the wallet context.
+ * @typeParam TChainDefinition - The chain definition type to use for the wallet context.
+ *
+ * @example
+ * ```typescript
+ * import type { DestinationWalletContext } from '@core/provider'
+ * import { adapter, blockchain } from './setup'
+ *
+ * // Bridge to a custom recipient address
+ * const destination: DestinationWalletContext = {
+ *   adapter,
+ *   address: '0x1234...abcd', // Signer address
+ *   chain: blockchain,
+ *   recipientAddress: '0x9876...fedc' // Custom recipient
+ * }
+ * ```
+ */
+interface DestinationWalletContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, 
+/**
+ * The chain definition type to use for the wallet context.
+ *
+ * @defaultValue ChainDefinition
+ */
+TChainDefinition extends ChainDefinition = ChainDefinition> extends WalletContext<TAdapterCapabilities, TChainDefinition> {
+    /**
+     * Optional custom recipient address for minted funds.
+     *
+     * When provided, minted tokens will be sent to this address instead of
+     * the address specified in the wallet context. The wallet context address
+     * is still used for transaction signing and authorization.
+     *
+     * Must be a valid address format for the specified blockchain.
+     */
+    recipientAddress?: string;
+}
+/**
+ * Parameters for executing a cross-chain bridge operation.
+ */
+interface BridgeParams<TFromCapabilities extends AdapterCapabilities = AdapterCapabilities, TToCapabilities extends AdapterCapabilities = AdapterCapabilities, 
+/**
+ * The chain definition type to use for the wallet context.
+ *
+ * @defaultValue ChainDefinition
+ */
+TChainDefinition extends ChainDefinition = ChainDefinition> {
+    /** The source adapter containing wallet and chain information */
+    source: WalletContext<TFromCapabilities, TChainDefinition>;
+    /** The destination adapter containing wallet and chain information */
+    destination: DestinationWalletContext<TToCapabilities, TChainDefinition>;
+    /** The amount to transfer (as a string to avoid precision issues) */
+    amount: string;
+    /** The token to transfer (currently only USDC is supported) */
+    token: 'USDC';
+    /** Bridge configuration (e.g., fast burn settings) */
+    config: BridgeConfig;
+    /**
+     * Optional invocation metadata for tracing and correlation.
+     *
+     * When provided, the `traceId` is used to correlate all events emitted during
+     * the bridge operation. If not provided, an OpenTelemetry-compatible traceId
+     * will be auto-generated.
+     */
+    invocationMeta?: InvocationMeta;
+}
+/**
+ * A step in the bridge process.
+ *
+ * @remarks
+ * This interface represents a single step in the bridge process,
+ * such as approval, burn, or mint.
+ *
+ * @example
+ * ```typescript
+ * const step: BridgeStep = {
+ *   name: 'Approve',
+ *   state: 'success',
+ *   txHash: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+ *   explorerUrl: 'https://etherscan.io/tx/0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+ * }
+ * ```
+ */
+interface BridgeStep {
+    /** Human-readable name of the step (e.g., "Approve", "Burn", "Mint") */
+    name: string;
+    /** The state of the step */
+    state: 'pending' | 'success' | 'error' | 'noop';
+    /** Optional transaction hash for this step (if applicable) */
+    txHash?: string;
+    /** Optional explorer URL for viewing this transaction on a block explorer */
+    explorerUrl?: string;
+    /** Optional data for the step */
+    data?: unknown;
+    /**
+     * Whether this step was executed via Circle's Forwarder (relay service).
+     * Only applicable for mint steps.
+     *
+     * - `true`: The mint was handled by Circle's Orbit relayer
+     * - `false`: The user submitted the mint transaction directly
+     * - `undefined`: Not applicable (non-mint steps)
+     */
+    forwarded?: boolean;
+    /** Optional human-readable error message */
+    errorMessage?: string;
+    /** Optional raw error object (can be Viem/Ethers/Chain error) */
+    error?: unknown;
+}
+/**
+ * Result object returned after a successful cross-chain bridge operation.
+ *
+ * This interface contains all the details about a completed bridge, including
+ * the bridge parameters, source and destination information,
+ * and the sequence of steps that were executed.
+ *
+ * @example
+ * ```typescript
+ * const result: BridgeResult = await provider.bridge(source, dest, '100')
+ * console.log(`Transferred ${result.amount} ${result.token}`)
+ * console.log(`Steps executed: ${result.steps.length}`)
+ * ```
+ */
+interface BridgeResult {
+    /** The amount that was transferred (as a string to avoid precision issues) */
+    amount: string;
+    /** The token that was transferred (currently only USDC is supported) */
+    token: 'USDC';
+    /** The state of the transfer */
+    state: 'pending' | 'success' | 'error';
+    /** The bridge configuration that was used for this operation */
+    config?: BridgeConfig;
+    /** The provider that was used for this operation */
+    provider: string;
+    /** Information about the source chain and address */
+    source: {
+        /** The source wallet/contract address */
+        address: string;
+        /** The source blockchain network */
+        chain: ChainDefinition;
+    };
+    /** Information about the destination chain and address */
+    destination: {
+        /** The destination wallet/contract address */
+        address: string;
+        /** The destination blockchain network */
+        chain: ChainDefinition;
+        /**
+         * Optional custom recipient address for minted funds.
+         *
+         * When provided during the bridge operation, minted tokens are sent to this
+         * address instead of the destination address. This field is preserved in the
+         * result for retry operations to maintain consistency with the original burn.
+         */
+        recipientAddress?: string;
+        /**
+         * Whether Circle's Forwarder was used for this bridge operation.
+         *
+         * When true, the mint transaction was handled by Circle's Orbit relayer
+         * instead of requiring the user to submit it manually.
+         */
+        useForwarder?: boolean;
+    };
+    /** Array of steps that were executed during the bridge process */
+    steps: BridgeStep[];
+}
+/**
+ * Cost estimation result for a cross-chain transfer operation.
+ *
+ * This interface provides detailed information about the expected costs
+ * for a transfer, including gas fees on different chains and protocol fees.
+ * It also includes the input context (token, amount, source, destination) to
+ * provide a complete view of the transfer being estimated.
+ *
+ * @example
+ * ```typescript
+ * const estimate: EstimateResult = await provider.estimate(source, dest, '100')
+ * console.log('Estimating transfer of', estimate.amount, estimate.token)
+ * console.log('From', estimate.source.chain.name, 'to', estimate.destination.chain.name)
+ * console.log('Total gas fees:', estimate.gasFees.length)
+ * console.log('Protocol fees:', estimate.fees.length)
+ * ```
+ */
+interface EstimateResult {
+    /** The token being transferred */
+    token: 'USDC';
     /** The amount being transferred */
     amount: string;
     /** Information about the source chain and address */
@@ -2706,8 +3905,8 @@ interface EstimateResult {
     }[];
     /** Array of protocol and service fees for the transfer */
     fees: {
-        /** The type of fee - either from the bridge kit or the underlying provider */
-        type: 'kit' | 'provider';
+        /** The type of fee - from the bridge kit, provider (CCTP), or forwarder (Circle Orbit relayer) */
+        type: 'kit' | 'provider' | 'forwarder';
         /** The token in which the fee is charged (currently only USDC) */
         token: 'USDC';
         /** The fee amount (as a string to avoid precision issues) */
@@ -2857,19 +4056,38 @@ interface CustomFee {
  * have access to both the source and destination chain information needed for
  * validation and execution.
  *
+ * The destination adapter (`to`) is optional to support forwarder-only destinations
+ * where Circle's Orbit relayer handles the mint transaction without requiring a
+ * destination adapter. When `to` is undefined, the retry operation relies on
+ * IRIS API confirmation instead of on-chain transaction confirmation.
+ *
  * @example
  * ```typescript
+ * // Standard retry with both adapters
  * const retryContext: RetryContext = {
- *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
- *   to: { adapter: destAdapter, chain: 'Base' }
+ *   from: sourceAdapter,
+ *   to: destAdapter
+ * }
+ *
+ * // Forwarder-only retry (no destination adapter)
+ * const forwarderRetryContext: RetryContext = {
+ *   from: sourceAdapter,
+ *   to: undefined // Forwarder handles mint
  * }
  * ```
  */
 interface RetryContext<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
     /** The source adapter context for the retry operation */
     from: Adapter<TFromAdapterCapabilities>;
-    /** The destination adapter context for the retry operation */
-    to: Adapter<TToAdapterCapabilities>;
+    /**
+     * The destination adapter context for the retry operation.
+     *
+     * Optional for forwarder-only destinations where Circle's Orbit relayer
+     * handles the mint transaction. When undefined, the retry operation relies
+     * on IRIS API confirmation (`forwardState === 'CONFIRMED'`) instead of
+     * on-chain transaction confirmation via the adapter.
+     */
+    to?: Adapter<TToAdapterCapabilities>;
 }
 /**
  * Result of analyzing bridge steps to determine retry feasibility and continuation point.
@@ -2966,6 +4184,7 @@ declare abstract class BridgingProvider<TProviderActions = Record<string, unknow
      * @param source - The source chain definition
      * @param destination - The destination chain definition
      * @param token - The token to transfer (currently only USDC is supported)
+     * @param useForwarder - When `true`, also checks that the route supports forwarding
      * @returns `true` if the provider supports this route, `false` otherwise
      *
      * @example
@@ -2977,7 +4196,7 @@ declare abstract class BridgingProvider<TProviderActions = Record<string, unknow
      * }
      * ```
      */
-    abstract supportsRoute(source: ChainDefinition, destination: ChainDefinition, token: 'USDC'): boolean;
+    abstract supportsRoute(source: ChainDefinition, destination: ChainDefinition, token: 'USDC', useForwarder?: boolean): boolean;
     /**
      * Executes a cross-chain bridge operation between the specified source and destination chains.
      *
@@ -3098,6 +4317,8 @@ declare abstract class BridgingProvider<TProviderActions = Record<string, unknow
      *
      * @param result - The failed bridge result to retry
      * @param context - The retry context containing source and destination adapter contexts
+     * @param invocationMeta - Optional invocation metadata for tracing and correlation.
+     *                         When provided, enables custom traceId, runtime overrides, and caller chain tracking.
      * @returns Promise resolving to the retry bridge result
      * @throws {Error} If retry is not supported by this provider
      *
@@ -3113,7 +4334,7 @@ declare abstract class BridgingProvider<TProviderActions = Record<string, unknow
      * }
      * ```
      */
-    retry<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(result: BridgeResult, context: RetryContext<TFromAdapterCapabilities, TToAdapterCapabilities>): Promise<BridgeResult>;
+    retry<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(result: BridgeResult, context: RetryContext<TFromAdapterCapabilities, TToAdapterCapabilities>, invocationMeta?: InvocationMeta): Promise<BridgeResult>;
     /**
      * Analyzes bridge steps to determine retry feasibility and continuation point.
      *
@@ -3286,6 +4507,21 @@ interface AttestationMessage {
      * The delay reason if the attestation is delayed.
      */
     delayReason?: string | null;
+    /**
+     * Forwarding state from Circle's relayer.
+     * Only present when useForwarder was enabled during burn.
+     * @description
+     * - 'PENDING': Relayer is processing the mint
+     * - 'CONFIRMED': Relayer has submitted the mint tx (waiting for finality)
+     * - 'COMPLETE': Relayer has successfully completed the mint tx with finality
+     * - 'FAILED': Relayer failed to process the mint (user may need manual mint)
+     */
+    forwardState?: 'PENDING' | 'CONFIRMED' | 'COMPLETE' | 'FAILED' | null;
+    /**
+     * Transaction hash of the mint tx submitted by Circle's relayer.
+     * Only present when forwardState is 'CONFIRMED' or 'COMPLETE'.
+     */
+    forwardTxHash?: string | null;
 }
 
 /**
@@ -3319,6 +4555,66 @@ type BridgeFetchAttestationStep = BridgeStep &
     data?: undefined;
 });
 
+/**
+ * Forwarder-only destination for CCTP v2 transfers without an adapter.
+ *
+ * Used when Circle's Forwarder handles the mint transaction and no destination
+ * adapter is available. Requires both `useForwarder: true` and a `recipientAddress`.
+ *
+ * When using this destination type:
+ * - The mint step completes when the IRIS API confirms `forwardState === 'CONFIRMED'`
+ * - No on-chain transaction confirmation is performed (no adapter available)
+ * - The mint step's `data` field will be undefined (no transaction receipt)
+ */
+interface CCTPV2ForwarderOnlyDestination<TChainDefinition extends ChainDefinitionWithCCTPv2 = ChainDefinitionWithCCTPv2> {
+    /** The destination chain where USDC will be minted */
+    chain: TChainDefinition;
+    /** The recipient address that will receive the minted USDC */
+    recipientAddress: string;
+    /** Must be true for forwarder-only destinations */
+    useForwarder: true;
+    /** The resolved address (same as recipientAddress for forwarder-only) */
+    address?: string;
+}
+/**
+ * Destination context for CCTP v2 transfers with optional forwarder support.
+ *
+ * Supports two modes:
+ * 1. **With adapter**: Standard destination where user or forwarder submits mint transaction.
+ *    The adapter is used for chain validation and transaction confirmation.
+ * 2. **Forwarder-only**: No adapter provided. Circle's Orbit relayer handles the mint
+ *    and confirmation is based on IRIS API response only.
+ *
+ * @example
+ * ```typescript
+ * // With adapter (standard or forwarder-assisted)
+ * const dest1: CCTPV2DestinationContext = {
+ *   adapter,
+ *   chain: BaseSepolia,
+ *   address: '0x...',
+ *   useForwarder: true // optional
+ * }
+ *
+ * // Forwarder-only (no adapter)
+ * const dest2: CCTPV2DestinationContext = {
+ *   chain: BaseSepolia,
+ *   recipientAddress: '0x...',
+ *   useForwarder: true
+ * }
+ * ```
+ */
+type CCTPV2DestinationContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainDefinition extends ChainDefinitionWithCCTPv2 = ChainDefinitionWithCCTPv2> = (DestinationWalletContext<TAdapterCapabilities, TChainDefinition> & {
+    /**
+     * Enable Circle's Forwarder to handle the mint transaction.
+     *
+     * When true, Circle's Orbit relayer will fetch the attestation and submit
+     * the mint transaction on the user's behalf. The relay fee is deducted from
+     * the minted USDC at mint time.
+     *
+     * @defaultValue false
+     */
+    useForwarder?: boolean;
+}) | CCTPV2ForwarderOnlyDestination<TChainDefinition>;
 /**
  * CCTPv2 bridge parameters.
  *
@@ -3332,31 +4628,56 @@ type CCTPV2BridgeParams<TFromAdapterCapabilities extends AdapterCapabilities = A
      */
     source: WalletContext<TFromAdapterCapabilities, ChainDefinitionWithCCTPv2>;
     /**
-     * The destination wallet context containing the chain definition and wallet address.
+     * The destination wallet context containing the chain definition, wallet address,
+     * and optional forwarder configuration.
      */
-    destination: DestinationWalletContext<TToAdapterCapabilities, ChainDefinitionWithCCTPv2>;
+    destination: CCTPV2DestinationContext<TToAdapterCapabilities>;
     /**
      * The bridge configuration for the CCTPv2 transfer.
      */
     config: BridgeConfig;
 };
+/**
+ * Base payload structure for CCTP v2 action events.
+ *
+ * @remarks
+ * All CCTP v2 actions share these common fields for protocol identification
+ * and tracing support.
+ */
+interface CCTPV2ActionBase {
+    /** The protocol identifier */
+    protocol: 'cctp';
+    /** The protocol version */
+    version: 'v2';
+    /**
+     * Optional trace ID for end-to-end correlation.
+     *
+     * When provided, this ID links all events in a single bridge operation, enabling
+     * integration with distributed tracing systems (OpenTelemetry, Datadog, etc.).
+     *
+     * Format: 32-character hex string or custom string (user-provided via invocation context).
+     */
+    traceId?: string;
+}
 /**
  * Action types supported by the CCTP v2 provider.
  *
  * @remarks
  * This interface defines the structure of actions that can be dispatched during
- * CCTP v2 transfer operations. Each action includes protocol metadata and a
- * `values` field containing the full bridge step with transaction details.
+ * CCTP v2 transfer operations. Each action includes protocol metadata, an optional
+ * `traceId` for correlation, and a `values` field containing the full bridge step
+ * with transaction details.
  *
  * All transaction-based steps (approve, burn, mint) include `txHash` and
  * `explorerUrl` fields for direct links to block explorers.
  *
  * @example
  * ```typescript
- * // Action structure received by event listeners
+ * // Action structure received by event listeners (with traceId)
  * const burnAction: CCTPV2Actions['burn'] = {
  *   protocol: 'cctp',
  *   version: 'v2',
+ *   traceId: '550e8400-e29b-41d4-a716-446655440000', // optional
  *   method: 'burn',
  *   values: {
  *     name: 'burn',
@@ -3373,9 +4694,7 @@ interface CCTPV2Actions {
      * Approval action for CCTP v2 transfers.
      * Used to approve token spending before initiating a burn operation.
      */
-    approve: {
-        protocol: 'cctp';
-        version: 'v2';
+    approve: CCTPV2ActionBase & {
         method: 'approve';
         values: BridgeStep;
     };
@@ -3383,9 +4702,7 @@ interface CCTPV2Actions {
      * Burn action for CCTP v2 transfers.
      * Used to burn tokens on the source chain to initiate a cross-chain transfer.
      */
-    burn: {
-        protocol: 'cctp';
-        version: 'v2';
+    burn: CCTPV2ActionBase & {
         method: 'burn';
         values: BridgeStep;
     };
@@ -3393,9 +4710,7 @@ interface CCTPV2Actions {
      * Attestation action for CCTP v2 transfers.
      * Used to fetch the attestation message for the source wallet.
      */
-    fetchAttestation: {
-        protocol: 'cctp';
-        version: 'v2';
+    fetchAttestation: CCTPV2ActionBase & {
         method: 'fetchAttestation';
         values: BridgeFetchAttestationStep;
     };
@@ -3403,9 +4718,7 @@ interface CCTPV2Actions {
      * Mint action for CCTP v2 transfers.
      * Used to mint tokens on the destination chain after a successful burn.
      */
-    mint: {
-        protocol: 'cctp';
-        version: 'v2';
+    mint: CCTPV2ActionBase & {
         method: 'mint';
         values: BridgeStep;
     };
@@ -3413,9 +4726,7 @@ interface CCTPV2Actions {
      * Re-attestation action for CCTP v2 transfers.
      * Used to request a fresh attestation when the original has expired.
      */
-    reAttest: {
-        protocol: 'cctp';
-        version: 'v2';
+    reAttest: CCTPV2ActionBase & {
         method: 'reAttest';
         values: BridgeFetchAttestationStep;
     };
@@ -3607,7 +4918,7 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      * const retryResult = await provider.retry(failedResult, retryContext)
      * ```
      */
-    retry<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(result: BridgeResult, context: RetryContext<TFromAdapterCapabilities, TToAdapterCapabilities>): Promise<BridgeResult>;
+    retry<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(result: BridgeResult, context: RetryContext<TFromAdapterCapabilities, TToAdapterCapabilities>, invocationMeta?: InvocationMeta): Promise<BridgeResult>;
     /**
      * Estimate the cost and fees for a CCTP v2 cross-chain bridge operation.
      *
@@ -3616,7 +4927,9 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      * chains, as well as any applicable protocol fees.
      *
      * @param params - The bridge parameters containing source, destination, amount, and optional config.
+     *                 Supports optional `invocation` for tracing and correlation.
      * @returns Promise resolving to detailed cost breakdown including:
+     *          - `traceId`: Correlation ID from invocation context (if provided)
      *          - `gasFees`: Array of gas estimates for each step (Approve, Burn, Mint)
      *            - Gas amounts in native token smallest units (wei for ETH, lamports for SOL, etc.)
      *          - `fees`: Array of protocol and kit fees
@@ -3627,16 +4940,29 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      *
      * @example
      * ```typescript
+     * import {
+     *   resolveInvocationContext,
+     *   createRuntime,
+     * } from '\@core/runtime'
+     * import { createTokenRegistry } from '\@core/tokens'
+     *
+     * const defaults = {
+     *   runtime: createRuntime(),
+     *   tokens: createTokenRegistry(),
+     * }
+     *
      * const estimate = await provider.estimate({
      *   source: { adapter: sourceAdapter, chain: 'Ethereum' },
      *   destination: { adapter: destAdapter, chain: 'Base' },
      *   amount: '10.50',
-     *   token: 'USDC'
+     *   token: 'USDC',
+     *   invocationMeta: {
+     *     callers: [{ type: 'app', name: 'MyDApp', version: '1.0.0' }],
+     *   },
      * })
      *
-     * console.log('Total cost:', estimate.totalCost)
-     * console.log('Source gas:', estimate.sourceGas)
-     * console.log('Destination gas:', estimate.destinationGas)
+     * console.log('Total gas fees:', estimate.gasFees.length)
+     * console.log('Protocol fees:', estimate.fees.length)
      * ```
      */
     estimate<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(params: CCTPV2BridgeParams<TFromAdapterCapabilities, TToAdapterCapabilities>): Promise<EstimateResult>;
@@ -3655,7 +4981,8 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      */
     private addGasFeeEstimate;
     /**
-     * Helper method to add provider fee estimates to the result.
+     * Helper method to add provider and forwarder fee estimates to the result.
+     * Only adds fee entries when the fee is greater than 0.
      */
     private addProviderFeeEstimate;
     /**
@@ -3832,10 +5159,14 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      *
      * This method validates that both chains have CCTP v2 contracts deployed and configured.
      * It uses the `isCCTPV2Supported` guard function to check each chain individually.
+     * When `useForwarder` is `true`, additionally checks that the source chain supports
+     * forwarding as source and the destination chain supports forwarding as destination.
      *
      * @param source - The source chain definition to check for CCTP v2 support
      * @param destination - The destination chain definition to check for CCTP v2 support
-     * @returns `true` if both chains support CCTP v2, `false` otherwise
+     * @param token - The token to transfer (currently only USDC is supported)
+     * @param useForwarder - When `true`, also checks that the route supports forwarding
+     * @returns `true` if both chains support CCTP v2 (and forwarding if requested), `false` otherwise
      *
      * @example
      * ```typescript
@@ -3844,19 +5175,30 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      *
      * if (canTransfer) {
      *   console.log('CCTP v2 transfer is supported between these chains')
-     * } else {
-     *   console.log('One or both chains do not support CCTP v2')
+     * }
+     *
+     * const canForward = provider.supportsRoute(Ethereum, Base, 'USDC', true)
+     *
+     * if (canForward) {
+     *   console.log('CCTP v2 transfer with forwarding is supported')
      * }
      * ```
      */
-    supportsRoute(source: ChainDefinition, destination: ChainDefinition, token: 'USDC'): boolean;
+    supportsRoute(source: ChainDefinition, destination: ChainDefinition, token: 'USDC', useForwarder?: boolean): boolean;
     /**
      * Determines the appropriate maximum fee for a cross-chain bridge operation.
      *
-     * For FAST bridge operations, it calculates a dynamic fee based on the bridge amount
-     * and fast bridge burn fee, or uses a provided maxFee if specified.
+     * The fee calculation depends on transfer speed and forwarding settings:
      *
-     * For SLOW bridge operations, it returns 0 as there are no additional fees.
+     * | Transfer Speed | useForwarder | maxFee provided | Behavior |
+     * |----------------|--------------|-----------------|----------|
+     * | SLOW           | false        | N/A             | maxFee = 0 |
+     * | SLOW           | true         | No              | maxFee = forwardingFee |
+     * | SLOW           | true         | Yes             | maxFee = config.maxFee |
+     * | FAST           | false        | No              | maxFee = calculatedBurnFee |
+     * | FAST           | false        | Yes             | maxFee = config.maxFee |
+     * | FAST           | true         | No              | maxFee = calculatedBurnFee + forwardingFee |
+     * | FAST           | true         | Yes             | maxFee = config.maxFee |
      *
      * @param params - The bridge parameters object containing:
      *   - `source`: The source wallet context with chain definition and adapter
@@ -3882,7 +5224,10 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      * console.log('Max fee:', maxFee)
      * ```
      */
-    getMaxFee<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(params: BridgeParams<TFromAdapterCapabilities, TToAdapterCapabilities>): Promise<bigint>;
+    getMaxFee<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(params: BridgeParams<TFromAdapterCapabilities, TToAdapterCapabilities>): Promise<{
+        providerFee: bigint;
+        forwarderFee: bigint;
+    }>;
     /**
      * Prepares a CCTP v2 burn operation to initiate a cross-chain bridge operation.
      *
@@ -3971,6 +5316,29 @@ rawAddress: string,
 /** The USDC mint address (ignored for EVM chains, required base58 address for Solana) */
 mintAddress: string) => Promise<string>;
 
+/**
+ * Validates and converts a fee value to bigint.
+ *
+ * This utility performs:
+ * 1. Conversion from string or number to bigint
+ * 2. Validation that the value is non-negative
+ *
+ * @param value - The fee value to validate and convert (string or number)
+ * @param fieldName - The name of the field for error messages
+ * @returns The validated fee as a bigint
+ * @throws {KitError} If the value cannot be converted to bigint or is negative
+ *
+ * @example
+ * ```typescript
+ * const fee = validateAndConvertFee('1000000', 'minimumFee')
+ * console.log(fee) // 1000000n
+ *
+ * const fee2 = validateAndConvertFee(500, 'forwardingFee')
+ * console.log(fee2) // 500n
+ * ```
+ */
+declare function validateAndConvertFee(value: number | string, fieldName: string): bigint;
+
 /** A block number value that can be provided as bigint, number, or string. */
 type BlockNumberInput = bigint | number | string | undefined;
 /**
@@ -4068,5 +5436,5 @@ declare const getBlocksUntilExpiry: (attestation: AttestationMessage, currentBlo
  */
 declare const isMintFailureRelatedToAttestation: (error: unknown) => boolean;
 
-export { CCTPV2BridgingProvider, getBlocksUntilExpiry, getMintRecipientAccount, isAttestationExpired, isMintFailureRelatedToAttestation };
+export { CCTPV2BridgingProvider, getBlocksUntilExpiry, getMintRecipientAccount, isAttestationExpired, isMintFailureRelatedToAttestation, validateAndConvertFee };
 export type { CCTPV2Config };