@circle-fin/bridge-kit 1.1.0 → 1.1.2

package/index.cjs.map

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

package/index.d.ts

@@ -596,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.
      *
@@ -677,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>;
 }
@@ -709,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.
@@ -1178,6 +1179,14 @@ interface CCTPv2ActionMap {
          * the adapter's default address.
          */
         readonly destinationAddress?: string;
+        /**
+         * The mint recipient address from the decoded CCTP message.
+         *
+         * This is the actual address encoded in the burn message where tokens will be minted.
+         * For Solana, this is already the Associated Token Account (ATA) address, not the owner.
+         * For EVM chains, this is the recipient's wallet address.
+         */
+        readonly mintRecipient?: string;
     };
     /**
      * Initiate a cross-chain USDC transfer using a custom bridge contract with preapproval funnel.
@@ -1967,10 +1976,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.
      *
@@ -2052,7 +2074,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.
      *
@@ -2106,10 +2128,10 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * This address is used as the default sender for transactions
      * and interactions initiated by this adapter.
      *
-     * @param chain - Optional chain definition for chain-specific address resolution (used by EVM adapters)
+     * @param chain - The chain to use for address resolution.
      * @returns A promise that resolves to the blockchain address as a string.
      */
-    abstract getAddress(chain?: ChainDefinition): Promise<string>;
+    abstract getAddress(chain: ChainDefinition): Promise<string>;
     /**
      * Switches the adapter to operate on the specified chain.
      *
@@ -2180,7 +2202,7 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * Validate that the target chain is supported by this adapter.
      *
      * @param targetChain - The chain to validate.
-     * @throws Error if the chain is not supported.
+     * @throws KitError with INVALID_CHAIN code if the chain is not supported by this adapter.
      */
     validateChainSupport(targetChain: ChainDefinition): void;
     /**
@@ -2434,6 +2456,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.
  */
@@ -2447,7 +2512,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) */
@@ -4004,6 +4069,15 @@ declare const RECOVERABILITY_VALUES: readonly ["RETRYABLE", "RESUMABLE", "FATAL"
  * - RESUMABLE errors are returned when a flow fails mid-execution but can be continued
  */
 type Recoverability = (typeof RECOVERABILITY_VALUES)[number];
+/**
+ * Array of valid error type values for validation.
+ * Derived from ERROR_TYPES const object.
+ */
+declare const ERROR_TYPE_VALUES: ("INPUT" | "BALANCE" | "ONCHAIN" | "RPC" | "NETWORK")[];
+/**
+ * Error type indicating the category of the error.
+ */
+type ErrorType = (typeof ERROR_TYPE_VALUES)[number];
 /**
  * Structured error details with consistent properties for programmatic handling.
  *
@@ -4015,7 +4089,8 @@ type Recoverability = (typeof RECOVERABILITY_VALUES)[number];
  * ```typescript
  * const error: ErrorDetails = {
  *   code: 1001,
- *   name: "NETWORK_MISMATCH",
+ *   name: "INPUT_NETWORK_MISMATCH",
+ *   type: "INPUT",
  *   recoverability: "FATAL",
  *   message: "Source and destination networks must be different",
  *   cause: {
@@ -4023,15 +4098,31 @@ type Recoverability = (typeof RECOVERABILITY_VALUES)[number];
  *   }
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * const error: ErrorDetails = {
+ *   code: 9001,
+ *   name: "BALANCE_INSUFFICIENT_TOKEN",
+ *   type: "BALANCE",
+ *   recoverability: "FATAL",
+ *   message: "Insufficient USDC balance on Ethereum",
+ *   cause: {
+ *     trace: { token: "USDC", chain: "Ethereum" }
+ *   }
+ * }
+ * ```
  */
 interface ErrorDetails {
-    /** Numeric identifier following standardized ranges (1000+ for INPUT errors) */
+    /** Numeric identifier following standardized ranges (see error code registry) */
     code: number;
-    /** Human-readable ID (e.g., "NETWORK_MISMATCH") */
+    /** Human-readable ID (e.g., "INPUT_NETWORK_MISMATCH", "BALANCE_INSUFFICIENT_TOKEN") */
     name: string;
+    /** Error category indicating where the error originated */
+    type: ErrorType;
     /** Error handling strategy */
     recoverability: Recoverability;
-    /** User-friendly explanation with network context */
+    /** User-friendly explanation with context */
     message: string;
     /** Raw error details, context, or the original error that caused this one. */
     cause?: {
@@ -4088,6 +4179,8 @@ declare class KitError extends Error implements ErrorDetails {
     readonly code: number;
     /** Human-readable ID (e.g., "NETWORK_MISMATCH") */
     readonly name: string;
+    /** Error category indicating where the error originated */
+    readonly type: ErrorType;
     /** Error handling strategy */
     readonly recoverability: Recoverability;
     /** Raw error details, context, or the original error that caused this one. */
@@ -4182,31 +4275,25 @@ declare function isFatalError(error: unknown): boolean;
  */
 declare function isRetryableError(error: unknown): boolean;
 /**
- * Combined type guard to check if error is KitError with INPUT type.
+ * 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.
+ * INPUT errors 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
+ * @returns True if error is KitError with INPUT type
  *
  * @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})`)
- *     }
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isInputError(error)) {
+ *     console.log('Validation error:', error.message)
+ *     showValidationUI()
  *   }
  * }
  * ```
@@ -4263,5 +4350,5 @@ declare function getErrorMessage(error: unknown): string;
  */
 declare function getErrorCode(error: unknown): number | null;
 
-export { Blockchain, BridgeKit, KitError, bridgeParamsWithChainIdentifierSchema, getErrorCode, getErrorMessage, isFatalError, isInputError, isKitError, isRetryableError, setExternalPrefix };
-export type { ActionHandler, BridgeKitConfig, BridgeParams, BridgeResult, ChainDefinition, ChainIdentifier, ErrorDetails, Recoverability };
+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, EstimateResult, Recoverability };