@circle-fin/bridge-kit 1.1.1 → 1.1.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @circle-fin/bridge-kit
 
+## 1.1.2
+
+### Patch Changes
+
+- Fixed bug where tokens could be burned when bridging to unsupported chains, and improved error messages to clearly show which chains are supported.
+
+  **What's Fixed:**
+  - **Prevents fund loss**: Bridge operations now fail immediately if your adapter doesn't support the source or destination chain, **before** any tokens are approved or burned. Previously, tokens could be burned on the source chain before discovering the destination chain was unsupported, requiring manual recovery.
+  - **Better error messages**: When you attempt to use an unsupported chain, the error now clearly lists all chains your adapter supports, making it easy to pick an alternative:
+    ```
+    Invalid chain 'Linea Sepolia': Not supported by this adapter.
+    It supports 17 chains: Arbitrum, Base, Ethereum, Polygon, Solana, ...
+    ```
+  - **Correct error codes**: Chain validation errors now use the correct `INVALID_CHAIN` error code instead of `UNSUPPORTED_ROUTE`, making it easier to handle errors programmatically.
+
 ## 1.1.1
 
 ### Patch Changes

package/index.cjs

@@ -2741,7 +2741,7 @@ class Actionable {
 }
 
 var name = "@circle-fin/bridge-kit";
-var version = "1.1.1";
+var version = "1.1.2";
 var pkg = {
 	name: name,
 	version: version};
@@ -2758,9 +2758,71 @@ const RECOVERABILITY_VALUES = [
     'RESUMABLE',
     'FATAL',
 ];
+/**
+ * Error type constants for categorizing errors by origin.
+ *
+ * This const object provides a reference for error types, enabling
+ * IDE autocomplete and preventing typos when creating custom errors.
+ *
+ * @remarks
+ * While internal error definitions use string literals with type annotations
+ * for strict type safety, this constant is useful for developers creating
+ * custom error instances or checking error types programmatically.
+ *
+ * @example
+ * ```typescript
+ * import { ERROR_TYPES, KitError } from '@core/errors'
+ *
+ * // Use for type checking
+ * if (error.type === ERROR_TYPES.BALANCE) {
+ *   console.log('This is a balance error')
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use as reference when creating custom errors
+ * const error = new KitError({
+ *   code: 9999,
+ *   name: 'CUSTOM_ERROR',
+ *   type: ERROR_TYPES.BALANCE,  // IDE autocomplete works here
+ *   recoverability: 'FATAL',
+ *   message: 'Custom balance error'
+ * })
+ * ```
+ */
+const ERROR_TYPES = {
+    /** User input validation and parameter checking */
+    INPUT: 'INPUT',
+    /** Insufficient token balances and amount validation */
+    BALANCE: 'BALANCE',
+    /** On-chain execution: reverts, gas issues, transaction failures */
+    ONCHAIN: 'ONCHAIN',
+    /** Blockchain RPC provider issues and endpoint problems */
+    RPC: 'RPC',
+    /** Internet connectivity, DNS resolution, connection issues */
+    NETWORK: 'NETWORK',
+};
+/**
+ * Array of valid error type values for validation.
+ * Derived from ERROR_TYPES const object.
+ */
+const ERROR_TYPE_VALUES = Object.values(ERROR_TYPES);
 
-// Create a mutable array for Zod enum validation
+// Create mutable arrays for Zod enum validation
 const RECOVERABILITY_ARRAY = [...RECOVERABILITY_VALUES];
+const ERROR_TYPE_ARRAY = [...ERROR_TYPE_VALUES];
+/**
+ * Error code ranges for validation.
+ * Single source of truth for valid error code ranges.
+ */
+const ERROR_CODE_RANGES = [
+    { min: 1000, max: 1999, type: 'INPUT' },
+    { min: 3000, max: 3999, type: 'NETWORK' },
+    { min: 4000, max: 4999, type: 'RPC' },
+    { min: 5000, max: 5999, type: 'ONCHAIN' },
+    { min: 9000, max: 9999, type: 'BALANCE' },
+];
 /**
  * Zod schema for validating ErrorDetails objects.
  *
@@ -2773,7 +2835,8 @@ const RECOVERABILITY_ARRAY = [...RECOVERABILITY_VALUES];
  *
  * const result = errorDetailsSchema.safeParse({
  *   code: 1001,
- *   name: 'NETWORK_MISMATCH',
+ *   name: 'INPUT_NETWORK_MISMATCH',
+ *   type: 'INPUT',
  *   recoverability: 'FATAL',
  *   message: 'Source and destination networks must be different'
  * })
@@ -2782,30 +2845,56 @@ const RECOVERABILITY_ARRAY = [...RECOVERABILITY_VALUES];
  *   console.error('Validation failed:', result.error.issues)
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Runtime error
+ * const result = errorDetailsSchema.safeParse({
+ *   code: 9001,
+ *   name: 'BALANCE_INSUFFICIENT_TOKEN',
+ *   type: 'BALANCE',
+ *   recoverability: 'FATAL',
+ *   message: 'Insufficient USDC balance'
+ * })
+ * ```
  */
 const errorDetailsSchema = zod.z.object({
-    /** Numeric identifier following standardized ranges (1000+ for INPUT errors) */
+    /**
+     * Numeric identifier following standardized ranges:
+     * - 1000-1999: INPUT errors - Parameter validation
+     * - 3000-3999: NETWORK errors - Connectivity issues
+     * - 4000-4999: RPC errors - Provider issues, gas estimation
+     * - 5000-5999: ONCHAIN errors - Transaction/simulation failures
+     * - 9000-9999: BALANCE errors - Insufficient funds
+     */
     code: zod.z
         .number()
         .int('Error code must be an integer')
-        .min(1000, 'Error code must be within valid range (1000+)')
-        .max(1099, 'Error code must be within valid range (1099 max)'),
-    /** Human-readable ID (e.g., "NETWORK_MISMATCH") */
+        .refine((code) => ERROR_CODE_RANGES.some((range) => code >= range.min && code <= range.max), {
+        message: 'Error code must be in valid ranges: 1000-1999 (INPUT), 3000-3999 (NETWORK), 4000-4999 (RPC), 5000-5999 (ONCHAIN), 9000-9999 (BALANCE)',
+    }),
+    /** Human-readable ID (e.g., "INPUT_NETWORK_MISMATCH", "BALANCE_INSUFFICIENT_TOKEN") */
     name: zod.z
         .string()
         .min(1, 'Error name must be a non-empty string')
         .regex(/^[A-Z_][A-Z0-9_]*$/, 'Error name must match pattern: ^[A-Z_][A-Z0-9_]*$'),
+    /** Error category indicating where the error originated */
+    type: zod.z.enum(ERROR_TYPE_ARRAY, {
+        errorMap: () => ({
+            message: 'Error type must be one of: INPUT, BALANCE, ONCHAIN, RPC, NETWORK',
+        }),
+    }),
     /** Error handling strategy */
     recoverability: zod.z.enum(RECOVERABILITY_ARRAY, {
         errorMap: () => ({
             message: 'Recoverability must be one of: RETRYABLE, RESUMABLE, FATAL',
         }),
     }),
-    /** User-friendly explanation with network context */
+    /** User-friendly explanation with context */
     message: zod.z
         .string()
         .min(1, 'Error message must be a non-empty string')
-        .max(500, 'Error message must be 500 characters or less'),
+        .max(1000, 'Error message must be 1000 characters or less'),
     /** Raw error details, context, or the original error that caused this one. */
     cause: zod.z
         .object({
@@ -2820,7 +2909,7 @@ const errorDetailsSchema = zod.z.object({
  *
  * @param details - The object to validate
  * @returns The validated ErrorDetails object
- * @throws {TypeError} When validation fails
+ * @throws TypeError When validation fails
  *
  * @example
  * ```typescript
@@ -2897,6 +2986,8 @@ class KitError extends Error {
     code;
     /** Human-readable ID (e.g., "NETWORK_MISMATCH") */
     name;
+    /** Error category indicating where the error originated */
+    type;
     /** Error handling strategy */
     recoverability;
     /** Raw error details, context, or the original error that caused this one. */
@@ -2925,6 +3016,12 @@ class KitError extends Error {
                 enumerable: true,
                 configurable: false,
             },
+            type: {
+                value: validatedDetails.type,
+                writable: false,
+                enumerable: true,
+                configurable: false,
+            },
             recoverability: {
                 value: validatedDetails.recoverability,
                 writable: false,
@@ -2944,20 +3041,19 @@ class KitError extends Error {
 }
 
 /**
- * Minimum error code for INPUT type errors.
- * INPUT errors represent validation failures and invalid parameters.
- */
-const INPUT_ERROR_CODE_MIN = 1000;
-/**
- * Maximum error code for INPUT type errors (exclusive).
- * INPUT error codes range from 1000 to 1099 inclusive.
+ * 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
  */
-const INPUT_ERROR_CODE_MAX = 1100;
 /**
  * Standardized error definitions for INPUT type errors.
  *
- * Each entry combines the numeric error code with its corresponding
- * string name to ensure consistency when creating error instances.
+ * 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
@@ -2974,9 +3070,10 @@ const INPUT_ERROR_CODE_MAX = 1100;
  *   message: 'Source and destination networks must be different'
  * })
  *
- * // Access code and name individually if needed
+ * // 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'
  * ```
  */
 const InputError = {
@@ -2984,31 +3081,37 @@ const InputError = {
     NETWORK_MISMATCH: {
         code: 1001,
         name: 'INPUT_NETWORK_MISMATCH',
+        type: 'INPUT',
     },
     /** Invalid amount format or value (negative, zero, or malformed) */
     INVALID_AMOUNT: {
         code: 1002,
         name: 'INPUT_INVALID_AMOUNT',
+        type: 'INPUT',
     },
     /** Unsupported or invalid bridge route configuration */
     UNSUPPORTED_ROUTE: {
         code: 1003,
         name: 'INPUT_UNSUPPORTED_ROUTE',
+        type: 'INPUT',
     },
     /** Invalid wallet or contract address format */
     INVALID_ADDRESS: {
         code: 1004,
         name: 'INPUT_INVALID_ADDRESS',
+        type: 'INPUT',
     },
     /** Invalid or unsupported chain identifier */
     INVALID_CHAIN: {
         code: 1005,
         name: 'INPUT_INVALID_CHAIN',
+        type: 'INPUT',
     },
     /** General validation failure for complex validation rules */
     VALIDATION_FAILED: {
         code: 1098,
         name: 'INPUT_VALIDATION_FAILED',
+        type: 'INPUT',
     },
 };
 
@@ -3254,39 +3357,31 @@ function isRetryableError(error) {
     return isKitError(error) && error.recoverability === 'RETRYABLE';
 }
 /**
- * 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()
  *   }
  * }
  * ```
  */
 function isInputError(error) {
-    return (isKitError(error) &&
-        error.code >= INPUT_ERROR_CODE_MIN &&
-        error.code < INPUT_ERROR_CODE_MAX);
+    return isKitError(error) && error.type === ERROR_TYPES.INPUT;
 }
 /**
  * Safely extracts error message from any error type.
@@ -3572,8 +3667,8 @@ function getChainFromParams(params) {
 /**
  * Maximum length for error messages in fallback validation errors.
  *
- * KitError enforces a 500-character limit on error messages. When creating
- * fallback validation errors that combine multiple Zod issues, we use 450
+ * KitError enforces a 1000-character limit on error messages. When creating
+ * fallback validation errors that combine multiple Zod issues, we use 950
  * characters to leave a 50-character buffer for:
  * - The error message prefix ("Invalid bridge parameters: ")
  * - Potential encoding differences or formatting overhead
@@ -3582,7 +3677,7 @@ function getChainFromParams(params) {
  * This ensures that even with concatenated issue summaries, the final message
  * stays within KitError's constraints.
  */
-const MAX_MESSAGE_LENGTH = 450;
+const MAX_MESSAGE_LENGTH = 950;
 
 /**
  * Converts a Zod validation error into a specific KitError instance using structured pattern matching.
@@ -4716,6 +4811,10 @@ function resolveConfig(params) {
 async function resolveBridgeParams(params) {
     const fromChain = resolveChainDefinition(params.from);
     const toChain = resolveChainDefinition(params.to);
+    // Validate adapter chain support after resolution
+    // This ensures adapters support the resolved chains before proceeding
+    params.from.adapter.validateChainSupport(fromChain);
+    params.to.adapter.validateChainSupport(toChain);
     const [fromAddress, toAddress] = await Promise.all([
         resolveAddress(params.from),
         resolveAddress(params.to),
@@ -4893,7 +4992,7 @@ class BridgeKit {
     async bridge(params) {
         // First validate the parameters
         assertBridgeParams(params, bridgeParamsWithChainIdentifierSchema);
-        // Then resolve chain definitions
+        // Then resolve chain definitions (includes adapter chain support validation)
         const resolvedParams = await resolveBridgeParams(params);
         // Validate network compatibility
         this.validateNetworkCompatibility(resolvedParams);
@@ -4997,7 +5096,7 @@ class BridgeKit {
     async estimate(params) {
         // First validate the parameters
         assertBridgeParams(params, bridgeParamsWithChainIdentifierSchema);
-        // Then resolve chain definitions
+        // Then resolve chain definitions (includes adapter chain support validation)
         const resolvedParams = await resolveBridgeParams(params);
         // Validate network compatibility
         this.validateNetworkCompatibility(resolvedParams);

package/index.d.ts

@@ -1179,6 +1179,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.
@@ -2120,10 +2128,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 +2202,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;
     /**
@@ -4061,6 +4069,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 +4089,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 +4098,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 +4179,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 +4275,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()
  *   }
  * }
  * ```
@@ -4321,4 +4351,4 @@ 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 type { ActionHandler, AdapterContext, BridgeConfig, BridgeKitConfig, BridgeParams, BridgeResult, ChainDefinition, ChainIdentifier, CustomFeePolicy, ErrorDetails, EstimateResult, Recoverability };

package/index.mjs

@@ -2739,7 +2739,7 @@ class Actionable {
 }
 
 var name = "@circle-fin/bridge-kit";
-var version = "1.1.1";
+var version = "1.1.2";
 var pkg = {
 	name: name,
 	version: version};
@@ -2756,9 +2756,71 @@ const RECOVERABILITY_VALUES = [
     'RESUMABLE',
     'FATAL',
 ];
+/**
+ * Error type constants for categorizing errors by origin.
+ *
+ * This const object provides a reference for error types, enabling
+ * IDE autocomplete and preventing typos when creating custom errors.
+ *
+ * @remarks
+ * While internal error definitions use string literals with type annotations
+ * for strict type safety, this constant is useful for developers creating
+ * custom error instances or checking error types programmatically.
+ *
+ * @example
+ * ```typescript
+ * import { ERROR_TYPES, KitError } from '@core/errors'
+ *
+ * // Use for type checking
+ * if (error.type === ERROR_TYPES.BALANCE) {
+ *   console.log('This is a balance error')
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use as reference when creating custom errors
+ * const error = new KitError({
+ *   code: 9999,
+ *   name: 'CUSTOM_ERROR',
+ *   type: ERROR_TYPES.BALANCE,  // IDE autocomplete works here
+ *   recoverability: 'FATAL',
+ *   message: 'Custom balance error'
+ * })
+ * ```
+ */
+const ERROR_TYPES = {
+    /** User input validation and parameter checking */
+    INPUT: 'INPUT',
+    /** Insufficient token balances and amount validation */
+    BALANCE: 'BALANCE',
+    /** On-chain execution: reverts, gas issues, transaction failures */
+    ONCHAIN: 'ONCHAIN',
+    /** Blockchain RPC provider issues and endpoint problems */
+    RPC: 'RPC',
+    /** Internet connectivity, DNS resolution, connection issues */
+    NETWORK: 'NETWORK',
+};
+/**
+ * Array of valid error type values for validation.
+ * Derived from ERROR_TYPES const object.
+ */
+const ERROR_TYPE_VALUES = Object.values(ERROR_TYPES);
 
-// Create a mutable array for Zod enum validation
+// Create mutable arrays for Zod enum validation
 const RECOVERABILITY_ARRAY = [...RECOVERABILITY_VALUES];
+const ERROR_TYPE_ARRAY = [...ERROR_TYPE_VALUES];
+/**
+ * Error code ranges for validation.
+ * Single source of truth for valid error code ranges.
+ */
+const ERROR_CODE_RANGES = [
+    { min: 1000, max: 1999, type: 'INPUT' },
+    { min: 3000, max: 3999, type: 'NETWORK' },
+    { min: 4000, max: 4999, type: 'RPC' },
+    { min: 5000, max: 5999, type: 'ONCHAIN' },
+    { min: 9000, max: 9999, type: 'BALANCE' },
+];
 /**
  * Zod schema for validating ErrorDetails objects.
  *
@@ -2771,7 +2833,8 @@ const RECOVERABILITY_ARRAY = [...RECOVERABILITY_VALUES];
  *
  * const result = errorDetailsSchema.safeParse({
  *   code: 1001,
- *   name: 'NETWORK_MISMATCH',
+ *   name: 'INPUT_NETWORK_MISMATCH',
+ *   type: 'INPUT',
  *   recoverability: 'FATAL',
  *   message: 'Source and destination networks must be different'
  * })
@@ -2780,30 +2843,56 @@ const RECOVERABILITY_ARRAY = [...RECOVERABILITY_VALUES];
  *   console.error('Validation failed:', result.error.issues)
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Runtime error
+ * const result = errorDetailsSchema.safeParse({
+ *   code: 9001,
+ *   name: 'BALANCE_INSUFFICIENT_TOKEN',
+ *   type: 'BALANCE',
+ *   recoverability: 'FATAL',
+ *   message: 'Insufficient USDC balance'
+ * })
+ * ```
  */
 const errorDetailsSchema = z.object({
-    /** Numeric identifier following standardized ranges (1000+ for INPUT errors) */
+    /**
+     * Numeric identifier following standardized ranges:
+     * - 1000-1999: INPUT errors - Parameter validation
+     * - 3000-3999: NETWORK errors - Connectivity issues
+     * - 4000-4999: RPC errors - Provider issues, gas estimation
+     * - 5000-5999: ONCHAIN errors - Transaction/simulation failures
+     * - 9000-9999: BALANCE errors - Insufficient funds
+     */
     code: z
         .number()
         .int('Error code must be an integer')
-        .min(1000, 'Error code must be within valid range (1000+)')
-        .max(1099, 'Error code must be within valid range (1099 max)'),
-    /** Human-readable ID (e.g., "NETWORK_MISMATCH") */
+        .refine((code) => ERROR_CODE_RANGES.some((range) => code >= range.min && code <= range.max), {
+        message: 'Error code must be in valid ranges: 1000-1999 (INPUT), 3000-3999 (NETWORK), 4000-4999 (RPC), 5000-5999 (ONCHAIN), 9000-9999 (BALANCE)',
+    }),
+    /** Human-readable ID (e.g., "INPUT_NETWORK_MISMATCH", "BALANCE_INSUFFICIENT_TOKEN") */
     name: z
         .string()
         .min(1, 'Error name must be a non-empty string')
         .regex(/^[A-Z_][A-Z0-9_]*$/, 'Error name must match pattern: ^[A-Z_][A-Z0-9_]*$'),
+    /** Error category indicating where the error originated */
+    type: z.enum(ERROR_TYPE_ARRAY, {
+        errorMap: () => ({
+            message: 'Error type must be one of: INPUT, BALANCE, ONCHAIN, RPC, NETWORK',
+        }),
+    }),
     /** Error handling strategy */
     recoverability: z.enum(RECOVERABILITY_ARRAY, {
         errorMap: () => ({
             message: 'Recoverability must be one of: RETRYABLE, RESUMABLE, FATAL',
         }),
     }),
-    /** User-friendly explanation with network context */
+    /** User-friendly explanation with context */
     message: z
         .string()
         .min(1, 'Error message must be a non-empty string')
-        .max(500, 'Error message must be 500 characters or less'),
+        .max(1000, 'Error message must be 1000 characters or less'),
     /** Raw error details, context, or the original error that caused this one. */
     cause: z
         .object({
@@ -2818,7 +2907,7 @@ const errorDetailsSchema = z.object({
  *
  * @param details - The object to validate
  * @returns The validated ErrorDetails object
- * @throws {TypeError} When validation fails
+ * @throws TypeError When validation fails
  *
  * @example
  * ```typescript
@@ -2895,6 +2984,8 @@ class KitError extends Error {
     code;
     /** Human-readable ID (e.g., "NETWORK_MISMATCH") */
     name;
+    /** Error category indicating where the error originated */
+    type;
     /** Error handling strategy */
     recoverability;
     /** Raw error details, context, or the original error that caused this one. */
@@ -2923,6 +3014,12 @@ class KitError extends Error {
                 enumerable: true,
                 configurable: false,
             },
+            type: {
+                value: validatedDetails.type,
+                writable: false,
+                enumerable: true,
+                configurable: false,
+            },
             recoverability: {
                 value: validatedDetails.recoverability,
                 writable: false,
@@ -2942,20 +3039,19 @@ class KitError extends Error {
 }
 
 /**
- * Minimum error code for INPUT type errors.
- * INPUT errors represent validation failures and invalid parameters.
- */
-const INPUT_ERROR_CODE_MIN = 1000;
-/**
- * Maximum error code for INPUT type errors (exclusive).
- * INPUT error codes range from 1000 to 1099 inclusive.
+ * 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
  */
-const INPUT_ERROR_CODE_MAX = 1100;
 /**
  * Standardized error definitions for INPUT type errors.
  *
- * Each entry combines the numeric error code with its corresponding
- * string name to ensure consistency when creating error instances.
+ * 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
@@ -2972,9 +3068,10 @@ const INPUT_ERROR_CODE_MAX = 1100;
  *   message: 'Source and destination networks must be different'
  * })
  *
- * // Access code and name individually if needed
+ * // 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'
  * ```
  */
 const InputError = {
@@ -2982,31 +3079,37 @@ const InputError = {
     NETWORK_MISMATCH: {
         code: 1001,
         name: 'INPUT_NETWORK_MISMATCH',
+        type: 'INPUT',
     },
     /** Invalid amount format or value (negative, zero, or malformed) */
     INVALID_AMOUNT: {
         code: 1002,
         name: 'INPUT_INVALID_AMOUNT',
+        type: 'INPUT',
     },
     /** Unsupported or invalid bridge route configuration */
     UNSUPPORTED_ROUTE: {
         code: 1003,
         name: 'INPUT_UNSUPPORTED_ROUTE',
+        type: 'INPUT',
     },
     /** Invalid wallet or contract address format */
     INVALID_ADDRESS: {
         code: 1004,
         name: 'INPUT_INVALID_ADDRESS',
+        type: 'INPUT',
     },
     /** Invalid or unsupported chain identifier */
     INVALID_CHAIN: {
         code: 1005,
         name: 'INPUT_INVALID_CHAIN',
+        type: 'INPUT',
     },
     /** General validation failure for complex validation rules */
     VALIDATION_FAILED: {
         code: 1098,
         name: 'INPUT_VALIDATION_FAILED',
+        type: 'INPUT',
     },
 };
 
@@ -3252,39 +3355,31 @@ function isRetryableError(error) {
     return isKitError(error) && error.recoverability === 'RETRYABLE';
 }
 /**
- * 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()
  *   }
  * }
  * ```
  */
 function isInputError(error) {
-    return (isKitError(error) &&
-        error.code >= INPUT_ERROR_CODE_MIN &&
-        error.code < INPUT_ERROR_CODE_MAX);
+    return isKitError(error) && error.type === ERROR_TYPES.INPUT;
 }
 /**
  * Safely extracts error message from any error type.
@@ -3570,8 +3665,8 @@ function getChainFromParams(params) {
 /**
  * Maximum length for error messages in fallback validation errors.
  *
- * KitError enforces a 500-character limit on error messages. When creating
- * fallback validation errors that combine multiple Zod issues, we use 450
+ * KitError enforces a 1000-character limit on error messages. When creating
+ * fallback validation errors that combine multiple Zod issues, we use 950
  * characters to leave a 50-character buffer for:
  * - The error message prefix ("Invalid bridge parameters: ")
  * - Potential encoding differences or formatting overhead
@@ -3580,7 +3675,7 @@ function getChainFromParams(params) {
  * This ensures that even with concatenated issue summaries, the final message
  * stays within KitError's constraints.
  */
-const MAX_MESSAGE_LENGTH = 450;
+const MAX_MESSAGE_LENGTH = 950;
 
 /**
  * Converts a Zod validation error into a specific KitError instance using structured pattern matching.
@@ -4714,6 +4809,10 @@ function resolveConfig(params) {
 async function resolveBridgeParams(params) {
     const fromChain = resolveChainDefinition(params.from);
     const toChain = resolveChainDefinition(params.to);
+    // Validate adapter chain support after resolution
+    // This ensures adapters support the resolved chains before proceeding
+    params.from.adapter.validateChainSupport(fromChain);
+    params.to.adapter.validateChainSupport(toChain);
     const [fromAddress, toAddress] = await Promise.all([
         resolveAddress(params.from),
         resolveAddress(params.to),
@@ -4891,7 +4990,7 @@ class BridgeKit {
     async bridge(params) {
         // First validate the parameters
         assertBridgeParams(params, bridgeParamsWithChainIdentifierSchema);
-        // Then resolve chain definitions
+        // Then resolve chain definitions (includes adapter chain support validation)
         const resolvedParams = await resolveBridgeParams(params);
         // Validate network compatibility
         this.validateNetworkCompatibility(resolvedParams);
@@ -4995,7 +5094,7 @@ class BridgeKit {
     async estimate(params) {
         // First validate the parameters
         assertBridgeParams(params, bridgeParamsWithChainIdentifierSchema);
-        // Then resolve chain definitions
+        // Then resolve chain definitions (includes adapter chain support validation)
         const resolvedParams = await resolveBridgeParams(params);
         // Validate network compatibility
         this.validateNetworkCompatibility(resolvedParams);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circle-fin/bridge-kit",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "SDK for seamless cross-chain stablecoin bridging",
   "engines": {
     "node": ">=16.0.0"
@@ -10,7 +10,7 @@
   "types": "./index.d.ts",
   "dependencies": {
     "zod": "3.25.67",
-    "@circle-fin/provider-cctp-v2": "^1.0.2",
+    "@circle-fin/provider-cctp-v2": "^1.0.4",
     "abitype": "^1.1.0",
     "@solana/web3.js": "^1.98.4",
     "@ethersproject/address": "^5.8.0",