@circle-fin/bridge-kit 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @circle-fin/bridge-kit
 
+## 1.3.0
+
+### Minor Changes
+
+- **Enhanced bridge estimate response**: `EstimateResult` now includes `token`, `amount`, `source`, `destination` fields to provide complete transfer information alongside cost estimates.
+- Export error handling utilities and constants.
+
+New exports include:
+
+- Error type guards: isKitError, isBalanceError, isOnchainError, isRpcError, isNetworkError, isRetryableError, isFatalError
+- Error constants: BalanceError, OnchainError, RpcError, NetworkError, InputError
+- Utility: getErrorCode, getErrorMessage
+
 ## 1.2.0
 
 ### Minor Changes

package/chains.cjs

@@ -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
  *

package/chains.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
  *

package/chains.mjs

@@ -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
  *

package/index.cjs

@@ -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
  *
@@ -272,6 +272,40 @@ function validateErrorDetails(details) {
  * stays within KitError's constraints.
  */
 const MAX_MESSAGE_LENGTH = 950;
+/**
+ * Standard error message for invalid amount format.
+ *
+ * The SDK enforces strict dot-decimal notation for amount values. This constant
+ * provides a consistent error message when users provide amounts with:
+ * - Comma decimals (e.g., "1,5")
+ * - Thousand separators (e.g., "1,000.50")
+ * - Non-numeric characters
+ * - Invalid format
+ */
+const AMOUNT_FORMAT_ERROR_MESSAGE = 'Amount must be a numeric string with dot (.) as decimal separator (e.g., "10.5", "100"), with no thousand separators or comma decimals';
+/**
+ * Error message for amounts that must be greater than zero.
+ */
+const AMOUNT_GREATER_THAN_ZERO_MESSAGE = 'Amount must be greater than 0';
+/**
+ * Error message for amounts exceeding maximum decimal places.
+ *
+ * USDC uses 6 decimal places, so amounts with more precision are invalid.
+ */
+const AMOUNT_MAX_DECIMAL_PLACES_MESSAGE = 'Maximum supported decimal places: 6';
+/**
+ * Error message for amounts that must be non-negative.
+ *
+ * Used when validating amounts that can be zero or positive but not negative.
+ */
+const AMOUNT_NON_NEGATIVE_MESSAGE = 'Amount must be non-negative';
+/**
+ * Error message for invalid maxFee format.
+ *
+ * Used when validating the maxFee configuration parameter. The maxFee can be zero
+ * or positive and must follow strict dot-decimal notation.
+ */
+const MAX_FEE_FORMAT_ERROR_MESSAGE = 'maxFee must be a numeric string with dot (.) as decimal separator (e.g., "1", "0.5", ".5", "1.5"), with no thousand separators or comma decimals';
 
 /**
  * Structured error class for Stablecoin Kit operations.
@@ -455,6 +489,158 @@ const InputError = {
         type: 'INPUT',
     },
 };
+/**
+ * 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' } }
+ * })
+ * ```
+ */
+const BalanceError = {
+    /** Insufficient token balance for transaction */
+    INSUFFICIENT_TOKEN: {
+        code: 9001,
+        name: 'BALANCE_INSUFFICIENT_TOKEN',
+        type: 'BALANCE',
+    },
+    /** Insufficient native token (ETH/SOL/etc) for gas fees */
+    INSUFFICIENT_GAS: {
+        code: 9002,
+        name: 'BALANCE_INSUFFICIENT_GAS',
+        type: 'BALANCE',
+    },
+    /** Insufficient allowance for token transfer */
+    INSUFFICIENT_ALLOWANCE: {
+        code: 9003,
+        name: 'BALANCE_INSUFFICIENT_ALLOWANCE',
+        type: 'BALANCE',
+    },
+};
+/**
+ * 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' } }
+ * })
+ * ```
+ */
+const OnchainError = {
+    /** Transaction reverted on-chain after execution */
+    TRANSACTION_REVERTED: {
+        code: 5001,
+        name: 'ONCHAIN_TRANSACTION_REVERTED',
+        type: 'ONCHAIN',
+    },
+    /** Pre-flight transaction simulation failed */
+    SIMULATION_FAILED: {
+        code: 5002,
+        name: 'ONCHAIN_SIMULATION_FAILED',
+        type: 'ONCHAIN',
+    },
+    /** Transaction ran out of gas during execution */
+    OUT_OF_GAS: {
+        code: 5003,
+        name: 'ONCHAIN_OUT_OF_GAS',
+        type: 'ONCHAIN',
+    },
+    /** Transaction exceeds block gas limit */
+    GAS_LIMIT_EXCEEDED: {
+        code: 5004,
+        name: 'ONCHAIN_GAS_LIMIT_EXCEEDED',
+        type: 'ONCHAIN',
+    },
+};
+/**
+ * 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' } }
+ * })
+ * ```
+ */
+const RpcError = {
+    /** RPC endpoint returned error or is unavailable */
+    ENDPOINT_ERROR: {
+        code: 4001,
+        name: 'RPC_ENDPOINT_ERROR',
+        type: 'RPC',
+    },
+    /** Invalid or unexpected RPC response format */
+    INVALID_RESPONSE: {
+        code: 4002,
+        name: 'RPC_INVALID_RESPONSE',
+        type: 'RPC',
+    },
+    /** Nonce-related errors from RPC provider */
+    NONCE_ERROR: {
+        code: 4003,
+        name: 'RPC_NONCE_ERROR',
+        type: 'RPC',
+    },
+};
+/**
+ * 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' } }
+ * })
+ * ```
+ */
+const NetworkError = {
+    /** Network connection failed or unreachable */
+    CONNECTION_FAILED: {
+        code: 3001,
+        name: 'NETWORK_CONNECTION_FAILED',
+        type: 'NETWORK',
+    },
+    /** Network request timeout */
+    TIMEOUT: {
+        code: 3002,
+        name: 'NETWORK_TIMEOUT',
+        type: 'NETWORK',
+    },
+};
 
 /**
  * Creates error for network type mismatch between source and destination.
@@ -3415,6 +3601,114 @@ function isRetryableError(error) {
 function isInputError(error) {
     return isKitError(error) && error.type === ERROR_TYPES.INPUT;
 }
+/**
+ * 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()
+ *   }
+ * }
+ * ```
+ */
+function isBalanceError(error) {
+    return isKitError(error) && error.type === ERROR_TYPES.BALANCE;
+}
+/**
+ * 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()
+ *   }
+ * }
+ * ```
+ */
+function isOnchainError(error) {
+    return isKitError(error) && error.type === ERROR_TYPES.ONCHAIN;
+}
+/**
+ * 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()
+ *   }
+ * }
+ * ```
+ */
+function isRpcError(error) {
+    return isKitError(error) && error.type === ERROR_TYPES.RPC;
+}
+/**
+ * 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()
+ *   }
+ * }
+ * ```
+ */
+function isNetworkError(error) {
+    return isKitError(error) && error.type === ERROR_TYPES.NETWORK;
+}
 /**
  * Safely extracts error message from any error type.
  *
@@ -3704,7 +3998,6 @@ function convertZodErrorToStructured(zodError, params) {
 function createValidationFailedError(zodError) {
     return createValidationErrorFromZod(zodError, 'parameters');
 }
-const AMOUNT_FORMAT_ERROR_MESSAGE = 'Amount must be a numeric string with dot (.) as decimal separator, with no thousand separators or comma decimals';
 /**
  * Handles amount-related validation errors from Zod.
  *
@@ -3754,7 +4047,7 @@ function handleAmountError(path, code, message, paramsObj) {
  */
 function handleNegativeAmountError(code, message, amount) {
     if (code === 'too_small' || message.includes('greater than')) {
-        return createInvalidAmountError(amount, 'Amount must be greater than 0');
+        return createInvalidAmountError(amount, AMOUNT_GREATER_THAN_ZERO_MESSAGE);
     }
     return null;
 }
@@ -3776,10 +4069,10 @@ function handleCustomAmountError(code, message, amount) {
     if (code !== 'custom')
         return null;
     if (message.includes('non-negative')) {
-        return createInvalidAmountError(amount, 'Amount must be non-negative');
+        return createInvalidAmountError(amount, AMOUNT_NON_NEGATIVE_MESSAGE);
     }
     if (message.includes('greater than 0')) {
-        return createInvalidAmountError(amount, 'Amount must be greater than 0');
+        return createInvalidAmountError(amount, AMOUNT_GREATER_THAN_ZERO_MESSAGE);
     }
     if (message.includes('decimal places')) {
         return createInvalidAmountError(amount, message);
@@ -3812,7 +4105,7 @@ function handleInvalidStringAmountError(code, message, amount) {
         return null;
     // Check for decimal places validation
     if (isDecimalPlacesError(message)) {
-        return createInvalidAmountError(amount, 'Maximum supported decimal places: 6');
+        return createInvalidAmountError(amount, AMOUNT_MAX_DECIMAL_PLACES_MESSAGE);
     }
     // Check for numeric format validation
     if (isNumericFormatError(message)) {
@@ -4337,7 +4630,7 @@ const parseAmount = (params) => {
 };
 
 var name = "@circle-fin/bridge-kit";
-var version = "1.2.0";
+var version = "1.3.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -4703,41 +4996,46 @@ exports.TransferSpeed = void 0;
  * - regexMessage: error message when the basic numeric format fails.
  * - maxDecimals: maximum number of decimal places allowed (e.g., 6 for USDC).
  */
-const createDecimalStringValidator = (options) => (schema) => schema
-    .regex(/^-?(?:\d+(?:\.\d+)?|\.\d+)$/, options.regexMessage)
-    .superRefine((val, ctx) => {
-    const amount = Number.parseFloat(val);
-    if (Number.isNaN(amount)) {
-        ctx.addIssue({
-            code: zod.z.ZodIssueCode.custom,
-            message: options.regexMessage,
-        });
-        return;
-    }
-    // Check decimal precision if maxDecimals is specified
-    if (options.maxDecimals !== undefined) {
-        const decimalPart = val.split('.')[1];
-        if (decimalPart && decimalPart.length > options.maxDecimals) {
+const createDecimalStringValidator = (options) => (schema) => {
+    // Capitalize first letter of attribute name for error messages
+    const capitalizedAttributeName = options.attributeName.charAt(0).toUpperCase() +
+        options.attributeName.slice(1);
+    return schema
+        .regex(/^-?(?:\d+(?:\.\d+)?|\.\d+)$/, options.regexMessage)
+        .superRefine((val, ctx) => {
+        const amount = Number.parseFloat(val);
+        if (Number.isNaN(amount)) {
             ctx.addIssue({
                 code: zod.z.ZodIssueCode.custom,
-                message: `Maximum supported decimal places: ${options.maxDecimals.toString()}`,
+                message: options.regexMessage,
             });
             return;
         }
-    }
-    if (options.allowZero && amount < 0) {
-        ctx.addIssue({
-            code: zod.z.ZodIssueCode.custom,
-            message: `${options.attributeName} must be non-negative`,
-        });
-    }
-    else if (!options.allowZero && amount <= 0) {
-        ctx.addIssue({
-            code: zod.z.ZodIssueCode.custom,
-            message: `${options.attributeName} must be greater than 0`,
-        });
-    }
-});
+        // Check decimal precision if maxDecimals is specified
+        if (options.maxDecimals !== undefined) {
+            const decimalPart = val.split('.')[1];
+            if (decimalPart && decimalPart.length > options.maxDecimals) {
+                ctx.addIssue({
+                    code: zod.z.ZodIssueCode.custom,
+                    message: `Maximum supported decimal places: ${options.maxDecimals.toString()}`,
+                });
+                return;
+            }
+        }
+        if (options.allowZero && amount < 0) {
+            ctx.addIssue({
+                code: zod.z.ZodIssueCode.custom,
+                message: `${capitalizedAttributeName} must be non-negative`,
+            });
+        }
+        else if (!options.allowZero && amount <= 0) {
+            ctx.addIssue({
+                code: zod.z.ZodIssueCode.custom,
+                message: `${capitalizedAttributeName} must be greater than 0`,
+            });
+        }
+    });
+};
 /**
  * Schema for validating chain definitions.
  * This ensures the basic structure of a chain definition is valid.
@@ -4897,7 +5195,7 @@ zod.z.object({
         .min(1, 'Required')
         .pipe(createDecimalStringValidator({
         allowZero: false,
-        regexMessage: 'Amount must be a numeric string with dot (.) as decimal separator (e.g., "0.1", ".1", "10.5", "1000.50"), with no thousand separators or comma decimals.',
+        regexMessage: AMOUNT_FORMAT_ERROR_MESSAGE,
         attributeName: 'amount',
         maxDecimals: 6,
     })(zod.z.string())),
@@ -4910,7 +5208,7 @@ zod.z.object({
             .string()
             .pipe(createDecimalStringValidator({
             allowZero: true,
-            regexMessage: 'maxFee must be a numeric string with dot (.) as decimal separator (e.g., "1", "0.5", ".5", "1.5"), with no thousand separators or comma decimals.',
+            regexMessage: MAX_FEE_FORMAT_ERROR_MESSAGE,
             attributeName: 'maxFee',
             maxDecimals: 6,
         })(zod.z.string()))
@@ -4919,11 +5217,6 @@ zod.z.object({
     }),
 });
 
-/**
- * Error message constants for validation
- */
-const AMOUNT_VALIDATION_MESSAGE = 'Amount must be a numeric string with dot (.) as decimal separator (e.g., "0.1", ".1", "10.5", "1000.50"), with no thousand separators or comma decimals.';
-const MAX_FEE_VALIDATION_MESSAGE = 'maxFee must be a numeric string with dot (.) as decimal separator (e.g., "1", "0.5", ".5", "1.5"), with no thousand separators or comma decimals.';
 /**
  * Schema for validating AdapterContext for bridge operations.
  * Must always contain both adapter and chain explicitly.
@@ -5018,7 +5311,7 @@ const bridgeParamsWithChainIdentifierSchema = zod.z.object({
         .min(1, 'Required')
         .pipe(createDecimalStringValidator({
         allowZero: false,
-        regexMessage: AMOUNT_VALIDATION_MESSAGE,
+        regexMessage: AMOUNT_FORMAT_ERROR_MESSAGE,
         attributeName: 'amount',
         maxDecimals: 6,
     })(zod.z.string())),
@@ -5031,7 +5324,7 @@ const bridgeParamsWithChainIdentifierSchema = zod.z.object({
             .min(1, 'Required')
             .pipe(createDecimalStringValidator({
             allowZero: true,
-            regexMessage: MAX_FEE_VALIDATION_MESSAGE,
+            regexMessage: MAX_FEE_FORMAT_ERROR_MESSAGE,
             attributeName: 'maxFee',
             maxDecimals: 6,
         })(zod.z.string()))
@@ -5292,6 +5585,8 @@ const getAmountTransformer = (formatDirection) => formatDirection === 'to-human-
     : (params) => parseAmount(params).toString();
 /**
  * Format the bridge result into human-readable string values for the user or bigint string values for internal use.
+ *
+ * @typeParam T - The specific result type (must extend BridgeResult or EstimateResult). Preserves the exact type passed in.
  * @param result - The bridge result to format.
  * @param formatDirection - The direction to format the result in.
  *   - If 'to-human-readable', the result will be converted to human-readable string values.
@@ -5321,7 +5616,9 @@ const formatBridgeResult = (result, formatDirection) => {
     return {
         ...result,
         amount: transform({ value: result.amount, token: result.token }),
-        ...(result.config && {
+        ...('config' in result &&
+            result.config &&
+            Object.keys(result.config).length > 0 && {
             config: {
                 ...result.config,
                 ...(result.config.maxFee && {
@@ -5333,12 +5630,12 @@ const formatBridgeResult = (result, formatDirection) => {
                 ...(result.config.customFee && {
                     customFee: {
                         ...result.config.customFee,
-                        value: result.config.customFee.value
-                            ? transform({
+                        ...(result.config.customFee.value && {
+                            value: transform({
                                 value: result.config.customFee.value,
                                 token: result.token,
-                            })
-                            : undefined,
+                            }),
+                        }),
                     },
                 }),
             },
@@ -5606,8 +5903,8 @@ class BridgeKit {
         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);
+        // Estimate the transfer using the provider and format amounts to human-readable strings
+        return formatBridgeResult(await provider.estimate(finalResolvedParams), 'to-human-readable');
     }
     /**
      * Get all chains supported by any provider in the kit.
@@ -5826,15 +6123,24 @@ class BridgeKit {
 // Auto-register this kit for user agent tracking
 registerKit(`${pkg.name}/${pkg.version}`);
 
+exports.BalanceError = BalanceError;
 exports.BridgeKit = BridgeKit;
+exports.InputError = InputError;
 exports.KitError = KitError;
+exports.NetworkError = NetworkError;
+exports.OnchainError = OnchainError;
+exports.RpcError = RpcError;
 exports.bridgeParamsWithChainIdentifierSchema = bridgeParamsWithChainIdentifierSchema;
 exports.getErrorCode = getErrorCode;
 exports.getErrorMessage = getErrorMessage;
+exports.isBalanceError = isBalanceError;
 exports.isFatalError = isFatalError;
 exports.isInputError = isInputError;
 exports.isKitError = isKitError;
+exports.isNetworkError = isNetworkError;
+exports.isOnchainError = isOnchainError;
 exports.isRetryableError = isRetryableError;
+exports.isRpcError = isRpcError;
 exports.resolveChainIdentifier = resolveChainIdentifier;
 exports.setExternalPrefix = setExternalPrefix;
 //# sourceMappingURL=index.cjs.map