@circle-fin/bridge-kit 1.0.0 → 1.1.1

package/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/index.d.ts

@@ -19,7 +19,7 @@
 import { Abi } from 'abitype';
 import { TransactionInstruction, Signer } from '@solana/web3.js';
 import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2';
-import { z } from '/home/runner/_work/stablecoin-kits-private/stablecoin-kits-private/node_modules/zod/dist/types/index.d.ts';
+import { z } from '/home/runner/_work/stablecoin-kits-private/stablecoin-kits-private/kits/bridge-kit/node_modules/zod/dist/types/index.d.ts';
 
 /**
  * @packageDocumentation
@@ -410,6 +410,7 @@ declare enum Blockchain {
     Algorand_Testnet = "Algorand_Testnet",
     Aptos = "Aptos",
     Aptos_Testnet = "Aptos_Testnet",
+    Arc_Testnet = "Arc_Testnet",
     Arbitrum = "Arbitrum",
     Arbitrum_Sepolia = "Arbitrum_Sepolia",
     Avalanche = "Avalanche",
@@ -595,10 +596,11 @@ interface EvmPreparedChainRequest {
      * Estimate the gas cost for the contract execution.
      *
      * @param overrides - Optional parameters to override the default estimation behavior
+     * @param fallback - Optional fallback gas information to use if the estimation fails
      * @returns A promise that resolves to the estimated gas information
      * @throws If the estimation fails
      */
-    estimate(overrides?: EvmEstimateOverrides): Promise<EstimatedGas>;
+    estimate(overrides?: EvmEstimateOverrides, fallback?: EstimatedGas): Promise<EstimatedGas>;
     /**
      * Execute the prepared contract call.
      *
@@ -676,7 +678,7 @@ interface SolanaPreparedChainRequest {
     /** The type of the chain request. */
     type: 'solana';
     /** Estimate the compute units and fee for the transaction. */
-    estimate(overrides?: SolanaEstimateOverrides): Promise<EstimatedGas>;
+    estimate(overrides?: SolanaEstimateOverrides, fallback?: EstimatedGas): Promise<EstimatedGas>;
     /** Execute the prepared transaction. */
     execute(overrides?: SolanaExecuteOverrides): Promise<string>;
 }
@@ -708,7 +710,7 @@ interface NoopPreparedChainRequest {
      * Placeholder for the estimate method.
      * @returns The estimated gas cost.
      */
-    estimate: () => Promise<EstimatedGas>;
+    estimate: (overrides?: EvmEstimateOverrides | SolanaEstimateOverrides, fallback?: EstimatedGas) => Promise<EstimatedGas>;
     /**
      * Placeholder for the execute method.
      * @returns The transaction hash.
@@ -1966,10 +1968,23 @@ interface AdapterCapabilities {
  */
 declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
     /**
-     * The type of the chain.
-     * @example 'evm', 'solana'
+     * The type of the chain for this adapter.
+     *
+     * - For concrete adapters, this should be a real chain type (e.g., `'evm'`, `'solana'`, etc.) from the ChainType union.
+     * - For hybrid adapters (adapters that route to concrete adapters supporting multiple ecosystems),
+     *   set this property to the string literal `'hybrid'`.
+     *
+     * Note: `'hybrid'` is not a legal ChainType and should only be used as a marker for multi-ecosystem adapters.
+     * Hybrid adapters do not interact directly with any chain, but instead route requests to a concrete underlying adapter.
+     *
+     * @example
+     *   // For an EVM-only adapter:
+     *   chainType = 'evm'
+     *
+     *   // For a hybrid adapter:
+     *   chainType = 'hybrid'
      */
-    abstract chainType: ChainType;
+    abstract chainType: ChainType | 'hybrid';
     /**
      * Capabilities of this adapter, defining address control model and supported chains.
      *
@@ -2051,7 +2066,7 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * })
      * ```
      */
-    prepareAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>, ctx?: OperationContext<TAdapterCapabilities>): Promise<PreparedChainRequest>;
+    prepareAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>, ctx: OperationContext<TAdapterCapabilities>): Promise<PreparedChainRequest>;
     /**
      * Prepares a transaction for future gas estimation and execution.
      *
@@ -2349,6 +2364,24 @@ declare class Actionable<AllActions> {
     dispatch<K extends keyof AllActions>(action: K, payload: AllActions[K]): void;
 }
 
+/**
+ * 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
+ * ```
+ */
+declare const setExternalPrefix: (prefix: string) => void;
+
 /**
  * Transfer speed options for cross-chain operations.
  *
@@ -2415,6 +2448,49 @@ TChainDefinition extends ChainDefinition = ChainDefinition> {
      */
     chain: TChainDefinition;
 }
+/**
+ * Wallet context for bridge destinations with optional custom recipient.
+ *
+ * Extends WalletContext to support scenarios where the recipient address
+ * differs from the signer address (e.g., bridging to a third-party wallet).
+ * The signer address is used for transaction authorization, while the
+ * recipient address specifies where the minted funds should be sent.
+ *
+ * @typeParam TAdapterCapabilities - The adapter capabilities type to use for the wallet context.
+ * @typeParam TChainDefinition - The chain definition type to use for the wallet context.
+ *
+ * @example
+ * ```typescript
+ * import type { DestinationWalletContext } from '@core/provider'
+ * import { adapter, blockchain } from './setup'
+ *
+ * // Bridge to a custom recipient address
+ * const destination: DestinationWalletContext = {
+ *   adapter,
+ *   address: '0x1234...abcd', // Signer address
+ *   chain: blockchain,
+ *   recipientAddress: '0x9876...fedc' // Custom recipient
+ * }
+ * ```
+ */
+interface DestinationWalletContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, 
+/**
+ * The chain definition type to use for the wallet context.
+ *
+ * @defaultValue ChainDefinition
+ */
+TChainDefinition extends ChainDefinition = ChainDefinition> extends WalletContext<TAdapterCapabilities, TChainDefinition> {
+    /**
+     * Optional custom recipient address for minted funds.
+     *
+     * When provided, minted tokens will be sent to this address instead of
+     * the address specified in the wallet context. The wallet context address
+     * is still used for transaction signing and authorization.
+     *
+     * Must be a valid address format for the specified blockchain.
+     */
+    recipientAddress?: string;
+}
 /**
  * Parameters for executing a cross-chain bridge operation.
  */
@@ -2428,7 +2504,7 @@ TChainDefinition extends ChainDefinition = ChainDefinition> {
     /** The source adapter containing wallet and chain information */
     source: WalletContext<TFromCapabilities, TChainDefinition>;
     /** The destination adapter containing wallet and chain information */
-    destination: WalletContext<TToCapabilities, TChainDefinition>;
+    destination: DestinationWalletContext<TToCapabilities, TChainDefinition>;
     /** The amount to transfer (as a string to avoid precision issues) */
     amount: string;
     /** The token to transfer (currently only USDC is supported) */
@@ -2572,7 +2648,26 @@ interface BridgeConfig {
     /**
      * The maximum fee to pay for the burn operation.
      *
-     * @defaultValue 0
+     * Provide the amount as a base-10 numeric string representing the
+     * token amount in human-readable format. For example: to set a maximum
+     * fee of 1 USDC, pass `"1"`. Decimal values are supported (e.g., `"0.5"`
+     * for half a USDC).
+     *
+     * @defaultValue `"0"`
+     *
+     * @example
+     * ```typescript
+     * import type { BridgeConfig, TransferSpeed } from '@core/provider'
+     *
+     * const config: BridgeConfig = {
+     *   transferSpeed: TransferSpeed.FAST,
+     *   maxFee: "1", // 1 USDC maximum fee
+     *   customFee: {
+     *     value: "0.5", // 0.5 USDC developer fee
+     *     recipientAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
+     *   }
+     * }
+     * ```
      */
     maxFee?: string;
     /**
@@ -2583,8 +2678,8 @@ interface BridgeConfig {
 /**
  * Custom fee configuration charged by the integrator.
  *
- * Use to charge an absolute fee on the source chain, in the token's
- * smallest unit.
+ * Use to charge an absolute fee on the source chain in human-readable
+ * token amounts.
  *
  * @remarks
  * This is an absolute amount, not a percentage. The `recipientAddress` must be
@@ -2595,7 +2690,7 @@ interface BridgeConfig {
  * import type { CustomFee } from '@core/provider'
  *
  * const config: CustomFee = {
- *   value: '1000000', // 1 USDC in base units (6 decimals)
+ *   value: '1', // 1 USDC
  *   recipientAddress: '0x1234567890123456789012345678901234567890',
  * }
  * ```
@@ -2603,20 +2698,25 @@ interface BridgeConfig {
 interface CustomFee {
     /**
      * The absolute fee to charge for the transfer.
-     * Provide the amount as a base-10 numeric string representing the integer amount of the token (not in smallest units).
-     * For example: to charge 1 USDC or 1 USDC, pass `'1'`.
+     *
+     * Provide the amount as a base-10 numeric string representing the token
+     * amount in human-readable format. For example: to charge 1 USDC, pass
+     * `"1"`. Decimal values are supported (e.g., `"0.5"` for half a USDC).
      * This is not a percentage.
      *
-     * Note: passing `'0'` results in no fee being charged.
+     * Note: passing `"0"` results in no fee being charged.
      */
     value?: string | undefined;
     /**
      * The fee recipient for the bridge transfer.
-     * This is the address that will receive the fee on the source chain of the bridge transfer.
-     * The fee recipient address **must be a valid address for the source chain** of the bridge transfer.
+     *
+     * This is the address that will receive the fee on the source chain of the
+     * bridge transfer. The fee recipient address **must be a valid address for
+     * the source chain** of the bridge transfer.
      *
      * For example: if bridging from Ethereum to Solana, pass an EVM address like
-     * `'0x1234567890123456789012345678901234567890'` because the source chain is Ethereum.
+     * `"0x1234567890123456789012345678901234567890"` because the source chain
+     * is Ethereum.
      */
     recipientAddress?: string | undefined;
 }
@@ -3732,13 +3832,15 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         }>;
         chain: never;
-    }, "strip", z.ZodTypeAny, {
+        address: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
             waitForTransaction: (...args: unknown[]) => unknown;
             getAddress: (...args: unknown[]) => unknown;
         };
         chain: never;
+        address?: string | undefined;
     }, {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
@@ -3746,6 +3848,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         };
         chain: never;
+        address?: string | undefined;
     }>;
     to: z.ZodUnion<[z.ZodEffects<z.ZodObject<{
         adapter: z.ZodObject<{
@@ -3762,6 +3865,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         }>;
         chain: never;
+        address: z.ZodOptional<z.ZodString>;
     } & {
         recipientAddress: z.ZodString;
     }, "strip", z.ZodTypeAny, {
@@ -3772,6 +3876,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
         };
         chain: never;
         recipientAddress: string;
+        address?: string | undefined;
     }, {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
@@ -3780,6 +3885,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
         };
         chain: never;
         recipientAddress: string;
+        address?: string | undefined;
     }>, {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
@@ -3788,6 +3894,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
         };
         chain: never;
         recipientAddress: string;
+        address?: string | undefined;
     }, {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
@@ -3796,6 +3903,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
         };
         chain: never;
         recipientAddress: string;
+        address?: string | undefined;
     }>, z.ZodObject<{
         adapter: z.ZodObject<{
             prepare: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
@@ -3811,6 +3919,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         }>;
         chain: never;
+        address: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
@@ -3818,6 +3927,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         };
         chain: never;
+        address?: string | undefined;
     }, {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
@@ -3825,12 +3935,13 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         };
         chain: never;
+        address?: string | undefined;
     }>]>;
     amount: z.ZodPipeline<z.ZodString, z.ZodType<string, z.ZodTypeDef, string>>;
     token: z.ZodOptional<z.ZodLiteral<"USDC">>;
     config: z.ZodOptional<z.ZodObject<{
         transferSpeed: z.ZodOptional<z.ZodNativeEnum<typeof TransferSpeed>>;
-        maxFee: z.ZodOptional<z.ZodString>;
+        maxFee: z.ZodOptional<z.ZodPipeline<z.ZodString, z.ZodType<string, z.ZodTypeDef, string>>>;
         customFee: z.ZodOptional<z.ZodObject<{
             value: z.ZodOptional<z.ZodType<string, z.ZodTypeDef, string>>;
             recipientAddress: z.ZodOptional<z.ZodString>;
@@ -3864,6 +3975,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         };
         chain: never;
+        address?: string | undefined;
     };
     to: {
         adapter: {
@@ -3872,6 +3984,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         };
         chain: never;
+        address?: string | undefined;
     } | {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
@@ -3880,6 +3993,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
         };
         chain: never;
         recipientAddress: string;
+        address?: string | undefined;
     };
     amount: string;
     token?: "USDC" | undefined;
@@ -3899,6 +4013,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         };
         chain: never;
+        address?: string | undefined;
     };
     to: {
         adapter: {
@@ -3907,6 +4022,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         };
         chain: never;
+        address?: string | undefined;
     } | {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
@@ -3915,6 +4031,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
         };
         chain: never;
         recipientAddress: string;
+        address?: string | undefined;
     };
     amount: string;
     token?: "USDC" | undefined;
@@ -4044,5 +4161,164 @@ declare class KitError extends Error implements ErrorDetails {
     constructor(details: ErrorDetails);
 }
 
-export { Blockchain, BridgeKit, KitError, bridgeParamsWithChainIdentifierSchema };
-export type { ActionHandler, BridgeKitConfig, BridgeParams, BridgeResult, ChainDefinition, ChainIdentifier, ErrorDetails, Recoverability };
+/**
+ * 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)
+ *   }
+ * }
+ * ```
+ */
+declare function isKitError(error: unknown): error is 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)
+ *   }
+ * }
+ * ```
+ */
+declare function isFatalError(error: unknown): boolean;
+/**
+ * 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)
+ *   }
+ * }
+ * ```
+ */
+declare function isRetryableError(error: unknown): boolean;
+/**
+ * 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})`)
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function isInputError(error: unknown): error is KitError;
+/**
+ * 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
+ * }
+ * ```
+ */
+declare function getErrorMessage(error: unknown): string;
+/**
+ * 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()
+ *   }
+ * }
+ * ```
+ */
+declare function getErrorCode(error: unknown): number | null;
+
+export { Blockchain, BridgeKit, KitError, TransferSpeed, bridgeParamsWithChainIdentifierSchema, getErrorCode, getErrorMessage, isFatalError, isInputError, isKitError, isRetryableError, setExternalPrefix };
+export type { ActionHandler, AdapterContext, BridgeConfig, BridgeKitConfig, BridgeParams, BridgeResult, ChainDefinition, ChainIdentifier, CustomFeePolicy, ErrorDetails, Recoverability };