@circle-fin/bridge-kit 1.0.0 → 1.1.0

package/index.cjs.js

@@ -25,6 +25,47 @@ require('bs58');
 var units = require('@ethersproject/units');
 var providerCctpV2 = require('@circle-fin/provider-cctp-v2');
 
+/**
+ * Detect the runtime environment and return a shortened identifier.
+ *
+ * @returns Runtime string, e.g., "node/18", "browser/Chrome", or "unknown"
+ */
+/**
+ * Set an application-level identifier prefix for all HTTP requests.
+ *
+ * This allows applications to identify themselves in the user agent string,
+ * which is useful for tracking and analytics at the application level.
+ *
+ * @param prefix - Application identifier with version, e.g., "my-app/1.0.0"
+ *
+ * @example
+ * ```typescript
+ * import { setExternalPrefix } from '\@circle-fin/bridge-kit'
+ *
+ * setExternalPrefix('my-dapp/2.1.0')
+ * // All subsequent HTTP requests will include this prefix
+ * ```
+ */
+const setExternalPrefix = (prefix) => {
+    if (typeof globalThis !== 'undefined') {
+        globalThis.__STABLECOIN_KITS_EXTERNAL_PREFIX__ = prefix;
+    }
+};
+/**
+ * Register a kit identifier globally (internal use only).
+ *
+ * This is called automatically when a kit module loads, using build-time
+ * injected constants. For now, only one kit can be registered at a time.
+ *
+ * @param kitIdentifier - Kit identifier, e.g., "\@circle-fin/bridge-kit/1.2.3"
+ * @internal
+ */
+const registerKit = (kitIdentifier) => {
+    if (typeof globalThis !== 'undefined') {
+        globalThis.__STABLECOIN_KITS_CURRENT_KIT__ = kitIdentifier;
+    }
+};
+
 /**
  * Custom error class for validation errors.
  * Provides structured error information while hiding implementation details.
@@ -328,6 +369,12 @@ const parseUnits = (value, decimals) => {
     return units.parseUnits(value, decimals).toBigInt();
 };
 
+var name = "@circle-fin/bridge-kit";
+var version = "1.1.0";
+var pkg = {
+	name: name,
+	version: version};
+
 /**
  * Valid recoverability values for error handling strategies.
  *
@@ -525,6 +572,16 @@ class KitError extends Error {
     }
 }
 
+/**
+ * Minimum error code for INPUT type errors.
+ * INPUT errors represent validation failures and invalid parameters.
+ */
+const INPUT_ERROR_CODE_MIN = 1000;
+/**
+ * Maximum error code for INPUT type errors (exclusive).
+ * INPUT error codes range from 1000 to 1099 inclusive.
+ */
+const INPUT_ERROR_CODE_MAX = 1100;
 /**
  * Standardized error definitions for INPUT type errors.
  *
@@ -742,6 +799,185 @@ function createInvalidChainError(chain, reason) {
     return new KitError(errorDetails);
 }
 
+/**
+ * Type guard to check if an error is a KitError instance.
+ *
+ * This guard enables TypeScript to narrow the type from `unknown` to
+ * `KitError`, providing access to structured error properties like
+ * code, name, and recoverability.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with proper type narrowing
+ *
+ * @example
+ * ```typescript
+ * import { isKitError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isKitError(error)) {
+ *     // TypeScript knows this is KitError
+ *     console.log(`Structured error: ${error.name} (${error.code})`)
+ *   } else {
+ *     console.log('Regular error:', error)
+ *   }
+ * }
+ * ```
+ */
+function isKitError(error) {
+    return error instanceof KitError;
+}
+/**
+ * Checks if an error is a KitError with FATAL recoverability.
+ *
+ * FATAL errors indicate issues that cannot be resolved through retries,
+ * such as invalid inputs, configuration problems, or business rule
+ * violations. These errors require user intervention to fix.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is a KitError with FATAL recoverability
+ *
+ * @example
+ * ```typescript
+ * import { isFatalError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isFatalError(error)) {
+ *     // Show user-friendly error message - don't retry
+ *     showUserError(error.message)
+ *   }
+ * }
+ * ```
+ */
+function isFatalError(error) {
+    return isKitError(error) && error.recoverability === 'FATAL';
+}
+/**
+ * Checks if an error is a KitError with RETRYABLE recoverability.
+ *
+ * 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
+ *
+ * @example
+ * ```typescript
+ * import { isRetryableError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isRetryableError(error)) {
+ *     // Implement retry logic with exponential backoff
+ *     setTimeout(() => retryOperation(), 5000)
+ *   }
+ * }
+ * ```
+ */
+function isRetryableError(error) {
+    return isKitError(error) && error.recoverability === 'RETRYABLE';
+}
+/**
+ * Combined type guard to check if error is KitError with INPUT type.
+ *
+ * INPUT errors have error codes in the 1000-1099 range and represent
+ * validation failures, invalid parameters, or user input problems.
+ * These errors are always FATAL and require the user to correct their
+ * input before retrying.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with INPUT error code range
+ *
+ * @example
+ * ```typescript
+ * import { isInputError } from '@core/errors'
+ * import { createBridgeKit } from '@core/bridge'
+ *
+ * async function handleBridge() {
+ *   const kit = createBridgeKit(config)
+ *   const params = { amount: '100', from: 'ethereum', to: 'polygon' }
+ *
+ *   try {
+ *     await kit.bridge(params)
+ *   } catch (error) {
+ *     if (isInputError(error)) {
+ *       console.log(`Input error: ${error.message} (code: ${error.code})`)
+ *     }
+ *   }
+ * }
+ * ```
+ */
+function isInputError(error) {
+    return (isKitError(error) &&
+        error.code >= INPUT_ERROR_CODE_MIN &&
+        error.code < INPUT_ERROR_CODE_MAX);
+}
+/**
+ * Safely extracts error message from any error type.
+ *
+ * This utility handles different error types gracefully, extracting
+ * meaningful messages from Error instances, string errors, or providing
+ * a fallback for unknown error types. Never throws.
+ *
+ * @param error - Unknown error to extract message from
+ * @returns Error message string, or fallback message
+ *
+ * @example
+ * ```typescript
+ * import { getErrorMessage } from '@core/errors'
+ *
+ * try {
+ *   await riskyOperation()
+ * } catch (error) {
+ *   const message = getErrorMessage(error)
+ *   console.log('Error occurred:', message)
+ *   // Works with Error, KitError, string, or any other type
+ * }
+ * ```
+ */
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return 'An unknown error occurred';
+}
+/**
+ * Gets the error code from a KitError, or null if not applicable.
+ *
+ * This utility safely extracts the numeric error code from KitError
+ * instances, returning null for non-KitError types. Useful for
+ * programmatic error handling based on specific error codes.
+ *
+ * @param error - Unknown error to extract code from
+ * @returns Error code number, or null if not a KitError
+ *
+ * @example
+ * ```typescript
+ * import { getErrorCode, InputError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   const code = getErrorCode(error)
+ *   if (code === InputError.NETWORK_MISMATCH.code) {
+ *     // Handle network mismatch specifically
+ *     showNetworkMismatchHelp()
+ *   }
+ * }
+ * ```
+ */
+function getErrorCode(error) {
+    return isKitError(error) ? error.code : null;
+}
+
 /**
  * Extracts chain information including name, display name, and expected address format.
  *
@@ -1401,6 +1637,7 @@ exports.Blockchain = void 0;
     Blockchain["Algorand_Testnet"] = "Algorand_Testnet";
     Blockchain["Aptos"] = "Aptos";
     Blockchain["Aptos_Testnet"] = "Aptos_Testnet";
+    Blockchain["Arc_Testnet"] = "Arc_Testnet";
     Blockchain["Arbitrum"] = "Arbitrum";
     Blockchain["Arbitrum_Sepolia"] = "Arbitrum_Sepolia";
     Blockchain["Avalanche"] = "Avalanche";
@@ -1621,6 +1858,48 @@ const BRIDGE_CONTRACT_EVM_TESTNET = '0xC5567a5E3370d4DBfB0540025078e283e36A363d'
  */
 const BRIDGE_CONTRACT_EVM_MAINNET = '0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0';
 
+/**
+ * Arc Testnet chain definition
+ * @remarks
+ * This represents the test network for the Arc blockchain,
+ * Circle's EVM-compatible Layer-1 designed for stablecoin finance
+ * and asset tokenization. Arc uses USDC as the native gas token and
+ * features the Malachite Byzantine Fault Tolerant (BFT) consensus
+ * engine for sub-second finality.
+ */
+const ArcTestnet = defineChain({
+    type: 'evm',
+    chain: exports.Blockchain.Arc_Testnet,
+    name: 'Arc Testnet',
+    title: 'ArcTestnet',
+    nativeCurrency: {
+        name: 'Arc',
+        symbol: 'Arc',
+        decimals: 18,
+    },
+    chainId: 5042002,
+    isTestnet: true,
+    explorerUrl: 'https://testnet.arcscan.app/tx/{hash}',
+    rpcEndpoints: ['https://rpc.testnet.arc.network/'],
+    eurcAddress: '0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a',
+    usdcAddress: '0x3600000000000000000000000000000000000000',
+    cctp: {
+        domain: 26,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 1,
+                fastConfirmations: 1,
+            },
+        },
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+    },
+});
+
 /**
  * Arbitrum Mainnet chain definition
  * @remarks
@@ -2912,26 +3191,26 @@ const Sonic = defineChain({
 });
 
 /**
- * Sonic Blaze Testnet chain definition
+ * Sonic Testnet chain definition
  * @remarks
  * This represents the official test network for the Sonic blockchain.
  */
 const SonicTestnet = defineChain({
     type: 'evm',
     chain: exports.Blockchain.Sonic_Testnet,
-    name: 'Sonic Blaze Testnet',
-    title: 'Sonic Blaze Testnet',
+    name: 'Sonic Testnet',
+    title: 'Sonic Testnet',
     nativeCurrency: {
         name: 'Sonic',
         symbol: 'S',
         decimals: 18,
     },
-    chainId: 57054,
+    chainId: 14601,
     isTestnet: true,
     explorerUrl: 'https://testnet.sonicscan.org/tx/{hash}',
-    rpcEndpoints: ['https://rpc.blaze.soniclabs.com'],
+    rpcEndpoints: ['https://rpc.testnet.soniclabs.com'],
     eurcAddress: null,
-    usdcAddress: '0xA4879Fed32Ecbef99399e5cbC247E533421C4eC6',
+    usdcAddress: '0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51',
     cctp: {
         domain: 13,
         contracts: {
@@ -3448,6 +3727,7 @@ var Blockchains = {
     AptosTestnet: AptosTestnet,
     Arbitrum: Arbitrum,
     ArbitrumSepolia: ArbitrumSepolia,
+    ArcTestnet: ArcTestnet,
     Avalanche: Avalanche,
     AvalancheFuji: AvalancheFuji,
     Base: Base,
@@ -4081,9 +4361,9 @@ const customFeeSchema = zod.z
  *   token: 'USDC',
  *   config: {
  *     transferSpeed: 'FAST',
- *     maxFee: '1000000'
+ *     maxFee: '1.5', // Decimal format
  *     customFee: {
- *       value: '1000000',
+ *       value: '0.5', // Decimal format
  *       recipientAddress: '0x1234567890123456789012345678901234567890'
  *     }
  *   }
@@ -4110,7 +4390,12 @@ zod.z.object({
         transferSpeed: zod.z.nativeEnum(TransferSpeed).optional(),
         maxFee: zod.z
             .string()
-            .regex(/^\d+$/, 'Max fee must be a numeric string')
+            .pipe(createDecimalStringValidator({
+            allowZero: true,
+            regexMessage: 'maxFee must be a numeric string with optional decimal places (e.g., "1", "0.5", "1.5")',
+            attributeName: 'maxFee',
+            maxDecimals: 6,
+        })(zod.z.string()))
             .optional(),
         customFee: customFeeSchema.optional(),
     }),
@@ -4119,10 +4404,12 @@ zod.z.object({
 /**
  * Schema for validating AdapterContext.
  * Must always contain both adapter and chain explicitly.
+ * Optionally includes address for developer-controlled adapters.
  */
 const adapterContextSchema = zod.z.object({
     adapter: adapterSchema,
     chain: chainIdentifierSchema,
+    address: zod.z.string().optional(),
 });
 /**
  * Schema for validating BridgeDestinationWithAddress objects.
@@ -4200,7 +4487,7 @@ const bridgeDestinationSchema = zod.z.union([
  * ```
  */
 const bridgeParamsWithChainIdentifierSchema = zod.z.object({
-    from: adapterContextSchema,
+    from: adapterContextSchema.strict(),
     to: bridgeDestinationSchema,
     amount: zod.z
         .string()
@@ -4217,7 +4504,13 @@ const bridgeParamsWithChainIdentifierSchema = zod.z.object({
         transferSpeed: zod.z.nativeEnum(TransferSpeed).optional(),
         maxFee: zod.z
             .string()
-            .regex(/^\d+$/, 'Max fee must be a numeric string')
+            .min(1, 'Required')
+            .pipe(createDecimalStringValidator({
+            allowZero: true,
+            regexMessage: 'Max fee must be a numeric string with optional decimal places (e.g., 1, 0.5, 1.5)',
+            attributeName: 'maxFee',
+            maxDecimals: 6,
+        })(zod.z.string()))
             .optional(),
         customFee: customFeeSchema.optional(),
     })
@@ -4286,10 +4579,25 @@ async function resolveAddress(ctx) {
     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);
+    // Handle based on adapter's addressContext
+    if (ctx.adapter.capabilities?.addressContext === 'developer-controlled') {
+        // Developer-controlled: address must be provided explicitly
+        if ('address' in ctx && ctx.address) {
+            return ctx.address;
+        }
+        throw new Error('Address is required in context for developer-controlled adapters. ' +
+            'Please provide: { adapter, chain, address: "0x..." }');
+    }
+    else {
+        // User-controlled: address should not be provided (auto-resolved from adapter)
+        if ('address' in ctx && ctx.address) {
+            throw new Error('Address should not be provided for user-controlled adapters. ' +
+                'The address is automatically resolved from the connected wallet.');
+        }
+        // Derive address from adapter
+        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.
@@ -4326,7 +4634,8 @@ function resolveAmount(params) {
  * 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)
+ * - Max fee values converted from human-readable to smallest units (6 decimals for USDC)
+ * - Custom fee values converted from human-readable to smallest units (6 decimals for USDC)
  *
  * @param params - The bridge parameters containing optional configuration
  * @returns A normalized BridgeConfig with defaults applied and values formatted
@@ -4341,35 +4650,45 @@ function resolveAmount(params) {
  *   from: { adapter: mockAdapter, chain: Ethereum },
  *   to: { adapter: mockAdapter, chain: Base },
  *   config: {
+ *     maxFee: '1',
  *     customFee: { value: '0.5' }
  *   }
  * }
  * const config = resolveConfig(params)
  * // Returns: {
  * //   transferSpeed: TransferSpeed.FAST,
+ * //   maxFee: '1000000',
  * //   customFee: { value: '500000' }
  * // }
  * ```
  */
 function resolveConfig(params) {
+    // Convert maxFee from human-readable to minor units if provided
+    const maxFee = params.config?.maxFee
+        ? parseUnits(params.config.maxFee, 6).toString()
+        : undefined;
+    // Convert customFee.value from human-readable to minor units if provided
+    const rawCustomFee = params.config?.customFee;
+    const customFee = rawCustomFee
+        ? {
+            ...rawCustomFee,
+            value: rawCustomFee.value
+                ? parseUnits(rawCustomFee.value, 6).toString()
+                : undefined,
+        }
+        : undefined;
     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,
+        ...(maxFee !== undefined && { maxFee }),
+        ...(customFee !== undefined && { customFee }),
     };
 }
 /**
  * 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.
+ * into the format expected by bridging providers.
  *
  * The function performs parallel resolution of:
  * - Source and destination addresses
@@ -4856,7 +5175,24 @@ class BridgeKit {
     }
 }
 
+/**
+ *
+ * Bridge Kit
+ *
+ * A strongly-typed SDK for moving USDC between heterogeneous blockchain networks
+ * @packageDocumentation
+ */
+// Auto-register this kit for user agent tracking
+registerKit(`${pkg.name}/${pkg.version}`);
+
 exports.BridgeKit = BridgeKit;
 exports.KitError = KitError;
 exports.bridgeParamsWithChainIdentifierSchema = bridgeParamsWithChainIdentifierSchema;
+exports.getErrorCode = getErrorCode;
+exports.getErrorMessage = getErrorMessage;
+exports.isFatalError = isFatalError;
+exports.isInputError = isInputError;
+exports.isKitError = isKitError;
+exports.isRetryableError = isRetryableError;
+exports.setExternalPrefix = setExternalPrefix;
 //# sourceMappingURL=index.cjs.js.map