@circle-fin/provider-cctp-v2 1.3.1 → 1.4.1

package/index.d.ts

@@ -33,7 +33,6 @@ import { TransactionInstruction, Signer, AddressLookupTableAccount } from '@sola
  */
 /**
  * Represents basic information about a currency or token.
- * @interface Currency
  * @category Types
  * @description Provides the essential properties of a cryptocurrency or token.
  * @example
@@ -65,7 +64,6 @@ interface Currency {
 }
 /**
  * Base information that all chain definitions must include.
- * @interface BaseChainDefinition
  * @category Types
  * @description Provides the common properties shared by all blockchain definitions.
  * @example
@@ -125,6 +123,11 @@ interface BaseChainDefinition {
      * @description Its presence indicates that USDC is supported.
      */
     usdcAddress: string | null;
+    /**
+     * The contract address for USDT.
+     * @description Its presence indicates that USDT is supported.
+     */
+    usdtAddress: string | null;
     /**
      * Optional CCTP configuration.
      * @description If provided, the chain supports CCTP.
@@ -166,7 +169,6 @@ interface BaseChainDefinition {
 }
 /**
  * Represents chain definitions for Ethereum Virtual Machine (EVM) compatible blockchains.
- * @interface EVMChainDefinition
  * @extends BaseChainDefinition
  * @category Types
  * @description Adds properties specific to EVM chains.
@@ -198,7 +200,6 @@ interface EVMChainDefinition extends BaseChainDefinition {
 }
 /**
  * Represents chain definitions for non-EVM blockchains.
- * @interface NonEVMChainDefinition
  * @extends BaseChainDefinition
  * @category Types
  * @description Contains properties for blockchains that do not use the EVM.
@@ -251,6 +252,7 @@ type ChainType = EVMChainDefinition['type'] | NonEVMChainDefinition['type'];
  *   rpcEndpoints: ['https://eth.example.com'],
  *   eurcAddress: null,
  *   usdcAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+ *   usdtAddress: '0xdac17f958d2ee523a2206206994597c13d831ec7',
  *   cctp: {
  *     domain: 0,
  *     contracts: {
@@ -313,18 +315,75 @@ 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}`;
+/**
+ * Split CCTP contract configuration.
+ *
+ * Used by chains that deploy separate TokenMessenger and MessageTransmitter contracts.
+ * This is the traditional CCTP architecture used by most EVM chains.
+ *
+ * @example
+ * ```typescript
+ * const splitConfig: CCTPSplitConfig = {
+ *   type: 'split',
+ *   tokenMessenger: '0x1234567890abcdef1234567890abcdef12345678',
+ *   messageTransmitter: '0xabcdef1234567890abcdef1234567890abcdef12',
+ *   confirmations: 12
+ * }
+ * ```
+ */
 interface CCTPSplitConfig {
     type: 'split';
     tokenMessenger: string;
     messageTransmitter: string;
     confirmations: number;
 }
+/**
+ * Merged CCTP contract configuration.
+ *
+ * Used by chains that deploy a single unified CCTP contract.
+ * This simplified architecture is used by newer chain integrations.
+ *
+ * @example
+ * ```typescript
+ * const mergedConfig: CCTPMergedConfig = {
+ *   type: 'merged',
+ *   contract: '0x9876543210fedcba9876543210fedcba98765432',
+ *   confirmations: 1
+ * }
+ * ```
+ */
 interface CCTPMergedConfig {
     type: 'merged';
     contract: string;
     confirmations: number;
 }
+/**
+ * Version configuration for CCTP contracts.
+ *
+ * Defines whether the chain uses split or merged CCTP contract architecture.
+ * Split configuration uses separate TokenMessenger and MessageTransmitter contracts,
+ * while merged configuration uses a single unified contract.
+ *
+ * @example Split configuration (most EVM chains)
+ * ```typescript
+ * const splitConfig: VersionConfig = {
+ *   type: 'split',
+ *   tokenMessenger: '0x1234567890abcdef1234567890abcdef12345678',
+ *   messageTransmitter: '0xabcdef1234567890abcdef1234567890abcdef12',
+ *   confirmations: 12
+ * }
+ * ```
+ *
+ * @example Merged configuration (newer chains)
+ * ```typescript
+ * const mergedConfig: VersionConfig = {
+ *   type: 'merged',
+ *   contract: '0x9876543210fedcba9876543210fedcba98765432',
+ *   confirmations: 1
+ * }
+ * ```
+ */
 type VersionConfig = CCTPSplitConfig | CCTPMergedConfig;
 type CCTPContracts = Partial<{
     v1: VersionConfig;
@@ -334,7 +393,6 @@ type CCTPContracts = Partial<{
 }>;
 /**
  * Configuration for the Cross-Chain Transfer Protocol (CCTP).
- * @interface CCTPConfig
  * @category Types
  * @description Contains the domain and required contract addresses for CCTP support.
  * @example
@@ -357,6 +415,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.
@@ -372,7 +446,7 @@ interface CCTPConfig {
  * const invalidType: KitContractType = 'invalid' // TypeScript error
  * ```
  */
-type KitContractType = 'bridge';
+type KitContractType = 'bridge' | 'adapter';
 /**
  * Kit-specific contract addresses for enhanced chain functionality.
  *
@@ -643,8 +717,20 @@ type EvmPreparedChainRequestParams = {
 interface SolanaPreparedChainRequestParams {
     /**
      * The array of instructions to include in the transaction.
+     *
+     * @remarks
+     * Used for instruction-based transaction building. Mutually exclusive with
+     * `serializedTransaction`.
+     */
+    instructions?: TransactionInstruction[];
+    /**
+     * A pre-serialized transaction as a Uint8Array (e.g., from a service like Jupiter).
+     *
+     * @remarks
+     * Used for executing pre-built transactions from external services.
+     * The transaction may be partially signed. Mutually exclusive with `instructions`.
      */
-    instructions: TransactionInstruction[];
+    serializedTransaction?: Uint8Array;
     /**
      * Additional signers besides the Adapter's wallet (e.g. program-derived authorities).
      */
@@ -913,7 +999,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 +1408,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;
+    };
 }
 
 /**
@@ -1348,31 +1527,443 @@ interface CCTPActionMap {
 }
 
 /**
- * Action map for native token operations (ETH, SOL, MATIC, etc.).
+ * Permit signature standards for gasless token approvals.
  *
- * Native tokens are the primary currency of each blockchain network,
- * used for paying transaction fees and as a store of value.
- * These actions operate on the native token without requiring
- * a separate token contract address.
+ * Defines the permit types that can be used to approve token spending
+ * without requiring a separate approval transaction.
  *
  * @remarks
- * Native token operations differ from ERC-20/SPL token operations
- * in that they don't require contract interactions for basic transfers
- * and balance checks.
+ * - NONE: No permit, tokens must be pre-approved via separate transaction
+ * - EIP2612: Standard ERC-20 permit (USDC, DAI v2, and most modern tokens)
+ */
+declare enum PermitType {
+    /** No permit required - tokens must be pre-approved */
+    NONE = 0,
+    /** EIP-2612 standard permit */
+    EIP2612 = 1
+}
+/**
+ * Token input with permit signature for gasless approval.
  *
- * @see {@link ActionMap} for the complete action structure
+ * The Adapter Contract uses this to pull tokens from the user's wallet
+ * using permit signatures instead of requiring separate approval transactions.
+ *
+ * @example
+ * ```typescript
+ * const tokenInput: TokenInput = {
+ *   permitType: PermitType.EIP2612,
+ *   token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
+ *   from: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
+ *   amount: 1000000n, // 1 USDC
+ *   permitCalldata: '0x...' // Encoded permit(value, deadline, v, r, s)
+ * }
+ * ```
  */
-interface NativeActionMap {
+interface TokenInput {
     /**
-     * Get the native token balance (SOL, ETH, etc.) for a wallet address.
+     * Type of permit to execute.
      */
-    balanceOf: ActionParameters & {
-        /**
-         * The address to check the native balance for. If not provided, it will be
-         * automatically derived from the adapter context.
-         */
-        walletAddress?: string | undefined;
-    };
+    permitType: PermitType;
+    /**
+     * Token contract address to pull from user.
+     */
+    token: `0x${string}`;
+    /**
+     * Amount of tokens to pull via permit.
+     */
+    amount: bigint;
+    /**
+     * ABI-encoded permit calldata.
+     *
+     * For EIP-2612: encode(value, deadline, v, r, s)
+     * For Permit2: encode(permit, signature)
+     *
+     * @example '0x0000000000000000000000000000000000000000000000000000000000989680...'
+     */
+    permitCalldata: `0x${string}`;
+}
+/**
+ * Single instruction to execute within the Adapter Contract.
+ *
+ * Each instruction represents a contract call (swap, fee collection, etc.)
+ * with pre-execution approval and post-execution validation.
+ *
+ * @example
+ * ```typescript
+ * const swapInstruction: Instruction = {
+ *   target: '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE', // LiFi Diamond
+ *   data: '0x...',  // LiFi swap calldata
+ *   value: 0n,
+ *   tokenIn: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
+ *   amountToApprove: 1000000000n, // 1000 USDC to approve
+ *   tokenOut: '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDT
+ *   minTokenOut: 995000000n // 995 USDT minimum (0.5% slippage)
+ * }
+ * ```
+ */
+interface Instruction {
+    /**
+     * Target contract address to call.
+     *
+     * Can be a DEX router, fee taker contract, or token contract.
+     */
+    target: `0x${string}`;
+    /**
+     * ABI-encoded calldata for the target contract.
+     */
+    data: `0x${string}`;
+    /**
+     * ETH value to send with the call (for native token operations).
+     *
+     * @defaultValue 0n
+     */
+    value: bigint;
+    /**
+     * Token to approve to target before executing instruction.
+     *
+     * Set to zero address (0x00...00) to disable pre-approval.
+     */
+    tokenIn: `0x${string}`;
+    /**
+     * Amount of tokenIn to approve to target before executing instruction.
+     *
+     * @remarks
+     * Field name matches the adapter contract's `amountToApprove` parameter exactly.
+     *
+     * @defaultValue 0n if tokenIn is zero address
+     */
+    amountToApprove: bigint;
+    /**
+     * Token to validate minimum balance after instruction.
+     *
+     * Set to zero address (0x00...00) to disable post-validation.
+     */
+    tokenOut: `0x${string}`;
+    /**
+     * Minimum required balance of tokenOut after instruction.
+     *
+     * @defaultValue 0n if tokenOut is zero address
+     */
+    minTokenOut: bigint;
+}
+/**
+ * Token recipient for residual sweep.
+ *
+ * After all instructions complete, the Adapter Contract sweeps
+ * any remaining balances to the specified beneficiaries.
+ */
+interface TokenRecipient {
+    /**
+     * Token contract address to sweep.
+     */
+    token: `0x${string}`;
+    /**
+     * Address to receive swept tokens.
+     */
+    beneficiary: `0x${string}`;
+}
+/**
+ * Execution parameters for the Adapter Contract.
+ *
+ * This struct is signed via EIP-712 by the Circle proxy and verified
+ * on-chain to ensure the execution is authorized.
+ *
+ * @remarks
+ * The executeParams are provided by the stablecoin-service and must be
+ * passed to the Adapter Contract exactly as received (no modification).
+ *
+ * @example
+ * ```typescript
+ * const executeParams: ExecuteParams = {
+ *   instructions: [
+ *     { target: dexRouter, data: swapCalldata, ... }
+ *   ],
+ *   tokens: [
+ *     { token: USDC, beneficiary: userAddress },
+ *     { token: USDT, beneficiary: userAddress }
+ *   ],
+ *   execId: 123456789n,
+ *   deadline: BigInt(Math.floor(Date.now() / 1000) + 1800),
+ *   metadata: '0x'
+ * }
+ * ```
+ */
+interface ExecuteParams {
+    /**
+     * Array of instructions to execute sequentially.
+     *
+     * Each instruction can be a swap, fee collection, or other contract call.
+     */
+    instructions: Instruction[];
+    /**
+     * Token recipients for residual sweep.
+     *
+     * Typically a 2-tuple: [tokenIn recipient, tokenOut recipient]
+     */
+    tokens: TokenRecipient[];
+    /**
+     * Unique execution identifier for replay protection.
+     *
+     * Must be globally unique and is marked as used after execution.
+     */
+    execId: bigint;
+    /**
+     * Execution deadline timestamp (Unix seconds).
+     *
+     * Transaction reverts if block.timestamp is greater than deadline.
+     */
+    deadline: bigint;
+    /**
+     * Optional metadata for tracking and analytics.
+     */
+    metadata: `0x${string}`;
+}
+/**
+ * Parameters for executing a swap transaction via the Adapter smart contract.
+ *
+ * This action executes swap transactions through the Adapter Contract, which
+ * handles token approvals via permits (EIP-2612, Permit2, etc.) and executes
+ * multi-step swap instructions atomically on-chain.
+ *
+ * @remarks
+ * The swap flow uses the Adapter Contract pattern:
+ * 1. Service provides `executeParams` and `signature` (proxy-signed EIP-712)
+ * 2. SDK builds `tokenInputs` with permit signatures for gasless approvals
+ * 3. SDK calls AdapterContract.execute(executeParams, tokenInputs, signature)
+ * 4. Adapter Contract pulls tokens via permits, executes swaps, validates outputs
+ *
+ * This enables:
+ * - Single atomic transaction (permit + swap in one tx)
+ * - Gasless approvals via EIP-2612/Permit2
+ * - Slippage protection enforced on-chain
+ * - Multi-step instructions (swap + fees) atomically
+ *
+ * **Permit Support**: The SDK constructs `TokenInput` with `permitCalldata`
+ * containing the encoded permit signature. The Adapter Contract executes
+ * the permit on-chain before pulling tokens.
+ *
+ * @example
+ * ```typescript
+ * import type { ExecuteSwapParams } from '@core/adapter'
+ * import { createSwap } from '@core/service-client'
+ * import { PermitType } from '@core/adapter'
+ *
+ * // Get swap transaction from service
+ * const swapResponse = await createSwap({
+ *   tokenInAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *   tokenOutAddress: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
+ *   tokenInChain: 'Ethereum',
+ *   fromAddress: '0x...',
+ *   toAddress: '0x...',
+ *   amount: '1000000',
+ *   apiKey: 'KIT_KEY:...',
+ * })
+ *
+ * // Build token inputs with permit
+ * const tokenInputs: TokenInput[] = [{
+ *   permitType: PermitType.EIP2612,
+ *   token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *   from: userAddress,
+ *   amount: 1000000n,
+ *   permitCalldata: '0x...' // Encoded permit signature
+ * }]
+ *
+ * // Prepare action parameters
+ * const params: ExecuteSwapParams = {
+ *   executeParams: swapResponse.transaction.executeParams,
+ *   tokenInputs,
+ *   signature: swapResponse.transaction.signature,
+ *   inputAmount: BigInt(swapResponse.amount),
+ *   tokenInAddress: swapResponse.tokenInAddress as `0x${string}`
+ * }
+ * ```
+ */
+interface ExecuteSwapEVMParams extends ActionParameters {
+    /**
+     * Execution parameters from the stablecoin-service.
+     *
+     * Contains instructions, token recipients, execution ID, deadline, and metadata.
+     * This is an EIP-712 signed struct that the Adapter Contract validates.
+     *
+     * Provided by the service - do not modify.
+     */
+    executeParams: ExecuteParams;
+    /**
+     * Token inputs with permit signatures for gasless approvals.
+     *
+     * The SDK constructs this array with permit data for each token that needs
+     * to be pulled from the user's wallet. The Adapter Contract executes these
+     * permits on-chain before executing swap instructions.
+     *
+     * @remarks
+     * For EIP-2612 permits, the SDK must:
+     * 1. Build typed data with token, spender (Adapter), amount, nonce, deadline
+     * 2. Get user signature via `adapter.signTypedData()`
+     * 3. Encode as permitCalldata: encode(value, deadline, v, r, s)
+     *
+     * @example
+     * ```typescript
+     * [{
+     *   permitType: PermitType.EIP2612,
+     *   token: '0xUSDC',
+     *   from: userAddress,
+     *   amount: 1000000n,
+     *   permitCalldata: '0x...'
+     * }]
+     * ```
+     */
+    tokenInputs: TokenInput[];
+    /**
+     * EIP-712 signature from the Circle proxy service.
+     *
+     * The service signs the executeParams to authorize the execution.
+     * The Adapter Contract verifies this signature on-chain.
+     *
+     * Provided by the service - do not modify.
+     */
+    signature: `0x${string}`;
+    /**
+     * Swap input amount in base units.
+     *
+     * @remarks
+     * The amount of tokens being swapped, provided in the token's base units (e.g., wei for ETH,
+     * smallest denomination for ERC20 tokens). This value should be extracted from the service
+     * response, as it represents the authoritative swap amount for the operation.
+     *
+     * For native currency swaps (ETH → USDC), this amount is sent as the transaction `value`.
+     * For ERC20 swaps (USDC → USDT), this amount determines the permit or approval quantity.
+     *
+     * @see CreateSwapResponse.amount - Service response field containing this value
+     *
+     * @example
+     * ```typescript
+     * import { createSwap } from '@core/service-client'
+     *
+     * // Get swap transaction from service
+     * const response = await createSwap({
+     *   tokenInAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+     *   amount: '1000000', // 1 USDC (6 decimals)
+     *   ...
+     * })
+     *
+     * // Prepare swap execution using service response amount
+     * await adapter.prepareAction('swap.execute', {
+     *   executeParams: response.transaction.executeParams,
+     *   tokenInputs,
+     *   signature: response.transaction.signature,
+     *   inputAmount: BigInt(response.amount),
+     *   tokenInAddress: response.tokenInAddress,
+     * }, context)
+     * ```
+     */
+    inputAmount: bigint;
+    /**
+     * Token address being swapped from.
+     *
+     * @remarks
+     * Used to determine if the swap involves native currency (ETH, MATIC, etc.) or ERC20 tokens.
+     * When tokenInAddress is NATIVE_TOKEN_ADDRESS (0xEeee...), the inputAmount is sent as tx.value.
+     *
+     * @see CreateSwapResponse.tokenInAddress - Service response field containing this value
+     *
+     * @example '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE' for ETH
+     * @example '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' for USDC
+     */
+    tokenInAddress: `0x${string}`;
+}
+/**
+ * Parameters for executing a swap transaction on Solana.
+ *
+ * This action executes swap transactions on Solana chains by deserializing
+ * and executing a pre-built transaction provided by the stablecoin-service.
+ *
+ * @remarks
+ * Unlike EVM chains that use the Adapter Contract pattern, Solana swaps
+ * execute a fully serialized transaction provided by the service. The
+ * transaction is base64-encoded and contains all necessary instructions
+ * for the swap operation.
+ *
+ * The service handles:
+ * - DEX aggregator routing (Jupiter, etc.)
+ * - Fee collection
+ * - Slippage protection
+ * - Token account management
+ *
+ * @example
+ * ```typescript
+ * import type { ExecuteSwapSolanaParams } from '@core/adapter'
+ * import { createSwap } from '@core/service-client'
+ *
+ * // Get swap transaction from service
+ * const swapResponse = await createSwap({
+ *   tokenInAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   tokenOutAddress: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
+ *   tokenInChain: 'Solana',
+ *   fromAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
+ *   toAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
+ *   amount: '1000000',
+ *   apiKey: 'KIT_KEY:...',
+ * })
+ *
+ * // Prepare action parameters
+ * const params: ExecuteSwapSolanaParams = {
+ *   serializedTransaction: swapResponse.transaction.data
+ * }
+ * ```
+ */
+interface ExecuteSwapSolanaParams extends ActionParameters {
+    /**
+     * Base64-encoded serialized Solana transaction.
+     *
+     * This transaction is fully constructed by the stablecoin-service and
+     * contains all swap instructions, fee payments, and token account setup.
+     * The transaction must be deserialized, signed, and submitted to the network.
+     *
+     * Provided by the service - do not modify.
+     *
+     * @example 'AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQAJFQg...'
+     */
+    serializedTransaction: string;
+}
+/**
+ * Parameters accepted by the swap.execute action, supporting both EVM and Solana chains.
+ *
+ * @remarks
+ * This union type covers all chain-specific swap execution parameter interfaces
+ * currently supported by the App Kit. Extend this union to support
+ * additional blockchains as needed. Each member provides all fields required
+ * to prepare and execute a pre-built swap transaction on its respective chain.
+ *
+ * **Type Narrowing**: The correct parameter type is inferred from the chain type
+ * in the `OperationContext` passed to `adapter.prepareAction()`. Action handlers
+ * use property-based type guards (checking for `executeParams`/`tokenInputs` for EVM
+ * or `serializedTransaction` for Solana) to narrow the union type at runtime.
+ *
+ * - {@link ExecuteSwapEVMParams} - For EVM chains (has `executeParams` and `tokenInputs`)
+ * - {@link ExecuteSwapSolanaParams} - For Solana chains (has `serializedTransaction`)
+ */
+type ExecuteSwapParams = ExecuteSwapEVMParams | ExecuteSwapSolanaParams;
+/**
+ * Action map for swap operations on EVM chains.
+ *
+ * This namespace contains actions related to token swapping operations.
+ * These actions handle the execution of pre-built swap transactions from
+ * DEX aggregators and routing services.
+ *
+ * @remarks
+ * The swap namespace is designed to be extensible for future swap-related
+ * operations such as multi-hop swaps, batched swaps, or swap-and-bridge
+ * compositions.
+ */
+interface SwapActionMap {
+    /**
+     * Execute a pre-built swap transaction.
+     *
+     * This action prepares and executes swap transactions constructed by the
+     * stablecoin-service API. It accepts transaction parameters (to, data, value)
+     * and returns a prepared chain request suitable for gas estimation or execution.
+     */
+    readonly execute: ExecuteSwapParams;
 }
 
 interface TokenActionMap {
@@ -1588,14 +2179,89 @@ interface USDCActionMap {
 }
 
 /**
- * Central registry of all available action namespaces and their operations.
+ * USDT-specific operations that automatically resolve the token address.
  *
- * 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.
+ * These include standard ERC20 operations. The interface provides the same core
+ * operations as {@link TokenActionMap} but without requiring a `tokenAddress`
+ * parameter.
  *
- * @remarks
+ * @example
+ * ```typescript
+ * // USDT operations (address auto-resolved)
+ * await adapter.action('usdt.transfer', {
+ *   to: '0x1234...',
+ *   amount: '1000000' // 1 USDT
+ * })
+ *
+ * // vs. general token operations (address required)
+ * await adapter.action('token.transfer', {
+ *   tokenAddress: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
+ *   to: '0x1234...',
+ *   amount: '1000000'
+ * })
+ * ```
+ */
+type BaseUSDTActions = {
+    [K in keyof TokenActionMap]: Omit<TokenActionMap[K], 'tokenAddress'>;
+};
+/**
+ * USDT action map with standard ERC20 operations.
+ *
+ * This provides standard token operations for USDT transfers.
+ */
+interface USDTActionMap {
+    /**
+     * Transfer USDT tokens directly from the wallet to another address.
+     *
+     * Automatically uses the USDT contract address for the current chain.
+     */
+    transfer: BaseUSDTActions['transfer'];
+}
+
+/**
+ * Native token-related action maps for the bridge kit.
+ *
+ * This module provides action definitions for native token operations.
+ */
+interface NativeActionMap {
+    /**
+     * Transfer native tokens directly from the wallet to another address.
+     */
+    transfer: ActionParameters & {
+        /**
+         * The chain to transfer the native tokens on.
+         */
+        chain?: ChainIdentifier$1;
+        /**
+         * The address to send the native tokens to.
+         */
+        to: string;
+        /**
+         * The amount of native tokens to transfer.
+         */
+        amount: bigint;
+    };
+    /**
+     * Get the native token balance (SOL, ETH, etc.) for a wallet address.
+     */
+    balanceOf: ActionParameters & {
+        /**
+         * The address to check the native balance for. If not provided, it will be
+         * automatically derived from the adapter context.
+         */
+        walletAddress?: string | undefined;
+    };
+}
+
+/**
+ * Central registry of all available action namespaces and their operations.
+ *
+ * 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.
+ *
+ * @remarks
  * This interface serves as the foundation for type-safe action dispatching
  * and provides compile-time validation of action keys and payload types.
  * All action-related utility types derive from this central definition.
@@ -1606,12 +2272,16 @@ interface USDCActionMap {
 interface ActionMap {
     /** CCTP-specific operations with automatic address resolution. */
     readonly cctp: CCTPActionMap;
-    /** Native token operations (ETH, SOL, MATIC, etc.). */
-    readonly native: NativeActionMap;
     /** General token operations requiring explicit token addresses. */
     readonly token: TokenActionMap;
     /** USDC-specific operations with automatic address resolution. */
     readonly usdc: USDCActionMap;
+    /** USDT-specific operations with automatic address resolution. */
+    readonly usdt: USDTActionMap;
+    /** Native token operations. */
+    readonly native: NativeActionMap;
+    /** Swap operations for DEX aggregator integrations. */
+    readonly swap: SwapActionMap;
 }
 /**
  * Determine if a type represents an action parameter object (leaf node).
@@ -1750,7 +2420,7 @@ type ActionHandler<TActionKey extends ActionKeys> = (params: ActionPayload<TActi
  * This type defines a registry object where each key is a valid action key
  * (as defined by {@link ActionKeys}) and each value is an {@link ActionHandler}
  * capable of processing the payload for that action. This enables strongly-typed
- * handler registration and lookup for all supported actions in the Stablecoin Kits.
+ * handler registration and lookup for all supported actions in the App Kits.
  *
  * @remarks
  * Each handler is typed as {@link ActionHandler}, which means the handler
@@ -2012,11 +2682,11 @@ interface AdapterCapabilities {
 /**
  * Abstract class defining the standard interface for an adapter that interacts with a specific blockchain.
  *
- * A `Adapter` is responsible for encapsulating chain-specific logic necessary to
+ * An `Adapter` is responsible for encapsulating chain-specific logic necessary to
  * perform operations like sending transactions, querying balances, or interacting with smart contracts.
  * Implementations of this class will provide concrete logic for a particular blockchain protocol.
  *
- * This abstraction allows the Stablecoin Kits to work with multiple blockchains in a uniform way.
+ * This abstraction allows the App Kit 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.
@@ -2277,6 +2947,35 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * @returns A promise that resolves to the total transaction fee as a bigint.
      */
     abstract calculateTransactionFee(baseComputeUnits: bigint, bufferBasisPoints: bigint | undefined, chain: ChainDefinition): Promise<EstimatedGas>;
+    /**
+     * Get the decimal places for a token address on a given chain.
+     *
+     * This method fetches the number of decimal places from a token contract.
+     * Different chain types implement this differently:
+     * - EVM: Calls the `decimals()` function on ERC-20 contracts
+     * - Solana: Reads the `decimals` field from the SPL token mint account
+     *
+     * @param tokenAddress - The token contract address (EVM) or mint address (Solana)
+     * @param chain - The chain definition where the token is deployed
+     * @returns Promise resolving to the number of decimal places for the token
+     * @throws Error when the token contract doesn't exist or decimals cannot be fetched
+     *
+     * @example
+     * ```typescript
+     * import { EthersAdapter } from '@circle-fin/adapter-ethers-v6'
+     * import { Ethereum } from '@core/chains'
+     *
+     * const adapter = new EthersAdapter({ signer })
+     *
+     * // Fetch decimals for DAI token
+     * const decimals = await adapter.getTokenDecimals(
+     *   '0x6B175474E89094C44Da98b954EedeAC495271d0F',
+     *   Ethereum
+     * )
+     * console.log(decimals) // 18
+     * ```
+     */
+    abstract getTokenDecimals(tokenAddress: string, chain: ChainDefinition): Promise<number>;
 }
 
 /**
@@ -2333,111 +3032,1210 @@ interface ApiPollingConfig {
  *   console.log('Event received:', payload);
  * });
  *
- * // Dispatch an event
- * transferEvents.dispatch('completed', {
- *   txHash: '0x123',
- *   destinationTxHash: '0xabc'
- * });
+ * // Dispatch an event
+ * transferEvents.dispatch('completed', {
+ *   txHash: '0x123',
+ *   destinationTxHash: '0xabc'
+ * });
+ * ```
+ */
+declare class Actionable<AllActions> {
+    private readonly handlers;
+    private readonly wildcard;
+    /**
+     * Register a handler for a specific action.
+     *
+     * @param action - The specific action key to listen for.
+     * @param handler - The callback function to execute when the action occurs.
+     *
+     * @example
+     * ```typescript
+     * const events = new Actionable<{ dataReceived: string }>();
+     *
+     * events.on('dataReceived', (data) => {
+     *   console.log(`Received: ${data}`);
+     * });
+     * ```
+     */
+    on<Action extends keyof AllActions>(action: Action, handler: (payload: AllActions[Action]) => void): void;
+    /**
+     * Register a handler for all actions using the wildcard '*'.
+     *
+     * @param action - The wildcard '*' signifying interest in all actions.
+     * @param handler - The callback function to execute for any action.
+     *
+     * @example
+     * ```typescript
+     * const events = new Actionable<{ started: boolean; completed: string }>();
+     *
+     * events.on('*', (payload) => {
+     *   console.log('Action occurred:', payload);
+     * });
+     * ```
+     */
+    on(action: '*', handler: (payload: AllActions[keyof AllActions]) => void): void;
+    /**
+     * Remove a previously registered handler for a specific action.
+     *
+     * @param action - The specific action key to unregister from.
+     * @param handler - The callback function to remove.
+     *
+     * @example
+     * ```typescript
+     * const events = new Actionable<{ dataReceived: string }>();
+     *
+     * const handler = (data: string) => console.log(data);
+     * events.on('dataReceived', handler);
+     *
+     * // Later, to remove the handler:
+     * events.off('dataReceived', handler);
+     * ```
+     */
+    off<Action extends keyof AllActions>(action: Action, handler: (payload: AllActions[Action]) => void): void;
+    /**
+     * Remove a previously registered wildcard handler.
+     *
+     * @param action - The wildcard '*' signifying removal from all actions.
+     * @param handler - The callback function to remove.
+     *
+     * @example
+     * ```typescript
+     * const events = new Actionable<{ started: boolean; completed: string }>();
+     *
+     * const globalHandler = (payload: any) => console.log(payload);
+     * events.on('*', globalHandler);
+     *
+     * // Later, to remove the handler:
+     * events.off('*', globalHandler);
+     * ```
+     */
+    off(action: '*', handler: (payload: AllActions[keyof AllActions]) => void): void;
+    /**
+     * Dispatch an action with its payload to all registered handlers.
+     *
+     * This method notifies both:
+     * - Handlers registered specifically for this action
+     * - Wildcard handlers registered for all actions
+     *
+     * @param action - The action key identifying the event type.
+     * @param payload - The data associated with the action.
+     *
+     * @example
+     * ```typescript
+     * type Actions = {
+     *   transferStarted: { amount: string; destination: string };
+     *   transferComplete: { txHash: string };
+     * };
+     *
+     * const events = new Actionable<Actions>();
+     *
+     * // Dispatch an event
+     * events.dispatch('transferStarted', {
+     *   amount: '100',
+     *   destination: '0xABC123'
+     * });
+     * ```
+     */
+    dispatch<K extends keyof AllActions>(action: K, payload: AllActions[K]): void;
+}
+
+/**
+ * Module augmentation to register known token symbols.
+ *
+ * @remarks
+ * This file augments the `TokenSymbolRegistry` interface to provide
+ * type-safe autocomplete for built-in tokens.
+ *
+ * When imported, TypeScript will recognize 'USDC' as a valid
+ * `TokenSymbol` value with autocomplete support.
+ *
+ * Other packages or applications can create their own augmentations
+ * to add additional tokens.
+ *
+ * @example
+ * ```typescript
+ * import '@core/tokens' // Automatically includes this augmentation
+ *
+ * const symbol: TokenSymbol = 'USDC' // ✓ Autocomplete shows USDC
+ * ```
+ */
+declare module './types' {
+    /**
+     * Module augmentation: Adds known token symbols as valid keys
+     * to the TokenSymbolRegistry interface.
+     *
+     * Keys are explicitly listed to ensure IDE autocomplete works properly.
+     */
+    interface TokenSymbolRegistry {
+        USDC: true;
+        USDT: true;
+        EURC: true;
+        DAI: true;
+        USDE: true;
+        PYUSD: true;
+        WETH: true;
+        WBTC: true;
+        WSOL: true;
+        WAVAX: true;
+        WPOL: true;
+        ETH: true;
+        POL: true;
+        PLUME: true;
+        MON: true;
+    }
+}
+
+/**
+ * Module augmentation to register Blockchain enum values as ChainIdentifiers.
+ *
+ * @remarks
+ * This file augments the `ChainRegistry` interface to provide type-safe
+ * autocomplete for all `Blockchain` enum values from `@core/chains`.
+ *
+ * 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 { Blockchain } from '@core/chains'
+ * import type { ChainIdentifier } from '@core/tokens'
+ *
+ * // Using enum value
+ * const chain1: ChainIdentifier = Blockchain.Ethereum
+ *
+ * // Using string literal (with autocomplete!)
+ * const chain2: ChainIdentifier = 'Base'
+ *
+ * // Arbitrary strings also work (escape hatch for custom chains)
+ * const chain3: ChainIdentifier = 'my-custom-chain'
+ * ```
+ */
+
+declare module './types' {
+    /**
+     * Module augmentation: Adds all Blockchain enum values as valid keys
+     * to the ChainRegistry interface for type-safe chain identifier support.
+     *
+     * 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.
+     *
+     * 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.
+     */
+    interface ChainRegistry extends Record<`${Blockchain}`, true> {
+    }
+}
+
+/**
+ * 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.
+ */
+type LiteralUnion<T extends string> = T | (string & Record<never, never>);
+/**
+ * Registry for known chain identifiers (augmentation target).
+ *
+ * @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.
+ */
+interface ChainRegistry {
+}
+/**
+ * Union of all registered chain identifiers.
+ *
+ * @remarks
+ * 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 chain: ChainIdentifier = 'Ethereum'  // Autocomplete works
+ * const custom: ChainIdentifier = 'my-chain' // Also valid
+ * ```
+ */
+type ChainIdentifier = keyof ChainRegistry extends never ? string : LiteralUnion<Extract<keyof ChainRegistry, string>>;
+/**
+ * Maps chain identifiers to their token locators.
+ *
+ * @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
+ * 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...',
+ * }
+ * ```
+ */
+type ChainLocatorMap = Record<ChainIdentifier, string>;
+/**
+ * Complete definition of a token including metadata and chain locators.
+ *
+ * @remarks
+ * This is the canonical representation of a token in the registry.
+ * It includes the symbol, decimals, and chain-specific locators.
+ *
+ * @example
+ * ```typescript
+ * const usdc: TokenDefinition = {
+ *   symbol: 'USDC',
+ *   decimals: 6,
+ *   locators: {
+ *     [Blockchain.Ethereum]: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+ *     [Blockchain.Solana]: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   },
+ * }
+ * ```
+ */
+interface TokenDefinition {
+    /**
+     * The token symbol (e.g., "USDC", "EURC").
+     */
+    readonly symbol: string;
+    /**
+     * The default number of decimal places for the token.
+     * Used when no chain-specific override exists in {@link chainDecimals}.
+     * @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>;
+    /**
+     * Optional per-chain decimal overrides.
+     *
+     * Some tokens have different decimal places on different chains
+     * (e.g., USDe is 18 decimals on EVM but 9 decimals on Solana).
+     * When present, the value for a specific chain takes precedence
+     * over the default {@link decimals}.
+     */
+    readonly chainDecimals?: Partial<Record<ChainIdentifier, number>>;
+}
+/**
+ * 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;
+    /**
+     * Resolve a token by chain-specific locator (address/program ID).
+     *
+     * @param address - The token locator to resolve.
+     * @param chainId - The chain identifier to resolve for.
+     * @returns The resolved token information.
+     * @throws When no registry token matches the locator on the chain.
+     */
+    resolveByAddress(address: string, 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: 'app-kit',
+ *   version: '1.0.0',
+ * })
+ *
+ * // All metrics include service + version labels
+ * appMetrics.counter('transfers.initiated').inc({ chain: 'ethereum' })
  * ```
  */
-declare class Actionable<AllActions> {
-    private readonly handlers;
-    private readonly wildcard;
+interface Metrics {
     /**
-     * Register a handler for a specific action.
+     * Get or create a counter metric by name.
      *
-     * @param action - The specific action key to listen for.
-     * @param handler - The callback function to execute when the action occurs.
+     * @param name - The metric name (e.g., 'http.requests.total').
+     * @returns A Counter instance for the given name.
      *
      * @example
      * ```typescript
-     * const events = new Actionable<{ dataReceived: string }>();
-     *
-     * events.on('dataReceived', (data) => {
-     *   console.log(`Received: ${data}`);
-     * });
+     * const counter = metrics.counter('requests.total')
+     * counter.inc({ method: 'GET' })
      * ```
      */
-    on<Action extends keyof AllActions>(action: Action, handler: (payload: AllActions[Action]) => void): void;
+    counter(name: string): Counter;
     /**
-     * Register a handler for all actions using the wildcard '*'.
+     * Get or create a histogram metric by name.
      *
-     * @param action - The wildcard '*' signifying interest in all actions.
-     * @param handler - The callback function to execute for any action.
+     * @param name - The metric name (e.g., 'http.request.duration').
+     * @returns A Histogram instance for the given name.
      *
      * @example
      * ```typescript
-     * const events = new Actionable<{ started: boolean; completed: string }>();
-     *
-     * events.on('*', (payload) => {
-     *   console.log('Action occurred:', payload);
-     * });
+     * const histogram = metrics.histogram('request.duration')
+     * histogram.observe({ status: 200 }, 42.5)
      * ```
      */
-    on(action: '*', handler: (payload: AllActions[keyof AllActions]) => void): void;
+    histogram(name: string): Histogram;
     /**
-     * Remove a previously registered handler for a specific action.
+     * Get or create a timer metric by name.
      *
-     * @param action - The specific action key to unregister from.
-     * @param handler - The callback function to remove.
+     * @param name - The metric name (e.g., 'db.query.duration').
+     * @returns A Timer instance for the given name.
      *
      * @example
      * ```typescript
-     * const events = new Actionable<{ dataReceived: string }>();
-     *
-     * const handler = (data: string) => console.log(data);
-     * events.on('dataReceived', handler);
-     *
-     * // Later, to remove the handler:
-     * events.off('dataReceived', handler);
+     * const stop = metrics.timer('db.query').start()
+     * await query()
+     * stop()
      * ```
      */
-    off<Action extends keyof AllActions>(action: Action, handler: (payload: AllActions[Action]) => void): void;
+    timer(name: string): Timer;
     /**
-     * Remove a previously registered wildcard handler.
+     * Create a child metrics instance with scoped labels.
      *
-     * @param action - The wildcard '*' signifying removal from all actions.
-     * @param handler - The callback function to remove.
+     * @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 events = new Actionable<{ started: boolean; completed: string }>();
+     * 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.
      *
-     * const globalHandler = (payload: any) => console.log(payload);
-     * events.on('*', globalHandler);
+     * @returns Current time in milliseconds.
+     */
+    now(): number;
+    /**
+     * Calculate elapsed time since a given timestamp.
      *
-     * // Later, to remove the handler:
-     * events.off('*', globalHandler);
-     * ```
+     * @param start - The start timestamp in milliseconds.
+     * @returns Elapsed time in milliseconds (`now() - start`).
      */
-    off(action: '*', handler: (payload: AllActions[keyof AllActions]) => void): void;
+    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 {
     /**
-     * Dispatch an action with its payload to all registered handlers.
+     * Clock for time operations.
      *
-     * This method notifies both:
-     * - Handlers registered specifically for this action
-     * - Wildcard handlers registered for all actions
+     * @remarks
+     * Provides the current timestamp. Use {@link defaultClock} for production
+     * or custom clocks for deterministic testing.
+     */
+    clock: Clock;
+    /**
+     * Logger for structured logging.
      *
-     * @param action - The action key identifying the event type.
-     * @param payload - The data associated with the action.
+     * @remarks
+     * Provides debug, info, warn, error methods with structured data support.
+     */
+    logger: Logger;
+    /**
+     * Metrics collector for observability.
      *
-     * @example
-     * ```typescript
-     * type Actions = {
-     *   transferStarted: { amount: string; destination: string };
-     *   transferComplete: { txHash: string };
-     * };
+     * @remarks
+     * Provides counters, histograms, and timers for application metrics.
+     */
+    metrics: Metrics;
+    /**
+     * Event bus for pub/sub events.
      *
-     * const events = new Actionable<Actions>();
+     * @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.
      *
-     * // Dispatch an event
-     * events.dispatch('transferStarted', {
-     *   amount: '100',
-     *   destination: '0xABC123'
-     * });
-     * ```
+     * @remarks
+     * Common types: `app`, `kit`, `provider`, `adapter`
      */
-    dispatch<K extends keyof AllActions>(action: K, payload: AllActions[K]): void;
+    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;
 }
 
 /**
@@ -2569,6 +4367,14 @@ TChainDefinition extends ChainDefinition = ChainDefinition> {
     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.
@@ -2598,6 +4404,15 @@ interface BridgeStep {
     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) */
@@ -2649,6 +4464,13 @@ interface BridgeResult {
          * 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[];
@@ -2706,8 +4528,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 +4679,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 +4807,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 +4819,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 +4940,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 +4957,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 +5130,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 +5178,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 +5251,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 +5317,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 +5325,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 +5333,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 +5341,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 +5349,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 +5541,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 +5550,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 +5563,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 +5604,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 +5782,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 +5798,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 +5847,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 +5939,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 +6059,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 };