@circle-fin/provider-cctp-v2 1.0.0 → 1.0.2

package/index.cjs.map

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

package/index.d.ts

@@ -408,6 +408,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",
@@ -593,10 +594,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.
      *
@@ -674,7 +676,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>;
 }
@@ -706,7 +708,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.
@@ -1964,10 +1966,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.
      *
@@ -2049,7 +2064,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.
      *
@@ -2434,6 +2449,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 +2505,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) */
@@ -2591,7 +2649,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;
     /**
@@ -2602,8 +2679,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
@@ -2614,7 +2691,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',
  * }
  * ```
@@ -2622,20 +2699,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;
 }
@@ -3125,7 +3207,7 @@ type CCTPV2BridgeParams<TFromAdapterCapabilities extends AdapterCapabilities = A
     /**
      * The destination wallet context containing the chain definition and wallet address.
      */
-    destination: WalletContext<TToAdapterCapabilities, ChainDefinitionWithCCTPv2>;
+    destination: DestinationWalletContext<TToAdapterCapabilities, ChainDefinitionWithCCTPv2>;
     /**
      * The bridge configuration for the CCTPv2 transfer.
      */
@@ -3134,17 +3216,28 @@ type CCTPV2BridgeParams<TFromAdapterCapabilities extends AdapterCapabilities = A
 /**
  * Action types supported by the CCTP v2 provider.
  *
+ * @remarks
  * This interface defines the structure of actions that can be dispatched during
- * CCTP v2 transfer operations. Each action includes protocol metadata and specific
- * values required for the operation.
+ * CCTP v2 transfer operations. Each action includes protocol metadata and a
+ * `values` field containing the full bridge step with transaction details.
+ *
+ * All transaction-based steps (approve, burn, mint) include `txHash` and
+ * `explorerUrl` fields for direct links to block explorers.
  *
  * @example
  * ```typescript
- * const approveAction: CCTPV2Actions['approve'] = {
+ * // Action structure received by event listeners
+ * const burnAction: CCTPV2Actions['burn'] = {
  *   protocol: 'cctp',
  *   version: 'v2',
- *   method: 'approve',
- *   values: { amount: '100.50', fee: '0.1' }
+ *   method: 'burn',
+ *   values: {
+ *     name: 'burn',
+ *     state: 'success',
+ *     txHash: '0x2ed454c5cfab41f0a58ad0c55bf6c326eb97067d2b02fa046dc5698bfc5530f1',
+ *     explorerUrl: 'https://sepolia.etherscan.io/tx/0x2ed454...',
+ *     data: { ... }
+ *   }
  * }
  * ```
  */
@@ -3220,7 +3313,7 @@ interface ICCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> {
      * @param txHash - The transaction hash of the deposit for burn transaction.
      * @returns A promise that resolves to the attestation message.
      */
-    fetchAttestation<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(source: BridgeParams<TFromAdapterCapabilities, TToAdapterCapabilities>['source'], txHash: string): Promise<AttestationMessage>;
+    fetchAttestation<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(source: BridgeParams<TFromAdapterCapabilities, TToAdapterCapabilities>['source'], txHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
     /**
      * Mints the amount of tokens for the destination wallet.
      *
@@ -3487,7 +3580,7 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      * console.log('Mint transaction:', txHash)
      * ```
      */
-    mint<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(source: WalletContext<TFromAdapterCapabilities, ChainDefinitionWithCCTPv2>, destination: WalletContext<TToAdapterCapabilities, ChainDefinitionWithCCTPv2>, attestation: AttestationMessage): Promise<PreparedChainRequest>;
+    mint<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(source: WalletContext<TFromAdapterCapabilities, ChainDefinitionWithCCTPv2>, destination: BridgeParams<TFromAdapterCapabilities, TToAdapterCapabilities>['destination'], attestation: AttestationMessage): Promise<PreparedChainRequest>;
     /**
      * Fetches attestation data for a burn transaction from the IRIS API.
      *
@@ -3568,7 +3661,9 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      *   - `source`: The source wallet context with chain definition and adapter
      *   - `destination`: The destination wallet context with chain definition and adapter
      *   - `amount`: The bridge amount in minor units (e.g., "1000000" for 1 USDC)
-     *   - `config`: Optional bridge configuration including transferSpeed and maxFee settings
+     *   - `config`: Optional bridge configuration including transferSpeed and maxFee settings.
+     *     When used via BridgeKit, fee values are automatically converted from human-readable
+     *     format (e.g., "1") to smallest units (e.g., "1000000").
      * @returns The maximum fee to be used for the bridge operation in minor units
      *
      * @example
@@ -3576,9 +3671,12 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      * const maxFee = await provider.getMaxFee({
      *   source: { adapter: sourceAdapter, chain: Chains.Ethereum, address: '0x...' },
      *   destination: { adapter: destAdapter, chain: Chains.Base, address: '0x...' },
-     *   amount: '1000000', // 1 USDC
+     *   amount: '1000000', // 1 USDC in minor units
      *   token: 'USDC',
-     *   config: { transferSpeed: TransferSpeed.FAST }
+     *   config: {
+     *     transferSpeed: TransferSpeed.FAST,
+     *     maxFee: '1000000' // Provider receives values in smallest units
+     *   }
      * })
      * console.log('Max fee:', maxFee)
      * ```
@@ -3633,5 +3731,44 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
     waitForTransaction(adapter: Adapter, txHash: string, chain: ChainDefinition, config?: WaitForTransactionConfig): Promise<WaitForTransactionResponse>;
 }
 
-export { CCTPV2BridgingProvider };
+/**
+ * Get the token account address where USDC will be minted for the recipient.
+ *
+ * For EVM chains, the recipient address directly holds ERC20 tokens, so the raw
+ * address is returned as-is. For Solana, USDC is held in Associated Token Accounts
+ * (ATAs), so this function derives the ATA address for the given owner and USDC mint.
+ *
+ * @param chainType - The type of blockchain ('evm' or 'solana').
+ * @param rawAddress - The recipient's wallet address on the destination chain.
+ * @param mint - The USDC mint address (only used for Solana chains).
+ * @returns The address where USDC tokens will be minted (raw address for EVM, ATA for Solana).
+ *
+ * @example
+ * ```typescript
+ * import { getMintRecipientAccount } from './getMintRecipientAccount'
+ *
+ * // EVM: returns the same address
+ * const evmAccount = await getMintRecipientAccount(
+ *   'evm',
+ *   '0x742d35Cc6634C0532925a3b8D89C7DA5C3cfa',
+ *   'N/A'
+ * )
+ *
+ * // Solana: derives the Associated Token Account
+ * const solanaAccount = await getMintRecipientAccount(
+ *   'solana',
+ *   '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
+ *   'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
+ * )
+ * ```
+ */
+declare const getMintRecipientAccount: (
+/** The blockchain type - determines how token accounts are handled */
+chainType: ChainType, 
+/** The recipient's wallet address (hex format for EVM, base58 for Solana) */
+rawAddress: string, 
+/** The USDC mint address (ignored for EVM chains, required base58 address for Solana) */
+mintAddress: string) => Promise<string>;
+
+export { CCTPV2BridgingProvider, getMintRecipientAccount };
 export type { CCTPV2Config };