@circle-fin/bridge-kit 1.1.2 → 1.3.0

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2025, Circle Internet Group, Inc. All rights reserved.
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -400,10 +400,16 @@ type KitContractType = 'bridge';
  */
 type KitContracts = Partial<Record<KitContractType, string>>;
 /**
- * Enumeration of all blockchains supported by this library.
+ * Enumeration of all blockchains known to this library.
+ *
+ * This enum contains every blockchain that has a chain definition, regardless
+ * of whether bridging is currently supported. For chains that support bridging
+ * via CCTPv2, see {@link BridgeChain}.
+ *
  * @enum
  * @category Enums
- * @description Provides string identifiers for each supported blockchain.
+ * @description Provides string identifiers for each blockchain with a definition.
+ * @see {@link BridgeChain} for the subset of chains that support CCTPv2 bridging.
  */
 declare enum Blockchain {
     Algorand = "Algorand",
@@ -462,6 +468,143 @@ declare enum Blockchain {
     ZKSync_Era = "ZKSync_Era",
     ZKSync_Sepolia = "ZKSync_Sepolia"
 }
+/**
+ * Enumeration of blockchains that support cross-chain bridging via CCTPv2.
+ *
+ * The enum is derived from the full {@link Blockchain} enum but filtered to only
+ * include chains with active CCTPv2 support. When new chains gain CCTPv2 support,
+ * they are added to this enum.
+ *
+ * @enum
+ * @category Enums
+ *
+ * @remarks
+ * - This enum is the **canonical source** of bridging-supported chains.
+ * - Use this enum (or its string literals) in `kit.bridge()` calls for type safety.
+ * - Attempting to use a chain not in this enum will produce a TypeScript compile error.
+ *
+ * @example
+ * ```typescript
+ * import { BridgeKit, BridgeChain } from '@circle-fin/bridge-kit'
+ *
+ * const kit = new BridgeKit()
+ *
+ * // ✅ Valid - autocomplete suggests only supported chains
+ * await kit.bridge({
+ *   from: { adapter, chain: BridgeChain.Ethereum },
+ *   to: { adapter, chain: BridgeChain.Base },
+ *   amount: '100'
+ * })
+ *
+ * // ✅ Also valid - string literals work with autocomplete
+ * await kit.bridge({
+ *   from: { adapter, chain: 'Ethereum_Sepolia' },
+ *   to: { adapter, chain: 'Base_Sepolia' },
+ *   amount: '100'
+ * })
+ *
+ * // ❌ Compile error - Algorand is not in BridgeChain
+ * await kit.bridge({
+ *   from: { adapter, chain: 'Algorand' }, // TypeScript error!
+ *   to: { adapter, chain: 'Base' },
+ *   amount: '100'
+ * })
+ * ```
+ *
+ * @see {@link Blockchain} for the complete list of all known blockchains.
+ * @see {@link BridgeChainIdentifier} for the type that accepts these values.
+ */
+declare enum BridgeChain {
+    Arbitrum = "Arbitrum",
+    Avalanche = "Avalanche",
+    Base = "Base",
+    Codex = "Codex",
+    Ethereum = "Ethereum",
+    HyperEVM = "HyperEVM",
+    Ink = "Ink",
+    Linea = "Linea",
+    Optimism = "Optimism",
+    Plume = "Plume",
+    Polygon = "Polygon",
+    Sei = "Sei",
+    Solana = "Solana",
+    Sonic = "Sonic",
+    Unichain = "Unichain",
+    World_Chain = "World_Chain",
+    XDC = "XDC",
+    Arc_Testnet = "Arc_Testnet",
+    Arbitrum_Sepolia = "Arbitrum_Sepolia",
+    Avalanche_Fuji = "Avalanche_Fuji",
+    Base_Sepolia = "Base_Sepolia",
+    Codex_Testnet = "Codex_Testnet",
+    Ethereum_Sepolia = "Ethereum_Sepolia",
+    HyperEVM_Testnet = "HyperEVM_Testnet",
+    Ink_Testnet = "Ink_Testnet",
+    Linea_Sepolia = "Linea_Sepolia",
+    Optimism_Sepolia = "Optimism_Sepolia",
+    Plume_Testnet = "Plume_Testnet",
+    Polygon_Amoy_Testnet = "Polygon_Amoy_Testnet",
+    Sei_Testnet = "Sei_Testnet",
+    Solana_Devnet = "Solana_Devnet",
+    Sonic_Testnet = "Sonic_Testnet",
+    Unichain_Sepolia = "Unichain_Sepolia",
+    World_Chain_Sepolia = "World_Chain_Sepolia",
+    XDC_Apothem = "XDC_Apothem"
+}
+/**
+ * Type representing valid bridge chain identifiers.
+ *
+ * This type constrains chain parameters to only accept chains that support CCTPv2 bridging
+ *
+ * Accepts:
+ * - A {@link BridgeChain} enum value (e.g., `BridgeChain.Ethereum`)
+ * - A string literal matching a BridgeChain value (e.g., `'Ethereum'`)
+ * - A {@link ChainDefinition} object for a supported chain
+ *
+ * @example
+ * ```typescript
+ * import type { BridgeChainIdentifier } from '@circle-fin/bridge-kit'
+ * import { BridgeChain } from '@circle-fin/bridge-kit'
+ * import { Solana } from '@circle-fin/bridge-kit/chains'
+ *
+ * // All of these are valid BridgeChainIdentifier values:
+ * const chain1: BridgeChainIdentifier = BridgeChain.Ethereum
+ * const chain2: BridgeChainIdentifier = 'Base_Sepolia'
+ * const chain3: BridgeChainIdentifier = Solana // ChainDefinition
+ *
+ * // This will cause a TypeScript error:
+ * const chain4: BridgeChainIdentifier = 'Algorand' // Error!
+ * ```
+ *
+ * @see {@link BridgeChain} for the enum of supported chains.
+ * @see {@link ChainIdentifier} for the less restrictive type accepting all chains.
+ */
+type BridgeChainIdentifier = ChainDefinition | BridgeChain | `${BridgeChain}`;
+
+/**
+ * Resolves a flexible chain identifier to a ChainDefinition.
+ *
+ * This function handles all three supported formats:
+ * - ChainDefinition objects (passed through unchanged)
+ * - Blockchain enum values (resolved via getChainByEnum)
+ * - String literals of blockchain values (resolved via getChainByEnum)
+ *
+ * @param chainIdentifier - The chain identifier to resolve
+ * @returns The resolved ChainDefinition object
+ * @throws Error if the chain identifier cannot be resolved
+ *
+ * @example
+ * ```typescript
+ * import { resolveChainIdentifier } from '@core/chains'
+ * import { Blockchain, Ethereum } from '@core/chains'
+ *
+ * // All of these resolve to the same ChainDefinition:
+ * const chain1 = resolveChainIdentifier(Ethereum)
+ * const chain2 = resolveChainIdentifier(Blockchain.Ethereum)
+ * const chain3 = resolveChainIdentifier('Ethereum')
+ * ```
+ */
+declare function resolveChainIdentifier(chainIdentifier: ChainIdentifier): ChainDefinition;
 
 /**
  * Core type definitions for blockchain transaction execution and gas estimation.
@@ -1878,10 +2021,9 @@ declare class ActionRegistry {
      * @param params - The parameters to pass to the action handler.
      * @param context - The resolved operation context with concrete chain and address values.
      * @returns A promise resolving to the prepared chain request.
-     *
-     * @throws {Error} When action parameter is not a valid string.
+     * @throws {KitError} When the handler execution fails with a structured error.
      * @throws {Error} When no handler is registered for the specified action.
-     * @throws {Error} When the handler execution fails.
+     * @throws {Error} When the handler execution fails with an unstructured error.
      *
      * @example
      * ```typescript
@@ -2591,6 +2733,14 @@ interface BridgeResult {
         address: string;
         /** The destination blockchain network */
         chain: ChainDefinition;
+        /**
+         * Optional custom recipient address for minted funds.
+         *
+         * When provided during the bridge operation, minted tokens are sent to this
+         * address instead of the destination address. This field is preserved in the
+         * result for retry operations to maintain consistency with the original burn.
+         */
+        recipientAddress?: string;
     };
     /** Array of steps that were executed during the bridge process */
     steps: BridgeStep[];
@@ -2600,15 +2750,39 @@ interface BridgeResult {
  *
  * This interface provides detailed information about the expected costs
  * for a transfer, including gas fees on different chains and protocol fees.
+ * It also includes the input context (token, amount, source, destination) to
+ * provide a complete view of the transfer being estimated.
  *
  * @example
  * ```typescript
  * const estimate: EstimateResult = await provider.estimate(source, dest, '100')
+ * console.log('Estimating transfer of', estimate.amount, estimate.token)
+ * console.log('From', estimate.source.chain.name, 'to', estimate.destination.chain.name)
  * console.log('Total gas fees:', estimate.gasFees.length)
  * console.log('Protocol fees:', estimate.fees.length)
  * ```
  */
 interface EstimateResult {
+    /** The token being transferred */
+    token: 'USDC';
+    /** The amount being transferred */
+    amount: string;
+    /** Information about the source chain and address */
+    source: {
+        /** The source wallet/contract address */
+        address: string;
+        /** The source blockchain network */
+        chain: Blockchain;
+    };
+    /** Information about the destination chain and address */
+    destination: {
+        /** The destination wallet/contract address */
+        address: string;
+        /** The destination blockchain network */
+        chain: Blockchain;
+        /** Optional custom recipient address for minted funds. */
+        recipientAddress?: string;
+    };
     /** Array of gas fees required for the transfer on different blockchains */
     gasFees: {
         /** The name of the step */
@@ -2680,6 +2854,40 @@ interface BridgeConfig {
     maxFee?: string;
     /**
      * The custom fee to charge for the transfer.
+     *
+     * Whatever value you provide here is **added on top of the transfer amount**. The user must have
+     * enough balance for `amount + customFee`, and the wallet signs for that total on the source
+     * chain. The custom fee is split automatically:
+     *
+     * - 10% routes to Circle.
+     * - 90% routes to your `recipientAddress`.
+     *
+     * The original transfer amount proceeds through CCTPv2 unchanged, and the protocol fee (1–14 bps
+     * in FAST mode, 0% in STANDARD) is taken from that transfer amount.
+     *
+     * @example
+     * ```typescript
+     * import type { BridgeConfig } from '@core/provider'
+     *
+     * const config: BridgeConfig = {
+     *   customFee: {
+     *     value: '5', // 5 USDC developer fee
+     *     recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
+     *   },
+     * }
+     *
+     * // Fee flow for a 100 USDC transfer with 5 USDC custom fee:
+     * // Source chain (Ethereum):
+     * // - Wallet debits: 105 USDC total (100 transfer + 5 custom fee)
+     * // - Custom fee split: 0.5 USDC (10%) → Circle, 4.5 USDC (90%) → your recipientAddress
+     * // - Amount sent to CCTPv2: 100 USDC (unchanged)
+     * //
+     * // Destination chain (Base):
+     * // - CCTPv2 FAST fee (example: 1 bps): ~0.01 USDC deducted
+     * // - User receives: ~99.99 USDC
+     * //
+     * // Note: Actual CCTP fees vary by route (1-14 bps for FAST, 0 bps for STANDARD)
+     * ```
      */
     customFee?: CustomFee | undefined;
 }
@@ -2722,6 +2930,10 @@ interface CustomFee {
      * bridge transfer. The fee recipient address **must be a valid address for
      * the source chain** of the bridge transfer.
      *
+     * @remarks
+     * Circle automatically receives 10% of every custom fee; the remaining 90% is
+     * sent to this `recipientAddress`.
+     *
      * For example: if bridging from Ethereum to Solana, pass an EVM address like
      * `"0x1234567890123456789012345678901234567890"` because the source chain
      * is Ethereum.
@@ -2744,6 +2956,7 @@ interface CustomFee {
  * and address requirements are enforced at compile time based on adapter capabilities.
  *
  * @typeParam TAdapterCapabilities - The adapter capabilities type to derive address requirements from
+ * @typeParam TChainIdentifier - The chain identifier type constraint (defaults to ChainIdentifier)
  *
  * @example
  * ```typescript
@@ -2762,11 +2975,11 @@ interface CustomFee {
  * }
  * ```
  */
-type AdapterContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> = {
+type AdapterContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends ChainIdentifier = ChainIdentifier> = {
     /** The adapter instance for blockchain operations */
     adapter: Adapter<TAdapterCapabilities>;
     /** The chain reference, which can be a ChainDefinition, Blockchain enum, or string literal */
-    chain: ChainIdentifier;
+    chain: TChainIdentifier;
 } & AddressField<ExtractAddressContext<TAdapterCapabilities>>;
 /**
  * Represents a bridge destination with an explicit custom recipient address.
@@ -2777,6 +2990,7 @@ type AdapterContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCa
  * the destination adapter.
  *
  * @typeParam TCapabilities - The adapter capabilities type for the destination adapter
+ * @typeParam TChainIdentifier - The chain identifier type constraint (defaults to ChainIdentifier)
  *
  * @remarks
  * The `recipientAddress` must be a valid address format for the destination chain
@@ -2797,7 +3011,7 @@ type AdapterContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCa
  * }
  * ```
  */
-type BridgeDestinationWithAddress<TCapabilities extends AdapterCapabilities = AdapterCapabilities> = AdapterContext<TCapabilities> & {
+type BridgeDestinationWithAddress<TCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends ChainIdentifier = ChainIdentifier> = AdapterContext<TCapabilities, TChainIdentifier> & {
     /**
      * The custom recipient address on the destination chain.
      *
@@ -2809,8 +3023,11 @@ type BridgeDestinationWithAddress<TCapabilities extends AdapterCapabilities = Ad
 /**
  * Union type representing a bridge destination.
  * Can be either an AdapterContext (for default recipient) or BridgeDestinationWithAddress (for explicit recipient).
+ *
+ * @typeParam TAdapterCapabilities - The adapter capabilities type for the destination adapter
+ * @typeParam TChainIdentifier - The chain identifier type constraint (defaults to ChainIdentifier)
  */
-type BridgeDestination<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> = AdapterContext<TAdapterCapabilities> | BridgeDestinationWithAddress<TAdapterCapabilities>;
+type BridgeDestination<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends ChainIdentifier = ChainIdentifier> = AdapterContext<TAdapterCapabilities, TChainIdentifier> | BridgeDestinationWithAddress<TAdapterCapabilities, TChainIdentifier>;
 /**
  * Context for retry operations containing source and destination adapter contexts.
  *
@@ -2953,7 +3170,7 @@ declare abstract class BridgingProvider<TProviderActions = Record<string, unknow
      * @param token - The token to bridge (currently only USDC is supported)
      * @param config - Optional bridge configuration including speed and fee settings
      * @returns Promise resolving to the bridge result with transaction details and steps
-     * @throws {ValidationError} If the parameters are invalid
+     * @throws {KitError} If the parameters are invalid
      * @throws {UnsupportedRouteError} If the route is not supported
      * @throws {BridgeError} If the bridge operation fails
      *
@@ -2978,7 +3195,7 @@ declare abstract class BridgingProvider<TProviderActions = Record<string, unknow
      *
      * @param params - The bridge parameters for cost estimation
      * @returns Promise resolving to the cost estimate including gas and protocol fees
-     * @throws {ValidationError} If the parameters are invalid
+     * @throws {KitError} If the parameters are invalid
      * @throws {UnsupportedRouteError} If the route is not supported
      *
      * @example
@@ -3104,44 +3321,62 @@ declare abstract class BridgingProvider<TProviderActions = Record<string, unknow
     analyzeStepsForRetry(steps: BridgeStep[]): StepAnalysisResult;
 }
 
+type FeeFunction<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities> = (params: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>) => Promise<string> | string;
+type FeeRecipientFunction<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities> = (feePayoutChain: ChainDefinition, params: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>) => Promise<string> | string;
 /**
  * Custom fee policy for BridgeKit.
  *
- * Provides hooks to calculate an absolute fee (in smallest unit string)
- * and to resolve the fee recipient address on the source chain.
+ * Provides hooks to calculate an absolute custom fee and resolve the fee recipient address
+ * on the source chain. The returned fee is **added on top of the transfer amount** (the wallet signs for
+ * `amount + customFee`). Once collected, the custom fee is split:
+ *
+ * - **10%** automatically routes to Circle.
+ * - **90%** routes to your supplied `recipientAddress`.
+ *
+ * The entire transfer amount still flows through CCTPv2, which then charges its own protocol fee.
+ *
+ * Use `computeFee` (recommended) for human-readable amounts, or `calculateFee` (deprecated)
+ * for smallest-unit amounts. Only one should be provided.
  *
  * @example
  * ```typescript
  * import type { CustomFeePolicy, BridgeParams } from '@circle-fin/bridge-kit'
  *
  * const policy: CustomFeePolicy = {
- *   // Charge 1 USDC on Solana, 0 on Ethereum, else 2 USDC
- *   calculateFee: (params: BridgeParams): string => {
- *     if (params.from.chain.type === 'solana') return '1000000'
- *     if (params.from.chain.name === 'Ethereum') return '0'
- *     return '2000000'
- *   },
- *   // Return a valid fee recipient for the source chain
- *   resolveFeeRecipientAddress: (feePayoutChain): string => {
- *     if (feePayoutChain.type === 'solana') {
- *       return 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
- *     }
- *     return '0x1234567890123456789012345678901234567890'
+ *   // computeFee receives human-readable amounts (e.g., '100' for 100 USDC)
+ *   computeFee: (params: BridgeParams) => {
+ *     const amount = parseFloat(params.amount)
+ *
+ *     // 1% fee, capped between 5-50 USDC
+ *     const fee = Math.min(Math.max(amount * 0.01, 5), 50)
+ *     return fee.toFixed(6)
  *   },
+ *   resolveFeeRecipientAddress: (feePayoutChain) =>
+ *     feePayoutChain.type === 'solana'
+ *       ? 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
+ *       : '0x1234567890123456789012345678901234567890',
  * }
  * ```
  */
-interface CustomFeePolicy {
+type CustomFeePolicy = {
     /**
      * A function that returns the fee to charge for the bridge transfer.
-     * The value returned from the function represents an absolute fee in the smallest unit of the token.
-     * It **does not** represent a percentage fee, only an absolute value.
+     * The value returned from the function represents an absolute fee.
+     * The returned fee is **added on top of the transfer amount**. For example, returning
+     * `'5'` (5 USDC) for a 100 USDC transfer causes the wallet to debit 105 USDC total.
+     * CCTPv2 still processes the full 100 USDC transfer amount, while the custom fee is split
+     * 10%/90% between Circle and your fee recipient.
      *
-     * For example: if you want to charge 1 USDC, you would return `'1000000'`.
-     *
-     * Note: returning `'0'` will result in no fee being charged.
+     * @example
+     * ```typescript
+     * computeFee: (params) => {
+     *   const amount = parseFloat(params.amount)
+     *   return (amount * 0.01).toString() // 1% fee
+     * }
+     * ```
      */
-    calculateFee: <TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(params: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>) => Promise<string> | string;
+    computeFee: FeeFunction<AdapterCapabilities, AdapterCapabilities>;
+    calculateFee?: never;
     /**
      * A function that returns the fee recipient for a bridge transfer.
      * The value returned from the function represents the address that will receive the fee on the source chain of the bridge transfer.
@@ -3150,18 +3385,27 @@ interface CustomFeePolicy {
      * For example: if you are bridging from Ethereum to Solana you would return `'0x1234567890123456789012345678901234567890'`,
      * because the source chain of the bridge transfer is Ethereum.
      */
-    resolveFeeRecipientAddress: <TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(
+    resolveFeeRecipientAddress: FeeRecipientFunction<AdapterCapabilities, AdapterCapabilities>;
+} | {
+    computeFee?: never;
     /**
-     * The chain definition for the chain on which the fee is paid (the source chain).
-     * For example, when bridging from Ethereum to Base, the fee payout chain is Ethereum,
-     * since the bridging originates on Ethereum and the fee is taken on the source chain.
+     * Calculate the fee to charge for the bridge transfer using smallest-unit amounts.
+     *
+     * @deprecated Use `computeFee` instead, which receives human-readable amounts.
+     *
+     * The `params.amount` is in smallest units (e.g., `'100000000'` for 100 USDC).
      */
-    feePayoutChain: ChainDefinition, 
+    calculateFee: FeeFunction<AdapterCapabilities, AdapterCapabilities>;
     /**
-     * The bridge parameters.
+     * A function that returns the fee recipient for a bridge transfer.
+     * The value returned from the function represents the address that will receive the fee on the source chain of the bridge transfer.
+     * The fee recipient address **must be a valid address for the source chain** of the bridge transfer.
+     *
+     * For example: if you are bridging from Ethereum to Solana you would return `'0x1234567890123456789012345678901234567890'`,
+     * because the source chain of the bridge transfer is Ethereum.
      */
-    params: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>) => Promise<string> | string;
-}
+    resolveFeeRecipientAddress: FeeRecipientFunction<AdapterCapabilities, AdapterCapabilities>;
+};
 /**
  * Parameters for initiating a cross-chain USDC bridge transfer.
  *
@@ -3173,46 +3417,69 @@ interface CustomFeePolicy {
  * - The `config` field allows customization of bridge behavior (e.g., transfer speed).
  * - The `token` field is optional and defaults to 'USDC'; other tokens are not currently supported.
  *
- * @typeParam TChainDefinition - The chain definition type for advanced usage (defaults to {@link ChainDefinition}).
+ * @typeParam TFromAdapterCapabilities - The source adapter capabilities type.
+ * @typeParam TToAdapterCapabilities - The destination adapter capabilities type.
  *
  * @example
  * ```typescript
+ * import { BridgeKit, BridgeChain } from '@circle-fin/bridge-kit'
+ *
+ * const kit = new BridgeKit()
+ *
+ * // Using BridgeChain enum values (full autocomplete support)
  * const params: BridgeParams = {
- *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
- *   to: { adapter: destAdapter, chain: 'Base' },
+ *   from: { adapter: sourceAdapter, chain: BridgeChain.Ethereum },
+ *   to: { adapter: destAdapter, chain: BridgeChain.Base },
  *   amount: '10.5',
- *   // Optional:
  *   config: { transferSpeed: 'FAST' },
  *   token: 'USDC'
  * }
  *
- * // Or with explicit recipient address:
+ * // Using string literals (also works with autocomplete)
+ * const params2: BridgeParams = {
+ *   from: { adapter: sourceAdapter, chain: 'Ethereum_Sepolia' },
+ *   to: { adapter: destAdapter, chain: 'Base_Sepolia' },
+ *   amount: '10.5'
+ * }
+ *
+ * // With explicit recipient address:
  * const paramsWithAddress: BridgeParams = {
- *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
+ *   from: { adapter: sourceAdapter, chain: BridgeChain.Ethereum },
  *   to: {
  *     recipientAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
- *     adapter: destAdapter, chain: 'Base'
+ *     adapter: destAdapter,
+ *     chain: BridgeChain.Base
  *   },
  *   amount: '10.5'
  * }
+ *
+ * // ❌ Compile error - Algorand is not a supported bridge chain
+ * const invalidParams: BridgeParams = {
+ *   from: { adapter: sourceAdapter, chain: 'Algorand' }, // TypeScript error!
+ *   to: { adapter: destAdapter, chain: 'Base' },
+ *   amount: '10.5'
+ * }
  * ```
+ *
+ * @see {@link BridgeChain} for the enum of supported chains.
+ * @see {@link BridgeChainIdentifier} for the type of valid chain values.
  */
 interface BridgeParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
     /**
      * The source adapter context (wallet and chain) for the transfer.
      */
-    from: AdapterContext<TFromAdapterCapabilities>;
+    from: AdapterContext<TFromAdapterCapabilities, BridgeChainIdentifier>;
     /**
-     * The destination for the transfer, supporting explicit or derived recipient addresses.
+     * The destination for the transfer, supporting explicit or derived recipient addresses
      */
-    to: BridgeDestination<TToAdapterCapabilities>;
+    to: BridgeDestination<TToAdapterCapabilities, BridgeChainIdentifier>;
     /**
-     * The amount to transfer.
+     * The amount to transfer
      */
     amount: string;
     /**
      * Optional bridge configuration (e.g., transfer speed).
-     * If omitted, defaults will be used.
+     * If omitted, defaults will be used
      */
     config?: BridgeConfig;
     /**
@@ -3250,8 +3517,9 @@ declare const getDefaultProviders: () => readonly [CCTPV2BridgingProvider];
  *
  * // Set custom fee policy using the setter method
  * kit.setCustomFeePolicy({
- *   calculateFee: (params: BridgeParams): string => {
- *     return '1000000' // 1 USDC
+ *   computeFee: (params: BridgeParams): string => {
+ *     const amount = parseFloat(params.amount)
+ *     return (amount * 0.01).toFixed(6) // 1% fee
  *   },
  *   resolveFeeRecipientAddress: (chain: ChainDefinition): string => {
  *     return '0x1234567890123456789012345678901234567890'
@@ -3410,18 +3678,18 @@ type FlexibleBridgingProvider = BridgingProvider<any>;
  *
  * @param params - The bridge parameters containing source, destination, amount, and token
  * @returns Promise resolving to the bridge result with transaction details and steps
- * @throws {ValidationError} If the parameters are invalid
+ * @throws {KitError} If the parameters are invalid
  * @throws {BridgeError} If the bridging process fails
  * @throws {UnsupportedRouteError} If the route is not supported
  *
  * @example
  * ```typescript
  * import { BridgeKit } from '@circle-fin/bridge-kit'
- * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+ * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
  *
  * // Create kit with default CCTPv2 provider
  * const kit = new BridgeKit()
- * const adapter = createAdapterFromPrivateKey({ privateKey: '0x...' })
+ * const adapter = createViemAdapterFromPrivateKey({ privateKey: '0x...' })
  *
  * // Execute cross-chain transfer
  * const result = await kit.bridge({
@@ -3542,18 +3810,18 @@ declare class BridgeKit<TExtraProviders extends FlexibleBridgingProvider[] = []>
      *
      * @param params - The transfer parameters containing source, destination, amount, and token
      * @returns Promise resolving to the transfer result with transaction details and steps
-     * @throws {ValidationError} When any parameter validation fails.
+     * @throws {KitError} When any parameter validation fails.
      * @throws {Error} When CCTPv2 does not support the specified route.
      *
      * @example
      * ```typescript
      * import { BridgeKit } from '@circle-fin/bridge-kit'
-     * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+     * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
      *
      * const kit = new BridgeKit()
      *
      * // Create a single adapter that can work across chains
-     * const adapter = createAdapterFromPrivateKey({
+     * const adapter = createViemAdapterFromPrivateKey({
      *   privateKey: process.env.PRIVATE_KEY,
      * })
      *
@@ -3612,10 +3880,14 @@ declare class BridgeKit<TExtraProviders extends FlexibleBridgingProvider[] = []>
      * @example
      * ```typescript
      * import { BridgeKit } from '@circle-fin/bridge-kit'
-     * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+     * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
      *
      * const kit = new BridgeKit()
      *
+     * // Create adapters for source and destination chains
+     * const sourceAdapter = createViemAdapterFromPrivateKey({ privateKey: '...' })
+     * const destAdapter = createViemAdapterFromPrivateKey({ privateKey: '...' })
+     *
      * // Assume we have a failed bridge result from a previous operation
      * const failedResult: BridgeResult = {
      *   state: 'error',
@@ -3651,7 +3923,7 @@ declare class BridgeKit<TExtraProviders extends FlexibleBridgingProvider[] = []>
      * as the bridge method but stops before execution.
      * @param params - The bridge parameters for cost estimation
      * @returns Promise resolving to detailed cost breakdown including gas estimates
-     * @throws {ValidationError} When the parameters are invalid.
+     * @throws {KitError} When the parameters are invalid.
      * @throws {UnsupportedRouteError} When the route is not supported.
      *
      * @example
@@ -3736,40 +4008,61 @@ declare class BridgeKit<TExtraProviders extends FlexibleBridgingProvider[] = []>
      */
     private mergeCustomFeeConfig;
     /**
-     * Sets the custom fee policy for the kit.
+     * Resolve the custom fee for a bridge transfer.
+     *
+     * Checks which fee function the user provided and executes accordingly:
+     * - `computeFee`: receives human-readable amounts, returns human-readable fee
+     * - `calculateFee` (deprecated): receives smallest units, returns smallest units
+     *
+     * @param providerParams - The resolved bridge parameters (amounts in smallest units).
+     * @returns The resolved fee in smallest units, or undefined if no fee policy is set.
+     */
+    private resolveFee;
+    /**
+     * Set the custom fee policy for the kit.
      *
-     * Ensures the fee is represented in the smallest unit of the token.
-     * - If the token is USDC, the fee is converted to base units (6 decimals).
-     * - If the token is not USDC, the fee is returned as is.
+     * Use `computeFee` (recommended) for human-readable amounts, or `calculateFee`
+     * (deprecated) for smallest-unit amounts. Only one should be provided.
      *
-     * This allows developers to specify the kit-level fee in base units (e.g., USDC: 1, ETH: 0.000001),
-     * and the kit will handle conversion to the smallest unit as needed.
+     * ```text
+     * Transfer amount (user input, e.g., 1,000 USDC)
+     *   ↓ Wallet signs for transfer + custom fee (e.g., 1,000 + 10 = 1,010 USDC)
+     *   ↓ Custom fee split (10% Circle, 90% your recipientAddress wallet)
+     *   ↓ Full transfer amount (1,000 USDC) forwarded to CCTPv2
+     *   ↓ CCTPv2 protocol fee (e.g., 0.1 USDC) deducted from transfer amount
+     *   ↓ User receives funds on destination chain (e.g., 999.9 USDC)
+     * ```
      *
      * @param customFeePolicy - The custom fee policy to set.
-     * @throws {ValidationError} If the custom fee policy is invalid or missing required functions
+     * @throws {KitError} If the custom fee policy is invalid or missing required functions
      *
      * @example
      * ```typescript
      * import { BridgeKit } from '@circle-fin/bridge-kit'
-     * import { Blockchain } from '@core/chains'
      *
      * const kit = new BridgeKit()
      *
      * kit.setCustomFeePolicy({
-     *   calculateFee: (params) => {
-     *     // Return decimal string - kit converts to smallest units automatically
-     *     // '0.1' becomes '100000' (0.1 USDC with 6 decimals)
-     *     return params.source.chain.chain === Blockchain.Ethereum_Sepolia
-     *       ? '0.1'  // 0.1 USDC
-     *       : '0.2'; // 0.2 USDC
+     *   // computeFee receives human-readable amounts (e.g., '100' for 100 USDC)
+     *   computeFee: (params) => {
+     *     const amount = parseFloat(params.amount)
+     *
+     *     // 1% fee, bounded to 5-50 USDC
+     *     const fee = Math.min(Math.max(amount * 0.01, 5), 50)
+     *     return fee.toFixed(6)
      *   },
-     *   resolveFeeRecipientAddress: (feePayoutChain, params) => {
-     *     // Return valid address for the source chain
-     *     return params.source.chain.chain === Blockchain.Ethereum_Sepolia
-     *       ? '0x23f9a5BEA7B92a0638520607407BC7f0310aEeD4'
-     *       : '0x1E1A18B7bD95bcFcFb4d6E245D289C1e95547b35';
+     *   resolveFeeRecipientAddress: (feePayoutChain) => {
+     *     return feePayoutChain.type === 'solana'
+     *       ? '9xQeWvG816bUx9EP9MnZ4buHh3A6E2dFQa4Xz6V7C7Gn'
+     *       : '0x23f9a5BEA7B92a0638520607407BC7f0310aEeD4'
      *   },
-     * });
+     * })
+     *
+     * // 100 USDC transfer + 5 USDC custom fee results:
+     * // - Wallet signs for 105 USDC total.
+     * // - Circle receives 0.5 USDC (10% share of the custom fee).
+     * // - Your recipientAddress wallet receives 4.5 USDC.
+     * // - CCTPv2 processes 100 USDC and later deducts its own protocol fee.
      * ```
      */
     setCustomFeePolicy(customFeePolicy: CustomFeePolicy): void;
@@ -4197,6 +4490,233 @@ declare class KitError extends Error implements ErrorDetails {
     constructor(details: ErrorDetails);
 }
 
+/**
+ * Standardized error code ranges for consistent categorization:
+ *
+ * - 1000-1999: INPUT errors - Parameter validation, input format errors
+ * - 3000-3999: NETWORK errors - Internet connectivity, DNS, connection issues
+ * - 4000-4999: RPC errors - Blockchain provider issues, gas estimation, nonce errors
+ * - 5000-5999: ONCHAIN errors - Transaction/simulation failures, gas exhaustion, reverts
+ * - 9000-9999: BALANCE errors - Insufficient funds, token balance, allowance
+ */
+/**
+ * Standardized error definitions for INPUT type errors.
+ *
+ * Each entry combines the numeric error code, string name, and type
+ * to ensure consistency when creating error instances.
+ *
+ * Error codes follow a hierarchical numbering scheme where the first digit
+ * indicates the error category (1 = INPUT) and subsequent digits provide
+ * specific error identification within that category.
+ *
+ *
+ * @example
+ * ```typescript
+ * import { InputError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...InputError.NETWORK_MISMATCH,
+ *   recoverability: 'FATAL',
+ *   message: 'Source and destination networks must be different'
+ * })
+ *
+ * // Access code, name, and type individually if needed
+ * console.log(InputError.NETWORK_MISMATCH.code)  // 1001
+ * console.log(InputError.NETWORK_MISMATCH.name)  // 'INPUT_NETWORK_MISMATCH'
+ * console.log(InputError.NETWORK_MISMATCH.type)  // 'INPUT'
+ * ```
+ */
+declare const InputError: {
+    /** Network type mismatch between chains (mainnet vs testnet) */
+    readonly NETWORK_MISMATCH: {
+        readonly code: 1001;
+        readonly name: "INPUT_NETWORK_MISMATCH";
+        readonly type: ErrorType;
+    };
+    /** Invalid amount format or value (negative, zero, or malformed) */
+    readonly INVALID_AMOUNT: {
+        readonly code: 1002;
+        readonly name: "INPUT_INVALID_AMOUNT";
+        readonly type: ErrorType;
+    };
+    /** Unsupported or invalid bridge route configuration */
+    readonly UNSUPPORTED_ROUTE: {
+        readonly code: 1003;
+        readonly name: "INPUT_UNSUPPORTED_ROUTE";
+        readonly type: ErrorType;
+    };
+    /** Invalid wallet or contract address format */
+    readonly INVALID_ADDRESS: {
+        readonly code: 1004;
+        readonly name: "INPUT_INVALID_ADDRESS";
+        readonly type: ErrorType;
+    };
+    /** Invalid or unsupported chain identifier */
+    readonly INVALID_CHAIN: {
+        readonly code: 1005;
+        readonly name: "INPUT_INVALID_CHAIN";
+        readonly type: ErrorType;
+    };
+    /** General validation failure for complex validation rules */
+    readonly VALIDATION_FAILED: {
+        readonly code: 1098;
+        readonly name: "INPUT_VALIDATION_FAILED";
+        readonly type: ErrorType;
+    };
+};
+/**
+ * Standardized error definitions for BALANCE type errors.
+ *
+ * BALANCE errors indicate insufficient funds or allowance issues
+ * that prevent transaction execution.
+ *
+ * @example
+ * ```typescript
+ * import { BalanceError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...BalanceError.INSUFFICIENT_TOKEN,
+ *   recoverability: 'FATAL',
+ *   message: 'Insufficient USDC balance on Ethereum',
+ *   cause: { trace: { required: '100', available: '50' } }
+ * })
+ * ```
+ */
+declare const BalanceError: {
+    /** Insufficient token balance for transaction */
+    readonly INSUFFICIENT_TOKEN: {
+        readonly code: 9001;
+        readonly name: "BALANCE_INSUFFICIENT_TOKEN";
+        readonly type: ErrorType;
+    };
+    /** Insufficient native token (ETH/SOL/etc) for gas fees */
+    readonly INSUFFICIENT_GAS: {
+        readonly code: 9002;
+        readonly name: "BALANCE_INSUFFICIENT_GAS";
+        readonly type: ErrorType;
+    };
+    /** Insufficient allowance for token transfer */
+    readonly INSUFFICIENT_ALLOWANCE: {
+        readonly code: 9003;
+        readonly name: "BALANCE_INSUFFICIENT_ALLOWANCE";
+        readonly type: ErrorType;
+    };
+};
+/**
+ * Standardized error definitions for ONCHAIN type errors.
+ *
+ * ONCHAIN errors occur during transaction execution, simulation,
+ * or interaction with smart contracts on the blockchain.
+ *
+ * @example
+ * ```typescript
+ * import { OnchainError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...OnchainError.SIMULATION_FAILED,
+ *   recoverability: 'FATAL',
+ *   message: 'Simulation failed: ERC20 transfer amount exceeds balance',
+ *   cause: { trace: { reason: 'ERC20: transfer amount exceeds balance' } }
+ * })
+ * ```
+ */
+declare const OnchainError: {
+    /** Transaction reverted on-chain after execution */
+    readonly TRANSACTION_REVERTED: {
+        readonly code: 5001;
+        readonly name: "ONCHAIN_TRANSACTION_REVERTED";
+        readonly type: ErrorType;
+    };
+    /** Pre-flight transaction simulation failed */
+    readonly SIMULATION_FAILED: {
+        readonly code: 5002;
+        readonly name: "ONCHAIN_SIMULATION_FAILED";
+        readonly type: ErrorType;
+    };
+    /** Transaction ran out of gas during execution */
+    readonly OUT_OF_GAS: {
+        readonly code: 5003;
+        readonly name: "ONCHAIN_OUT_OF_GAS";
+        readonly type: ErrorType;
+    };
+    /** Transaction exceeds block gas limit */
+    readonly GAS_LIMIT_EXCEEDED: {
+        readonly code: 5004;
+        readonly name: "ONCHAIN_GAS_LIMIT_EXCEEDED";
+        readonly type: ErrorType;
+    };
+};
+/**
+ * Standardized error definitions for RPC type errors.
+ *
+ * RPC errors occur when communicating with blockchain RPC providers,
+ * including endpoint failures, invalid responses, and provider-specific issues.
+ *
+ * @example
+ * ```typescript
+ * import { RpcError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...RpcError.ENDPOINT_ERROR,
+ *   recoverability: 'RETRYABLE',
+ *   message: 'RPC endpoint unavailable on Ethereum',
+ *   cause: { trace: { endpoint: 'https://mainnet.infura.io' } }
+ * })
+ * ```
+ */
+declare const RpcError: {
+    /** RPC endpoint returned error or is unavailable */
+    readonly ENDPOINT_ERROR: {
+        readonly code: 4001;
+        readonly name: "RPC_ENDPOINT_ERROR";
+        readonly type: ErrorType;
+    };
+    /** Invalid or unexpected RPC response format */
+    readonly INVALID_RESPONSE: {
+        readonly code: 4002;
+        readonly name: "RPC_INVALID_RESPONSE";
+        readonly type: ErrorType;
+    };
+    /** Nonce-related errors from RPC provider */
+    readonly NONCE_ERROR: {
+        readonly code: 4003;
+        readonly name: "RPC_NONCE_ERROR";
+        readonly type: ErrorType;
+    };
+};
+/**
+ * Standardized error definitions for NETWORK type errors.
+ *
+ * NETWORK errors indicate connectivity issues at the network layer,
+ * including DNS failures, connection timeouts, and unreachable endpoints.
+ *
+ * @example
+ * ```typescript
+ * import { NetworkError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...NetworkError.CONNECTION_FAILED,
+ *   recoverability: 'RETRYABLE',
+ *   message: 'Failed to connect to Ethereum network',
+ *   cause: { trace: { error: 'ECONNREFUSED' } }
+ * })
+ * ```
+ */
+declare const NetworkError: {
+    /** Network connection failed or unreachable */
+    readonly CONNECTION_FAILED: {
+        readonly code: 3001;
+        readonly name: "NETWORK_CONNECTION_FAILED";
+        readonly type: ErrorType;
+    };
+    /** Network request timeout */
+    readonly TIMEOUT: {
+        readonly code: 3002;
+        readonly name: "NETWORK_TIMEOUT";
+        readonly type: ErrorType;
+    };
+};
+
 /**
  * Type guard to check if an error is a KitError instance.
  *
@@ -4299,6 +4819,106 @@ declare function isRetryableError(error: unknown): boolean;
  * ```
  */
 declare function isInputError(error: unknown): error is KitError;
+/**
+ * Type guard to check if error is KitError with BALANCE type.
+ *
+ * BALANCE errors indicate insufficient funds or allowance issues
+ * that prevent transaction execution. These errors are always FATAL
+ * and require the user to add funds or approve more tokens.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with BALANCE type
+ *
+ * @example
+ * ```typescript
+ * import { isBalanceError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isBalanceError(error)) {
+ *     console.log('Insufficient funds:', error.message)
+ *     showAddFundsUI()
+ *   }
+ * }
+ * ```
+ */
+declare function isBalanceError(error: unknown): error is KitError;
+/**
+ * Type guard to check if error is KitError with ONCHAIN type.
+ *
+ * ONCHAIN errors occur during transaction execution or simulation,
+ * including reverts, gas issues, and smart contract failures.
+ * These errors are typically FATAL.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with ONCHAIN type
+ *
+ * @example
+ * ```typescript
+ * import { isOnchainError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isOnchainError(error)) {
+ *     console.log('Transaction failed:', error.message)
+ *     showTransactionErrorUI()
+ *   }
+ * }
+ * ```
+ */
+declare function isOnchainError(error: unknown): error is KitError;
+/**
+ * Type guard to check if error is KitError with RPC type.
+ *
+ * RPC errors occur when communicating with blockchain RPC providers.
+ * These errors are typically RETRYABLE as they often indicate
+ * temporary provider issues.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with RPC type
+ *
+ * @example
+ * ```typescript
+ * import { isRpcError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isRpcError(error)) {
+ *     console.log('RPC error:', error.message)
+ *     retryWithBackoff()
+ *   }
+ * }
+ * ```
+ */
+declare function isRpcError(error: unknown): error is KitError;
+/**
+ * Type guard to check if error is KitError with NETWORK type.
+ *
+ * NETWORK errors indicate connectivity issues at the network layer.
+ * These errors are typically RETRYABLE as they often indicate
+ * temporary network problems.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with NETWORK type
+ *
+ * @example
+ * ```typescript
+ * import { isNetworkError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isNetworkError(error)) {
+ *     console.log('Network issue:', error.message)
+ *     retryWithBackoff()
+ *   }
+ * }
+ * ```
+ */
+declare function isNetworkError(error: unknown): error is KitError;
 /**
  * Safely extracts error message from any error type.
  *
@@ -4350,5 +4970,5 @@ declare function getErrorMessage(error: unknown): string;
  */
 declare function getErrorCode(error: unknown): number | null;
 
-export { Blockchain, BridgeKit, KitError, TransferSpeed, bridgeParamsWithChainIdentifierSchema, getErrorCode, getErrorMessage, isFatalError, isInputError, isKitError, isRetryableError, setExternalPrefix };
-export type { ActionHandler, AdapterContext, BridgeConfig, BridgeKitConfig, BridgeParams, BridgeResult, ChainDefinition, ChainIdentifier, CustomFeePolicy, ErrorDetails, EstimateResult, Recoverability };
+export { BalanceError, Blockchain, BridgeChain, BridgeKit, InputError, KitError, NetworkError, OnchainError, RpcError, TransferSpeed, bridgeParamsWithChainIdentifierSchema, getErrorCode, getErrorMessage, isBalanceError, isFatalError, isInputError, isKitError, isNetworkError, isOnchainError, isRetryableError, isRpcError, resolveChainIdentifier, setExternalPrefix };
+export type { ActionHandler, AdapterContext, BaseChainDefinition, BridgeChainIdentifier, BridgeConfig, BridgeKitConfig, BridgeParams, BridgeResult, CCTPConfig, CCTPContracts, CCTPMergedConfig, CCTPSplitConfig, ChainDefinition, ChainIdentifier, Currency, CustomFeePolicy, EVMChainDefinition, ErrorDetails, EstimateResult, EstimatedGas, KitContractType, KitContracts, NonEVMChainDefinition, Recoverability, RetryContext, VersionConfig };