@circle-fin/provider-cctp-v2 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @circle-fin/provider-cctp-v2
 
+## 1.0.4
+
+### 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.
+
+- Improved error handling with more informative and consistent error messages.
+
+  Errors now include:
+  - Specific error codes for programmatic handling
+  - Error type categorization (BALANCE, ONCHAIN, RPC, NETWORK)
+  - Recoverability information (FATAL vs RETRYABLE)
+  - Clearer error messages with chain context
+  - Original error details preserved for debugging
+
+- Fixed an issue where bridging USDC to Solana would fail when specifying a recipient address different from the transaction signing wallet. The adapter now correctly creates the Associated Token Account (ATA) for the specified recipient address and delivers USDC to that address.
+
+## 1.0.3
+
+### Patch Changes
+
+- Improves the Solana CCTP v2 custom burn flow to ensure developer fee payouts never fail due to a missing associated token account (ATA). The instruction builder now checks for the existence of the developer fee recipient's ATA and, if absent, emits an idempotent creation instruction.
+
 ## 1.0.2
 
 ### Patch Changes

package/index.cjs

@@ -4191,9 +4191,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.
  *
@@ -4206,7 +4268,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'
  * })
@@ -4215,30 +4278,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({
@@ -4253,7 +4342,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
@@ -4330,6 +4419,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. */
@@ -4358,6 +4449,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,
@@ -4377,14 +4474,19 @@ class KitError extends Error {
 }
 
 /**
- * Minimum error code for INPUT type errors.
- * INPUT errors represent validation failures and invalid parameters.
+ * 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 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
@@ -4401,9 +4503,10 @@ class KitError extends Error {
  *   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 = {
@@ -4411,16 +4514,19 @@ const InputError = {
     NETWORK_MISMATCH: {
         code: 1001,
         name: 'INPUT_NETWORK_MISMATCH',
+        type: 'INPUT',
     },
     /** Unsupported or invalid bridge route configuration */
     UNSUPPORTED_ROUTE: {
         code: 1003,
         name: 'INPUT_UNSUPPORTED_ROUTE',
+        type: 'INPUT',
     },
     /** General validation failure for complex validation rules */
     VALIDATION_FAILED: {
         code: 1098,
         name: 'INPUT_VALIDATION_FAILED',
+        type: 'INPUT',
     },
 };
 
@@ -4535,6 +4641,36 @@ function createValidationFailedError(field, value, reason) {
     return new KitError(errorDetails);
 }
 
+/**
+ * Type guard to check if an error is a KitError instance.
+ *
+ * This guard enables TypeScript to narrow the type from `unknown` to
+ * `KitError`, providing access to structured error properties like
+ * code, name, and recoverability.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with proper type narrowing
+ *
+ * @example
+ * ```typescript
+ * import { isKitError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isKitError(error)) {
+ *     // TypeScript knows this is KitError
+ *     console.log(`Structured error: ${error.name} (${error.code})`)
+ *   } else {
+ *     console.log('Regular error:', error)
+ *   }
+ * }
+ * ```
+ */
+function isKitError(error) {
+    return error instanceof KitError;
+}
+
 const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
 /**
  * Asserts that the provided parameters match the CCTPv2 bridge parameters interface.
@@ -4629,6 +4765,11 @@ function assertCCTPv2BridgeParams(params) {
     // Validate CCTP v2 specific requirements for both wallets
     assertCCTPv2WalletContext(bridgeParams.source);
     assertCCTPv2WalletContext(bridgeParams.destination);
+    // Validate that adapters support their respective chains (defense-in-depth)
+    // This provides additional validation for users calling the provider directly
+    // without going through the kit layer, ensuring early detection of unsupported chains
+    bridgeParams.source.adapter.validateChainSupport(bridgeParams.source.chain);
+    bridgeParams.destination.adapter.validateChainSupport(bridgeParams.destination.chain);
 }
 /**
  * Validate CCTP v2 support on both chains
@@ -5211,7 +5352,11 @@ async function bridge(params, provider) {
         try {
             const step = await executor(params, provider, context);
             if (step.state === 'error') {
-                // Include error details from the step in the thrown error. Fall back to step.error.
+                // If step.error is a KitError, preserve it by re-throwing directly
+                if (isKitError(step.error)) {
+                    throw step.error;
+                }
+                // For non-KitError errors, wrap in descriptive Error
                 let fallbackErrorMessage = 'Unknown error';
                 if (step.error instanceof Error) {
                     fallbackErrorMessage = step.error.message;

package/index.d.ts

@@ -1177,6 +1177,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.
@@ -2118,10 +2126,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.
      *
@@ -2192,7 +2200,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;
     /**

package/index.mjs

@@ -4185,9 +4185,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.
  *
@@ -4200,7 +4262,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'
  * })
@@ -4209,30 +4272,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({
@@ -4247,7 +4336,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
@@ -4324,6 +4413,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. */
@@ -4352,6 +4443,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,
@@ -4371,14 +4468,19 @@ class KitError extends Error {
 }
 
 /**
- * Minimum error code for INPUT type errors.
- * INPUT errors represent validation failures and invalid parameters.
+ * 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 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
@@ -4395,9 +4497,10 @@ class KitError extends Error {
  *   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 = {
@@ -4405,16 +4508,19 @@ const InputError = {
     NETWORK_MISMATCH: {
         code: 1001,
         name: 'INPUT_NETWORK_MISMATCH',
+        type: 'INPUT',
     },
     /** Unsupported or invalid bridge route configuration */
     UNSUPPORTED_ROUTE: {
         code: 1003,
         name: 'INPUT_UNSUPPORTED_ROUTE',
+        type: 'INPUT',
     },
     /** General validation failure for complex validation rules */
     VALIDATION_FAILED: {
         code: 1098,
         name: 'INPUT_VALIDATION_FAILED',
+        type: 'INPUT',
     },
 };
 
@@ -4529,6 +4635,36 @@ function createValidationFailedError(field, value, reason) {
     return new KitError(errorDetails);
 }
 
+/**
+ * Type guard to check if an error is a KitError instance.
+ *
+ * This guard enables TypeScript to narrow the type from `unknown` to
+ * `KitError`, providing access to structured error properties like
+ * code, name, and recoverability.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with proper type narrowing
+ *
+ * @example
+ * ```typescript
+ * import { isKitError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isKitError(error)) {
+ *     // TypeScript knows this is KitError
+ *     console.log(`Structured error: ${error.name} (${error.code})`)
+ *   } else {
+ *     console.log('Regular error:', error)
+ *   }
+ * }
+ * ```
+ */
+function isKitError(error) {
+    return error instanceof KitError;
+}
+
 const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
 /**
  * Asserts that the provided parameters match the CCTPv2 bridge parameters interface.
@@ -4623,6 +4759,11 @@ function assertCCTPv2BridgeParams(params) {
     // Validate CCTP v2 specific requirements for both wallets
     assertCCTPv2WalletContext(bridgeParams.source);
     assertCCTPv2WalletContext(bridgeParams.destination);
+    // Validate that adapters support their respective chains (defense-in-depth)
+    // This provides additional validation for users calling the provider directly
+    // without going through the kit layer, ensuring early detection of unsupported chains
+    bridgeParams.source.adapter.validateChainSupport(bridgeParams.source.chain);
+    bridgeParams.destination.adapter.validateChainSupport(bridgeParams.destination.chain);
 }
 /**
  * Validate CCTP v2 support on both chains
@@ -5205,7 +5346,11 @@ async function bridge(params, provider) {
         try {
             const step = await executor(params, provider, context);
             if (step.state === 'error') {
-                // Include error details from the step in the thrown error. Fall back to step.error.
+                // If step.error is a KitError, preserve it by re-throwing directly
+                if (isKitError(step.error)) {
+                    throw step.error;
+                }
+                // For non-KitError errors, wrap in descriptive Error
                 let fallbackErrorMessage = 'Unknown error';
                 if (step.error instanceof Error) {
                     fallbackErrorMessage = step.error.message;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circle-fin/provider-cctp-v2",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Circle's official Cross-Chain Transfer Protocol v2 provider for native USDC bridging",
   "main": "./index.cjs",
   "module": "./index.mjs",