@circle-fin/bridge-kit 1.3.0 → 1.5.0

package/index.cjs

@@ -122,6 +122,8 @@ const ERROR_TYPES = {
     RPC: 'RPC',
     /** Internet connectivity, DNS resolution, connection issues */
     NETWORK: 'NETWORK',
+    /** Catch-all for unrecognized errors (code 0) */
+    UNKNOWN: 'UNKNOWN',
 };
 /**
  * Array of valid error type values for validation.
@@ -135,6 +137,8 @@ const ERROR_TYPE_ARRAY = [...ERROR_TYPE_VALUES];
 /**
  * Error code ranges for validation.
  * Single source of truth for valid error code ranges.
+ *
+ * Note: Code 0 is special - it's the UNKNOWN catch-all error.
  */
 const ERROR_CODE_RANGES = [
     { min: 1000, max: 1999, type: 'INPUT' },
@@ -143,6 +147,8 @@ const ERROR_CODE_RANGES = [
     { min: 5000, max: 5999, type: 'ONCHAIN' },
     { min: 9000, max: 9999, type: 'BALANCE' },
 ];
+/** Special code for UNKNOWN errors */
+const UNKNOWN_ERROR_CODE = 0;
 /**
  * Zod schema for validating ErrorDetails objects.
  *
@@ -181,6 +187,7 @@ const ERROR_CODE_RANGES = [
 const errorDetailsSchema = zod.z.object({
     /**
      * Numeric identifier following standardized ranges:
+     * - 0: UNKNOWN - Catch-all for unrecognized errors
      * - 1000-1999: INPUT errors - Parameter validation
      * - 3000-3999: NETWORK errors - Connectivity issues
      * - 4000-4999: RPC errors - Provider issues, gas estimation
@@ -190,8 +197,9 @@ const errorDetailsSchema = zod.z.object({
     code: zod.z
         .number()
         .int('Error code must be an integer')
-        .refine((code) => ERROR_CODE_RANGES.some((range) => code >= range.min && code <= range.max), {
-        message: 'Error code must be in valid ranges: 1000-1999 (INPUT), 3000-3999 (NETWORK), 4000-4999 (RPC), 5000-5999 (ONCHAIN), 9000-9999 (BALANCE)',
+        .refine((code) => code === UNKNOWN_ERROR_CODE ||
+        ERROR_CODE_RANGES.some((range) => code >= range.min && code <= range.max), {
+        message: 'Error code must be 0 (UNKNOWN) or in valid ranges: 1000-1999 (INPUT), 3000-3999 (NETWORK), 4000-4999 (RPC), 5000-5999 (ONCHAIN), 9000-9999 (BALANCE)',
     }),
     /** Human-readable ID (e.g., "INPUT_NETWORK_MISMATCH", "BALANCE_INSUFFICIENT_TOKEN") */
     name: zod.z
@@ -201,7 +209,7 @@ const errorDetailsSchema = zod.z.object({
     /** Error category indicating where the error originated */
     type: zod.z.enum(ERROR_TYPE_ARRAY, {
         errorMap: () => ({
-            message: 'Error type must be one of: INPUT, BALANCE, ONCHAIN, RPC, NETWORK',
+            message: 'Error type must be one of: INPUT, BALANCE, ONCHAIN, RPC, NETWORK, UNKNOWN',
         }),
     }),
     /** Error handling strategy */
@@ -418,6 +426,7 @@ class KitError extends Error {
 /**
  * Standardized error code ranges for consistent categorization:
  *
+ * - 0: UNKNOWN - Catch-all for unrecognized errors
  * - 1000-1999: INPUT errors - Parameter validation, input format errors
  * - 3000-3999: NETWORK errors - Internet connectivity, DNS, connection issues
  * - 4000-4999: RPC errors - Blockchain provider issues, gas estimation, nonce errors
@@ -482,6 +491,12 @@ const InputError = {
         name: 'INPUT_INVALID_CHAIN',
         type: 'INPUT',
     },
+    /** Invalid or unknown token (symbol not found, missing decimals, etc.) */
+    INVALID_TOKEN: {
+        code: 1006,
+        name: 'INPUT_INVALID_TOKEN',
+        type: 'INPUT',
+    },
     /** General validation failure for complex validation rules */
     VALIDATION_FAILED: {
         code: 1098,
@@ -960,6 +975,8 @@ exports.Blockchain = void 0;
     Blockchain["Ink_Testnet"] = "Ink_Testnet";
     Blockchain["Linea"] = "Linea";
     Blockchain["Linea_Sepolia"] = "Linea_Sepolia";
+    Blockchain["Monad"] = "Monad";
+    Blockchain["Monad_Testnet"] = "Monad_Testnet";
     Blockchain["NEAR"] = "NEAR";
     Blockchain["NEAR_Testnet"] = "NEAR_Testnet";
     Blockchain["Noble"] = "Noble";
@@ -1051,6 +1068,7 @@ exports.BridgeChain = void 0;
     BridgeChain["HyperEVM"] = "HyperEVM";
     BridgeChain["Ink"] = "Ink";
     BridgeChain["Linea"] = "Linea";
+    BridgeChain["Monad"] = "Monad";
     BridgeChain["Optimism"] = "Optimism";
     BridgeChain["Plume"] = "Plume";
     BridgeChain["Polygon"] = "Polygon";
@@ -1070,6 +1088,7 @@ exports.BridgeChain = void 0;
     BridgeChain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
     BridgeChain["Ink_Testnet"] = "Ink_Testnet";
     BridgeChain["Linea_Sepolia"] = "Linea_Sepolia";
+    BridgeChain["Monad_Testnet"] = "Monad_Testnet";
     BridgeChain["Optimism_Sepolia"] = "Optimism_Sepolia";
     BridgeChain["Plume_Testnet"] = "Plume_Testnet";
     BridgeChain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
@@ -1264,8 +1283,11 @@ const ArcTestnet = defineChain({
     name: 'Arc Testnet',
     title: 'ArcTestnet',
     nativeCurrency: {
-        name: 'Arc',
-        symbol: 'Arc',
+        name: 'USDC',
+        symbol: 'USDC',
+        // Arc uses native USDC with 18 decimals for gas payments (EVM standard).
+        // Note: The ERC-20 USDC contract at usdcAddress uses 6 decimals.
+        // See: https://docs.arc.network/arc/references/contract-addresses
         decimals: 18,
     },
     chainId: 5042002,
@@ -2053,6 +2075,86 @@ const LineaSepolia = defineChain({
     },
 });
 
+/**
+ * Monad Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Monad blockchain.
+ * Monad is a high-performance EVM-compatible Layer-1 blockchain featuring
+ * over 10,000 TPS, sub-second finality, and near-zero gas fees.
+ */
+const Monad = defineChain({
+    type: 'evm',
+    chain: exports.Blockchain.Monad,
+    name: 'Monad',
+    title: 'Monad Mainnet',
+    nativeCurrency: {
+        name: 'Monad',
+        symbol: 'MON',
+        decimals: 18,
+    },
+    chainId: 143,
+    isTestnet: false,
+    explorerUrl: 'https://monadscan.com/tx/{hash}',
+    rpcEndpoints: ['https://rpc.monad.xyz'],
+    eurcAddress: null,
+    usdcAddress: '0x754704Bc059F8C67012fEd69BC8A327a5aafb603',
+    cctp: {
+        domain: 15,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+    },
+});
+
+/**
+ * Monad Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Monad blockchain.
+ * Monad is a high-performance EVM-compatible Layer-1 blockchain featuring
+ * over 10,000 TPS, sub-second finality, and near-zero gas fees.
+ */
+const MonadTestnet = defineChain({
+    type: 'evm',
+    chain: exports.Blockchain.Monad_Testnet,
+    name: 'Monad Testnet',
+    title: 'Monad Testnet',
+    nativeCurrency: {
+        name: 'Monad',
+        symbol: 'MON',
+        decimals: 18,
+    },
+    chainId: 10143,
+    isTestnet: true,
+    explorerUrl: 'https://testnet.monadscan.com/tx/{hash}',
+    rpcEndpoints: ['https://testnet-rpc.monad.xyz'],
+    eurcAddress: null,
+    usdcAddress: '0x534b2f3A21130d7a60830c2Df862319e593943A3',
+    cctp: {
+        domain: 15,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
 /**
  * NEAR Protocol Mainnet chain definition
  * @remarks
@@ -3137,6 +3239,8 @@ var Blockchains = {
     InkTestnet: InkTestnet,
     Linea: Linea,
     LineaSepolia: LineaSepolia,
+    Monad: Monad,
+    MonadTestnet: MonadTestnet,
     NEAR: NEAR,
     NEARTestnet: NEARTestnet,
     Noble: Noble,
@@ -3548,14 +3652,41 @@ function isFatalError(error) {
     return isKitError(error) && error.recoverability === 'FATAL';
 }
 /**
- * Checks if an error is a KitError with RETRYABLE recoverability.
+ * Error codes that are considered retryable by default.
+ *
+ * @remarks
+ * These are typically transient errors that may succeed on retry:
+ * - Network connectivity issues (3001, 3002)
+ * - Provider unavailability (4001, 4002)
+ * - RPC nonce errors (4003)
+ */
+const DEFAULT_RETRYABLE_ERROR_CODES = [
+    // Network errors
+    3001, // NETWORK_CONNECTION_FAILED
+    3002, // NETWORK_TIMEOUT
+    // Provider errors
+    4001, // PROVIDER_UNAVAILABLE
+    4002, // PROVIDER_TIMEOUT
+    4003, // RPC_NONCE_ERROR
+];
+/**
+ * Checks if an error is retryable.
+ *
+ * @remarks
+ * Check order for KitError instances:
+ * 1. If `recoverability === 'RETRYABLE'`, return `true` immediately (priority check).
+ * 2. Otherwise, check if `error.code` is in `DEFAULT_RETRYABLE_ERROR_CODES` (fallback check).
+ * 3. Non-KitError instances always return `false`.
+ *
+ * This two-tier approach allows both explicit recoverability control and
+ * backward-compatible code-based retry logic.
  *
  * RETRYABLE errors indicate transient failures that may succeed on
  * subsequent attempts, such as network timeouts or temporary service
  * unavailability. These errors are safe to retry after a delay.
  *
  * @param error - Unknown error to check
- * @returns True if error is a KitError with RETRYABLE recoverability
+ * @returns True if error is retryable
  *
  * @example
  * ```typescript
@@ -3570,9 +3701,51 @@ function isFatalError(error) {
  *   }
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * import { isRetryableError, createNetworkConnectionError, KitError } from '@core/errors'
+ *
+ * // KitError with RETRYABLE recoverability (priority check)
+ * const error1 = createNetworkConnectionError('Ethereum')
+ * isRetryableError(error1) // true
+ *
+ * // KitError with default retryable code (fallback check)
+ * const error2 = new KitError({
+ *   code: 3002, // NETWORK_TIMEOUT - in DEFAULT_RETRYABLE_ERROR_CODES
+ *   name: 'NETWORK_TIMEOUT',
+ *   type: 'NETWORK',
+ *   recoverability: 'FATAL', // Not RETRYABLE
+ *   message: 'Timeout',
+ * })
+ * isRetryableError(error2) // true (code 3002 is in default list)
+ *
+ * // KitError with non-retryable code and FATAL recoverability
+ * const error3 = new KitError({
+ *   code: 1001,
+ *   name: 'INVALID_INPUT',
+ *   type: 'INPUT',
+ *   recoverability: 'FATAL',
+ *   message: 'Invalid input',
+ * })
+ * isRetryableError(error3) // false
+ *
+ * // Non-KitError
+ * const error4 = new Error('Standard error')
+ * isRetryableError(error4) // false
+ * ```
  */
 function isRetryableError(error) {
-    return isKitError(error) && error.recoverability === 'RETRYABLE';
+    // Use proper type guard to check if it's a KitError
+    if (isKitError(error)) {
+        // Priority check: explicit recoverability
+        if (error.recoverability === 'RETRYABLE') {
+            return true;
+        }
+        // Fallback check: error code against default retryable codes
+        return DEFAULT_RETRYABLE_ERROR_CODES.includes(error.code);
+    }
+    return false;
 }
 /**
  * Type guard to check if error is KitError with INPUT type.
@@ -4630,7 +4803,7 @@ const parseAmount = (params) => {
 };
 
 var name = "@circle-fin/bridge-kit";
-var version = "1.3.0";
+var version = "1.5.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -5907,7 +6080,7 @@ class BridgeKit {
         return formatBridgeResult(await provider.estimate(finalResolvedParams), 'to-human-readable');
     }
     /**
-     * Get all chains supported by any provider in the kit.
+     * Get all chains supported by any provider in the kit, with optional filtering.
      *
      * Aggregate and deduplicate the supported chains from all registered providers.
      * This provides a comprehensive list of chains that can be used as either source
@@ -5917,6 +6090,7 @@ class BridgeKit {
      * ensuring each chain appears only once in the result regardless of how many
      * providers support it.
      *
+     * @param options - Optional filtering options to narrow down the returned chains
      * @returns Array of unique chain definitions supported by the registered providers
      *
      * @example
@@ -5924,19 +6098,56 @@ class BridgeKit {
      * import { BridgeKit } from '@circle-fin/bridge-kit'
      *
      * const kit = new BridgeKit()
-     * const chains = kit.getSupportedChains()
+     *
+     * // Get all supported chains (no filtering)
+     * const allChains = kit.getSupportedChains()
+     *
+     * // Get only EVM chains
+     * const evmChains = kit.getSupportedChains({ chainType: 'evm' })
+     *
+     * // Get EVM and Solana chains
+     * const evmAndSolana = kit.getSupportedChains({ chainType: ['evm', 'solana'] })
+     *
+     * // Get only mainnet chains
+     * const mainnets = kit.getSupportedChains({ isTestnet: false })
+     *
+     * // Get only EVM mainnet chains
+     * const evmMainnets = kit.getSupportedChains({ chainType: 'evm', isTestnet: false })
      *
      * console.log('Supported chains:')
-     * chains.forEach(chain => {
+     * allChains.forEach(chain => {
      *   console.log(`- ${chain.name} (${chain.type})`)
      * })
      * ```
      */
-    getSupportedChains() {
+    getSupportedChains(options) {
         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])));
+        let chains = Object.values(Object.fromEntries(supportedChains.map((chain) => [chain.chain, chain])));
+        // Apply chain type filter if provided
+        if (options?.chainType !== undefined) {
+            // Validate at runtime since JS consumers can bypass TypeScript's narrow type.
+            const supportedChainTypes = ['evm', 'solana'];
+            const chainTypeInput = options.chainType;
+            const chainTypeValues = Array.isArray(chainTypeInput)
+                ? chainTypeInput
+                : [chainTypeInput];
+            if (!chainTypeValues.every((chainType) => supportedChainTypes.includes(chainType))) {
+                const listFormatter = new Intl.ListFormat('en', {
+                    style: 'long',
+                    type: 'conjunction',
+                });
+                throw createValidationFailedError$1('options.chainType', options.chainType, `Supported chain types include: ${listFormatter.format(supportedChainTypes)}`);
+            }
+            const chainTypes = new Set(chainTypeValues);
+            chains = chains.filter((chain) => chainTypes.has(chain.type));
+        }
+        // Apply testnet filter if provided
+        if (options?.isTestnet !== undefined) {
+            chains = chains.filter((chain) => chain.isTestnet === options.isTestnet);
+        }
+        return chains;
     }
     /**
      * Validate that source and destination chains are on the same network type.