@circle-fin/bridge-kit 1.0.0

package/index.mjs

@@ -0,0 +1,4858 @@
+/**
+ * Copyright (c) 2025, Circle Internet Group, Inc. All rights reserved.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { z } from 'zod';
+import '@ethersproject/bytes';
+import '@ethersproject/address';
+import 'bs58';
+import { parseUnits as parseUnits$1 } from '@ethersproject/units';
+import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2';
+
+/**
+ * Custom error class for validation errors.
+ * Provides structured error information while hiding implementation details.
+ */
+class ValidationError extends Error {
+    errors;
+    constructor(message, errors) {
+        super(message);
+        this.errors = errors;
+        this.name = 'ValidationError';
+    }
+}
+
+/**
+ * Formats a Zod error for display.
+ * @internal
+ */
+const formatZodError = (error) => {
+    const path = error.path.length > 0 ? `${error.path.join('.')}: ` : '';
+    return `${path}${error.message}`;
+};
+/**
+ * Validates data against a Zod schema with enhanced error reporting.
+ *
+ * This function performs validation using Zod schemas and provides detailed error
+ * messages that include the validation context. It's designed to give developers
+ * clear feedback about what went wrong during validation.
+ *
+ * @param schema - The Zod schema to validate against
+ * @param data - The data to validate
+ * @param context - Context string to include in error messages (e.g., 'bridge parameters')
+ * @returns The validated and parsed data
+ * @throws {ValidationError} If validation fails
+ *
+ * @example
+ * ```typescript
+ * const result = validate(BridgeParamsSchema, params, 'bridge parameters')
+ * ```
+ */
+function validate(value, schema, context) {
+    const result = schema.safeParse(value);
+    if (!result.success) {
+        const errors = result.error.errors.map(formatZodError);
+        const firstError = errors[0] ?? 'Invalid value';
+        throw new ValidationError(`Invalid ${context}: ${firstError}`, errors);
+    }
+}
+
+/**
+ * Symbol used to track validation state on objects.
+ * This allows us to attach metadata to objects without interfering with their structure,
+ * enabling optimized validation by skipping already validated objects.
+ * @internal
+ */
+const VALIDATION_STATE = Symbol('validationState');
+/**
+ * Validates data against a Zod schema with state tracking and enhanced error reporting.
+ *
+ * This function performs validation using Zod schemas while tracking validation state
+ * and providing detailed error messages. It's designed for use in scenarios where
+ * validation state needs to be monitored and reported.
+ *
+ * @param schema - The Zod schema to validate against
+ * @param data - The data to validate
+ * @param context - Context string to include in error messages (e.g., 'bridge parameters')
+ * @returns Object containing validation result and state information
+ * @throws {ValidationError} If validation fails
+ *
+ * @example
+ * ```typescript
+ * const result = validateWithStateTracking(BridgeParamsSchema, params, 'bridge parameters')
+ * ```
+ */
+function validateWithStateTracking(value, schema, context, validatorName) {
+    // Skip validation for null or undefined values
+    if (value === null) {
+        throw new ValidationError(`Invalid ${context}: Value is null`, [
+            `Value is null`,
+        ]);
+    }
+    if (value === undefined) {
+        throw new ValidationError(`Invalid ${context}: Value is undefined`, [
+            `Value is undefined`,
+        ]);
+    }
+    // Ensure value is an object that can hold validation state
+    if (typeof value !== 'object') {
+        throw new ValidationError(`Invalid ${context}: Value must be an object`, [
+            `Value must be an object, got ${typeof value}`,
+        ]);
+    }
+    // Get or initialize validation state
+    const valueWithState = value;
+    const state = valueWithState[VALIDATION_STATE] ?? { validatedBy: [] };
+    // Skip validation if already validated by this validator
+    if (state.validatedBy.includes(validatorName)) {
+        return;
+    }
+    // Delegate to the validate function for actual validation
+    validate(value, schema, context);
+    // Update validation state
+    state.validatedBy.push(validatorName);
+    valueWithState[VALIDATION_STATE] = state;
+}
+
+/**
+ * Zod schema for validating chain definition objects used in buildExplorerUrl.
+ * This schema ensures the chain definition has the required properties for URL generation.
+ */
+const chainDefinitionSchema$1 = z.object({
+    name: z
+        .string({
+        required_error: 'Chain name is required',
+        invalid_type_error: 'Chain name must be a string',
+    })
+        .min(1, 'Chain name cannot be empty'),
+    explorerUrl: z
+        .string({
+        required_error: 'Explorer URL template is required',
+        invalid_type_error: 'Explorer URL template must be a string',
+    })
+        .min(1, 'Explorer URL template cannot be empty')
+        .refine((url) => url.includes('{hash}'), 'Explorer URL template must contain a {hash} placeholder'),
+});
+/**
+ * Zod schema for validating transaction hash strings used in buildExplorerUrl.
+ * This schema ensures the transaction hash is a non-empty string.
+ */
+const transactionHashSchema = z
+    .string({
+    required_error: 'Transaction hash is required',
+    invalid_type_error: 'Transaction hash must be a string',
+})
+    .min(1, 'Transaction hash cannot be empty')
+    .transform((hash) => hash.trim()) // Automatically trim whitespace
+    .refine((hash) => hash.length > 0, 'Transaction hash must not be empty or whitespace-only');
+/**
+ * Zod schema for validating buildExplorerUrl function parameters.
+ * This schema validates both the chain definition and transaction hash together.
+ */
+z.object({
+    chainDef: chainDefinitionSchema$1,
+    txHash: transactionHashSchema,
+});
+/**
+ * Zod schema for validating the generated explorer URL.
+ * This schema ensures the generated URL is valid.
+ */
+z
+    .string()
+    .url('Generated explorer URL is invalid');
+
+/**
+ * A type-safe event emitter for managing action-based event subscriptions.
+ *
+ * Actionable provides a strongly-typed publish/subscribe pattern for events,
+ * where each event (action) has its own specific payload type. Handlers can
+ * subscribe to specific events or use a wildcard to receive all events.
+ *
+ * @typeParam AllActions - A record mapping action names to their payload types.
+ *
+ * @example
+ * ```typescript
+ * import { Actionable } from '@circle-fin/bridge-kit/utils';
+ *
+ * // Define your action types
+ * type TransferActions = {
+ *   started: { txHash: string; amount: string };
+ *   completed: { txHash: string; destinationTxHash: string };
+ *   failed: { error: Error };
+ * };
+ *
+ * // Create an actionable instance
+ * const transferEvents = new Actionable<TransferActions>();
+ *
+ * // Subscribe to a specific event
+ * transferEvents.on('completed', (payload) => {
+ *   console.log(`Transfer completed with hash: ${payload.destinationTxHash}`);
+ * });
+ *
+ * // Subscribe to all events
+ * transferEvents.on('*', (payload) => {
+ *   console.log('Event received:', payload);
+ * });
+ *
+ * // Dispatch an event
+ * transferEvents.dispatch('completed', {
+ *   txHash: '0x123',
+ *   destinationTxHash: '0xabc'
+ * });
+ * ```
+ */
+class Actionable {
+    // Store event handlers by action key
+    handlers = {};
+    // Store wildcard handlers that receive all events
+    wildcard = [];
+    // Implementation that handles both overloads
+    on(action, handler) {
+        if (action === '*') {
+            // Add to wildcard handlers array
+            this.wildcard.push(handler);
+        }
+        else {
+            // Initialize the action's handler array if it doesn't exist
+            if (!this.handlers[action]) {
+                this.handlers[action] = [];
+            }
+            // Add the handler to the specific action's array
+            this.handlers[action].push(handler);
+        }
+    }
+    // Implementation that handles both overloads
+    off(action, handler) {
+        if (action === '*') {
+            // Find and remove the handler from wildcard array
+            const index = this.wildcard.indexOf(handler);
+            if (index !== -1) {
+                this.wildcard.splice(index, 1);
+            }
+        }
+        else if (this.handlers[action]) {
+            // Check if there are handlers for this action
+            // Find and remove the specific handler
+            const index = this.handlers[action].indexOf(handler);
+            if (index !== -1) {
+                this.handlers[action].splice(index, 1);
+            }
+        }
+    }
+    /**
+     * Dispatch an action with its payload to all registered handlers.
+     *
+     * This method notifies both:
+     * - Handlers registered specifically for this action
+     * - Wildcard handlers registered for all actions
+     *
+     * @param action - The action key identifying the event type.
+     * @param payload - The data associated with the action.
+     *
+     * @example
+     * ```typescript
+     * type Actions = {
+     *   transferStarted: { amount: string; destination: string };
+     *   transferComplete: { txHash: string };
+     * };
+     *
+     * const events = new Actionable<Actions>();
+     *
+     * // Dispatch an event
+     * events.dispatch('transferStarted', {
+     *   amount: '100',
+     *   destination: '0xABC123'
+     * });
+     * ```
+     */
+    dispatch(action, payload) {
+        // Execute all handlers registered for this specific action
+        for (const h of this.handlers[action] ?? [])
+            h(payload);
+        // Execute all wildcard handlers
+        for (const h of this.wildcard)
+            h(payload);
+    }
+}
+
+/**
+ * Convert a human-readable decimal string to its smallest unit representation.
+ *
+ * This function converts user-friendly decimal values into the integer representation
+ * required by blockchain operations, where all values are stored in the smallest
+ * denomination. Uses the battle-tested implementation from @ethersproject/units.
+ *
+ * @param value - The decimal string to convert (e.g., "1.0")
+ * @param decimals - The number of decimal places for the unit conversion
+ * @returns The value in smallest units as a bigint (e.g., 1000000n for 1 USDC with 6 decimals)
+ * @throws Error if the value is not a valid decimal string
+ *
+ * @example
+ * ```typescript
+ * import { parseUnits } from '@core/utils'
+ *
+ * // Parse USDC (6 decimals)
+ * const usdcParsed = parseUnits('1.0', 6)
+ * console.log(usdcParsed) // 1000000n
+ *
+ * // Parse ETH (18 decimals)
+ * const ethParsed = parseUnits('1.0', 18)
+ * console.log(ethParsed) // 1000000000000000000n
+ *
+ * // Parse fractional amount
+ * const fractionalParsed = parseUnits('1.5', 6)
+ * console.log(fractionalParsed) // 1500000n
+ *
+ * // Parse integer (no decimal point)
+ * const integerParsed = parseUnits('42', 6)
+ * console.log(integerParsed) // 42000000n
+ * ```
+ */
+const parseUnits = (value, decimals) => {
+    return parseUnits$1(value, decimals).toBigInt();
+};
+
+/**
+ * Valid recoverability values for error handling strategies.
+ *
+ * - FATAL errors are thrown immediately (invalid inputs, insufficient funds)
+ * - RETRYABLE errors are returned when a flow fails to start but could work later
+ * - RESUMABLE errors are returned when a flow fails mid-execution but can be continued
+ */
+const RECOVERABILITY_VALUES = [
+    'RETRYABLE',
+    'RESUMABLE',
+    'FATAL',
+];
+
+// Create a mutable array for Zod enum validation
+const RECOVERABILITY_ARRAY = [...RECOVERABILITY_VALUES];
+/**
+ * Zod schema for validating ErrorDetails objects.
+ *
+ * This schema provides runtime validation for all ErrorDetails properties,
+ * ensuring type safety and proper error handling for JavaScript consumers.
+ *
+ * @example
+ * ```typescript
+ * import { errorDetailsSchema } from '@core/errors'
+ *
+ * const result = errorDetailsSchema.safeParse({
+ *   code: 1001,
+ *   name: 'NETWORK_MISMATCH',
+ *   recoverability: 'FATAL',
+ *   message: 'Source and destination networks must be different'
+ * })
+ *
+ * if (!result.success) {
+ *   console.error('Validation failed:', result.error.issues)
+ * }
+ * ```
+ */
+const errorDetailsSchema = z.object({
+    /** Numeric identifier following standardized ranges (1000+ for INPUT errors) */
+    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") */
+    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 handling strategy */
+    recoverability: z.enum(RECOVERABILITY_ARRAY, {
+        errorMap: () => ({
+            message: 'Recoverability must be one of: RETRYABLE, RESUMABLE, FATAL',
+        }),
+    }),
+    /** User-friendly explanation with network context */
+    message: z
+        .string()
+        .min(1, 'Error message must be a non-empty string')
+        .max(500, 'Error message must be 500 characters or less'),
+    /** Raw error details, context, or the original error that caused this one. */
+    cause: z
+        .object({
+        /** Free-form error payload from underlying system */
+        trace: z.unknown().optional(),
+    })
+        .optional(),
+});
+
+/**
+ * Validates an ErrorDetails object using Zod schema.
+ *
+ * @param details - The object to validate
+ * @returns The validated ErrorDetails object
+ * @throws {TypeError} When validation fails
+ *
+ * @example
+ * ```typescript
+ * import { validateErrorDetails } from '@core/errors'
+ *
+ * try {
+ *   const validDetails = validateErrorDetails({
+ *     code: 1001,
+ *     name: 'NETWORK_MISMATCH',
+ *     recoverability: 'FATAL',
+ *     message: 'Source and destination networks must be different'
+ *   })
+ * } catch (error) {
+ *   console.error('Validation failed:', error.message)
+ * }
+ * ```
+ */
+function validateErrorDetails(details) {
+    const result = errorDetailsSchema.safeParse(details);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+            .join(', ');
+        throw new TypeError(`Invalid ErrorDetails: ${issues}`);
+    }
+    return result.data;
+}
+
+/**
+ * Structured error class for Stablecoin Kit operations.
+ *
+ * This class extends the native Error class while implementing the ErrorDetails
+ * interface, providing a consistent error format for programmatic handling
+ * across the Stablecoin Kits ecosystem. All properties are immutable to ensure
+ * error objects cannot be modified after creation.
+ *
+ * @example
+ * ```typescript
+ * import { KitError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   code: 1001,
+ *   name: 'INPUT_NETWORK_MISMATCH',
+ *   recoverability: 'FATAL',
+ *   message: 'Cannot bridge between mainnet and testnet'
+ * })
+ *
+ * if (error instanceof KitError) {
+ *   console.log(`Error ${error.code}: ${error.name}`)
+ *   // → "Error 1001: INPUT_NETWORK_MISMATCH"
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { KitError } from '@core/errors'
+ *
+ * // Error with cause information
+ * const error = new KitError({
+ *   code: 1002,
+ *   name: 'INVALID_AMOUNT',
+ *   recoverability: 'FATAL',
+ *   message: 'Amount must be greater than zero',
+ *   cause: {
+ *     trace: { providedAmount: -100, minimumAmount: 0 }
+ *   }
+ * })
+ *
+ * throw error
+ * ```
+ */
+class KitError extends Error {
+    /** Numeric identifier following standardized ranges (1000+ for INPUT errors) */
+    code;
+    /** Human-readable ID (e.g., "NETWORK_MISMATCH") */
+    name;
+    /** Error handling strategy */
+    recoverability;
+    /** Raw error details, context, or the original error that caused this one. */
+    cause;
+    /**
+     * Create a new KitError instance.
+     *
+     * @param details - The error details object containing all required properties.
+     * @throws \{TypeError\} When details parameter is missing or invalid.
+     */
+    constructor(details) {
+        // Validate input at runtime for JavaScript consumers using Zod
+        const validatedDetails = validateErrorDetails(details);
+        super(validatedDetails.message);
+        // Set properties as readonly at runtime
+        Object.defineProperties(this, {
+            name: {
+                value: validatedDetails.name,
+                writable: false,
+                enumerable: true,
+                configurable: false,
+            },
+            code: {
+                value: validatedDetails.code,
+                writable: false,
+                enumerable: true,
+                configurable: false,
+            },
+            recoverability: {
+                value: validatedDetails.recoverability,
+                writable: false,
+                enumerable: true,
+                configurable: false,
+            },
+            ...(validatedDetails.cause && {
+                cause: {
+                    value: validatedDetails.cause,
+                    writable: false,
+                    enumerable: true,
+                    configurable: false,
+                },
+            }),
+        });
+    }
+}
+
+/**
+ * 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.
+ *
+ * Error codes follow a hierarchical numbering scheme where the first digit
+ * indicates the error category (1 = INPUT) and subsequent digits provide
+ * specific error identification within that category.
+ *
+ *
+ * @example
+ * ```typescript
+ * import { InputError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...InputError.NETWORK_MISMATCH,
+ *   recoverability: 'FATAL',
+ *   message: 'Source and destination networks must be different'
+ * })
+ *
+ * // Access code and name individually if needed
+ * console.log(InputError.NETWORK_MISMATCH.code)  // 1001
+ * console.log(InputError.NETWORK_MISMATCH.name)  // 'INPUT_NETWORK_MISMATCH'
+ * ```
+ */
+const InputError = {
+    /** Network type mismatch between chains (mainnet vs testnet) */
+    NETWORK_MISMATCH: {
+        code: 1001,
+        name: 'INPUT_NETWORK_MISMATCH',
+    },
+    /** Invalid amount format or value (negative, zero, or malformed) */
+    INVALID_AMOUNT: {
+        code: 1002,
+        name: 'INPUT_INVALID_AMOUNT',
+    },
+    /** Unsupported or invalid bridge route configuration */
+    UNSUPPORTED_ROUTE: {
+        code: 1003,
+        name: 'INPUT_UNSUPPORTED_ROUTE',
+    },
+    /** Invalid wallet or contract address format */
+    INVALID_ADDRESS: {
+        code: 1004,
+        name: 'INPUT_INVALID_ADDRESS',
+    },
+    /** Invalid or unsupported chain identifier */
+    INVALID_CHAIN: {
+        code: 1005,
+        name: 'INPUT_INVALID_CHAIN',
+    },
+    /** General validation failure for complex validation rules */
+    VALIDATION_FAILED: {
+        code: 1098,
+        name: 'INPUT_VALIDATION_FAILED',
+    },
+};
+
+/**
+ * Creates error for network type mismatch between source and destination.
+ *
+ * This error is thrown when attempting to bridge between chains that have
+ * different network types (e.g., mainnet to testnet), which is not supported
+ * for security reasons.
+ *
+ * @param sourceChain - The source chain definition
+ * @param destChain - The destination chain definition
+ * @returns KitError with specific network mismatch details
+ *
+ * @example
+ * ```typescript
+ * import { createNetworkMismatchError } from '@core/errors'
+ * import { Ethereum, BaseSepolia } from '@core/chains'
+ *
+ * // This will throw a detailed error
+ * throw createNetworkMismatchError(Ethereum, BaseSepolia)
+ * // Message: "Cannot bridge between Ethereum (mainnet) and Base Sepolia (testnet). Source and destination networks must both be testnet or both be mainnet."
+ * ```
+ */
+function createNetworkMismatchError(sourceChain, destChain) {
+    const sourceNetworkType = sourceChain.isTestnet ? 'testnet' : 'mainnet';
+    const destNetworkType = destChain.isTestnet ? 'testnet' : 'mainnet';
+    const errorDetails = {
+        ...InputError.NETWORK_MISMATCH,
+        recoverability: 'FATAL',
+        message: `Cannot bridge between ${sourceChain.name} (${sourceNetworkType}) and ${destChain.name} (${destNetworkType}). Source and destination networks must both be testnet or both be mainnet.`,
+        cause: {
+            trace: { sourceChain: sourceChain.name, destChain: destChain.name },
+        },
+    };
+    return new KitError(errorDetails);
+}
+/**
+ * Creates error for unsupported bridge route.
+ *
+ * This error is thrown when attempting to bridge between chains that don't
+ * have a supported bridge route configured.
+ *
+ * @param source - Source chain name
+ * @param destination - Destination chain name
+ * @returns KitError with specific route details
+ *
+ * @example
+ * ```typescript
+ * import { createUnsupportedRouteError } from '@core/errors'
+ *
+ * throw createUnsupportedRouteError('Ethereum', 'Solana')
+ * // Message: "Route from Ethereum to Solana is not supported"
+ * ```
+ */
+function createUnsupportedRouteError(source, destination) {
+    const errorDetails = {
+        ...InputError.UNSUPPORTED_ROUTE,
+        recoverability: 'FATAL',
+        message: `Route from ${source} to ${destination} is not supported.`,
+        cause: {
+            trace: { source, destination },
+        },
+    };
+    return new KitError(errorDetails);
+}
+/**
+ * Creates error for invalid amount format or precision.
+ *
+ * This error is thrown when the provided amount doesn't meet validation
+ * requirements such as precision, range, or format.
+ *
+ * @param amount - The invalid amount string
+ * @param reason - Specific reason why amount is invalid
+ * @returns KitError with amount details and validation rule
+ *
+ * @example
+ * ```typescript
+ * import { createInvalidAmountError } from '@core/errors'
+ *
+ * throw createInvalidAmountError('0.000001', 'Amount must be at least 0.01 USDC')
+ * // Message: "Invalid amount '0.000001': Amount must be at least 0.01 USDC"
+ *
+ * throw createInvalidAmountError('abc', 'Amount must be a valid number')
+ * // Message: "Invalid amount 'abc': Amount must be a valid number"
+ * ```
+ */
+function createInvalidAmountError(amount, reason) {
+    const errorDetails = {
+        ...InputError.INVALID_AMOUNT,
+        recoverability: 'FATAL',
+        message: `Invalid amount '${amount}': ${reason}.`,
+        cause: {
+            trace: { amount, reason },
+        },
+    };
+    return new KitError(errorDetails);
+}
+/**
+ * Creates error for invalid wallet address format.
+ *
+ * This error is thrown when the provided address doesn't match the expected
+ * format for the specified chain.
+ *
+ * @param address - The invalid address string
+ * @param chain - Chain name where address is invalid
+ * @param expectedFormat - Description of expected address format
+ * @returns KitError with address details and format requirements
+ *
+ * @example
+ * ```typescript
+ * import { createInvalidAddressError } from '@core/errors'
+ *
+ * throw createInvalidAddressError('0x123', 'Ethereum', '42-character hex string starting with 0x')
+ * // Message: "Invalid address '0x123' for Ethereum. Expected 42-character hex string starting with 0x."
+ *
+ * throw createInvalidAddressError('invalid', 'Solana', 'base58-encoded string')
+ * // Message: "Invalid address 'invalid' for Solana. Expected base58-encoded string."
+ * ```
+ */
+function createInvalidAddressError(address, chain, expectedFormat) {
+    const errorDetails = {
+        ...InputError.INVALID_ADDRESS,
+        recoverability: 'FATAL',
+        message: `Invalid address '${address}' for ${chain}. Expected ${expectedFormat}.`,
+        cause: {
+            trace: { address, chain, expectedFormat },
+        },
+    };
+    return new KitError(errorDetails);
+}
+/**
+ * Creates error for invalid chain configuration.
+ *
+ * This error is thrown when the provided chain doesn't meet the required
+ * configuration or is not supported for the operation.
+ *
+ * @param chain - The invalid chain name or identifier
+ * @param reason - Specific reason why chain is invalid
+ * @returns KitError with chain details and validation rule
+ *
+ * @example
+ * ```typescript
+ * import { createInvalidChainError } from '@core/errors'
+ *
+ * throw createInvalidChainError('UnknownChain', 'Chain is not supported by this bridge')
+ * // Message: "Invalid chain 'UnknownChain': Chain is not supported by this bridge"
+ * ```
+ */
+function createInvalidChainError(chain, reason) {
+    const errorDetails = {
+        ...InputError.INVALID_CHAIN,
+        recoverability: 'FATAL',
+        message: `Invalid chain '${chain}': ${reason}`,
+        cause: {
+            trace: { chain, reason },
+        },
+    };
+    return new KitError(errorDetails);
+}
+
+/**
+ * Extracts chain information including name, display name, and expected address format.
+ *
+ * This function determines the chain type by checking the explicit `type` property first,
+ * then falls back to name-based matching. This approach is more robust than relying solely
+ * on string matching and future-proofs the code for new chain ecosystems.
+ *
+ * @param chain - The chain identifier (string, chain object, or undefined/null)
+ * @returns Chain information with name, display name, and expected address format
+ *
+ * @example
+ * ```typescript
+ * import { extractChainInfo } from '@core/errors'
+ *
+ * // With chain object
+ * const info1 = extractChainInfo({ name: 'Ethereum', type: 'evm' })
+ * console.log(info1.expectedAddressFormat)
+ * // → "42-character hex address starting with 0x"
+ *
+ * // With string
+ * const info2 = extractChainInfo('Solana')
+ * console.log(info2.expectedAddressFormat)
+ * // → "44-character base58 encoded string"
+ *
+ * // With undefined
+ * const info3 = extractChainInfo(undefined)
+ * console.log(info3.name) // → "unknown"
+ * ```
+ */
+function extractChainInfo(chain) {
+    const name = typeof chain === 'string' ? chain : (chain?.name ?? 'unknown');
+    const chainType = typeof chain === 'object' && chain !== null ? chain.type : undefined;
+    // Use explicit chain type if available, fallback to name matching
+    const isSolana = chainType !== undefined
+        ? chainType === 'solana'
+        : name.toLowerCase().includes('solana');
+    return {
+        name,
+        displayName: name.replace(/_/g, ' '),
+        expectedAddressFormat: isSolana
+            ? '44-character base58 encoded string'
+            : '42-character hex address starting with 0x',
+    };
+}
+/**
+ * Validates if an address format is correct for the specified chain.
+ *
+ * This function checks the explicit chain `type` property first, then falls back
+ * to name-based matching to determine whether to validate as a Solana or EVM address.
+ *
+ * @param address - The address to validate
+ * @param chain - The chain identifier or chain definition (cannot be null)
+ * @returns True if the address format is valid for the chain, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isValidAddressForChain } from '@core/errors'
+ *
+ * // EVM address validation
+ * isValidAddressForChain('0x742d35Cc6634C0532925a3b8D0C0C1C4C5C6C7C8', 'Ethereum')
+ * // → true
+ *
+ * // Solana address validation
+ * isValidAddressForChain('9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM', { name: 'Solana', type: 'solana' })
+ * // → true
+ *
+ * // Invalid format
+ * isValidAddressForChain('invalid', 'Ethereum')
+ * // → false
+ * ```
+ */
+function isValidAddressForChain(address, chain) {
+    const chainType = typeof chain === 'object' ? chain.type : undefined;
+    const name = typeof chain === 'string' ? chain : chain.name;
+    // Use explicit chain type if available, fallback to name matching
+    const isSolana = chainType !== undefined
+        ? chainType === 'solana'
+        : name.toLowerCase().includes('solana');
+    if (isSolana) {
+        // Solana base58 address: 32-44 characters from base58 alphabet
+        return /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(address);
+    }
+    // EVM hex address: 0x followed by 40 hex characters
+    return /^0x[a-fA-F0-9]{40}$/.test(address);
+}
+/**
+ * Type guard to check if a value is an object.
+ *
+ * @param val - The value to check
+ * @returns True if the value is a non-null object
+ */
+function isObject(val) {
+    return typeof val === 'object' && val !== null;
+}
+/**
+ * Type guard to check if a value is a chain with isTestnet property.
+ *
+ * @param chain - The value to check
+ * @returns True if the value is a chain object with name and isTestnet properties
+ *
+ * @example
+ * ```typescript
+ * import { isChainWithTestnet } from '@core/errors'
+ *
+ * const chain1 = { name: 'Ethereum', isTestnet: false }
+ * isChainWithTestnet(chain1) // → true
+ *
+ * const chain2 = { name: 'Ethereum' }
+ * isChainWithTestnet(chain2) // → false
+ *
+ * const chain3 = 'Ethereum'
+ * isChainWithTestnet(chain3) // → false
+ * ```
+ */
+function isChainWithTestnet(chain) {
+    return (isObject(chain) &&
+        'isTestnet' in chain &&
+        typeof chain['isTestnet'] === 'boolean' &&
+        'name' in chain &&
+        typeof chain['name'] === 'string');
+}
+/**
+ * Gets chain identifier from toData object.
+ *
+ * Looks for chain in context.chain first, then falls back to direct chain property.
+ *
+ * @param toData - The destination data object
+ * @returns The chain identifier or null
+ */
+function getChainFromToData(toData) {
+    const context = toData['context'];
+    const chain = context?.['chain'] ?? toData['chain'];
+    return chain;
+}
+/**
+ * Gets chain name from params object.
+ *
+ * @param params - The parameters object
+ * @returns The chain name as a string, or null if not found
+ */
+function getChainName(params) {
+    if (isObject(params)) {
+        const chain = params['chain'];
+        if (typeof chain === 'string') {
+            return chain;
+        }
+        if (isObject(chain) && 'name' in chain) {
+            return chain.name;
+        }
+    }
+    return null;
+}
+/**
+ * Extracts from data from params object.
+ *
+ * Supports both 'from' and 'source' property names.
+ *
+ * @param params - The parameters object
+ * @returns The from/source data or undefined
+ */
+function extractFromData(params) {
+    return (params['from'] ?? params['source']);
+}
+/**
+ * Extracts to data from params object.
+ *
+ * Supports both 'to' and 'destination' property names.
+ *
+ * @param params - The parameters object
+ * @returns The to/destination data or undefined
+ */
+function extractToData(params) {
+    return (params['to'] ?? params['destination']);
+}
+/**
+ * Gets address from params object using a dot-separated path.
+ *
+ * Traverses nested objects to extract the address value at the specified path.
+ *
+ * @param params - The parameters object
+ * @param path - Dot-separated path to extract address from (e.g., 'to.recipientAddress')
+ * @returns The address as a string, or 'unknown' if not found
+ *
+ * @example
+ * ```typescript
+ * // Extract from specific path
+ * getAddressFromParams(params, 'to.recipientAddress')
+ * // Returns the value at params.to.recipientAddress
+ * ```
+ */
+function getAddressFromParams(params, path) {
+    const parts = path.split('.');
+    let current = params;
+    for (const part of parts) {
+        if (current !== null &&
+            current !== undefined &&
+            typeof current === 'object' &&
+            part in current) {
+            current = current[part];
+        }
+        else {
+            return 'unknown';
+        }
+    }
+    return typeof current === 'string' ? current : 'unknown';
+}
+/**
+ * Gets chain identifier from params object.
+ *
+ * Looks for chain in to.context.chain, to.chain, or direct chain property.
+ *
+ * @param params - The parameters object
+ * @returns The chain identifier or null
+ */
+function getChainFromParams(params) {
+    const to = extractToData(params);
+    const chain = to?.['chain'] ?? params['chain'];
+    return chain;
+}
+
+/**
+ * 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
+ * characters to leave a 50-character buffer for:
+ * - The error message prefix ("Invalid bridge parameters: ")
+ * - Potential encoding differences or formatting overhead
+ * - Safety margin to prevent KitError constructor failures
+ *
+ * This ensures that even with concatenated issue summaries, the final message
+ * stays within KitError's constraints.
+ */
+const MAX_MESSAGE_LENGTH = 450;
+
+/**
+ * Converts a Zod validation error into a specific KitError instance using structured pattern matching.
+ *
+ * This function inspects Zod's error details (path, code, message) and delegates each issue
+ * to specialized handlers that generate domain-specific KitError objects. It leverages
+ * Zod's error codes and path information for robust matching, avoiding fragile string checks.
+ *
+ * @param zodError - The Zod validation error containing one or more issues
+ * @param params - The original parameters that failed validation (used to extract invalid values)
+ * @returns A specific KitError instance with actionable error details
+ */
+function convertZodErrorToStructured(zodError, params) {
+    // Handle null/undefined params gracefully
+    if (params === null || params === undefined) {
+        return createValidationFailedError(zodError);
+    }
+    const paramsObj = params;
+    const toData = extractToData(paramsObj);
+    const fromData = extractFromData(paramsObj);
+    for (const issue of zodError.issues) {
+        const path = issue.path.join('.');
+        const code = issue.code;
+        // Try to handle specific error types
+        const amountError = handleAmountError(path, code, issue.message, paramsObj);
+        if (amountError)
+            return amountError;
+        const chainError = handleChainError(path, code, issue.message, fromData, toData);
+        if (chainError)
+            return chainError;
+        const addressError = handleAddressError(path, code, issue.message, paramsObj);
+        if (addressError)
+            return addressError;
+    }
+    // Fallback
+    return createValidationFailedError(zodError);
+}
+/**
+ * Creates a generic validation failed error for null/undefined params or unmapped error cases.
+ *
+ * This is a fallback handler used when:
+ * - Parameters are null or undefined
+ * - No specific error handler matches the Zod error
+ * - The error doesn't fit into amount/chain/address categories
+ *
+ * The function truncates the error message to stay within KitError's 500-character limit.
+ *
+ * @param zodError - The Zod validation error with all issues
+ * @param params - The original parameters (may be null/undefined)
+ * @returns A generic KitError with INPUT_VALIDATION_FAILED code
+ */
+function createValidationFailedError(zodError) {
+    const issueSummary = zodError.issues
+        .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+        .join('; ');
+    // Truncate message to avoid KitError constructor failure.
+    const fullMessage = `Invalid parameters: ${issueSummary}`;
+    const truncatedMessage = fullMessage.length > MAX_MESSAGE_LENGTH
+        ? `${fullMessage.substring(0, MAX_MESSAGE_LENGTH)}...`
+        : fullMessage;
+    return new KitError({
+        ...InputError.VALIDATION_FAILED,
+        recoverability: 'FATAL',
+        message: truncatedMessage,
+        cause: {
+            trace: {
+                originalError: zodError.message,
+                zodIssues: zodError.issues,
+            },
+        },
+    });
+}
+/**
+ * Handles amount-related validation errors from Zod.
+ *
+ * Checks if the validation error path includes 'amount' and attempts
+ * to convert generic Zod errors into specific KitError instances with
+ * actionable messages. Delegates to specialized handlers in order of specificity:
+ * 1. Negative amount errors (too_small)
+ * 2. Custom validation errors (decimal places, numeric string)
+ * 3. Invalid string format errors
+ * 4. Invalid type errors
+ *
+ * @param path - The Zod error path (e.g., 'amount' or 'config.amount')
+ * @param code - The Zod error code (e.g., 'too_small', 'invalid_string', 'custom')
+ * @param message - The original Zod error message
+ * @param paramsObj - The original params object for extracting the invalid amount value
+ * @returns KitError with INPUT_INVALID_AMOUNT code if this is an amount error, null otherwise
+ */
+function handleAmountError(path, code, message, paramsObj) {
+    if (!path.includes('amount'))
+        return null;
+    const amount = typeof paramsObj['amount'] === 'string' ? paramsObj['amount'] : 'unknown';
+    // Try different error handlers in order of specificity
+    const negativeError = handleNegativeAmountError(code, message, amount);
+    if (negativeError)
+        return negativeError;
+    const customError = handleCustomAmountError(code, message, amount);
+    if (customError)
+        return customError;
+    const stringFormatError = handleInvalidStringAmountError(code, message, amount);
+    if (stringFormatError)
+        return stringFormatError;
+    const typeError = handleInvalidTypeAmountError(code, amount);
+    if (typeError)
+        return typeError;
+    return null;
+}
+/**
+ * Handles negative or too-small amount validation errors.
+ *
+ * Detects Zod 'too_small' error codes or messages containing 'greater than'
+ * and creates a specific error indicating the amount must be positive.
+ *
+ * @param code - The Zod error code
+ * @param message - The Zod error message
+ * @param amount - The invalid amount value as a string
+ * @returns KitError if this is a negative/too-small amount error, null otherwise
+ */
+function handleNegativeAmountError(code, message, amount) {
+    if (code === 'too_small' || message.includes('greater than')) {
+        return createInvalidAmountError(amount, 'Amount must be greater than 0');
+    }
+    return null;
+}
+/**
+ * Handles custom Zod refinement validation errors for amounts.
+ *
+ * Processes Zod 'custom' error codes from .refine() validators and matches
+ * against known patterns:
+ * - 'non-negative' - amount must be \>= 0
+ * - 'decimal places' - too many decimal places
+ * - 'numeric string' - value is not a valid numeric string
+ *
+ * @param code - The Zod error code (must be 'custom')
+ * @param message - The custom error message from the refinement
+ * @param amount - The invalid amount value as a string
+ * @returns KitError with specific message if pattern matches, null otherwise
+ */
+function handleCustomAmountError(code, message, amount) {
+    if (code !== 'custom')
+        return null;
+    if (message.includes('non-negative')) {
+        return createInvalidAmountError(amount, 'Amount must be non-negative');
+    }
+    if (message.includes('decimal places')) {
+        return createInvalidAmountError(amount, message);
+    }
+    if (message.includes('numeric string')) {
+        return createInvalidAmountError(amount, 'Amount must be a numeric string');
+    }
+    return null;
+}
+/**
+ * Handles Zod 'invalid_string' errors for amount values.
+ *
+ * Processes string validation failures (e.g., regex mismatches) and categorizes them:
+ * 1. Negative numbers that pass Number() but fail other validations
+ * 2. Decimal places validation failures (too many decimal places)
+ * 3. Numeric format validation failures (contains non-numeric characters)
+ * 4. Generic invalid number strings
+ *
+ * @param code - The Zod error code (must be 'invalid_string')
+ * @param message - The Zod error message from string validation
+ * @param amount - The invalid amount value as a string
+ * @returns KitError with context-specific message if pattern matches, null otherwise
+ */
+function handleInvalidStringAmountError(code, message, amount) {
+    if (code !== 'invalid_string')
+        return null;
+    // Check if it's a negative number first
+    if (amount.startsWith('-') && !isNaN(Number(amount))) {
+        return createInvalidAmountError(amount, 'Amount must be greater than 0');
+    }
+    // Check for decimal places validation
+    if (isDecimalPlacesError(message)) {
+        return createInvalidAmountError(amount, 'Maximum supported decimal places: 6');
+    }
+    // Check for numeric format validation
+    if (isNumericFormatError(message)) {
+        return createInvalidAmountError(amount, 'Amount must be a valid number format');
+    }
+    // For other cases like 'abc', return specific error
+    if (!message.includes('valid number format')) {
+        return createInvalidAmountError(amount, 'Amount must be a valid number string');
+    }
+    return null;
+}
+/**
+ * Handles Zod 'invalid_type' errors for amount values.
+ *
+ * Triggered when the amount is not a string type (e.g., number, boolean, object).
+ * Creates an error indicating the amount must be a string representation of a number.
+ *
+ * @param code - The Zod error code (must be 'invalid_type')
+ * @param amount - The invalid amount value (will be converted to string for error message)
+ * @returns KitError if this is a type mismatch, null otherwise
+ */
+function handleInvalidTypeAmountError(code, amount) {
+    if (code === 'invalid_type') {
+        return createInvalidAmountError(amount, 'Amount must be a valid number string');
+    }
+    return null;
+}
+/**
+ * Checks if an error message indicates a decimal places validation failure.
+ *
+ * Looks for keywords like 'maximum', 'at most', and 'decimal places' to identify
+ * errors related to too many decimal digits in an amount value.
+ *
+ * @param message - The error message to analyze
+ * @returns True if the message indicates a decimal places error, false otherwise
+ */
+function isDecimalPlacesError(message) {
+    return ((message.includes('maximum') || message.includes('at most')) &&
+        message.includes('decimal places'));
+}
+/**
+ * Checks if an error message indicates a numeric format validation failure.
+ *
+ * Identifies errors where a value contains 'numeric' but is not specifically
+ * about 'valid number format' or 'numeric string' (to avoid false positives).
+ *
+ * @param message - The error message to analyze
+ * @returns True if the message indicates a numeric format error, false otherwise
+ */
+function isNumericFormatError(message) {
+    return (message.includes('numeric') &&
+        !message.includes('valid number format') &&
+        !message.includes('numeric string'));
+}
+/**
+ * Handles chain-related validation errors from Zod.
+ *
+ * Checks if the validation error path includes 'chain' and extracts the
+ * chain name from either the source (from) or destination (to) data.
+ * Creates a KitError with the invalid chain name and original error message.
+ *
+ * @param path - The Zod error path (e.g., 'from.chain' or 'to.chain')
+ * @param _code - The Zod error code (unused, prefixed with _ to indicate intentionally ignored)
+ * @param message - The original Zod error message
+ * @param fromData - The source/from data object (may contain chain info)
+ * @param toData - The destination/to data object (may contain chain info)
+ * @returns KitError with INPUT_INVALID_CHAIN code if this is a chain error, null otherwise
+ */
+function handleChainError(path, _code, message, fromData, toData) {
+    if (!path.includes('chain'))
+        return null;
+    const chain = getChainName(fromData) ?? getChainName(toData);
+    return createInvalidChainError(chain ?? 'unknown', message);
+}
+/**
+ * Handles address-related validation errors from Zod.
+ *
+ * Checks if the validation error path includes 'address' and extracts both
+ * the invalid address from the path and the target chain from the params.
+ * Uses chain utilities to determine the expected address format (EVM or Solana)
+ * and creates a context-specific error message.
+ *
+ * @param path - The Zod error path (e.g., 'to.recipientAddress')
+ * @param _code - The Zod error code (unused, prefixed with _ to indicate intentionally ignored)
+ * @param _message - The original Zod error message (unused, we create a more specific message)
+ * @param paramsObj - The original params object for extracting address and chain info
+ * @returns KitError with INPUT_INVALID_ADDRESS code if this is an address error, null otherwise
+ */
+function handleAddressError(path, _code, _message, paramsObj) {
+    if (!path.toLowerCase().includes('address'))
+        return null;
+    const address = getAddressFromParams(paramsObj, path);
+    const chain = getChainFromParams(paramsObj);
+    const chainInfo = extractChainInfo(chain);
+    return createInvalidAddressError(address, chainInfo.displayName, chainInfo.expectedAddressFormat);
+}
+
+const assertCustomFeePolicySymbol = Symbol('assertCustomFeePolicy');
+/**
+ * Schema for validating BridgeKit custom fee policy.
+ *
+ * Validates the shape of {@link CustomFeePolicy}, which lets SDK consumers
+ * provide custom fee calculation and fee-recipient resolution logic.
+ *
+ * - calculateFee: required function that returns a fee as a string (or Promise<string>).
+ * - resolveFeeRecipientAddress: required function that returns a recipient address as a
+ *   string (or Promise<string>).
+ *
+ * This schema only ensures the presence and return types of the functions; it
+ * does not validate their argument types.
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   calculateFee: async () => '1000000',
+ *   resolveFeeRecipientAddress: () => '0x1234567890123456789012345678901234567890',
+ * }
+ * const result = customFeePolicySchema.safeParse(config)
+ * // result.success === true
+ * ```
+ */
+const customFeePolicySchema = z
+    .object({
+    calculateFee: z.function().returns(z.string().or(z.promise(z.string()))),
+    resolveFeeRecipientAddress: z
+        .function()
+        .returns(z.string().or(z.promise(z.string()))),
+})
+    .strict();
+/**
+ * Assert that the provided value conforms to {@link CustomFeePolicy}.
+ *
+ * Throws a validation error with annotated paths if the configuration is
+ * malformed.
+ *
+ * @param config - The custom fee policy to validate
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   calculateFee: () => '1000000',
+ *   resolveFeeRecipientAddress: () => '0x1234567890123456789012345678901234567890',
+ * }
+ * assertCustomFeePolicy(config)
+ * // If no error is thrown, `config` is a valid CustomFeePolicy
+ * ```
+ */
+function assertCustomFeePolicy(config) {
+    validateWithStateTracking(config, customFeePolicySchema, 'BridgeKit custom fee policy', assertCustomFeePolicySymbol);
+}
+
+/**
+ * Symbol used to track that assertBridgeParams has validated an object.
+ * @internal
+ */
+const ASSERT_BRIDGE_PARAMS_SYMBOL = Symbol('assertBridgeParams');
+/**
+ * Validates that source and destination chains are both testnet or both mainnet.
+ * @param fromData - Source chain data
+ * @param toData - Destination chain data
+ * @throws KitError If networks are mismatched
+ * @internal
+ */
+function validateNetworkMatch(fromData, toData) {
+    if (!isChainWithTestnet(fromData['chain']) ||
+        !isChainWithTestnet(toData['chain']) ||
+        fromData['chain'].isTestnet === toData['chain'].isTestnet) {
+        return;
+    }
+    throw new KitError({
+        ...InputError.NETWORK_MISMATCH,
+        recoverability: 'FATAL',
+        message: `Cannot bridge between ${fromData['chain'].name} (${fromData['chain'].isTestnet ? 'testnet' : 'mainnet'}) and ${toData['chain'].name} (${toData['chain'].isTestnet ? 'testnet' : 'mainnet'}). Source and destination networks must both be testnet or both be mainnet.`,
+        cause: {
+            trace: {
+                fromChain: fromData['chain'].name,
+                toChain: toData['chain'].name,
+                fromIsTestnet: fromData['chain'].isTestnet,
+                toIsTestnet: toData['chain'].isTestnet,
+            },
+        },
+    });
+}
+/**
+ * Validates that the address format matches the destination chain requirements.
+ * @param toData - Destination chain data containing address
+ * @throws KitError If address format is invalid for the chain
+ * @internal
+ */
+function validateAddressFormat(toData) {
+    if (typeof toData['address'] !== 'string') {
+        return;
+    }
+    const address = toData['address'];
+    const chain = getChainFromToData(toData);
+    if (chain !== null && !isValidAddressForChain(address, chain)) {
+        const chainInfo = extractChainInfo(chain);
+        throw createInvalidAddressError(address, chainInfo.displayName, chainInfo.expectedAddressFormat);
+    }
+}
+function assertBridgeParams(params, schema) {
+    // Use validateWithStateTracking to avoid duplicate validations
+    // This will skip validation if already validated by this function
+    try {
+        validateWithStateTracking(params, schema, 'bridge parameters', ASSERT_BRIDGE_PARAMS_SYMBOL);
+    }
+    catch (error) {
+        // Convert ValidationError to structured KitError
+        if (error instanceof ValidationError) {
+            // Extract the underlying Zod error from ValidationError
+            // ValidationError wraps the Zod validation failure
+            const result = schema.safeParse(params);
+            if (!result.success) {
+                throw convertZodErrorToStructured(result.error, params);
+            }
+        }
+        // Re-throw if it's not a ValidationError
+        throw error;
+    }
+    // Additional business logic checks that Zod cannot handle
+    const typedParams = params;
+    const fromData = extractFromData(typedParams);
+    const toData = extractToData(typedParams);
+    // Check for network mismatch if both chains have isTestnet property
+    if (fromData && toData) {
+        validateNetworkMatch(fromData, toData);
+    }
+    // Address format validation with chain context (if address provided)
+    if (toData) {
+        validateAddressFormat(toData);
+    }
+}
+
+// -----------------------------------------------------------------------------
+// Blockchain Enum
+// -----------------------------------------------------------------------------
+/**
+ * Enumeration of all blockchains supported by this library.
+ * @enum
+ * @category Enums
+ * @description Provides string identifiers for each supported blockchain.
+ */
+var Blockchain;
+(function (Blockchain) {
+    Blockchain["Algorand"] = "Algorand";
+    Blockchain["Algorand_Testnet"] = "Algorand_Testnet";
+    Blockchain["Aptos"] = "Aptos";
+    Blockchain["Aptos_Testnet"] = "Aptos_Testnet";
+    Blockchain["Arbitrum"] = "Arbitrum";
+    Blockchain["Arbitrum_Sepolia"] = "Arbitrum_Sepolia";
+    Blockchain["Avalanche"] = "Avalanche";
+    Blockchain["Avalanche_Fuji"] = "Avalanche_Fuji";
+    Blockchain["Base"] = "Base";
+    Blockchain["Base_Sepolia"] = "Base_Sepolia";
+    Blockchain["Celo"] = "Celo";
+    Blockchain["Celo_Alfajores_Testnet"] = "Celo_Alfajores_Testnet";
+    Blockchain["Codex"] = "Codex";
+    Blockchain["Codex_Testnet"] = "Codex_Testnet";
+    Blockchain["Ethereum"] = "Ethereum";
+    Blockchain["Ethereum_Sepolia"] = "Ethereum_Sepolia";
+    Blockchain["Hedera"] = "Hedera";
+    Blockchain["Hedera_Testnet"] = "Hedera_Testnet";
+    Blockchain["HyperEVM"] = "HyperEVM";
+    Blockchain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
+    Blockchain["Ink"] = "Ink";
+    Blockchain["Ink_Testnet"] = "Ink_Testnet";
+    Blockchain["Linea"] = "Linea";
+    Blockchain["Linea_Sepolia"] = "Linea_Sepolia";
+    Blockchain["NEAR"] = "NEAR";
+    Blockchain["NEAR_Testnet"] = "NEAR_Testnet";
+    Blockchain["Noble"] = "Noble";
+    Blockchain["Noble_Testnet"] = "Noble_Testnet";
+    Blockchain["Optimism"] = "Optimism";
+    Blockchain["Optimism_Sepolia"] = "Optimism_Sepolia";
+    Blockchain["Polkadot_Asset_Hub"] = "Polkadot_Asset_Hub";
+    Blockchain["Polkadot_Westmint"] = "Polkadot_Westmint";
+    Blockchain["Plume"] = "Plume";
+    Blockchain["Plume_Testnet"] = "Plume_Testnet";
+    Blockchain["Polygon"] = "Polygon";
+    Blockchain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
+    Blockchain["Sei"] = "Sei";
+    Blockchain["Sei_Testnet"] = "Sei_Testnet";
+    Blockchain["Solana"] = "Solana";
+    Blockchain["Solana_Devnet"] = "Solana_Devnet";
+    Blockchain["Sonic"] = "Sonic";
+    Blockchain["Sonic_Testnet"] = "Sonic_Testnet";
+    Blockchain["Stellar"] = "Stellar";
+    Blockchain["Stellar_Testnet"] = "Stellar_Testnet";
+    Blockchain["Sui"] = "Sui";
+    Blockchain["Sui_Testnet"] = "Sui_Testnet";
+    Blockchain["Unichain"] = "Unichain";
+    Blockchain["Unichain_Sepolia"] = "Unichain_Sepolia";
+    Blockchain["World_Chain"] = "World_Chain";
+    Blockchain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
+    Blockchain["XDC"] = "XDC";
+    Blockchain["XDC_Apothem"] = "XDC_Apothem";
+    Blockchain["ZKSync_Era"] = "ZKSync_Era";
+    Blockchain["ZKSync_Sepolia"] = "ZKSync_Sepolia";
+})(Blockchain || (Blockchain = {}));
+
+/**
+ * Helper function to define a chain with proper TypeScript typing.
+ *
+ * This utility function works with TypeScript's `as const` assertion to create
+ * strongly-typed, immutable chain definition objects. It preserves literal types
+ * from the input and ensures the resulting object maintains all type information.
+ *
+ * When used with `as const`, it allows TypeScript to infer the most specific
+ * possible types for all properties, including string literals and numeric literals,
+ * rather than widening them to general types like string or number.
+ * @typeParam T - The specific chain definition type (must extend ChainDefinition)
+ * @param chain - The chain definition object, typically with an `as const` assertion
+ * @returns The same chain definition with preserved literal types
+ * @example
+ * ```typescript
+ * // Define an EVM chain with literal types preserved
+ * const Ethereum = defineChain({
+ *   type: 'evm',
+ *   chain: Blockchain.Ethereum,
+ *   chainId: 1,
+ *   name: 'Ethereum',
+ *   nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+ *   isTestnet: false,
+ *   usdcAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *   eurcAddress: null,
+ *   cctp: {
+ *     domain: 0,
+ *     contracts: {
+ *       TokenMessengerV1: '0xbd3fa81b58ba92a82136038b25adec7066af3155',
+ *       MessageTransmitterV1: '0x0a992d191deec32afe36203ad87d7d289a738f81'
+ *     }
+ *   }
+ * } as const);
+ * ```
+ */
+function defineChain(chain) {
+    return chain;
+}
+
+/**
+ * Algorand Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Algorand blockchain.
+ */
+const Algorand = defineChain({
+    type: 'algorand',
+    chain: Blockchain.Algorand,
+    name: 'Algorand',
+    title: 'Algorand Mainnet',
+    nativeCurrency: {
+        name: 'Algo',
+        symbol: 'ALGO',
+        decimals: 6,
+    },
+    isTestnet: false,
+    explorerUrl: 'https://explorer.perawallet.app/tx/{hash}',
+    rpcEndpoints: ['https://mainnet-api.algonode.cloud'],
+    eurcAddress: null,
+    usdcAddress: '31566704',
+    cctp: null,
+});
+
+/**
+ * Algorand Testnet chain definition
+ * @remarks
+ * This represents the official testnet for the Algorand blockchain.
+ */
+const AlgorandTestnet = defineChain({
+    type: 'algorand',
+    chain: Blockchain.Algorand_Testnet,
+    name: 'Algorand Testnet',
+    title: 'Algorand Test Network',
+    nativeCurrency: {
+        name: 'Algo',
+        symbol: 'ALGO',
+        decimals: 6,
+    },
+    isTestnet: true,
+    explorerUrl: 'https://testnet.explorer.perawallet.app/tx/{hash}',
+    rpcEndpoints: ['https://testnet-api.algonode.cloud'],
+    eurcAddress: null,
+    usdcAddress: '10458941',
+    cctp: null,
+});
+
+/**
+ * Aptos Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Aptos blockchain.
+ */
+const Aptos = defineChain({
+    type: 'aptos',
+    chain: Blockchain.Aptos,
+    name: 'Aptos',
+    title: 'Aptos Mainnet',
+    nativeCurrency: {
+        name: 'Aptos',
+        symbol: 'APT',
+        decimals: 8,
+    },
+    isTestnet: false,
+    explorerUrl: 'https://explorer.aptoslabs.com/txn/{hash}?network=mainnet',
+    rpcEndpoints: ['https://fullnode.mainnet.aptoslabs.com/v1'],
+    eurcAddress: null,
+    usdcAddress: '0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b',
+    cctp: {
+        domain: 9,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x9bce6734f7b63e835108e3bd8c36743d4709fe435f44791918801d0989640a9d',
+                messageTransmitter: '0x177e17751820e4b4371873ca8c30279be63bdea63b88ed0f2239c2eea10f1772',
+                confirmations: 1,
+            },
+        },
+    },
+});
+
+/**
+ * Aptos Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Aptos blockchain.
+ */
+const AptosTestnet = defineChain({
+    type: 'aptos',
+    chain: Blockchain.Aptos_Testnet,
+    name: 'Aptos Testnet',
+    title: 'Aptos Test Network',
+    nativeCurrency: {
+        name: 'Aptos',
+        symbol: 'APT',
+        decimals: 8,
+    },
+    isTestnet: true,
+    explorerUrl: 'https://explorer.aptoslabs.com/txn/{hash}?network=testnet',
+    rpcEndpoints: ['https://fullnode.testnet.aptoslabs.com/v1'],
+    eurcAddress: null,
+    usdcAddress: '0x69091fbab5f7d635ee7ac5098cf0c1efbe31d68fec0f2cd565e8d168daf52832',
+    cctp: {
+        domain: 9,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x5f9b937419dda90aa06c1836b7847f65bbbe3f1217567758dc2488be31a477b9',
+                messageTransmitter: '0x081e86cebf457a0c6004f35bd648a2794698f52e0dde09a48619dcd3d4cc23d9',
+                confirmations: 1,
+            },
+        },
+    },
+});
+
+/**
+ * The bridge contract address for EVM testnet networks.
+ *
+ * This contract handles USDC transfers on testnet environments across
+ * EVM-compatible chains. Use this address when deploying or testing
+ * cross-chain USDC transfers on test networks.
+ */
+const BRIDGE_CONTRACT_EVM_TESTNET = '0xC5567a5E3370d4DBfB0540025078e283e36A363d';
+/**
+ * The bridge contract address for EVM mainnet networks.
+ *
+ * This contract handles USDC transfers on mainnet environments across
+ * EVM-compatible chains. Use this address for production cross-chain
+ * USDC transfers on live networks.
+ */
+const BRIDGE_CONTRACT_EVM_MAINNET = '0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0';
+
+/**
+ * Arbitrum Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Arbitrum blockchain.
+ */
+const Arbitrum = defineChain({
+    type: 'evm',
+    chain: Blockchain.Arbitrum,
+    name: 'Arbitrum',
+    title: 'Arbitrum Mainnet',
+    nativeCurrency: {
+        name: 'Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 42161,
+    isTestnet: false,
+    explorerUrl: 'https://arbiscan.io/tx/{hash}',
+    rpcEndpoints: ['https://arb1.arbitrum.io/rpc'],
+    eurcAddress: null,
+    usdcAddress: '0xaf88d065e77c8cc2239327c5edb3a432268e5831',
+    cctp: {
+        domain: 3,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x19330d10D9Cc8751218eaf51E8885D058642E08A',
+                messageTransmitter: '0xC30362313FBBA5cf9163F0bb16a0e01f01A896ca',
+                confirmations: 65,
+            },
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Arbitrum Sepolia Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Arbitrum blockchain on Sepolia.
+ */
+const ArbitrumSepolia = defineChain({
+    type: 'evm',
+    chain: Blockchain.Arbitrum_Sepolia,
+    name: 'Arbitrum Sepolia',
+    title: 'Arbitrum Sepolia Testnet',
+    nativeCurrency: {
+        name: 'Sepolia Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 421614,
+    isTestnet: true,
+    explorerUrl: 'https://sepolia.arbiscan.io/tx/{hash}',
+    rpcEndpoints: ['https://sepolia-rollup.arbitrum.io/rpc'],
+    eurcAddress: null,
+    usdcAddress: '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d',
+    cctp: {
+        domain: 3,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5',
+                messageTransmitter: '0xaCF1ceeF35caAc005e15888dDb8A3515C41B4872',
+                confirmations: 65,
+            },
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * Avalanche Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Avalanche blockchain.
+ */
+const Avalanche = defineChain({
+    type: 'evm',
+    chain: Blockchain.Avalanche,
+    name: 'Avalanche',
+    title: 'Avalanche Mainnet',
+    nativeCurrency: {
+        name: 'Avalanche',
+        symbol: 'AVAX',
+        decimals: 18,
+    },
+    chainId: 43114,
+    isTestnet: false,
+    explorerUrl: 'https://subnets.avax.network/c-chain/tx/{hash}',
+    rpcEndpoints: ['https://api.avax.network/ext/bc/C/rpc'],
+    eurcAddress: '0xc891eb4cbdeff6e073e859e987815ed1505c2acd',
+    usdcAddress: '0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E',
+    cctp: {
+        domain: 1,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x6b25532e1060ce10cc3b0a99e5683b91bfde6982',
+                messageTransmitter: '0x8186359af5f57fbb40c6b14a588d2a59c0c29880',
+                confirmations: 1,
+            },
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Avalanche Fuji Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Avalanche blockchain.
+ */
+const AvalancheFuji = defineChain({
+    type: 'evm',
+    chain: Blockchain.Avalanche_Fuji,
+    name: 'Avalanche Fuji',
+    title: 'Avalanche Fuji Testnet',
+    nativeCurrency: {
+        name: 'Avalanche',
+        symbol: 'AVAX',
+        decimals: 18,
+    },
+    chainId: 43113,
+    isTestnet: true,
+    explorerUrl: 'https://subnets-test.avax.network/c-chain/tx/{hash}',
+    eurcAddress: '0x5e44db7996c682e92a960b65ac713a54ad815c6b',
+    usdcAddress: '0x5425890298aed601595a70ab815c96711a31bc65',
+    cctp: {
+        domain: 1,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0xeb08f243e5d3fcff26a9e38ae5520a669f4019d0',
+                messageTransmitter: '0xa9fb1b3009dcb79e2fe346c16a604b8fa8ae0a79',
+                confirmations: 1,
+            },
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    rpcEndpoints: ['https://api.avax-test.network/ext/bc/C/rpc'],
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * Base chain definition
+ * @remarks
+ * This represents the official production network for the Base blockchain.
+ */
+const Base = defineChain({
+    type: 'evm',
+    chain: Blockchain.Base,
+    name: 'Base',
+    title: 'Base Mainnet',
+    nativeCurrency: {
+        name: 'Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 8453,
+    isTestnet: false,
+    explorerUrl: 'https://basescan.org/tx/{hash}',
+    rpcEndpoints: ['https://mainnet.base.org', 'https://base.publicnode.com'],
+    eurcAddress: '0x60a3e35cc302bfa44cb288bc5a4f316fdb1adb42',
+    usdcAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    cctp: {
+        domain: 6,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x1682Ae6375C4E4A97e4B583BC394c861A46D8962',
+                messageTransmitter: '0xAD09780d193884d503182aD4588450C416D6F9D4',
+                confirmations: 65,
+            },
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Base Sepolia Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Base blockchain on Sepolia.
+ */
+const BaseSepolia = defineChain({
+    type: 'evm',
+    chain: Blockchain.Base_Sepolia,
+    name: 'Base Sepolia',
+    title: 'Base Sepolia Testnet',
+    nativeCurrency: {
+        name: 'Sepolia Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 84532,
+    isTestnet: true,
+    explorerUrl: 'https://sepolia.basescan.org/tx/{hash}',
+    rpcEndpoints: ['https://sepolia.base.org'],
+    eurcAddress: '0x808456652fdb597867f38412077A9182bf77359F',
+    usdcAddress: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+    cctp: {
+        domain: 6,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5',
+                messageTransmitter: '0x7865fAfC2db2093669d92c0F33AeEF291086BEFD',
+                confirmations: 65,
+            },
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * Celo Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Celo blockchain.
+ */
+const Celo = defineChain({
+    type: 'evm',
+    chain: Blockchain.Celo,
+    name: 'Celo',
+    title: 'Celo Mainnet',
+    nativeCurrency: {
+        name: 'Celo',
+        symbol: 'CELO',
+        decimals: 18,
+    },
+    chainId: 42220,
+    isTestnet: false,
+    explorerUrl: 'https://celoscan.io/tx/{hash}',
+    rpcEndpoints: ['https://forno.celo.org'],
+    eurcAddress: null,
+    usdcAddress: '0xcebA9300f2b948710d2653dD7B07f33A8B32118C',
+    cctp: null,
+});
+
+/**
+ * Celo Alfajores Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Celo blockchain.
+ */
+const CeloAlfajoresTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Celo_Alfajores_Testnet,
+    name: 'Celo Alfajores',
+    title: 'Celo Alfajores Testnet',
+    nativeCurrency: {
+        name: 'Celo',
+        symbol: 'CELO',
+        decimals: 18,
+    },
+    chainId: 44787,
+    isTestnet: true,
+    explorerUrl: 'https://alfajores.celoscan.io/tx/{hash}',
+    rpcEndpoints: ['https://alfajores-forno.celo-testnet.org'],
+    eurcAddress: null,
+    usdcAddress: '0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B',
+    cctp: null,
+});
+
+/**
+ * Codex Mainnet chain definition
+ * @remarks
+ * This represents the main network for the Codex blockchain.
+ */
+const Codex = defineChain({
+    type: 'evm',
+    chain: Blockchain.Codex,
+    name: 'Codex Mainnet',
+    title: 'Codex Mainnet',
+    nativeCurrency: {
+        name: 'ETH',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 81224,
+    isTestnet: false,
+    explorerUrl: 'https://explorer.codex.xyz/tx/{hash}',
+    rpcEndpoints: ['https://rpc.codex.xyz'],
+    eurcAddress: null,
+    usdcAddress: '0xd996633a415985DBd7D6D12f4A4343E31f5037cf',
+    cctp: {
+        domain: 12,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Codex Testnet chain definition
+ * @remarks
+ * This represents the test network for the Codex blockchain.
+ */
+const CodexTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Codex_Testnet,
+    name: 'Codex Testnet',
+    title: 'Codex Testnet',
+    nativeCurrency: {
+        name: 'ETH',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 812242,
+    isTestnet: true,
+    explorerUrl: 'https://explorer.codex-stg.xyz/tx/{hash}',
+    rpcEndpoints: ['https://rpc.codex-stg.xyz'],
+    eurcAddress: null,
+    usdcAddress: '0x6d7f141b6819C2c9CC2f818e6ad549E7Ca090F8f',
+    cctp: {
+        domain: 12,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * Ethereum Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Ethereum blockchain.
+ */
+const Ethereum = defineChain({
+    type: 'evm',
+    chain: Blockchain.Ethereum,
+    name: 'Ethereum',
+    title: 'Ethereum Mainnet',
+    nativeCurrency: {
+        name: 'Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 1,
+    isTestnet: false,
+    explorerUrl: 'https://etherscan.io/tx/{hash}',
+    rpcEndpoints: ['https://eth.merkle.io', 'https://ethereum.publicnode.com'],
+    eurcAddress: '0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c',
+    usdcAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+    cctp: {
+        domain: 0,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0xbd3fa81b58ba92a82136038b25adec7066af3155',
+                messageTransmitter: '0x0a992d191deec32afe36203ad87d7d289a738f81',
+                confirmations: 65,
+            },
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 65,
+                fastConfirmations: 2,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Ethereum Sepolia Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Ethereum blockchain on Sepolia.
+ */
+const EthereumSepolia = defineChain({
+    type: 'evm',
+    chain: Blockchain.Ethereum_Sepolia,
+    name: 'Ethereum Sepolia',
+    title: 'Ethereum Sepolia Testnet',
+    nativeCurrency: {
+        name: 'Sepolia Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 11155111,
+    isTestnet: true,
+    explorerUrl: 'https://sepolia.etherscan.io/tx/{hash}',
+    rpcEndpoints: ['https://sepolia.drpc.org'],
+    eurcAddress: '0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4',
+    usdcAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
+    cctp: {
+        domain: 0,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5',
+                messageTransmitter: '0x7865fAfC2db2093669d92c0F33AeEF291086BEFD',
+                confirmations: 65,
+            },
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
+                confirmations: 65,
+                fastConfirmations: 2,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * Hedera Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Hedera blockchain.
+ */
+const Hedera = defineChain({
+    type: 'hedera',
+    chain: Blockchain.Hedera,
+    name: 'Hedera',
+    title: 'Hedera Mainnet',
+    nativeCurrency: {
+        name: 'HBAR',
+        symbol: 'HBAR',
+        decimals: 18,
+    },
+    isTestnet: false,
+    explorerUrl: 'https://hashscan.io/mainnet/transaction/{hash}', // Note: Hedera uses `transaction_id`, not hash. Format is typically `0.0.X-YYYY...`.
+    rpcEndpoints: ['https://mainnet.hashio.io/api'],
+    eurcAddress: null,
+    usdcAddress: '0.0.456858',
+    cctp: null,
+});
+
+/**
+ * Hedera Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Hedera blockchain.
+ */
+const HederaTestnet = defineChain({
+    type: 'hedera',
+    chain: Blockchain.Hedera_Testnet,
+    name: 'Hedera Testnet',
+    title: 'Hedera Test Network',
+    nativeCurrency: {
+        name: 'HBAR',
+        symbol: 'HBAR',
+        decimals: 18,
+    },
+    isTestnet: true,
+    explorerUrl: 'https://hashscan.io/testnet/transaction/{hash}', // Note: Hedera uses `transaction_id`, not hash. Format is typically `0.0.X-YYYY...`.
+    rpcEndpoints: ['https://testnet.hashio.io/api'],
+    eurcAddress: null,
+    usdcAddress: '0.0.429274',
+    cctp: null,
+});
+
+/**
+ * HyperEVM Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the HyperEVM blockchain.
+ * HyperEVM is a Layer 1 blockchain specialized for DeFi and trading applications
+ * with native orderbook and matching engine.
+ */
+const HyperEVM = defineChain({
+    type: 'evm',
+    chain: Blockchain.HyperEVM,
+    name: 'HyperEVM',
+    title: 'HyperEVM Mainnet',
+    nativeCurrency: {
+        name: 'Hype',
+        symbol: 'HYPE',
+        decimals: 18,
+    },
+    chainId: 999,
+    isTestnet: false,
+    explorerUrl: 'https://hyperevmscan.io/tx/{hash}',
+    rpcEndpoints: ['https://rpc.hyperliquid.xyz/evm'],
+    eurcAddress: null,
+    usdcAddress: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
+    cctp: {
+        domain: 19,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * HyperEVM Testnet chain definition
+ * @remarks
+ * This represents the official testnet for the HyperEVM blockchain.
+ * Used for development and testing purposes before deploying to mainnet.
+ */
+const HyperEVMTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.HyperEVM_Testnet,
+    name: 'HyperEVM Testnet',
+    title: 'HyperEVM Test Network',
+    nativeCurrency: {
+        name: 'Hype',
+        symbol: 'HYPE',
+        decimals: 18,
+    },
+    chainId: 998,
+    isTestnet: true,
+    explorerUrl: 'https://testnet.hyperliquid.xyz/explorer/tx/{hash}',
+    rpcEndpoints: ['https://rpc.hyperliquid-testnet.xyz/evm'],
+    eurcAddress: null,
+    usdcAddress: '0x2B3370eE501B4a559b57D449569354196457D8Ab',
+    cctp: {
+        domain: 19,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * Ink Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Ink blockchain.
+ * Ink is a Layer 1 blockchain specialized for DeFi and trading applications
+ * with native orderbook and matching engine.
+ */
+const Ink = defineChain({
+    type: 'evm',
+    chain: Blockchain.Ink,
+    name: 'Ink',
+    title: 'Ink Mainnet',
+    nativeCurrency: {
+        name: 'Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 57073,
+    isTestnet: false,
+    explorerUrl: 'https://explorer.inkonchain.com/tx/{hash}',
+    rpcEndpoints: [
+        'https://rpc-gel.inkonchain.com',
+        'https://rpc-qnd.inkonchain.com',
+    ],
+    eurcAddress: null,
+    usdcAddress: '0x2D270e6886d130D724215A266106e6832161EAEd',
+    cctp: {
+        domain: 21,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Ink Testnet chain definition
+ * @remarks
+ * This represents the official testnet for the Ink blockchain.
+ * Used for development and testing purposes before deploying to mainnet.
+ */
+const InkTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Ink_Testnet,
+    name: 'Ink Sepolia',
+    title: 'Ink Sepolia Testnet',
+    nativeCurrency: {
+        name: 'Sepolia Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 763373,
+    isTestnet: true,
+    explorerUrl: 'https://explorer-sepolia.inkonchain.com/tx/{hash}',
+    rpcEndpoints: [
+        'https://rpc-gel-sepolia.inkonchain.com',
+        'https://rpc-qnd-sepolia.inkonchain.com',
+    ],
+    eurcAddress: null,
+    usdcAddress: '0xFabab97dCE620294D2B0b0e46C68964e326300Ac',
+    cctp: {
+        domain: 21,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * Linea Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Linea blockchain.
+ */
+const Linea = defineChain({
+    type: 'evm',
+    chain: Blockchain.Linea,
+    name: 'Linea',
+    title: 'Linea Mainnet',
+    nativeCurrency: {
+        name: 'Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 59144,
+    isTestnet: false,
+    explorerUrl: 'https://lineascan.build/tx/{hash}',
+    rpcEndpoints: ['https://rpc.linea.build'],
+    eurcAddress: null,
+    usdcAddress: '0x176211869ca2b568f2a7d4ee941e073a821ee1ff',
+    cctp: {
+        domain: 11,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Linea Sepolia Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Linea blockchain on Sepolia.
+ */
+const LineaSepolia = defineChain({
+    type: 'evm',
+    chain: Blockchain.Linea_Sepolia,
+    name: 'Linea Sepolia',
+    title: 'Linea Sepolia Testnet',
+    nativeCurrency: {
+        name: 'Sepolia Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 59141,
+    isTestnet: true,
+    explorerUrl: 'https://sepolia.lineascan.build/tx/{hash}',
+    rpcEndpoints: ['https://rpc.sepolia.linea.build'],
+    eurcAddress: null,
+    usdcAddress: '0xfece4462d57bd51a6a552365a011b95f0e16d9b7',
+    cctp: {
+        domain: 11,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * NEAR Protocol Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the NEAR Protocol blockchain.
+ */
+const NEAR = defineChain({
+    type: 'near',
+    chain: Blockchain.NEAR,
+    name: 'NEAR Protocol',
+    title: 'NEAR Mainnet',
+    nativeCurrency: {
+        name: 'NEAR',
+        symbol: 'NEAR',
+        decimals: 24,
+    },
+    isTestnet: false,
+    explorerUrl: 'https://nearblocks.io/txns/{hash}',
+    rpcEndpoints: ['https://eth-rpc.mainnet.near.org'],
+    eurcAddress: null,
+    usdcAddress: '17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1',
+    cctp: null,
+});
+
+/**
+ * NEAR Testnet chain definition
+ * @remarks
+ * This represents the official test network for the NEAR Protocol blockchain.
+ */
+const NEARTestnet = defineChain({
+    type: 'near',
+    chain: Blockchain.NEAR_Testnet,
+    name: 'NEAR Protocol Testnet',
+    title: 'NEAR Test Network',
+    nativeCurrency: {
+        name: 'NEAR',
+        symbol: 'NEAR',
+        decimals: 24,
+    },
+    isTestnet: true,
+    explorerUrl: 'https://testnet.nearblocks.io/txns/{hash}',
+    rpcEndpoints: ['https://eth-rpc.testnet.near.org'],
+    eurcAddress: null,
+    usdcAddress: '3e2210e1184b45b64c8a434c0a7e7b23cc04ea7eb7a6c3c32520d03d4afcb8af',
+    cctp: null,
+});
+
+/**
+ * Noble Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Noble blockchain.
+ */
+const Noble = defineChain({
+    type: 'noble',
+    chain: Blockchain.Noble,
+    name: 'Noble',
+    title: 'Noble Mainnet',
+    nativeCurrency: {
+        name: 'Noble USDC',
+        symbol: 'USDC',
+        decimals: 6,
+    },
+    isTestnet: false,
+    explorerUrl: 'https://www.mintscan.io/noble/tx/{hash}',
+    rpcEndpoints: ['https://noble-rpc.polkachu.com'],
+    eurcAddress: null,
+    usdcAddress: 'uusdc',
+    cctp: {
+        domain: 4,
+        contracts: {
+            v1: {
+                type: 'merged',
+                contract: 'noble12l2w4ugfz4m6dd73yysz477jszqnfughxvkss5',
+                confirmations: 1,
+            },
+        },
+    },
+});
+
+/**
+ * Noble Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Noble blockchain.
+ */
+const NobleTestnet = defineChain({
+    type: 'noble',
+    chain: Blockchain.Noble_Testnet,
+    name: 'Noble Testnet',
+    title: 'Noble Test Network',
+    nativeCurrency: {
+        name: 'Noble USDC',
+        symbol: 'USDC',
+        decimals: 6,
+    },
+    isTestnet: true,
+    explorerUrl: 'https://www.mintscan.io/noble-testnet/tx/{hash}',
+    rpcEndpoints: ['https://noble-testnet-rpc.polkachu.com'],
+    eurcAddress: null,
+    usdcAddress: 'uusdc',
+    cctp: {
+        domain: 4,
+        contracts: {
+            v1: {
+                type: 'merged',
+                contract: 'noble12l2w4ugfz4m6dd73yysz477jszqnfughxvkss5',
+                confirmations: 1,
+            },
+        },
+    },
+});
+
+/**
+ * Optimism Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Optimism blockchain.
+ */
+const Optimism = defineChain({
+    type: 'evm',
+    chain: Blockchain.Optimism,
+    name: 'Optimism',
+    title: 'Optimism Mainnet',
+    nativeCurrency: {
+        name: 'Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 10,
+    isTestnet: false,
+    explorerUrl: 'https://optimistic.etherscan.io/tx/{hash}',
+    rpcEndpoints: ['https://mainnet.optimism.io'],
+    eurcAddress: null,
+    usdcAddress: '0x0b2c639c533813f4aa9d7837caf62653d097ff85',
+    cctp: {
+        domain: 2,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x2B4069517957735bE00ceE0fadAE88a26365528f',
+                messageTransmitter: '0x0a992d191deec32afe36203ad87d7d289a738f81',
+                confirmations: 65,
+            },
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Optimism Sepolia Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Optimism blockchain on Sepolia.
+ */
+const OptimismSepolia = defineChain({
+    type: 'evm',
+    chain: Blockchain.Optimism_Sepolia,
+    name: 'Optimism Sepolia',
+    title: 'Optimism Sepolia Testnet',
+    nativeCurrency: {
+        name: 'Sepolia Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 11155420,
+    isTestnet: true,
+    explorerUrl: 'https://sepolia-optimistic.etherscan.io/tx/{hash}',
+    rpcEndpoints: ['https://sepolia.optimism.io'],
+    eurcAddress: null,
+    usdcAddress: '0x5fd84259d66Cd46123540766Be93DFE6D43130D7',
+    cctp: {
+        domain: 2,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5',
+                messageTransmitter: '0x7865fAfC2db2093669d92c0F33AeEF291086BEFD',
+                confirmations: 65,
+            },
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * Plume Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Plume blockchain.
+ * Plume is a Layer 1 blockchain specialized for DeFi and trading applications
+ * with native orderbook and matching engine.
+ */
+const Plume = defineChain({
+    type: 'evm',
+    chain: Blockchain.Plume,
+    name: 'Plume',
+    title: 'Plume Mainnet',
+    nativeCurrency: {
+        name: 'Plume',
+        symbol: 'PLUME',
+        decimals: 18,
+    },
+    chainId: 98866,
+    isTestnet: false,
+    explorerUrl: 'https://explorer.plume.org/tx/{hash}',
+    rpcEndpoints: ['https://rpc.plume.org'],
+    eurcAddress: null,
+    usdcAddress: '0x222365EF19F7947e5484218551B56bb3965Aa7aF',
+    cctp: {
+        domain: 22,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Plume Testnet chain definition
+ * @remarks
+ * This represents the official testnet for the Plume blockchain.
+ * Used for development and testing purposes before deploying to mainnet.
+ */
+const PlumeTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Plume_Testnet,
+    name: 'Plume Testnet',
+    title: 'Plume Test Network',
+    nativeCurrency: {
+        name: 'Plume',
+        symbol: 'PLUME',
+        decimals: 18,
+    },
+    chainId: 98867,
+    isTestnet: true,
+    explorerUrl: 'https://testnet-explorer.plume.org/tx/{hash}',
+    rpcEndpoints: ['https://testnet-rpc.plume.org'],
+    eurcAddress: null,
+    usdcAddress: '0xcB5f30e335672893c7eb944B374c196392C19D18',
+    cctp: {
+        domain: 22,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * Polkadot Asset Hub chain definition
+ * @remarks
+ * This represents the official asset management parachain for the Polkadot blockchain.
+ */
+const PolkadotAssetHub = defineChain({
+    type: 'polkadot',
+    chain: Blockchain.Polkadot_Asset_Hub,
+    name: 'Polkadot Asset Hub',
+    title: 'Polkadot Asset Hub',
+    nativeCurrency: {
+        name: 'Polkadot',
+        symbol: 'DOT',
+        decimals: 10,
+    },
+    isTestnet: false,
+    explorerUrl: 'https://polkadot.subscan.io/extrinsic/{hash}',
+    rpcEndpoints: ['https://asset-hub-polkadot-rpc.n.dwellir.com'],
+    eurcAddress: null,
+    usdcAddress: '1337',
+    cctp: null,
+});
+
+/**
+ * Polkadot Westmint chain definition
+ * @remarks
+ * This represents an asset management parachain in the Polkadot ecosystem.
+ */
+const PolkadotWestmint = defineChain({
+    type: 'polkadot',
+    chain: Blockchain.Polkadot_Westmint,
+    name: 'Polkadot Westmint',
+    title: 'Polkadot Westmint',
+    nativeCurrency: {
+        name: 'Polkadot',
+        symbol: 'DOT',
+        decimals: 10,
+    },
+    isTestnet: false,
+    explorerUrl: 'https://assethub-polkadot.subscan.io/extrinsic/{hash}',
+    rpcEndpoints: ['https://westmint-rpc.polkadot.io'],
+    eurcAddress: null,
+    usdcAddress: 'Asset ID 31337',
+    cctp: null,
+});
+
+/**
+ * Polygon Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Polygon blockchain.
+ */
+const Polygon = defineChain({
+    type: 'evm',
+    chain: Blockchain.Polygon,
+    name: 'Polygon',
+    title: 'Polygon Mainnet',
+    nativeCurrency: {
+        name: 'POL',
+        symbol: 'POL',
+        decimals: 18,
+    },
+    chainId: 137,
+    isTestnet: false,
+    explorerUrl: 'https://polygonscan.com/tx/{hash}',
+    rpcEndpoints: ['https://polygon-rpc.com', 'https://polygon.publicnode.com'],
+    eurcAddress: null,
+    usdcAddress: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359',
+    cctp: {
+        domain: 7,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x9daF8c91AEFAE50b9c0E69629D3F6Ca40cA3B3FE',
+                messageTransmitter: '0xF3be9355363857F3e001be68856A2f96b4C39Ba9',
+                confirmations: 200,
+            },
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 33,
+                fastConfirmations: 13,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Polygon Amoy Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Polygon blockchain.
+ */
+const PolygonAmoy = defineChain({
+    type: 'evm',
+    chain: Blockchain.Polygon_Amoy_Testnet,
+    name: 'Polygon Amoy',
+    title: 'Polygon Amoy Testnet',
+    nativeCurrency: {
+        name: 'POL',
+        symbol: 'POL',
+        decimals: 18,
+    },
+    chainId: 80002,
+    isTestnet: true,
+    explorerUrl: 'https://amoy.polygonscan.com/tx/{hash}',
+    rpcEndpoints: ['https://rpc-amoy.polygon.technology'],
+    eurcAddress: null,
+    usdcAddress: '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582',
+    cctp: {
+        domain: 7,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5',
+                messageTransmitter: '0x7865fAfC2db2093669d92c0F33AeEF291086BEFD',
+                confirmations: 200,
+            },
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 33,
+                fastConfirmations: 13,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * Sei Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Sei blockchain.
+ * Sei is a Layer 1 blockchain specialized for DeFi and trading applications
+ * with native orderbook and matching engine.
+ */
+const Sei = defineChain({
+    type: 'evm',
+    chain: Blockchain.Sei,
+    name: 'Sei',
+    title: 'Sei Mainnet',
+    nativeCurrency: {
+        name: 'Sei',
+        symbol: 'SEI',
+        decimals: 18,
+    },
+    chainId: 1329,
+    isTestnet: false,
+    explorerUrl: 'https://seitrace.com/tx/{hash}?chain=pacific-1',
+    rpcEndpoints: ['https://evm-rpc.sei-apis.com'],
+    eurcAddress: null,
+    usdcAddress: '0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392',
+    cctp: {
+        domain: 16,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Sei Testnet chain definition
+ * @remarks
+ * This represents the official testnet for the Sei blockchain.
+ * Used for development and testing purposes before deploying to mainnet.
+ */
+const SeiTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Sei_Testnet,
+    name: 'Sei Testnet',
+    title: 'Sei Test Network',
+    nativeCurrency: {
+        name: 'Sei',
+        symbol: 'SEI',
+        decimals: 18,
+    },
+    chainId: 1328,
+    isTestnet: true,
+    explorerUrl: 'https://seitrace.com/tx/{hash}?chain=atlantic-2',
+    rpcEndpoints: ['https://evm-rpc-testnet.sei-apis.com'],
+    eurcAddress: null,
+    usdcAddress: '0x4fCF1784B31630811181f670Aea7A7bEF803eaED',
+    cctp: {
+        domain: 16,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * Sonic Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Sonic blockchain.
+ */
+const Sonic = defineChain({
+    type: 'evm',
+    chain: Blockchain.Sonic,
+    name: 'Sonic',
+    title: 'Sonic Mainnet',
+    nativeCurrency: {
+        name: 'Sonic',
+        symbol: 'S',
+        decimals: 18,
+    },
+    chainId: 146,
+    isTestnet: false,
+    explorerUrl: 'https://sonicscan.org/tx/{hash}',
+    rpcEndpoints: ['https://rpc.soniclabs.com'],
+    eurcAddress: null,
+    usdcAddress: '0x29219dd400f2Bf60E5a23d13Be72B486D4038894',
+    cctp: {
+        domain: 13,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Sonic Blaze Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Sonic blockchain.
+ */
+const SonicTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Sonic_Testnet,
+    name: 'Sonic Blaze Testnet',
+    title: 'Sonic Blaze Testnet',
+    nativeCurrency: {
+        name: 'Sonic',
+        symbol: 'S',
+        decimals: 18,
+    },
+    chainId: 57054,
+    isTestnet: true,
+    explorerUrl: 'https://testnet.sonicscan.org/tx/{hash}',
+    rpcEndpoints: ['https://rpc.blaze.soniclabs.com'],
+    eurcAddress: null,
+    usdcAddress: '0xA4879Fed32Ecbef99399e5cbC247E533421C4eC6',
+    cctp: {
+        domain: 13,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * Solana Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Solana blockchain.
+ */
+const Solana = defineChain({
+    type: 'solana',
+    chain: Blockchain.Solana,
+    name: 'Solana',
+    title: 'Solana Mainnet',
+    nativeCurrency: {
+        name: 'Solana',
+        symbol: 'SOL',
+        decimals: 9,
+    },
+    isTestnet: false,
+    explorerUrl: 'https://solscan.io/tx/{hash}',
+    rpcEndpoints: ['https://api.mainnet-beta.solana.com'],
+    eurcAddress: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
+    usdcAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+    cctp: {
+        domain: 5,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: 'CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3',
+                messageTransmitter: 'CCTPmbSD7gX1bxKPAmg77w8oFzNFpaQiQUWD43TKaecd',
+                confirmations: 32,
+            },
+            v2: {
+                type: 'split',
+                tokenMessenger: 'CCTPV2vPZJS2u2BBsUoscuikbYjnpFmbFsvVuJdgUMQe',
+                messageTransmitter: 'CCTPV2Sm4AdWt5296sk4P66VBZ7bEhcARwFaaS9YPbeC',
+                confirmations: 32,
+                fastConfirmations: 3,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: 'DFaauJEjmiHkPs1JG89A4p95hDWi9m9SAEERY1LQJiC3',
+    },
+});
+
+/**
+ * Solana Devnet chain definition
+ * @remarks
+ * This represents the development test network for the Solana blockchain.
+ */
+const SolanaDevnet = defineChain({
+    type: 'solana',
+    chain: Blockchain.Solana_Devnet,
+    name: 'Solana Devnet',
+    title: 'Solana Development Network',
+    nativeCurrency: {
+        name: 'Solana',
+        symbol: 'SOL',
+        decimals: 9,
+    },
+    isTestnet: true,
+    explorerUrl: 'https://solscan.io/tx/{hash}?cluster=devnet',
+    eurcAddress: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
+    usdcAddress: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU',
+    cctp: {
+        domain: 5,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: 'CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3',
+                messageTransmitter: 'CCTPmbSD7gX1bxKPAmg77w8oFzNFpaQiQUWD43TKaecd',
+                confirmations: 32,
+            },
+            v2: {
+                type: 'split',
+                tokenMessenger: 'CCTPV2vPZJS2u2BBsUoscuikbYjnpFmbFsvVuJdgUMQe',
+                messageTransmitter: 'CCTPV2Sm4AdWt5296sk4P66VBZ7bEhcARwFaaS9YPbeC',
+                confirmations: 32,
+                fastConfirmations: 3,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: 'DFaauJEjmiHkPs1JG89A4p95hDWi9m9SAEERY1LQJiC3',
+    },
+    rpcEndpoints: ['https://api.devnet.solana.com'],
+});
+
+/**
+ * Stellar Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Stellar blockchain.
+ */
+const Stellar = defineChain({
+    type: 'stellar',
+    chain: Blockchain.Stellar,
+    name: 'Stellar',
+    title: 'Stellar Mainnet',
+    nativeCurrency: {
+        name: 'Stellar Lumens',
+        symbol: 'XLM',
+        decimals: 7,
+    },
+    isTestnet: false,
+    explorerUrl: 'https://stellar.expert/explorer/public/tx/{hash}',
+    rpcEndpoints: ['https://horizon.stellar.org'],
+    eurcAddress: 'EURC-GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP2',
+    usdcAddress: 'USDC-GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN',
+    cctp: null,
+});
+
+/**
+ * Stellar Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Stellar blockchain.
+ */
+const StellarTestnet = defineChain({
+    type: 'stellar',
+    chain: Blockchain.Stellar_Testnet,
+    name: 'Stellar Testnet',
+    title: 'Stellar Test Network',
+    nativeCurrency: {
+        name: 'Stellar Lumens',
+        symbol: 'XLM',
+        decimals: 7,
+    },
+    isTestnet: true,
+    explorerUrl: 'https://stellar.expert/explorer/testnet/tx/{hash}',
+    rpcEndpoints: ['https://horizon-testnet.stellar.org'],
+    eurcAddress: 'EURC-GB3Q6QDZYTHWT7E5PVS3W7FUT5GVAFC5KSZFFLPU25GO7VTC3NM2ZTVO',
+    usdcAddress: 'USDC-GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5',
+    cctp: null,
+});
+
+/**
+ * Sui Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Sui blockchain.
+ */
+const Sui = defineChain({
+    type: 'sui',
+    chain: Blockchain.Sui,
+    name: 'Sui',
+    title: 'Sui Mainnet',
+    nativeCurrency: {
+        name: 'Sui',
+        symbol: 'SUI',
+        decimals: 9,
+    },
+    isTestnet: false,
+    explorerUrl: 'https://suiscan.xyz/mainnet/tx/{hash}',
+    rpcEndpoints: ['https://fullnode.mainnet.sui.io'],
+    eurcAddress: null,
+    usdcAddress: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC',
+    cctp: {
+        domain: 8,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x2aa6c5d56376c371f88a6cc42e852824994993cb9bab8d3e6450cbe3cb32b94e',
+                messageTransmitter: '0x08d87d37ba49e785dde270a83f8e979605b03dc552b5548f26fdf2f49bf7ed1b',
+                confirmations: 1,
+            },
+        },
+    },
+});
+
+/**
+ * Sui Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Sui blockchain.
+ */
+const SuiTestnet = defineChain({
+    type: 'sui',
+    chain: Blockchain.Sui_Testnet,
+    name: 'Sui Testnet',
+    title: 'Sui Test Network',
+    nativeCurrency: {
+        name: 'Sui',
+        symbol: 'SUI',
+        decimals: 9,
+    },
+    isTestnet: true,
+    explorerUrl: 'https://suiscan.xyz/testnet/tx/{hash}',
+    rpcEndpoints: ['https://fullnode.testnet.sui.io'],
+    eurcAddress: null,
+    usdcAddress: '0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC',
+    cctp: {
+        domain: 8,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x31cc14d80c175ae39777c0238f20594c6d4869cfab199f40b69f3319956b8beb',
+                messageTransmitter: '0x4931e06dce648b3931f890035bd196920770e913e43e45990b383f6486fdd0a5',
+                confirmations: 1,
+            },
+        },
+    },
+});
+
+/**
+ * Unichain Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Unichain blockchain.
+ */
+const Unichain = defineChain({
+    type: 'evm',
+    chain: Blockchain.Unichain,
+    name: 'Unichain',
+    title: 'Unichain Mainnet',
+    nativeCurrency: {
+        name: 'Uni',
+        symbol: 'UNI',
+        decimals: 18,
+    },
+    chainId: 130,
+    isTestnet: false,
+    explorerUrl: 'https://unichain.blockscout.com/tx/{hash}',
+    rpcEndpoints: ['https://rpc.unichain.org', 'https://mainnet.unichain.org'],
+    eurcAddress: null,
+    usdcAddress: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
+    cctp: {
+        domain: 10,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x4e744b28E787c3aD0e810eD65A24461D4ac5a762',
+                messageTransmitter: '0x353bE9E2E38AB1D19104534e4edC21c643Df86f4',
+                confirmations: 65,
+            },
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Unichain Sepolia Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Unichain blockchain.
+ */
+const UnichainSepolia = defineChain({
+    type: 'evm',
+    chain: Blockchain.Unichain_Sepolia,
+    name: 'Unichain Sepolia',
+    title: 'Unichain Sepolia Testnet',
+    nativeCurrency: {
+        name: 'Sepolia Uni',
+        symbol: 'UNI',
+        decimals: 18,
+    },
+    chainId: 1301,
+    isTestnet: true,
+    explorerUrl: 'https://unichain-sepolia.blockscout.com/tx/{hash}',
+    rpcEndpoints: ['https://sepolia.unichain.org'],
+    eurcAddress: null,
+    usdcAddress: '0x31d0220469e10c4E71834a79b1f276d740d3768F',
+    cctp: {
+        domain: 10,
+        contracts: {
+            v1: {
+                type: 'split',
+                tokenMessenger: '0x8ed94B8dAd2Dc5453862ea5e316A8e71AAed9782',
+                messageTransmitter: '0xbc498c326533d675cf571B90A2Ced265ACb7d086',
+                confirmations: 65,
+            },
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * World Chain chain definition
+ * @remarks
+ * This represents the main network for the World Chain blockchain.
+ */
+const WorldChain = defineChain({
+    type: 'evm',
+    chain: Blockchain.World_Chain,
+    name: 'World Chain',
+    title: 'World Chain',
+    nativeCurrency: {
+        name: 'Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 480,
+    isTestnet: false,
+    explorerUrl: 'https://worldscan.org/tx/{hash}',
+    rpcEndpoints: ['https://worldchain-mainnet.g.alchemy.com/public'],
+    eurcAddress: null,
+    usdcAddress: '0x79A02482A880bCe3F13E09da970dC34dB4cD24D1',
+    cctp: {
+        domain: 14,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cF5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * World Chain Sepolia chain definition
+ * @remarks
+ * This represents the test network for the World Chain blockchain.
+ */
+const WorldChainSepolia = defineChain({
+    type: 'evm',
+    chain: Blockchain.World_Chain_Sepolia,
+    name: 'World Chain Sepolia',
+    title: 'World Chain Sepolia',
+    nativeCurrency: {
+        name: 'Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 4801,
+    isTestnet: true,
+    explorerUrl: 'https://sepolia.worldscan.org/tx/{hash}',
+    rpcEndpoints: [
+        'https://worldchain-sepolia.drpc.org',
+        'https://worldchain-sepolia.g.alchemy.com/public',
+    ],
+    eurcAddress: null,
+    usdcAddress: '0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88',
+    cctp: {
+        domain: 14,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
+                confirmations: 65,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * XDC Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the XDC blockchain.
+ * XDC is a Layer 1 blockchain specialized for DeFi and trading applications
+ * with native orderbook and matching engine.
+ */
+const XDC = defineChain({
+    type: 'evm',
+    chain: Blockchain.XDC,
+    name: 'XDC',
+    title: 'XDC Mainnet',
+    nativeCurrency: {
+        name: 'XDC',
+        symbol: 'XDC',
+        decimals: 18,
+    },
+    chainId: 50,
+    isTestnet: false,
+    explorerUrl: 'https://xdcscan.io/tx/{hash}',
+    rpcEndpoints: ['https://erpc.xinfin.network'],
+    eurcAddress: null,
+    usdcAddress: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
+    cctp: {
+        domain: 18,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 3,
+                fastConfirmations: 3,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * XDC Apothem Testnet chain definition
+ * @remarks
+ * This represents the official test network for the XDC Network, known as Apothem.
+ */
+const XDCApothem = defineChain({
+    type: 'evm',
+    chain: Blockchain.XDC_Apothem,
+    name: 'Apothem Network',
+    title: 'Apothem Network',
+    nativeCurrency: {
+        name: 'TXDC',
+        symbol: 'TXDC',
+        decimals: 18,
+    },
+    chainId: 51,
+    isTestnet: true,
+    explorerUrl: 'https://testnet.xdcscan.com/tx/{hash}',
+    rpcEndpoints: ['https://erpc.apothem.network'],
+    eurcAddress: null,
+    usdcAddress: '0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4',
+    cctp: {
+        domain: 18,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 3,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
+/**
+ * ZKSync Era Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the ZKSync Era blockchain.
+ */
+const ZKSyncEra = defineChain({
+    type: 'evm',
+    chain: Blockchain.ZKSync_Era,
+    name: 'ZKSync Era',
+    title: 'ZKSync Era Mainnet',
+    nativeCurrency: {
+        name: 'Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 324,
+    isTestnet: false,
+    explorerUrl: 'https://explorer.zksync.io/tx/{hash}',
+    rpcEndpoints: ['https://mainnet.era.zksync.io'],
+    eurcAddress: null,
+    usdcAddress: '0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4',
+    cctp: null,
+});
+
+/**
+ * ZKSync Era Sepolia Testnet chain definition
+ * @remarks
+ * This represents the official test network for the ZKSync Era blockchain on Sepolia.
+ */
+const ZKSyncEraSepolia = defineChain({
+    type: 'evm',
+    chain: Blockchain.ZKSync_Sepolia,
+    name: 'ZKSync Era Sepolia',
+    title: 'ZKSync Era Sepolia Testnet',
+    nativeCurrency: {
+        name: 'Sepolia Ether',
+        symbol: 'ETH',
+        decimals: 18,
+    },
+    chainId: 300,
+    isTestnet: true,
+    explorerUrl: 'https://sepolia.explorer.zksync.io/tx/{hash}',
+    rpcEndpoints: ['https://sepolia.era.zksync.dev'],
+    eurcAddress: null,
+    usdcAddress: '0xAe045DE5638162fa134807Cb558E15A3F5A7F853',
+    cctp: null,
+});
+
+var Blockchains = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    Algorand: Algorand,
+    AlgorandTestnet: AlgorandTestnet,
+    Aptos: Aptos,
+    AptosTestnet: AptosTestnet,
+    Arbitrum: Arbitrum,
+    ArbitrumSepolia: ArbitrumSepolia,
+    Avalanche: Avalanche,
+    AvalancheFuji: AvalancheFuji,
+    Base: Base,
+    BaseSepolia: BaseSepolia,
+    Celo: Celo,
+    CeloAlfajoresTestnet: CeloAlfajoresTestnet,
+    Codex: Codex,
+    CodexTestnet: CodexTestnet,
+    Ethereum: Ethereum,
+    EthereumSepolia: EthereumSepolia,
+    Hedera: Hedera,
+    HederaTestnet: HederaTestnet,
+    HyperEVM: HyperEVM,
+    HyperEVMTestnet: HyperEVMTestnet,
+    Ink: Ink,
+    InkTestnet: InkTestnet,
+    Linea: Linea,
+    LineaSepolia: LineaSepolia,
+    NEAR: NEAR,
+    NEARTestnet: NEARTestnet,
+    Noble: Noble,
+    NobleTestnet: NobleTestnet,
+    Optimism: Optimism,
+    OptimismSepolia: OptimismSepolia,
+    Plume: Plume,
+    PlumeTestnet: PlumeTestnet,
+    PolkadotAssetHub: PolkadotAssetHub,
+    PolkadotWestmint: PolkadotWestmint,
+    Polygon: Polygon,
+    PolygonAmoy: PolygonAmoy,
+    Sei: Sei,
+    SeiTestnet: SeiTestnet,
+    Solana: Solana,
+    SolanaDevnet: SolanaDevnet,
+    Sonic: Sonic,
+    SonicTestnet: SonicTestnet,
+    Stellar: Stellar,
+    StellarTestnet: StellarTestnet,
+    Sui: Sui,
+    SuiTestnet: SuiTestnet,
+    Unichain: Unichain,
+    UnichainSepolia: UnichainSepolia,
+    WorldChain: WorldChain,
+    WorldChainSepolia: WorldChainSepolia,
+    XDC: XDC,
+    XDCApothem: XDCApothem,
+    ZKSyncEra: ZKSyncEra,
+    ZKSyncEraSepolia: ZKSyncEraSepolia
+});
+
+/**
+ * Base schema for common chain definition properties.
+ * This contains all properties shared between EVM and non-EVM chains.
+ */
+const baseChainDefinitionSchema = z.object({
+    chain: z.nativeEnum(Blockchain, {
+        required_error: 'Chain enum is required. Please provide a valid Blockchain enum value.',
+        invalid_type_error: 'Chain must be a valid Blockchain enum value.',
+    }),
+    name: z.string({
+        required_error: 'Chain name is required. Please provide a valid chain name.',
+        invalid_type_error: 'Chain name must be a string.',
+    }),
+    title: z.string().optional(),
+    nativeCurrency: z.object({
+        name: z.string(),
+        symbol: z.string(),
+        decimals: z.number(),
+    }),
+    isTestnet: z.boolean({
+        required_error: 'isTestnet is required. Please specify whether this is a testnet.',
+        invalid_type_error: 'isTestnet must be a boolean.',
+    }),
+    explorerUrl: z.string({
+        required_error: 'Explorer URL is required. Please provide a valid explorer URL.',
+        invalid_type_error: 'Explorer URL must be a string.',
+    }),
+    rpcEndpoints: z.array(z.string()),
+    eurcAddress: z.string().nullable(),
+    usdcAddress: z.string().nullable(),
+    cctp: z.any().nullable(), // We'll accept any CCTP config structure
+    kitContracts: z
+        .object({
+        bridge: z.string().optional(),
+    })
+        .optional(),
+});
+/**
+ * Zod schema for validating EVM chain definitions specifically.
+ * This schema extends the base schema with EVM-specific properties.
+ *
+ * @example
+ * ```typescript
+ * import { evmChainDefinitionSchema } from '@core/chains/validation'
+ * import { Blockchain } from '@core/chains'
+ *
+ * const ethereumChain = {
+ *   type: 'evm',
+ *   chain: Blockchain.Ethereum,
+ *   name: 'Ethereum',
+ *   chainId: 1,
+ *   nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+ *   isTestnet: false,
+ *   explorerUrl: 'https://etherscan.io/tx/{hash}',
+ *   usdcAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+ *   eurcAddress: null,
+ *   cctp: null
+ * }
+ *
+ * const result = evmChainDefinitionSchema.safeParse(ethereumChain)
+ * if (result.success) {
+ *   console.log('EVM chain definition is valid')
+ * } else {
+ *   console.error('Validation failed:', result.error)
+ * }
+ * ```
+ */
+const evmChainDefinitionSchema = baseChainDefinitionSchema
+    .extend({
+    type: z.literal('evm'),
+    chainId: z.number({
+        required_error: 'EVM chains must have a chainId. Please provide a valid EVM chain ID.',
+        invalid_type_error: 'EVM chain ID must be a number.',
+    }),
+})
+    .strict(); //// Reject any additional properties not defined in the schema
+/**
+ * Zod schema for validating non-EVM chain definitions.
+ * This schema extends the base schema with non-EVM specific properties.
+ */
+const nonEvmChainDefinitionSchema = baseChainDefinitionSchema
+    .extend({
+    type: z.enum([
+        'algorand',
+        'avalanche',
+        'solana',
+        'aptos',
+        'near',
+        'stellar',
+        'sui',
+        'hedera',
+        'noble',
+        'polkadot',
+    ]),
+})
+    .strict(); // Reject any additional properties not defined in the schema
+/**
+ * Discriminated union schema for all chain definitions.
+ * This schema validates different chain types based on their 'type' field.
+ *
+ * @example
+ * ```typescript
+ * import { chainDefinitionSchema } from '@core/chains/validation'
+ * import { Blockchain } from '@core/chains'
+ *
+ * // EVM chain
+ * chainDefinitionSchema.parse({
+ *   type: 'evm',
+ *   chain: Blockchain.Ethereum,
+ *   chainId: 1,
+ *   // ... other properties
+ * })
+ *
+ * // Non-EVM chain
+ * chainDefinitionSchema.parse({
+ *   type: 'solana',
+ *   chain: Blockchain.Solana,
+ *   // ... other properties (no chainId)
+ * })
+ * ```
+ */
+const chainDefinitionSchema = z.discriminatedUnion('type', [
+    evmChainDefinitionSchema,
+    nonEvmChainDefinitionSchema,
+]);
+/**
+ * Zod schema for validating chain identifiers.
+ * This schema accepts either a string blockchain identifier, a Blockchain enum value,
+ * or a full ChainDefinition object.
+ *
+ * @example
+ * ```typescript
+ * import { chainIdentifierSchema } from '@core/chains/validation'
+ * import { Blockchain, Ethereum } from '@core/chains'
+ *
+ * // All of these are valid:
+ * chainIdentifierSchema.parse('Ethereum')
+ * chainIdentifierSchema.parse(Blockchain.Ethereum)
+ * chainIdentifierSchema.parse(Ethereum)
+ * ```
+ */
+const chainIdentifierSchema = z.union([
+    z
+        .string()
+        .refine((val) => val in Blockchain, 'Must be a valid Blockchain enum value as string'),
+    z.nativeEnum(Blockchain),
+    chainDefinitionSchema,
+]);
+
+/**
+ * Retrieve a chain definition by its blockchain enum value.
+ *
+ * Searches the set of known chain definitions and returns the one matching the provided
+ * blockchain enum or string value. Throws an error if no matching chain is found.
+ *
+ * @param blockchain - The blockchain enum or its string representation to look up.
+ * @returns The corresponding ChainDefinition object for the given blockchain.
+ *
+ * @throws Error If no chain definition is found for the provided enum value.
+ *
+ * @example
+ * ```typescript
+ * import { getChainByEnum } from '@core/chains'
+ * import { Blockchain } from '@core/chains'
+ *
+ * const ethereum = getChainByEnum(Blockchain.Ethereum)
+ * console.log(ethereum.name) // "Ethereum"
+ * ```
+ */
+const getChainByEnum = (blockchain) => {
+    const chain = Object.values(Blockchains).find((chain) => {
+        return chain.chain === blockchain;
+    });
+    if (!chain) {
+        throw new Error(`No chain definition found for blockchain: ${blockchain}`);
+    }
+    return chain;
+};
+
+/**
+ * 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')
+ * ```
+ */
+function resolveChainIdentifier(chainIdentifier) {
+    // If it's already a ChainDefinition object, return it unchanged
+    if (typeof chainIdentifier === 'object') {
+        return chainIdentifier;
+    }
+    // If it's a string or enum value, resolve it via getChainByEnum
+    if (typeof chainIdentifier === 'string') {
+        return getChainByEnum(chainIdentifier);
+    }
+    // This should never happen with proper typing, but provide a fallback
+    throw new Error(`Invalid chain identifier type: ${typeof chainIdentifier}. Expected ChainDefinition object, Blockchain enum, or string literal.`);
+}
+
+/**
+ * Schema for validating hexadecimal strings with '0x' prefix.
+ *
+ * This schema validates that a string:
+ * - Is a string type
+ * - Is not empty after trimming
+ * - Starts with '0x'
+ * - Contains only valid hexadecimal characters (0-9, a-f, A-F) after '0x'
+ *
+ * @remarks
+ * This schema does not validate length, making it suitable for various hex string types
+ * like addresses, transaction hashes, and other hex-encoded data.
+ *
+ * @throws {ValidationError} If validation fails, with details about which properties failed
+ *
+ * @example
+ * ```typescript
+ * import { hexStringSchema } from '@core/adapter'
+ *
+ * const validAddress = '0x1234567890123456789012345678901234567890'
+ * const validTxHash = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
+ *
+ * const addressResult = hexStringSchema.safeParse(validAddress)
+ * const txHashResult = hexStringSchema.safeParse(validTxHash)
+ * console.log(addressResult.success) // true
+ * console.log(txHashResult.success) // true
+ * ```
+ */
+const hexStringSchema = z
+    .string()
+    .min(1, 'Hex string is required')
+    .refine((value) => value.trim().length > 0, 'Hex string cannot be empty')
+    .refine((value) => value.startsWith('0x'), 'Hex string must start with 0x prefix')
+    .refine((value) => {
+    const hexPattern = /^0x[0-9a-fA-F]+$/;
+    return hexPattern.test(value);
+}, 'Hex string contains invalid characters. Only hexadecimal characters (0-9, a-f, A-F) are allowed after 0x');
+/**
+ * Schema for validating EVM addresses.
+ *
+ * This schema validates that a string is a properly formatted EVM address:
+ * - Must be a valid hex string with '0x' prefix
+ * - Must be exactly 42 characters long (0x + 40 hex characters)
+ *
+ * @throws {ValidationError} If validation fails, with details about which properties failed
+ *
+ * @example
+ * ```typescript
+ * import { evmAddressSchema } from '@core/adapter'
+ *
+ * const validAddress = '0x1234567890123456789012345678901234567890'
+ *
+ * const result = evmAddressSchema.safeParse(validAddress)
+ * console.log(result.success) // true
+ * ```
+ */
+hexStringSchema.refine((value) => value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)');
+/**
+ * Schema for validating transaction hashes.
+ *
+ * This schema validates that a string is a properly formatted transaction hash:
+ * - Must be a valid hex string with '0x' prefix
+ * - Must be exactly 66 characters long (0x + 64 hex characters)
+ *
+ * @throws {ValidationError} If validation fails, with details about which properties failed
+ *
+ * @example
+ * ```typescript
+ * import { evmTransactionHashSchema } from '@core/adapter'
+ *
+ * const validTxHash = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
+ *
+ * const result = evmTransactionHashSchema.safeParse(validTxHash)
+ * console.log(result.success) // true
+ * ```
+ */
+hexStringSchema.refine((value) => value.length === 66, 'Transaction hash must be exactly 66 characters long (0x + 64 hex characters)');
+/**
+ * Schema for validating base58-encoded strings.
+ *
+ * This schema validates that a string:
+ * - Is a string type
+ * - Is not empty after trimming
+ * - Contains only valid base58 characters (1-9, A-H, J-N, P-Z, a-k, m-z)
+ * - Does not contain commonly confused characters (0, O, I, l)
+ *
+ * @remarks
+ * This schema does not validate length, making it suitable for various base58-encoded data
+ * like Solana addresses, transaction signatures, and other base58-encoded data.
+ *
+ * @throws {ValidationError} If validation fails, with details about which properties failed
+ *
+ * @example
+ * ```typescript
+ * import { base58StringSchema } from '@core/adapter'
+ *
+ * const validAddress = 'DhzPkKCLJGHBZbs1AzmK2tRNLZkV8J3yWF3LuWMuKJpN'
+ * const validTxHash = '3Jf8k2L5mN9pQ7rS1tV4wX6yZ8aB2cD4eF5gH7iJ9kL1mN3oP5qR7sT9uV1wX3yZ5'
+ *
+ * const addressResult = base58StringSchema.safeParse(validAddress)
+ * const txHashResult = base58StringSchema.safeParse(validTxHash)
+ * console.log(addressResult.success) // true
+ * console.log(txHashResult.success) // true
+ * ```
+ */
+const base58StringSchema = z
+    .string()
+    .min(1, 'Base58 string is required')
+    .refine((value) => value.trim().length > 0, 'Base58 string cannot be empty')
+    .refine((value) => {
+    // Base58 alphabet: 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
+    // Excludes: 0, O, I, l to avoid confusion
+    const base58Pattern = /^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+$/;
+    return base58Pattern.test(value);
+}, 'Base58 string contains invalid characters. Only base58 characters (1-9, A-H, J-N, P-Z, a-k, m-z) are allowed');
+/**
+ * Schema for validating Solana addresses.
+ *
+ * This schema validates that a string is a properly formatted Solana address:
+ * - Must be a valid base58-encoded string
+ * - Must be between 32-44 characters long (typical length for base58-encoded 32-byte addresses)
+ *
+ * @throws {ValidationError} If validation fails, with details about which properties failed
+ *
+ * @example
+ * ```typescript
+ * import { solanaAddressSchema } from '@core/adapter'
+ *
+ * const validAddress = 'DhzPkKCLJGHBZbs1AzmK2tRNLZkV8J3yWF3LuWMuKJpN'
+ *
+ * const result = solanaAddressSchema.safeParse(validAddress)
+ * console.log(result.success) // true
+ * ```
+ */
+base58StringSchema.refine((value) => value.length >= 32 && value.length <= 44, 'Solana address must be between 32-44 characters long (base58-encoded 32-byte address)');
+/**
+ * Schema for validating Solana transaction hashes.
+ *
+ * This schema validates that a string is a properly formatted Solana transaction hash:
+ * - Must be a valid base58-encoded string
+ * - Must be between 86-88 characters long (typical length for base58-encoded 64-byte signatures)
+ *
+ * @throws {ValidationError} If validation fails, with details about which properties failed
+ *
+ * @example
+ * ```typescript
+ * import { solanaTransactionHashSchema } from '@core/adapter'
+ *
+ * const validTxHash = '5VfYmGBjvQKe3xgLtTQPSMEUdpEVHrJwLK7pKBJWKzYpNBE2g3kJrq7RSe9M8DqzQJ5J2aZPTjHLvd4WgxPpJKS'
+ *
+ * const result = solanaTransactionHashSchema.safeParse(validTxHash)
+ * console.log(result.success) // true
+ * ```
+ */
+base58StringSchema.refine((value) => value.length >= 86 && value.length <= 88, 'Solana transaction hash must be between 86-88 characters long (base58-encoded 64-byte signature)');
+/**
+ * Schema for validating Adapter objects.
+ * Checks for the required methods that define an Adapter.
+ */
+const adapterSchema = z.object({
+    prepare: z.function(),
+    waitForTransaction: z.function(),
+    getAddress: z.function(),
+});
+
+/**
+ * Transfer speed options for cross-chain operations.
+ *
+ * Defines the available speed modes for CCTPv2 transfers, affecting
+ * both transfer time and potential fee implications.
+ */
+var TransferSpeed;
+(function (TransferSpeed) {
+    /** Fast burn mode - reduces transfer time but may have different fee implications */
+    TransferSpeed["FAST"] = "FAST";
+    /** Standard burn mode - normal transfer time with standard fees */
+    TransferSpeed["SLOW"] = "SLOW";
+})(TransferSpeed || (TransferSpeed = {}));
+
+/**
+ * Factory to validate a numeric string that may include thousand separators and decimal part.
+ * Supports either comma or dot as decimal separator and the other as thousands.
+ *
+ * Behavior differences controlled by options:
+ * - allowZero: when false, value must be strictly greater than 0; when true, non-negative.
+ * - regexMessage: error message when the basic numeric format fails.
+ */
+const createDecimalStringValidator = (options) => (schema) => schema
+    .regex(/^\d+(?:[.,]\d{3})*(?:[.,]\d+)?$/, options.regexMessage)
+    .superRefine((val, ctx) => {
+    const lastSeparator = val.lastIndexOf(',');
+    const lastDot = val.lastIndexOf('.');
+    const isCommaSeparated = lastSeparator > lastDot;
+    const normalizedValue = val
+        .replace(isCommaSeparated ? /\./g : /,/g, '')
+        .replace(isCommaSeparated ? ',' : '.', '.');
+    const amount = parseFloat(normalizedValue);
+    if (Number.isNaN(amount)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: options.regexMessage,
+        });
+        return;
+    }
+    // Check decimal precision if maxDecimals is specified
+    if (options.maxDecimals !== undefined) {
+        const decimalPart = normalizedValue.split('.')[1];
+        if (decimalPart && decimalPart.length > options.maxDecimals) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Maximum supported decimal places: ${options.maxDecimals.toString()}`,
+            });
+            return;
+        }
+    }
+    if (options.allowZero && amount < 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `${options.attributeName} must be non-negative`,
+        });
+    }
+    else if (!options.allowZero && amount <= 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `${options.attributeName} must be greater than 0`,
+        });
+    }
+});
+/**
+ * Schema for validating chain definitions.
+ * This ensures the basic structure of a chain definition is valid.
+ * A chain definition must include at minimum a name and type.
+ *
+ * @throws ValidationError If validation fails, with details about which properties failed
+ *
+ * @example
+ * ```typescript
+ * import { chainDefinitionSchema } from '@core/provider'
+ *
+ * const validChain = {
+ *   name: 'Ethereum',
+ *   type: 'evm'
+ * }
+ *
+ * const result = chainDefinitionSchema.safeParse(validChain)
+ * console.log(result.success) // true
+ * ```
+ */
+z.object({
+    name: z.string().min(1, 'Chain name is required'),
+    type: z.string().min(1, 'Chain type is required'),
+});
+/**
+ * Schema for validating wallet contexts.
+ * This ensures all required fields are present and properly typed.
+ * A wallet context must include:
+ * - A valid adapter with prepare and execute methods
+ * - A valid Ethereum address
+ * - A valid chain definition with required properties
+ *
+ * @throws ValidationError If validation fails, with details about which properties failed
+ *
+ * @example
+ * ```typescript
+ * import { walletContextSchema } from '@core/provider'
+ *
+ * const validContext = {
+ *   adapter: {
+ *     prepare: () => Promise.resolve({}),
+ *     waitForTransaction: () => Promise.resolve({})
+ *   },
+ *   address: '0x1234567890123456789012345678901234567890',
+ *   chain: {
+ *     name: 'Ethereum',
+ *     type: 'evm',
+ *     isTestnet: false
+ *   }
+ * }
+ *
+ * const result = walletContextSchema.safeParse(validContext)
+ * console.log(result.success) // true
+ * ```
+ */
+const walletContextSchema = z.object({
+    adapter: z.object({
+        prepare: z.function().returns(z.any()),
+        waitForTransaction: z.function().returns(z.any()),
+    }),
+    address: z.string().min(1),
+    chain: z.object({
+        name: z.string(),
+        type: z.string(),
+        isTestnet: z.boolean(),
+    }),
+});
+/**
+ * Schema for validating a custom fee configuration.
+ * Validates the simplified CustomFee interface which includes:
+ * - An optional fee amount as string
+ * - An optional fee recipient as string address
+ *
+ * @throws ValidationError If validation fails
+ *
+ * @example
+ * ```typescript
+ * import { customFeeSchema } from '@core/provider'
+ *
+ * const validConfig = {
+ *   value: '1000000',
+ *   recipientAddress: '0x1234567890123456789012345678901234567890'
+ * }
+ *
+ * const result = customFeeSchema.safeParse(validConfig)
+ * console.log(result.success) // true
+ * ```
+ */
+const customFeeSchema = z
+    .object({
+    /**
+     * The fee to charge for the transfer as string.
+     * Must be a non-negative value.
+     */
+    value: createDecimalStringValidator({
+        allowZero: true,
+        regexMessage: 'Value must be non-negative',
+        attributeName: 'value',
+    })(z.string()).optional(),
+    /**
+     * The fee recipient address.
+     * Must be a valid address string.
+     */
+    recipientAddress: z
+        .string()
+        .trim()
+        .min(1, 'Fee recipient must be a non-empty string')
+        .optional(),
+})
+    .strict();
+/**
+ * Schema for validating bridge parameters.
+ * This ensures all required fields are present and properly typed.
+ * A bridge must include:
+ * - A valid amount (non-empty numeric string \> 0)
+ * - Valid source and destination wallet contexts
+ * - USDC as the token
+ * - Optional config with transfer speed and max fee settings
+ *
+ * @throws ValidationError If validation fails, with details about which properties failed
+ *
+ * @example
+ * ```typescript
+ * import { bridgeParamsSchema } from '@core/provider'
+ *
+ * const validBridge = {
+ *   amount: '100.50',
+ *   source: {
+ *     adapter: sourceAdapter,
+ *     address: '0xSourceAddress',
+ *     chain: sourceChain
+ *   },
+ *   destination: {
+ *     adapter: destAdapter,
+ *     address: '0xDestAddress',
+ *     chain: destChain
+ *   },
+ *   token: 'USDC',
+ *   config: {
+ *     transferSpeed: 'FAST',
+ *     maxFee: '1000000'
+ *     customFee: {
+ *       value: '1000000',
+ *       recipientAddress: '0x1234567890123456789012345678901234567890'
+ *     }
+ *   }
+ * }
+ *
+ * const result = bridgeParamsSchema.safeParse(validBridge)
+ * console.log(result.success) // true
+ * ```
+ */
+z.object({
+    amount: z
+        .string()
+        .min(1, 'Required')
+        .pipe(createDecimalStringValidator({
+        allowZero: false,
+        regexMessage: 'Amount must be a numeric string with optional decimal places (e.g., 10.5, 10,5, 1.000,50 or 1,000.50)',
+        attributeName: 'amount',
+        maxDecimals: 6,
+    })(z.string())),
+    source: walletContextSchema,
+    destination: walletContextSchema,
+    token: z.literal('USDC'),
+    config: z.object({
+        transferSpeed: z.nativeEnum(TransferSpeed).optional(),
+        maxFee: z
+            .string()
+            .regex(/^\d+$/, 'Max fee must be a numeric string')
+            .optional(),
+        customFee: customFeeSchema.optional(),
+    }),
+});
+
+/**
+ * Schema for validating AdapterContext.
+ * Must always contain both adapter and chain explicitly.
+ */
+const adapterContextSchema = z.object({
+    adapter: adapterSchema,
+    chain: chainIdentifierSchema,
+});
+/**
+ * Schema for validating BridgeDestinationWithAddress objects.
+ * Contains an explicit recipientAddress along with adapter and chain.
+ * The address format is validated based on the chain type (EVM or Solana).
+ */
+const bridgeDestinationWithAddressSchema = adapterContextSchema
+    .extend({
+    recipientAddress: z.string().min(1, 'Recipient address is required'),
+})
+    .superRefine((data, ctx) => {
+    const chain = data.chain;
+    if (chain === null) {
+        return;
+    }
+    if (!isValidAddressForChain(data.recipientAddress, chain)) {
+        const chainInfo = extractChainInfo(chain);
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['recipientAddress'],
+            message: `Invalid address format for ${String(chainInfo.name)}. Expected ${chainInfo.expectedAddressFormat}, but received: ${data.recipientAddress}`,
+        });
+    }
+});
+/**
+ * Schema for validating BridgeDestination union type.
+ * Can be an AdapterContext or BridgeDestinationWithAddress.
+ *
+ * The order matters: we check the more specific schema (with recipientAddress) first.
+ * This ensures that objects with an empty recipientAddress field are rejected rather
+ * than silently treated as AdapterContext with the field ignored.
+ */
+const bridgeDestinationSchema = z.union([
+    bridgeDestinationWithAddressSchema,
+    adapterContextSchema.strict(),
+]);
+/**
+ * Schema for validating bridge parameters with chain identifiers.
+ * This extends the core provider's schema but adapts it for the bridge kit's
+ * more flexible interface that accepts chain identifiers.
+ *
+ * The schema validates:
+ * - From adapter context (must always include both adapter and chain)
+ * - To bridge destination (AdapterContext or BridgeDestinationWithAddress)
+ * - Amount is a non-empty numeric string \> 0
+ * - Token is optional and defaults to 'USDC'
+ * - Optional config parameters (transfer speed, max fee)
+ *
+ * @example
+ * ```typescript
+ * import { bridgeParamsWithChainIdentifierSchema } from '@circle-fin/bridge-kit'
+ *
+ * const params = {
+ *   from: {
+ *     adapter: sourceAdapter,
+ *     chain: 'Ethereum'
+ *   },
+ *   to: {
+ *     adapter: destAdapter,
+ *     chain: 'Base'
+ *   },
+ *   amount: '100.50',
+ *   token: 'USDC',
+ *   config: {
+ *     transferSpeed: 'FAST'
+ *   }
+ * }
+ *
+ * const result = bridgeParamsWithChainIdentifierSchema.safeParse(params)
+ * if (result.success) {
+ *   console.log('Parameters are valid')
+ * } else {
+ *   console.error('Validation failed:', result.error)
+ * }
+ * ```
+ */
+const bridgeParamsWithChainIdentifierSchema = z.object({
+    from: adapterContextSchema,
+    to: bridgeDestinationSchema,
+    amount: z
+        .string()
+        .min(1, 'Required')
+        .pipe(createDecimalStringValidator({
+        allowZero: false,
+        regexMessage: 'Amount must be a numeric string with optional decimal places (e.g., 10.5, 10,5, 1.000,50 or 1,000.50)',
+        attributeName: 'amount',
+        maxDecimals: 6,
+    })(z.string())),
+    token: z.literal('USDC').optional(),
+    config: z
+        .object({
+        transferSpeed: z.nativeEnum(TransferSpeed).optional(),
+        maxFee: z
+            .string()
+            .regex(/^\d+$/, 'Max fee must be a numeric string')
+            .optional(),
+        customFee: customFeeSchema.optional(),
+    })
+        .optional(),
+});
+
+/**
+ * Resolves a chain identifier to a chain definition.
+ *
+ * Both AdapterContext and BridgeDestinationWithAddress have the chain property
+ * at the top level, so we can directly access it from either type.
+ *
+ * @param ctx - The bridge destination containing the chain identifier
+ * @returns The resolved chain definition
+ * @throws If the chain definition cannot be resolved
+ *
+ * @example
+ * ```typescript
+ * import { Blockchain } from '@core/chains'
+ *
+ * // AdapterContext
+ * const chain1 = resolveChainDefinition({
+ *   adapter: mockAdapter,
+ *   chain: 'Ethereum'
+ * })
+ *
+ * // BridgeDestinationWithAddress
+ * const chain2 = resolveChainDefinition({
+ *   adapter: mockAdapter,
+ *   chain: 'Base',
+ *   recipientAddress: '0x123...'
+ * })
+ * ```
+ */
+function resolveChainDefinition(ctx) {
+    return resolveChainIdentifier(ctx.chain);
+}
+/**
+ * Resolves an address from a bridge destination.
+ *
+ * It handles two cases:
+ * - BridgeDestinationWithAddress - returns the explicit recipientAddress
+ * - AdapterContext - calls getAddress() on the adapter
+ *
+ * @param ctx - The bridge destination to resolve the address from
+ * @returns The resolved address string
+ *
+ * @example
+ * ```typescript
+ * // Explicit recipient address
+ * const addr1 = await resolveAddress({
+ *   adapter: mockAdapter,
+ *   chain: 'Ethereum',
+ *   recipientAddress: '0x1234567890123456789012345678901234567890'
+ * }) // Returns: '0x1234567890123456789012345678901234567890'
+ *
+ * // Derived from adapter
+ * const addr2 = await resolveAddress({
+ *   adapter: mockAdapter,
+ *   chain: 'Ethereum'
+ * }) // Returns adapter's address
+ * ```
+ */
+async function resolveAddress(ctx) {
+    // Handle BridgeDestinationWithAddress (has explicit recipientAddress)
+    if ('recipientAddress' in ctx) {
+        return ctx.recipientAddress;
+    }
+    // Handle AdapterContext (derive from adapter)
+    // Pass the chain to support OperationContext pattern
+    const chain = resolveChainDefinition(ctx);
+    return await ctx.adapter.getAddress(chain);
+}
+/**
+ * Resolves the amount of a transfer by formatting it according to the token's decimal places.
+ *
+ * This function takes the raw amount from the transfer parameters and formats it
+ * using the appropriate decimal places for the specified token. Currently supports
+ * USDC (6 decimals) and falls back to the raw amount for other tokens.
+ *
+ * @param params - The bridge parameters containing the amount, token type, and from context
+ * @returns The formatted amount string with proper decimal places
+ *
+ * @example
+ * ```typescript
+ * import { Adapter } from '@core/adapter'
+ *
+ * const params = {
+ *   amount: '1000000',
+ *   token: 'USDC',
+ *   from: { adapter: mockAdapter, chain: Ethereum },
+ *   to: { adapter: mockAdapter, chain: Base }
+ * }
+ * const formattedAmount = resolveAmount(params) // Returns '1000000000000'
+ * ```
+ */
+function resolveAmount(params) {
+    if (params.token === 'USDC') {
+        return parseUnits(params.amount, 6).toString();
+    }
+    return params.amount;
+}
+/**
+ * Resolves and normalizes bridge configuration for the provider.
+ *
+ * This function takes the optional configuration from bridge parameters and returns
+ * a normalized BridgeConfig with:
+ * - Default transfer speed set to FAST if not provided
+ * - Custom fee values formatted with proper decimal places (6 decimals for USDC)
+ *
+ * @param params - The bridge parameters containing optional configuration
+ * @returns A normalized BridgeConfig with defaults applied and values formatted
+ *
+ * @example
+ * ```typescript
+ * import { TransferSpeed } from '@core/provider'
+ *
+ * const params = {
+ *   amount: '100',
+ *   token: 'USDC',
+ *   from: { adapter: mockAdapter, chain: Ethereum },
+ *   to: { adapter: mockAdapter, chain: Base },
+ *   config: {
+ *     customFee: { value: '0.5' }
+ *   }
+ * }
+ * const config = resolveConfig(params)
+ * // Returns: {
+ * //   transferSpeed: TransferSpeed.FAST,
+ * //   customFee: { value: '500000' }
+ * // }
+ * ```
+ */
+function resolveConfig(params) {
+    return {
+        ...params.config,
+        transferSpeed: params.config?.transferSpeed ?? TransferSpeed.FAST,
+        customFee: params.config?.customFee
+            ? {
+                ...params.config?.customFee,
+                value: params.config?.customFee?.value
+                    ? parseUnits(params.config?.customFee?.value, 6).toString()
+                    : undefined,
+            }
+            : undefined,
+    };
+}
+/**
+ * Resolves and normalizes bridge parameters for the BridgeKit.
+ *
+ * This function takes bridge parameters with explicit adapter contexts and normalizes them
+ * into a consistent format that can be used by the bridging providers.
+ *
+ * The function performs parallel resolution of:
+ * - Source and destination addresses
+ * - Source and destination chain definitions
+ * - Amount formatting
+ *
+ * @param params - The bridge parameters containing source/destination contexts, amount, and token
+ * @returns Promise resolving to normalized bridge parameters for provider consumption
+ * @throws \{Error\} If parameters cannot be resolved (invalid chains, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { BridgeKit } from '@bridge-kit'
+ *
+ * const params = {
+ *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
+ *   to: { adapter: destAdapter, chain: 'Base' },
+ *   amount: '10.5',
+ *   token: 'USDC'
+ * }
+ *
+ * const resolved = await resolveBridgeParams(params)
+ * console.log('Normalized for provider:', resolved)
+ * ```
+ */
+async function resolveBridgeParams(params) {
+    const fromChain = resolveChainDefinition(params.from);
+    const toChain = resolveChainDefinition(params.to);
+    const [fromAddress, toAddress] = await Promise.all([
+        resolveAddress(params.from),
+        resolveAddress(params.to),
+    ]);
+    const token = params.token ?? 'USDC';
+    // Extract adapters - now always from explicit contexts
+    const fromAdapter = params.from.adapter;
+    const toAdapter = params.to.adapter;
+    return {
+        amount: resolveAmount({
+            ...params,
+            token,
+        }),
+        token,
+        config: resolveConfig({
+            ...params}),
+        source: {
+            adapter: fromAdapter,
+            chain: fromChain,
+            address: fromAddress,
+        },
+        destination: {
+            adapter: toAdapter,
+            chain: toChain,
+            address: toAddress,
+        },
+    };
+}
+
+/**
+ * The default providers that will be used in addition to the providers provided
+ * to the BridgeKit constructor.
+ */
+const getDefaultProviders = () => [new CCTPV2BridgingProvider()];
+
+/**
+ * Route cross-chain USDC bridging through Circle's Cross-Chain Transfer Protocol v2 (CCTPv2).
+ *
+ * This method orchestrates the entire cross-chain bridging process including:
+ * 1. Parameter validation and route resolution
+ * 2. Provider selection and configuration
+ * 3. Transaction execution on both source and destination chains
+ * 4. Event emission for monitoring and debugging
+ *
+ * The process is atomic - if any step fails, the method will throw an error
+ * with detailed information about the failure point and any completed steps.
+ *
+ * @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 {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'
+ *
+ * // Create kit with default CCTPv2 provider
+ * const kit = new BridgeKit()
+ * const adapter = createAdapterFromPrivateKey({ privateKey: '0x...' })
+ *
+ * // Execute cross-chain transfer
+ * const result = await kit.bridge({
+ *   from: { adapter, chain: 'Ethereum' },
+ *   to: { adapter, chain: 'Base' },
+ *   amount: '10.50'
+ * })
+ *
+ * // Monitor bridge events
+ * kit.on('approve', (payload) => {
+ *   console.log('Approval complete:', payload.values.txHash)
+ * })
+ * ```
+ */
+class BridgeKit {
+    /**
+     * The providers used for executing transfers.
+     */
+    providers;
+    /**
+     * The action dispatcher for the kit.
+     */
+    actionDispatcher;
+    /**
+     * A custom fee policy for the kit.
+     */
+    customFeePolicy;
+    /**
+     * Create a new BridgeKit instance.
+     *
+     * @param config - The configuration containing the CCTPv2 provider
+     *
+     * @example
+     * ```typescript
+     * import { BridgeKit } from '@circle-fin/bridge-kit'
+     *
+     * const kit = new BridgeKit()
+     * ```
+     */
+    constructor(config = {}) {
+        // Handle provider configuration
+        const defaultProviders = getDefaultProviders();
+        this.providers = [...defaultProviders, ...(config.providers ?? [])];
+        this.actionDispatcher = new Actionable();
+        for (const provider of this.providers) {
+            provider.registerDispatcher(this.actionDispatcher);
+        }
+    }
+    // implementation just forwards to the bus
+    on(actionOrWildCard, handler) {
+        this.actionDispatcher.on(actionOrWildCard, handler);
+    }
+    // implementation just forwards to the bus
+    off(actionOrWildCard, handler) {
+        this.actionDispatcher.off(actionOrWildCard, handler);
+    }
+    /**
+     * Execute a cross-chain USDC transfer using CCTPv2.
+     *
+     * Handle the complete CCTPv2 transfer flow, including parameter validation,
+     * chain resolution, and transfer execution. Provide comprehensive validation of
+     * all parameters before initiating the transfer.
+     *
+     * Perform validation of:
+     * - Source and destination wallet contexts
+     * - Chain identifiers (string, enum, or chain definition)
+     * - Amount format and token type
+     * - CCTPv2 support for the chain pair
+     * - Transfer configuration options
+     *
+     * @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 {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'
+     *
+     * const kit = new BridgeKit()
+     *
+     * // Create a single adapter that can work across chains
+     * const adapter = createAdapterFromPrivateKey({
+     *   privateKey: process.env.PRIVATE_KEY,
+     * })
+     *
+     * const result = await kit.bridge({
+     *   from: {
+     *     adapter,
+     *     chain: 'Ethereum'
+     *   },
+     *   to: {
+     *     adapter,
+     *     chain: 'Base'
+     *   },
+     *   amount: '100.50'
+     * })
+     *
+     * // Handle result
+     * if (result.state === 'success') {
+     *   console.log('Bridge completed!')
+     *   result.steps.forEach(step => {
+     *     console.log(`${step.name}: ${step.explorerUrl}`)
+     *   })
+     * } else {
+     *   console.error('Bridge failed:', result.steps)
+     * }
+     * ```
+     */
+    async bridge(params) {
+        // First validate the parameters
+        assertBridgeParams(params, bridgeParamsWithChainIdentifierSchema);
+        // Then resolve chain definitions
+        const resolvedParams = await resolveBridgeParams(params);
+        // Validate network compatibility
+        this.validateNetworkCompatibility(resolvedParams);
+        // Merge the custom fee config into the resolved params
+        const finalResolvedParams = await this.mergeCustomFeeConfig(resolvedParams);
+        // Find a provider that supports this route
+        const provider = this.findProviderForRoute(finalResolvedParams);
+        // Execute the transfer using the provider
+        return provider.bridge(finalResolvedParams);
+    }
+    /**
+     * Retry a failed or incomplete cross-chain USDC bridge operation.
+     *
+     * Provide a high-level interface for resuming bridge operations that have failed
+     * or become stuck during execution. Automatically identify the provider that was
+     * used for the original transfer and delegate the retry logic to that provider's
+     * implementation.
+     *
+     * Use this functionality to handle:
+     * - Network timeouts or temporary connectivity issues
+     * - Gas estimation failures that can be resolved with updated parameters
+     * - Pending transactions that need to be resubmitted
+     * - Failed steps in multi-step bridge flows
+     *
+     * @param result - The bridge result from a previous failed or incomplete operation.
+     *                 Must contain the provider name and step execution history.
+     * @param context - The retry context containing fresh adapter instances for both
+     *                  source and destination chains. These adapters should be properly
+     *                  configured with current network connections and signing capabilities.
+     * @returns A promise that resolves to the updated bridge result after retry execution.
+     *          The result will contain the complete step history including both original
+     *          and retry attempts.
+     *
+     * @throws {Error} When the original provider specified in the result is not found
+     *         in the current kit configuration.
+     * @throws {Error} When the underlying provider's retry operation fails due to
+     *         non-recoverable errors or invalid state.
+     *
+     * @example
+     * ```typescript
+     * import { BridgeKit } from '@circle-fin/bridge-kit'
+     * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+     *
+     * const kit = new BridgeKit()
+     *
+     * // Assume we have a failed bridge result from a previous operation
+     * const failedResult: BridgeResult = {
+     *   state: 'error',
+     *   provider: 'CCTPV2BridgingProvider',
+     *   steps: [
+     *     { name: 'approve', state: 'success', txHash: '0x123...' },
+     *     { name: 'burn', state: 'error', errorMessage: 'Gas limit exceeded' }
+     *   ],
+     *   // ... other properties
+     * }
+     *
+     *
+     * try {
+     *   const retryResult = await kit.retry(failedResult, {
+     *     from: sourceAdapter,
+     *     to: destAdapter
+     *   })
+     *
+     *   console.log('Retry completed successfully:', retryResult.state)
+     *   console.log('Total steps executed:', retryResult.steps.length)
+     * } catch (error) {
+     *   console.error('Retry failed:', error.message)
+     *   // Handle retry failure (may require manual intervention)
+     * }
+     * ```
+     */
+    async retry(result, context) {
+        const provider = this.providers.find((p) => p.name === result.provider);
+        if (!provider) {
+            throw new Error(`Provider ${result.provider} not found`);
+        }
+        return provider.retry(result, context);
+    }
+    /**
+     * Estimate the cost and fees for a cross-chain USDC bridge operation.
+     *
+     * This method calculates the expected gas fees and protocol costs for bridging
+     * without actually executing the transaction. It performs the same validation
+     * 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 {UnsupportedRouteError} When the route is not supported.
+     *
+     * @example
+     * ```typescript
+     * const estimate = await kit.estimate({
+     *   from: { adapter: adapter, chain: 'Ethereum' },
+     *   to: { adapter: adapter, chain: 'Base' },
+     *   amount: '10.50',
+     *   token: 'USDC'
+     * })
+     * console.log('Estimated cost:', estimate.totalCost)
+     * ```
+     */
+    async estimate(params) {
+        // First validate the parameters
+        assertBridgeParams(params, bridgeParamsWithChainIdentifierSchema);
+        // Then resolve chain definitions
+        const resolvedParams = await resolveBridgeParams(params);
+        // Validate network compatibility
+        this.validateNetworkCompatibility(resolvedParams);
+        // Merge the custom fee config into the resolved params
+        const finalResolvedParams = await this.mergeCustomFeeConfig(resolvedParams);
+        // Find a provider that supports this route
+        const provider = this.findProviderForRoute(finalResolvedParams);
+        // Estimate the transfer using the provider
+        return provider.estimate(finalResolvedParams);
+    }
+    /**
+     * Get all chains supported by any provider in the kit.
+     *
+     * Aggregate and deduplicate the supported chains from all registered providers.
+     * This provides a comprehensive list of chains that can be used as either source
+     * or destination for transfers through this kit instance.
+     *
+     * The method automatically deduplicates chains based on their chain identifier,
+     * ensuring each chain appears only once in the result regardless of how many
+     * providers support it.
+     *
+     * @returns Array of unique chain definitions supported by the registered providers
+     *
+     * @example
+     * ```typescript
+     * import { BridgeKit } from '@circle-fin/bridge-kit'
+     *
+     * const kit = new BridgeKit()
+     * const chains = kit.getSupportedChains()
+     *
+     * console.log('Supported chains:')
+     * chains.forEach(chain => {
+     *   console.log(`- ${chain.name} (${chain.type})`)
+     * })
+     * ```
+     */
+    getSupportedChains() {
+        const supportedChains = this.providers.flatMap((p) => p.supportedChains);
+        // Deduplicate chains by using chain identifiers as object keys
+        // Later duplicates will override earlier ones, keeping only the last occurrence
+        return Object.values(Object.fromEntries(supportedChains.map((chain) => [chain.chain, chain])));
+    }
+    /**
+     * Validate that source and destination chains are on the same network type.
+     *
+     * This method ensures that both chains are either testnet or mainnet, preventing
+     * cross-network transfers which are not supported by the bridging protocols.
+     *
+     * @param resolvedParams - The resolved bridge parameters containing source and destination chains
+     * @throws {NetworkMismatchError} If source and destination chains are on different network types
+     */
+    validateNetworkCompatibility(resolvedParams) {
+        if (resolvedParams.source.chain.isTestnet !==
+            resolvedParams.destination.chain.isTestnet) {
+            throw createNetworkMismatchError(resolvedParams.source.chain, resolvedParams.destination.chain);
+        }
+    }
+    /**
+     * Find a provider that supports the given transfer route.
+     *
+     * This method centralizes the provider selection logic to ensure consistency
+     * between transfer and estimate operations. It resolves the source and destination
+     * chains from the provided adapters and finds the first provider that supports
+     * the route for the specified token.
+     *
+     * @param params - The transfer parameters containing source, destination, and token
+     * @returns Promise resolving to the provider that supports this route
+     * @throws Will throw an error if no provider supports the route
+     */
+    findProviderForRoute(params) {
+        const provider = this.providers.find((p) => p.supportsRoute(params.source.chain, params.destination.chain, params.token));
+        if (!provider) {
+            throw createUnsupportedRouteError(params.source.chain.name, params.destination.chain.name);
+        }
+        return provider;
+    }
+    /**
+     * Merge custom fee configuration into provider parameters.
+     *
+     * Prioritizes any custom fee configuration already present on the
+     * provider-resolved params and uses the kit-level custom fee configuration
+     * as a fallback only when a value is missing. If neither the provider params
+     * nor the kit configuration can supply a value, no custom fee configuration
+     * is added to the provider params.
+     *
+     * @param originalParams - The original bridge parameters received by the kit.
+     * @param providerParams - The provider-resolved bridge parameters that may be enriched.
+     * @returns The same `providerParams` reference with custom fee configuration merged when applicable.
+     *
+     * @remarks
+     * - Existing values on `providerParams.config.customFee` are preserved.
+     * - Kit-level functions are invoked lazily and only for missing values.
+     * - If both sources provide no values, `customFee` is omitted entirely.
+     */
+    async mergeCustomFeeConfig(providerParams) {
+        // Prefer any custom fee already resolved by the provider
+        const existingFee = providerParams.config?.customFee?.value;
+        const existingFeeRecipient = providerParams.config?.customFee?.recipientAddress;
+        // Fill missing values using kit-level configuration (if available)
+        const fee = existingFee ?? (await this.customFeePolicy?.calculateFee(providerParams));
+        const feeRecipient = existingFeeRecipient ??
+            (await this.customFeePolicy?.resolveFeeRecipientAddress(providerParams.source.chain, providerParams));
+        // Only attach customFee if at least one value is defined
+        if (fee !== undefined || feeRecipient !== undefined) {
+            providerParams.config = {
+                ...providerParams.config,
+                customFee: {
+                    value: fee,
+                    recipientAddress: feeRecipient,
+                },
+            };
+        }
+        return providerParams;
+    }
+    /**
+     * Sets the custom fee policy for the kit.
+     *
+     * Ensures the fee is represented in the smallest unit of the token.
+     * - If the token is USDC, the fee is converted to base units (6 decimals).
+     * - If the token is not USDC, the fee is returned as is.
+     *
+     * 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.
+     *
+     * @param customFeePolicy - The custom fee policy to set.
+     * @throws {ValidationError} 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
+     *   },
+     *   resolveFeeRecipientAddress: (feePayoutChain, params) => {
+     *     // Return valid address for the source chain
+     *     return params.source.chain.chain === Blockchain.Ethereum_Sepolia
+     *       ? '0x23f9a5BEA7B92a0638520607407BC7f0310aEeD4'
+     *       : '0x1E1A18B7bD95bcFcFb4d6E245D289C1e95547b35';
+     *   },
+     * });
+     * ```
+     */
+    setCustomFeePolicy(customFeePolicy) {
+        assertCustomFeePolicy(customFeePolicy);
+        const { calculateFee, resolveFeeRecipientAddress } = customFeePolicy;
+        // Format the calculateFee function to convert the fee to the smallest unit of the token
+        const formattedCalculateFee = async (params) => {
+            const fee = await calculateFee(params);
+            const token = params.token ?? 'USDC';
+            return token === 'USDC' ? parseUnits(fee, 6).toString() : fee;
+        };
+        // Return a new custom fee policy with the formatted calculateFee function
+        this.customFeePolicy = {
+            calculateFee: formattedCalculateFee,
+            resolveFeeRecipientAddress,
+        };
+    }
+    /**
+     * Remove the custom fee policy for the kit.
+     *
+     * @example
+     * ```typescript
+     * kit.removeCustomFeePolicy()
+     * ```
+     */
+    removeCustomFeePolicy() {
+        this.customFeePolicy = undefined;
+    }
+}
+
+export { Blockchain, BridgeKit, KitError, bridgeParamsWithChainIdentifierSchema };
+//# sourceMappingURL=index.mjs.map