@circle-fin/bridge-kit 1.1.1 → 1.2.0

package/index.d.ts

@@ -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.
@@ -1179,6 +1322,14 @@ interface CCTPv2ActionMap {
          * the adapter's default address.
          */
         readonly destinationAddress?: string;
+        /**
+         * The mint recipient address from the decoded CCTP message.
+         *
+         * This is the actual address encoded in the burn message where tokens will be minted.
+         * For Solana, this is already the Associated Token Account (ATA) address, not the owner.
+         * For EVM chains, this is the recipient's wallet address.
+         */
+        readonly mintRecipient?: string;
     };
     /**
      * Initiate a cross-chain USDC transfer using a custom bridge contract with preapproval funnel.
@@ -1870,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
@@ -2120,10 +2270,10 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * This address is used as the default sender for transactions
      * and interactions initiated by this adapter.
      *
-     * @param chain - Optional chain definition for chain-specific address resolution (used by EVM adapters)
+     * @param chain - The chain to use for address resolution.
      * @returns A promise that resolves to the blockchain address as a string.
      */
-    abstract getAddress(chain?: ChainDefinition): Promise<string>;
+    abstract getAddress(chain: ChainDefinition): Promise<string>;
     /**
      * Switches the adapter to operate on the specified chain.
      *
@@ -2194,7 +2344,7 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * Validate that the target chain is supported by this adapter.
      *
      * @param targetChain - The chain to validate.
-     * @throws Error if the chain is not supported.
+     * @throws KitError with INVALID_CHAIN code if the chain is not supported by this adapter.
      */
     validateChainSupport(targetChain: ChainDefinition): void;
     /**
@@ -2583,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[];
@@ -2672,6 +2830,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;
 }
@@ -2714,6 +2906,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.
@@ -2736,6 +2932,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
@@ -2754,11 +2951,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.
@@ -2769,6 +2966,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
@@ -2789,7 +2987,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.
      *
@@ -2801,8 +2999,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.
  *
@@ -2945,7 +3146,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
      *
@@ -2970,7 +3171,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
@@ -3096,44 +3297,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.
-     *
-     * For example: if you want to charge 1 USDC, you would return `'1000000'`.
+     * 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.
      *
-     * 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.
@@ -3142,18 +3361,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.
  *
@@ -3165,46 +3393,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;
     /**
@@ -3242,8 +3493,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'
@@ -3402,18 +3654,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({
@@ -3534,18 +3786,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,
      * })
      *
@@ -3604,10 +3856,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',
@@ -3643,7 +3899,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
@@ -3728,40 +3984,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.
      *
-     * 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.
+     * 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.
      *
-     * 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.
+     * Use `computeFee` (recommended) for human-readable amounts, or `calculateFee`
+     * (deprecated) for smallest-unit amounts. Only one should be provided.
+     *
+     * ```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;
@@ -4061,6 +4338,15 @@ declare const RECOVERABILITY_VALUES: readonly ["RETRYABLE", "RESUMABLE", "FATAL"
  * - RESUMABLE errors are returned when a flow fails mid-execution but can be continued
  */
 type Recoverability = (typeof RECOVERABILITY_VALUES)[number];
+/**
+ * Array of valid error type values for validation.
+ * Derived from ERROR_TYPES const object.
+ */
+declare const ERROR_TYPE_VALUES: ("INPUT" | "BALANCE" | "ONCHAIN" | "RPC" | "NETWORK")[];
+/**
+ * Error type indicating the category of the error.
+ */
+type ErrorType = (typeof ERROR_TYPE_VALUES)[number];
 /**
  * Structured error details with consistent properties for programmatic handling.
  *
@@ -4072,7 +4358,8 @@ type Recoverability = (typeof RECOVERABILITY_VALUES)[number];
  * ```typescript
  * const error: ErrorDetails = {
  *   code: 1001,
- *   name: "NETWORK_MISMATCH",
+ *   name: "INPUT_NETWORK_MISMATCH",
+ *   type: "INPUT",
  *   recoverability: "FATAL",
  *   message: "Source and destination networks must be different",
  *   cause: {
@@ -4080,15 +4367,31 @@ type Recoverability = (typeof RECOVERABILITY_VALUES)[number];
  *   }
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * const error: ErrorDetails = {
+ *   code: 9001,
+ *   name: "BALANCE_INSUFFICIENT_TOKEN",
+ *   type: "BALANCE",
+ *   recoverability: "FATAL",
+ *   message: "Insufficient USDC balance on Ethereum",
+ *   cause: {
+ *     trace: { token: "USDC", chain: "Ethereum" }
+ *   }
+ * }
+ * ```
  */
 interface ErrorDetails {
-    /** Numeric identifier following standardized ranges (1000+ for INPUT errors) */
+    /** Numeric identifier following standardized ranges (see error code registry) */
     code: number;
-    /** Human-readable ID (e.g., "NETWORK_MISMATCH") */
+    /** Human-readable ID (e.g., "INPUT_NETWORK_MISMATCH", "BALANCE_INSUFFICIENT_TOKEN") */
     name: string;
+    /** Error category indicating where the error originated */
+    type: ErrorType;
     /** Error handling strategy */
     recoverability: Recoverability;
-    /** User-friendly explanation with network context */
+    /** User-friendly explanation with context */
     message: string;
     /** Raw error details, context, or the original error that caused this one. */
     cause?: {
@@ -4145,6 +4448,8 @@ declare class KitError extends Error implements ErrorDetails {
     readonly code: number;
     /** Human-readable ID (e.g., "NETWORK_MISMATCH") */
     readonly name: string;
+    /** Error category indicating where the error originated */
+    readonly type: ErrorType;
     /** Error handling strategy */
     readonly recoverability: Recoverability;
     /** Raw error details, context, or the original error that caused this one. */
@@ -4239,31 +4544,25 @@ declare function isFatalError(error: unknown): boolean;
  */
 declare function isRetryableError(error: unknown): boolean;
 /**
- * Combined type guard to check if error is KitError with INPUT type.
+ * Type guard to check if error is KitError with INPUT type.
  *
- * INPUT errors have error codes in the 1000-1099 range and represent
- * validation failures, invalid parameters, or user input problems.
- * These errors are always FATAL and require the user to correct their
- * input before retrying.
+ * INPUT errors represent validation failures, invalid parameters,
+ * or user input problems. These errors are always FATAL and require
+ * the user to correct their input before retrying.
  *
  * @param error - Unknown error to check
- * @returns True if error is KitError with INPUT error code range
+ * @returns True if error is KitError with INPUT type
  *
  * @example
  * ```typescript
  * import { isInputError } from '@core/errors'
- * import { createBridgeKit } from '@core/bridge'
  *
- * async function handleBridge() {
- *   const kit = createBridgeKit(config)
- *   const params = { amount: '100', from: 'ethereum', to: 'polygon' }
- *
- *   try {
- *     await kit.bridge(params)
- *   } catch (error) {
- *     if (isInputError(error)) {
- *       console.log(`Input error: ${error.message} (code: ${error.code})`)
- *     }
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isInputError(error)) {
+ *     console.log('Validation error:', error.message)
+ *     showValidationUI()
  *   }
  * }
  * ```
@@ -4320,5 +4619,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, Recoverability };
+export { Blockchain, BridgeChain, BridgeKit, KitError, TransferSpeed, bridgeParamsWithChainIdentifierSchema, getErrorCode, getErrorMessage, isFatalError, isInputError, isKitError, isRetryableError, resolveChainIdentifier, setExternalPrefix };
+export type { ActionHandler, AdapterContext, BridgeChainIdentifier, BridgeConfig, BridgeKitConfig, BridgeParams, BridgeResult, ChainDefinition, ChainIdentifier, CustomFeePolicy, ErrorDetails, EstimateResult, Recoverability };