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

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",
@@ -2591,7 +2592,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 +2622,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 +2634,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 +2642,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;
 }
@@ -3134,17 +3159,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 +3256,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.
      *
@@ -3568,7 +3604,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 +3614,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 +3674,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 };