@circle-fin/bridge-kit 1.2.0 → 1.3.0

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2025, Circle Internet Group, Inc. All rights reserved.
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -2750,15 +2750,39 @@ interface BridgeResult {
  *
  * This interface provides detailed information about the expected costs
  * for a transfer, including gas fees on different chains and protocol fees.
+ * It also includes the input context (token, amount, source, destination) to
+ * provide a complete view of the transfer being estimated.
  *
  * @example
  * ```typescript
  * const estimate: EstimateResult = await provider.estimate(source, dest, '100')
+ * console.log('Estimating transfer of', estimate.amount, estimate.token)
+ * console.log('From', estimate.source.chain.name, 'to', estimate.destination.chain.name)
  * console.log('Total gas fees:', estimate.gasFees.length)
  * console.log('Protocol fees:', estimate.fees.length)
  * ```
  */
 interface EstimateResult {
+    /** The token being transferred */
+    token: 'USDC';
+    /** The amount being transferred */
+    amount: string;
+    /** Information about the source chain and address */
+    source: {
+        /** The source wallet/contract address */
+        address: string;
+        /** The source blockchain network */
+        chain: Blockchain;
+    };
+    /** Information about the destination chain and address */
+    destination: {
+        /** The destination wallet/contract address */
+        address: string;
+        /** The destination blockchain network */
+        chain: Blockchain;
+        /** Optional custom recipient address for minted funds. */
+        recipientAddress?: string;
+    };
     /** Array of gas fees required for the transfer on different blockchains */
     gasFees: {
         /** The name of the step */
@@ -4466,6 +4490,233 @@ declare class KitError extends Error implements ErrorDetails {
     constructor(details: ErrorDetails);
 }
 
+/**
+ * Standardized error code ranges for consistent categorization:
+ *
+ * - 1000-1999: INPUT errors - Parameter validation, input format errors
+ * - 3000-3999: NETWORK errors - Internet connectivity, DNS, connection issues
+ * - 4000-4999: RPC errors - Blockchain provider issues, gas estimation, nonce errors
+ * - 5000-5999: ONCHAIN errors - Transaction/simulation failures, gas exhaustion, reverts
+ * - 9000-9999: BALANCE errors - Insufficient funds, token balance, allowance
+ */
+/**
+ * Standardized error definitions for INPUT type errors.
+ *
+ * Each entry combines the numeric error code, string name, and type
+ * to ensure consistency when creating error instances.
+ *
+ * Error codes follow a hierarchical numbering scheme where the first digit
+ * indicates the error category (1 = INPUT) and subsequent digits provide
+ * 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, name, and type individually if needed
+ * console.log(InputError.NETWORK_MISMATCH.code)  // 1001
+ * console.log(InputError.NETWORK_MISMATCH.name)  // 'INPUT_NETWORK_MISMATCH'
+ * console.log(InputError.NETWORK_MISMATCH.type)  // 'INPUT'
+ * ```
+ */
+declare const InputError: {
+    /** Network type mismatch between chains (mainnet vs testnet) */
+    readonly NETWORK_MISMATCH: {
+        readonly code: 1001;
+        readonly name: "INPUT_NETWORK_MISMATCH";
+        readonly type: ErrorType;
+    };
+    /** Invalid amount format or value (negative, zero, or malformed) */
+    readonly INVALID_AMOUNT: {
+        readonly code: 1002;
+        readonly name: "INPUT_INVALID_AMOUNT";
+        readonly type: ErrorType;
+    };
+    /** Unsupported or invalid bridge route configuration */
+    readonly UNSUPPORTED_ROUTE: {
+        readonly code: 1003;
+        readonly name: "INPUT_UNSUPPORTED_ROUTE";
+        readonly type: ErrorType;
+    };
+    /** Invalid wallet or contract address format */
+    readonly INVALID_ADDRESS: {
+        readonly code: 1004;
+        readonly name: "INPUT_INVALID_ADDRESS";
+        readonly type: ErrorType;
+    };
+    /** Invalid or unsupported chain identifier */
+    readonly INVALID_CHAIN: {
+        readonly code: 1005;
+        readonly name: "INPUT_INVALID_CHAIN";
+        readonly type: ErrorType;
+    };
+    /** General validation failure for complex validation rules */
+    readonly VALIDATION_FAILED: {
+        readonly code: 1098;
+        readonly name: "INPUT_VALIDATION_FAILED";
+        readonly type: ErrorType;
+    };
+};
+/**
+ * Standardized error definitions for BALANCE type errors.
+ *
+ * BALANCE errors indicate insufficient funds or allowance issues
+ * that prevent transaction execution.
+ *
+ * @example
+ * ```typescript
+ * import { BalanceError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...BalanceError.INSUFFICIENT_TOKEN,
+ *   recoverability: 'FATAL',
+ *   message: 'Insufficient USDC balance on Ethereum',
+ *   cause: { trace: { required: '100', available: '50' } }
+ * })
+ * ```
+ */
+declare const BalanceError: {
+    /** Insufficient token balance for transaction */
+    readonly INSUFFICIENT_TOKEN: {
+        readonly code: 9001;
+        readonly name: "BALANCE_INSUFFICIENT_TOKEN";
+        readonly type: ErrorType;
+    };
+    /** Insufficient native token (ETH/SOL/etc) for gas fees */
+    readonly INSUFFICIENT_GAS: {
+        readonly code: 9002;
+        readonly name: "BALANCE_INSUFFICIENT_GAS";
+        readonly type: ErrorType;
+    };
+    /** Insufficient allowance for token transfer */
+    readonly INSUFFICIENT_ALLOWANCE: {
+        readonly code: 9003;
+        readonly name: "BALANCE_INSUFFICIENT_ALLOWANCE";
+        readonly type: ErrorType;
+    };
+};
+/**
+ * Standardized error definitions for ONCHAIN type errors.
+ *
+ * ONCHAIN errors occur during transaction execution, simulation,
+ * or interaction with smart contracts on the blockchain.
+ *
+ * @example
+ * ```typescript
+ * import { OnchainError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...OnchainError.SIMULATION_FAILED,
+ *   recoverability: 'FATAL',
+ *   message: 'Simulation failed: ERC20 transfer amount exceeds balance',
+ *   cause: { trace: { reason: 'ERC20: transfer amount exceeds balance' } }
+ * })
+ * ```
+ */
+declare const OnchainError: {
+    /** Transaction reverted on-chain after execution */
+    readonly TRANSACTION_REVERTED: {
+        readonly code: 5001;
+        readonly name: "ONCHAIN_TRANSACTION_REVERTED";
+        readonly type: ErrorType;
+    };
+    /** Pre-flight transaction simulation failed */
+    readonly SIMULATION_FAILED: {
+        readonly code: 5002;
+        readonly name: "ONCHAIN_SIMULATION_FAILED";
+        readonly type: ErrorType;
+    };
+    /** Transaction ran out of gas during execution */
+    readonly OUT_OF_GAS: {
+        readonly code: 5003;
+        readonly name: "ONCHAIN_OUT_OF_GAS";
+        readonly type: ErrorType;
+    };
+    /** Transaction exceeds block gas limit */
+    readonly GAS_LIMIT_EXCEEDED: {
+        readonly code: 5004;
+        readonly name: "ONCHAIN_GAS_LIMIT_EXCEEDED";
+        readonly type: ErrorType;
+    };
+};
+/**
+ * Standardized error definitions for RPC type errors.
+ *
+ * RPC errors occur when communicating with blockchain RPC providers,
+ * including endpoint failures, invalid responses, and provider-specific issues.
+ *
+ * @example
+ * ```typescript
+ * import { RpcError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...RpcError.ENDPOINT_ERROR,
+ *   recoverability: 'RETRYABLE',
+ *   message: 'RPC endpoint unavailable on Ethereum',
+ *   cause: { trace: { endpoint: 'https://mainnet.infura.io' } }
+ * })
+ * ```
+ */
+declare const RpcError: {
+    /** RPC endpoint returned error or is unavailable */
+    readonly ENDPOINT_ERROR: {
+        readonly code: 4001;
+        readonly name: "RPC_ENDPOINT_ERROR";
+        readonly type: ErrorType;
+    };
+    /** Invalid or unexpected RPC response format */
+    readonly INVALID_RESPONSE: {
+        readonly code: 4002;
+        readonly name: "RPC_INVALID_RESPONSE";
+        readonly type: ErrorType;
+    };
+    /** Nonce-related errors from RPC provider */
+    readonly NONCE_ERROR: {
+        readonly code: 4003;
+        readonly name: "RPC_NONCE_ERROR";
+        readonly type: ErrorType;
+    };
+};
+/**
+ * Standardized error definitions for NETWORK type errors.
+ *
+ * NETWORK errors indicate connectivity issues at the network layer,
+ * including DNS failures, connection timeouts, and unreachable endpoints.
+ *
+ * @example
+ * ```typescript
+ * import { NetworkError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...NetworkError.CONNECTION_FAILED,
+ *   recoverability: 'RETRYABLE',
+ *   message: 'Failed to connect to Ethereum network',
+ *   cause: { trace: { error: 'ECONNREFUSED' } }
+ * })
+ * ```
+ */
+declare const NetworkError: {
+    /** Network connection failed or unreachable */
+    readonly CONNECTION_FAILED: {
+        readonly code: 3001;
+        readonly name: "NETWORK_CONNECTION_FAILED";
+        readonly type: ErrorType;
+    };
+    /** Network request timeout */
+    readonly TIMEOUT: {
+        readonly code: 3002;
+        readonly name: "NETWORK_TIMEOUT";
+        readonly type: ErrorType;
+    };
+};
+
 /**
  * Type guard to check if an error is a KitError instance.
  *
@@ -4568,6 +4819,106 @@ declare function isRetryableError(error: unknown): boolean;
  * ```
  */
 declare function isInputError(error: unknown): error is KitError;
+/**
+ * Type guard to check if error is KitError with BALANCE type.
+ *
+ * BALANCE errors indicate insufficient funds or allowance issues
+ * that prevent transaction execution. These errors are always FATAL
+ * and require the user to add funds or approve more tokens.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with BALANCE type
+ *
+ * @example
+ * ```typescript
+ * import { isBalanceError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isBalanceError(error)) {
+ *     console.log('Insufficient funds:', error.message)
+ *     showAddFundsUI()
+ *   }
+ * }
+ * ```
+ */
+declare function isBalanceError(error: unknown): error is KitError;
+/**
+ * Type guard to check if error is KitError with ONCHAIN type.
+ *
+ * ONCHAIN errors occur during transaction execution or simulation,
+ * including reverts, gas issues, and smart contract failures.
+ * These errors are typically FATAL.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with ONCHAIN type
+ *
+ * @example
+ * ```typescript
+ * import { isOnchainError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isOnchainError(error)) {
+ *     console.log('Transaction failed:', error.message)
+ *     showTransactionErrorUI()
+ *   }
+ * }
+ * ```
+ */
+declare function isOnchainError(error: unknown): error is KitError;
+/**
+ * Type guard to check if error is KitError with RPC type.
+ *
+ * RPC errors occur when communicating with blockchain RPC providers.
+ * These errors are typically RETRYABLE as they often indicate
+ * temporary provider issues.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with RPC type
+ *
+ * @example
+ * ```typescript
+ * import { isRpcError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isRpcError(error)) {
+ *     console.log('RPC error:', error.message)
+ *     retryWithBackoff()
+ *   }
+ * }
+ * ```
+ */
+declare function isRpcError(error: unknown): error is KitError;
+/**
+ * Type guard to check if error is KitError with NETWORK type.
+ *
+ * NETWORK errors indicate connectivity issues at the network layer.
+ * These errors are typically RETRYABLE as they often indicate
+ * temporary network problems.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with NETWORK type
+ *
+ * @example
+ * ```typescript
+ * import { isNetworkError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isNetworkError(error)) {
+ *     console.log('Network issue:', error.message)
+ *     retryWithBackoff()
+ *   }
+ * }
+ * ```
+ */
+declare function isNetworkError(error: unknown): error is KitError;
 /**
  * Safely extracts error message from any error type.
  *
@@ -4619,5 +4970,5 @@ declare function getErrorMessage(error: unknown): string;
  */
 declare function getErrorCode(error: unknown): number | null;
 
-export { Blockchain, BridgeChain, BridgeKit, KitError, TransferSpeed, bridgeParamsWithChainIdentifierSchema, getErrorCode, getErrorMessage, isFatalError, isInputError, isKitError, isRetryableError, resolveChainIdentifier, setExternalPrefix };
-export type { ActionHandler, AdapterContext, BridgeChainIdentifier, BridgeConfig, BridgeKitConfig, BridgeParams, BridgeResult, ChainDefinition, ChainIdentifier, CustomFeePolicy, ErrorDetails, EstimateResult, Recoverability };
+export { BalanceError, Blockchain, BridgeChain, BridgeKit, InputError, KitError, NetworkError, OnchainError, RpcError, TransferSpeed, bridgeParamsWithChainIdentifierSchema, getErrorCode, getErrorMessage, isBalanceError, isFatalError, isInputError, isKitError, isNetworkError, isOnchainError, isRetryableError, isRpcError, resolveChainIdentifier, setExternalPrefix };
+export type { ActionHandler, AdapterContext, BaseChainDefinition, BridgeChainIdentifier, BridgeConfig, BridgeKitConfig, BridgeParams, BridgeResult, CCTPConfig, CCTPContracts, CCTPMergedConfig, CCTPSplitConfig, ChainDefinition, ChainIdentifier, Currency, CustomFeePolicy, EVMChainDefinition, ErrorDetails, EstimateResult, EstimatedGas, KitContractType, KitContracts, NonEVMChainDefinition, Recoverability, RetryContext, VersionConfig };