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

package/index.mjs

@@ -28,10 +28,10 @@ if (typeof window !== 'undefined' && typeof window.Buffer === 'undefined') {
 
 
 import { z } from 'zod';
+import { formatUnits as formatUnits$1 } from '@ethersproject/units';
 import { hexlify, hexZeroPad } from '@ethersproject/bytes';
 import { getAddress } from '@ethersproject/address';
 import bs58 from 'bs58';
-import { formatUnits as formatUnits$1 } from '@ethersproject/units';
 
 // -----------------------------------------------------------------------------
 // Blockchain Enum
@@ -48,6 +48,7 @@ var Blockchain;
     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";
@@ -268,6 +269,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: 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
@@ -1559,26 +1602,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: 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: {
@@ -2095,6 +2138,7 @@ var Chains = /*#__PURE__*/Object.freeze({
     AptosTestnet: AptosTestnet,
     Arbitrum: Arbitrum,
     ArbitrumSepolia: ArbitrumSepolia,
+    ArcTestnet: ArcTestnet,
     Avalanche: Avalanche,
     AvalancheFuji: AvalancheFuji,
     Base: Base,
@@ -2569,69 +2613,133 @@ class BridgingProvider {
 }
 
 /**
- * Sets and gets the Stablecoin Kits SDK user agent string for HTTP requests.
- *
- * The user agent string is formatted as:
- *   name/version (platform)
- *
- * - name: The SDK or kit name, set at runtime.
- * - version: The SDK version, set at runtime.
- * - platform: The runtime environment, e.g., "node/nodeVersion" or "browser/browserName".
+ * Detect the runtime environment and return a shortened identifier.
  *
- * @remarks
- * The kit should call setKitIdentifier(name, version) once at startup.
- * A custom user agent will be automatically added to all HTTP requests made by the SDK.
- * This user agent includes the kit name, version, and platform information to help with
- * debugging and analytics.
- *
- * @example
- * ```typescript
- * setKitIdentifier('bridge-kit', '1.2.3')
- * getUserAgent() // "bridge-kit/1.2.3 (node/18.16.0)"
- * ```
- *
- * @returns The Stablecoin Kits SDK user agent string.
+ * @returns Runtime string, e.g., "node/18", "browser/Chrome", or "unknown"
  */
-let cachedUserAgent;
-function getRuntime() {
+const getRuntime = () => {
+    // Node.js environment
     if (typeof process !== 'undefined' &&
         typeof process.versions === 'object' &&
         typeof process.versions.node === 'string') {
-        return `node/${process.versions.node}`;
+        // Shorten to major version only
+        const majorVersion = process.versions.node.split('.')[0] ?? 'unknown';
+        return `node/${majorVersion}`;
     }
-    // Detect browser environment
+    // Browser environment
     if (typeof window !== 'undefined' && typeof navigator !== 'undefined') {
         const userAgent = navigator.userAgent;
         const browserMatchers = {
-            'browser/Edge': (ua) => ua.includes('Edg'),
-            'browser/Chrome': (ua) => ua.includes('Chrome') && !ua.includes('Edg'),
-            'browser/Firefox': (ua) => ua.includes('Firefox'),
-            'browser/Safari': (ua) => ua.includes('Safari') && !ua.includes('Chrome'),
-            'browser/InternetExplorer': (ua) => ua.includes('MSIE') || ua.includes('Trident'),
-            'browser/Opera': (ua) => ua.includes('Opera') || ua.includes('OPR'),
-            'browser/Brave': (ua) => ua.includes('Brave'),
+            Edge: (ua) => ua.includes('Edg'),
+            Chrome: (ua) => ua.includes('Chrome') && !ua.includes('Edg'),
+            Firefox: (ua) => ua.includes('Firefox'),
+            Safari: (ua) => ua.includes('Safari') && !ua.includes('Chrome'),
+            Opera: (ua) => ua.includes('Opera') || ua.includes('OPR'),
         };
         for (const [browserName, matcher] of Object.entries(browserMatchers)) {
             if (matcher(userAgent))
-                return browserName;
+                return `browser/${browserName}`;
         }
         return 'browser/unknown';
     }
     return 'unknown';
-}
+};
 /**
- * Get the user agent string for Stablecoin Kits SDK (universal, sync).
+ * Shorten package names by removing common prefixes.
  *
- * @returns The user agent string, e.g., "bridge-kit/1.2.3 (node/18.16.0)"
+ * @param fullName - Full package name, e.g., "\@circle-fin/bridge-kit"
+ * @returns Shortened name, e.g., "bridge-kit"
  */
-function getUserAgent() {
-    if (cachedUserAgent !== undefined)
-        return cachedUserAgent;
-    const name = 'unknown';
-    const version = 'unknown';
-    cachedUserAgent = `${name}/${version} (${getRuntime()})`;
-    return cachedUserAgent;
-}
+const shortenPackageName = (fullName) => {
+    return fullName.replace('@circle-fin/', '');
+};
+/**
+ * Format a component (name/version) with length optimizations.
+ *
+ * @param nameWithVersion - Component identifier, e.g., "\@circle-fin/bridge-kit/1.2.3"
+ * @returns Formatted component, e.g., "bridge-kit/1.2"
+ */
+const formatComponent = (nameWithVersion) => {
+    // Find the last / to split name and version
+    // This handles scoped packages like @circle-fin/bridge-kit/1.0.0 correctly
+    const lastSlashIndex = nameWithVersion.lastIndexOf('/');
+    if (lastSlashIndex === -1) {
+        // No version, just a name
+        return shortenPackageName(nameWithVersion);
+    }
+    const name = nameWithVersion.substring(0, lastSlashIndex);
+    const version = nameWithVersion.substring(lastSlashIndex + 1);
+    if (name === '')
+        return '';
+    if (version === '')
+        return shortenPackageName(name);
+    return `${shortenPackageName(name)}/${version}`;
+};
+/**
+ * Create a new request context from global state.
+ *
+ * Reads the current external prefix and kit identifier from globalThis.
+ * This is used internally by HTTP utilities.
+ *
+ * @returns A new request context
+ * @internal
+ */
+const createRequestContext = () => {
+    const context = {};
+    if (typeof globalThis !== 'undefined') {
+        if (globalThis.__STABLECOIN_KITS_EXTERNAL_PREFIX__ !== undefined) {
+            context.externalPrefix = globalThis.__STABLECOIN_KITS_EXTERNAL_PREFIX__;
+        }
+        if (globalThis.__STABLECOIN_KITS_CURRENT_KIT__ !== undefined) {
+            context.kit = globalThis.__STABLECOIN_KITS_CURRENT_KIT__;
+        }
+    }
+    return context;
+};
+/**
+ * Build a user agent string from a request context.
+ *
+ * Formats the context into a user agent string with automatic optimizations
+ * (shortened package names and truncated versions). The current implementation
+ * tracks a single kit globally.
+ *
+ * Format: `[external-prefix] kit (runtime)`
+ *
+ * @param context - Request context or undefined to use the global context
+ * @returns Formatted user agent string
+ *
+ * @example
+ * ```typescript
+ * // With application prefix and kit
+ * const ua = getUserAgent(context)
+ * // → "my-app/1.0 bridge-kit/1.2 (node/18)"
+ *
+ * // Kit only (no application prefix set)
+ * const ua = getUserAgent()
+ * // → "bridge-kit/1.2 (node/18)"
+ * ```
+ */
+const getUserAgent = (context) => {
+    const ctx = createRequestContext();
+    const runtime = getRuntime();
+    // Build user agent string
+    const parts = [];
+    // Add external prefix if set
+    if (ctx.externalPrefix !== undefined) {
+        const formatted = formatComponent(ctx.externalPrefix);
+        if (formatted)
+            parts.push(formatted);
+    }
+    // Add kit if set
+    if (ctx.kit !== undefined) {
+        const formatted = formatComponent(ctx.kit);
+        if (formatted)
+            parts.push(formatted);
+    }
+    // Add runtime
+    parts.push(`(${runtime})`);
+    return parts.join(' ');
+};
 
 /**
  * Default configuration values for the API polling utility.
@@ -2883,6 +2991,84 @@ const pollApiGet = async (url, isValidType, config) => {
     return pollApiWithValidation(url, 'GET', isValidType, config);
 };
 
+/**
+ * Convert a value from its smallest unit representation to a human-readable decimal string.
+ *
+ * This function normalizes token values from their blockchain representation (where
+ * everything is stored as integers in the smallest denomination) to human-readable
+ * decimal format. Uses the battle-tested implementation from @ethersproject/units.
+ *
+ * @param value - The value in smallest units (e.g., "1000000" for 1 USDC with 6 decimals)
+ * @param decimals - The number of decimal places for the unit conversion
+ * @returns A human-readable decimal string (e.g., "1.0")
+ * @throws Error if the value is not a valid numeric string
+ *
+ * @example
+ * ```typescript
+ * import { formatUnits } from '@core/utils'
+ *
+ * // Format USDC (6 decimals)
+ * const usdcFormatted = formatUnits('1000000', 6)
+ * console.log(usdcFormatted) // "1.0"
+ *
+ * // Format ETH (18 decimals)
+ * const ethFormatted = formatUnits('1000000000000000000', 18)
+ * console.log(ethFormatted) // "1.0"
+ *
+ * // Format with fractional part
+ * const fractionalFormatted = formatUnits('1500000', 6)
+ * console.log(fractionalFormatted) // "1.5"
+ * ```
+ */
+const formatUnits = (value, decimals) => {
+    return formatUnits$1(value, decimals);
+};
+
+/**
+ * Format a token amount into a human-readable decimal string.
+ *
+ * Accepts a smallest-unit string and either assumes USDC's 6 decimals or derives the
+ * native decimals from the provided chain definition. Delegates to {@link formatUnits}
+ * to preserve consistent rounding and formatting behaviour across the SDK.
+ *
+ * @remarks
+ * When `token` is `'native'`, supply a chain identifier that {@link resolveChainIdentifier}
+ * can resolve so the native currency decimals can be determined.
+ *
+ * @param params - The formatting input including the raw value and token selector.
+ * @returns The decimal string representation of the amount.
+ * @throws Error if the value cannot be parsed or if the chain identifier is unknown.
+ *
+ * @example
+ * ```typescript
+ * import { formatAmount } from '@core/utils'
+ * import { Ethereum } from '@core/chains'
+ *
+ * const usdcAmount = formatAmount({ value: '1000000', token: 'USDC' })
+ * console.log(usdcAmount) // "1"
+ *
+ * const ethAmount = formatAmount({
+ *   value: '3141592000000000000',
+ *   token: 'native',
+ *   chain: Ethereum,
+ * })
+ * console.log(ethAmount) // "3.141592"
+ * ```
+ */
+const formatAmount = (params) => {
+    const { value, token } = params;
+    switch (token) {
+        case 'USDC':
+            return formatUnits(value, 6);
+        case 'native':
+            return formatUnits(value, resolveChainIdentifier(params.chain).nativeCurrency.decimals);
+        default:
+            // This will cause a compile-time error if a new token type is added to
+            // `FormatAmountParams` but not handled in this switch statement, ensuring exhaustiveness.
+            throw new Error(`formatAmount: Unhandled token type: ${token}`);
+    }
+};
+
 /**
  * Custom error class for insufficient funds errors.
  * Provides structured error information while hiding implementation details.
@@ -2890,7 +3076,7 @@ const pollApiGet = async (url, isValidType, config) => {
 class InsufficientFundsError extends Error {
     balance;
     amount;
-    tokenName;
+    token;
     tokenAddress;
     chain;
     /**
@@ -2898,16 +3084,27 @@ class InsufficientFundsError extends Error {
      *
      * @param balance - The current token balance in the wallet (smallest unit).
      * @param amount - The required transaction amount (smallest unit).
-     * @param tokenName - The human-readable token name (e.g., 'USDC').
+     * @param token - The token ('USDC' or 'native').
      * @param tokenAddress - The contract address of the token.
      * @param chain - The blockchain network name where the transaction failed.
      */
-    constructor(balance, amount, tokenName, tokenAddress, chain) {
-        const message = `Insufficient funds for ${tokenName} (${tokenAddress}) transaction on ${chain}. Balance: ${balance} ${tokenName}, is less than transaction amount: ${amount} ${tokenName}.`;
+    constructor(balance, amount, token, tokenAddress, chain) {
+        const formattedBalance = formatAmount({
+            value: balance,
+            token,
+            chain,
+        });
+        const formattedAmount = formatAmount({
+            value: amount,
+            token,
+            chain,
+        });
+        const chainName = typeof chain === 'object' && 'name' in chain ? chain.name : chain;
+        const message = `Insufficient funds for ${token} (${tokenAddress}) transaction on ${chainName}. Balance: ${formattedBalance} ${token}, is less than transaction amount: ${formattedAmount} ${token}.`;
         super(message);
         this.balance = balance;
         this.amount = amount;
-        this.tokenName = tokenName;
+        this.token = token;
         this.tokenAddress = tokenAddress;
         this.chain = chain;
         this.name = 'InsufficientFundsError';
@@ -3286,39 +3483,6 @@ const convertAddress = (address, targetFormat) => {
     throw new Error(`Unsupported address format: ${address}`);
 };
 
-/**
- * Convert a value from its smallest unit representation to a human-readable decimal string.
- *
- * This function normalizes token values from their blockchain representation (where
- * everything is stored as integers in the smallest denomination) to human-readable
- * decimal format. Uses the battle-tested implementation from @ethersproject/units.
- *
- * @param value - The value in smallest units (e.g., "1000000" for 1 USDC with 6 decimals)
- * @param decimals - The number of decimal places for the unit conversion
- * @returns A human-readable decimal string (e.g., "1.0")
- * @throws Error if the value is not a valid numeric string
- *
- * @example
- * ```typescript
- * import { formatUnits } from '@core/utils'
- *
- * // Format USDC (6 decimals)
- * const usdcFormatted = formatUnits('1000000', 6)
- * console.log(usdcFormatted) // "1.0"
- *
- * // Format ETH (18 decimals)
- * const ethFormatted = formatUnits('1000000000000000000', 18)
- * console.log(ethFormatted) // "1.0"
- *
- * // Format with fractional part
- * const fractionalFormatted = formatUnits('1500000', 6)
- * console.log(fractionalFormatted) // "1.5"
- * ```
- */
-const formatUnits = (value, decimals) => {
-    return formatUnits$1(value, decimals);
-};
-
 /**
  * Build a complete explorer URL from a chain definition and transaction hash.
  *
@@ -3580,9 +3744,9 @@ const customFeeSchema = z
  *   token: 'USDC',
  *   config: {
  *     transferSpeed: 'FAST',
- *     maxFee: '1000000'
+ *     maxFee: '1.5', // Decimal format
  *     customFee: {
- *       value: '1000000',
+ *       value: '0.5', // Decimal format
  *       recipientAddress: '0x1234567890123456789012345678901234567890'
  *     }
  *   }
@@ -3609,7 +3773,12 @@ const bridgeParamsSchema = z.object({
         transferSpeed: z.nativeEnum(TransferSpeed).optional(),
         maxFee: 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,
+        })(z.string()))
             .optional(),
         customFee: customFeeSchema.optional(),
     }),
@@ -3739,9 +3908,11 @@ async function fetchUsdcFastBurnFee(sourceDomain, destinationDomain, isTestnet)
  * amount and invalid atttestation messages.
  *
  * These values were obtained by averaging gas for the function call from the last 3 months.
+ * see: https://dune.com/queries/6022210/9697710/
  */
-const DEPOSIT_FOR_BURN_GAS_ESTIMATE_EVM = 124527n;
-const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 177778n;
+const DEPOSIT_FOR_BURN_GAS_ESTIMATE_EVM = 169914n; // (99p: 111_521n + max: 226_506n) / 2 = 169_914n
+const CUSTOM_BURN_GAS_ESTIMATE_EVM = 201525n; // p99 and max are same here: 201_525n
+const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 237401n; // (99p: 163_963n + max: 310_839n) / 2 = 237_401n
 /**
  * The minimum finality threshold for CCTPv2 transfers.
  *
@@ -3766,8 +3937,8 @@ const CCTPv2MinFinalityThreshold = {
  */
 const DEFAULT_CONFIG = {
     timeout: 2_000, // 2 seconds
-    maxRetries: 30 * 20, // 2 seconds * 30 * 20 = 20 minutes (to account for slow transfers maximum time based on confirmations)
-    retryDelay: 500,
+    maxRetries: 30 * 20, // 30 * 20 * 2 seconds (from the retry delay) = 20 minutes (to account for slow transfers maximum time based on confirmations)
+    retryDelay: 2_000, // 2 seconds
     headers: {
         'Content-Type': 'application/json',
     },
@@ -4199,6 +4370,10 @@ class KitError extends Error {
     }
 }
 
+/**
+ * Minimum error code for INPUT type errors.
+ * INPUT errors represent validation failures and invalid parameters.
+ */
 /**
  * Standardized error definitions for INPUT type errors.
  *
@@ -4552,7 +4727,9 @@ async function assertCCTPv2AttestationParams(attestation, params) {
     const errors = [];
     const message = attestation.decodedMessage;
     const messageBody = message.decodedMessageBody;
-    const mintRecipient = await getMintRecipientAccount(params.destination.chain.type, params.destination.address, params.destination.chain.usdcAddress);
+    // Use recipientAddress if provided, otherwise use destination.address
+    const destinationAddressForMint = params.destination.recipientAddress ?? params.destination.address;
+    const mintRecipient = await getMintRecipientAccount(params.destination.chain.type, destinationAddressForMint, params.destination.chain.usdcAddress);
     let sender;
     if (hasCustomContractSupport(params.source.chain, 'bridge')) {
         if (params.source.chain.type === 'solana') {
@@ -4684,8 +4861,6 @@ async function bridgeApproval({ params, provider, }) {
         adapter: params.source.adapter,
         chain: params.source.chain,
         request: await provider.approve(params.source, approvalAmount),
-        // We need to wait for the approval to be confirmed on chain before the transfer can be executed
-        confirmations: 2,
     });
 }
 
@@ -4699,8 +4874,8 @@ async function bridgeApproval({ params, provider, }) {
  * @param params - The bridge parameters containing source, destination, amount and optional config
  * @param sourceChain - The source chain definition where the burn will occur
  * @returns Promise resolving to the bridge step with transaction details
- * @throws {ValidationError} If the parameters are invalid
- * @throws {BridgeError} If the burn transaction fails
+ * @throws \{ValidationError\} If the parameters are invalid
+ * @throws \{BridgeError\} If the burn transaction fails
  *
  * @example
  * ```typescript
@@ -4709,16 +4884,11 @@ async function bridgeApproval({ params, provider, }) {
  * ```
  */
 async function bridgeBurn({ params, provider, }) {
-    const transferSpeed = params.config?.transferSpeed ?? TransferSpeed.FAST;
     return await executePreparedChainRequest({
         name: 'burn',
         adapter: params.source.adapter,
         chain: params.source.chain,
         request: await provider.burn(params),
-        confirmations: transferSpeed === TransferSpeed.FAST
-            ? params.source.chain.cctp.contracts.v2.fastConfirmations
-            : params.source.chain.cctp.contracts.v2.confirmations,
-        timeout: transferSpeed === TransferSpeed.FAST ? undefined : 1_200_000, // 20 minutes (max timeout for cctpv2 slow transfers)
     });
 }
 
@@ -4730,16 +4900,18 @@ async function bridgeBurn({ params, provider, }) {
  * and authorizes the minting of equivalent tokens.
  *
  * @param params - The bridge parameters containing source, destination, amount and optional config
- * @param sourceChain - The source chain definition where the burn occurred
- * @param burnTransactionHash - The hash of the burn transaction
- * @returns Promise resolving to the bridge step with transaction details
- * @throws {ValidationError} If the parameters are invalid
- * @throws {BridgeError} If the attestation fetch fails
+ * @param txHash - The hash of the burn transaction
+ * @returns Promise resolving to the bridge step with attestation data
+ * @throws \{ValidationError\} If the parameters are invalid
+ * @throws \{BridgeError\} If the attestation fetch fails
  *
  * @example
  * ```typescript
- * const attestationStep = await fetchAttestation(params, sourceChain, burnTxHash)
- * console.log('Attestation:', attestationStep.attestation)
+ * const attestationStep = await bridgeFetchAttestation(
+ *   { params, provider },
+ *   burnTxHash
+ * )
+ * console.log('Attestation data:', attestationStep.data)
  * ```
  */
 async function bridgeFetchAttestation({ params, provider, }, txHash) {
@@ -4748,7 +4920,17 @@ async function bridgeFetchAttestation({ params, provider, }, txHash) {
         state: 'pending',
     };
     try {
-        const attestation = await provider.fetchAttestation(params.source, txHash);
+        /**
+         * Give slow transfers a longer retry delay of 30 seconds to account for the longer time it takes to get the
+         * attestation so that we do not hit the rate limit of the IRIS API or the retry limit of the API polling utility.
+         * We only do this for slow transfers on source chains that have greater than 20 confirmations (5 minutes of blocktime
+         * on the slowest blocktime chains) so that we do not slow down the attestation polling for lower confirmation chains.
+         */
+        const apiPollingConfig = params.config?.transferSpeed === TransferSpeed.SLOW &&
+            params.source.chain.cctp.contracts.v2.confirmations > 20
+            ? { retryDelay: 30_000 }
+            : undefined;
+        const attestation = await provider.fetchAttestation(params.source, txHash, apiPollingConfig);
         step = {
             ...step,
             state: 'success',
@@ -4756,10 +4938,18 @@ async function bridgeFetchAttestation({ params, provider, }, txHash) {
         };
     }
     catch (err) {
+        let errorMessage = 'Unknown attestation error';
+        if (err instanceof Error) {
+            errorMessage = err.message;
+        }
+        else if (typeof err === 'string') {
+            errorMessage = err;
+        }
         step = {
             ...step,
             state: 'error',
             error: err,
+            errorMessage,
             data: undefined,
         };
     }
@@ -4795,10 +4985,37 @@ async function bridgeMint({ params, provider, }, attestation) {
         adapter: params.destination.adapter,
         chain: params.destination.chain,
         request: await provider.mint(params.source, params.destination, attestation),
-        // We will wait for the mint to be confirmed on chain before we will return is as success
-        confirmations: 2,
     });
 }
+const mockAttestationMessage = {
+    attestation: '0x8bd9b9e63eb05128eb2896b63e3e1df39bfd6bbfb893b69dc53c39252aeb85df1ded70263b07da17abf88e6e1b77f16ebcdb4eb1c6b4ea4c625215e5cb9dddb81bffe0b9d75e2094f05e48f18f70d0b254999bde90bab26f5c0da29b2d7e00feca1cfed119cba0d2a0e887648a40e803e0ca34aa8fd94ce068515eeaef72b520aa1b',
+    message: '0x000000010000000000000006f446cb82eb486fef485c14c301eaab73aa35f87e3feda3547acf0f33cd4b40f30000000000000000000000008fe6b999dc680ccfdd5bf7eb0974218be2542daa0000000000000000000000008fe6b999dc680ccfdd5bf7eb0974218be2542daa0000000000000000000000000000000000000000000000000000000000000000000003e8000003e8000000010000000000000000000000001c7d4b196cb0c7b01d743fbc6116a902379c723800000000000000000000000023f9a5bea7b92a0638520607407bc7f0310aeed400000000000000000000000000000000000000000000000000000000000186a0000000000000000000000000c5567a5e3370d4dbfb0540025078e283e36a363d000000000000000000000000000000000000000000000000000000000000000b000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000001f6b158',
+    eventNonce: '0xf446cb82eb486fef485c14c301eaab73aa35f87e3feda3547acf0f33cd4b40f3',
+    cctpVersion: 2,
+    status: 'complete',
+    decodedMessage: {
+        sourceDomain: '0',
+        destinationDomain: '6',
+        nonce: '0xf446cb82eb486fef485c14c301eaab73aa35f87e3feda3547acf0f33cd4b40f3',
+        sender: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+        recipient: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+        destinationCaller: '0x0000000000000000000000000000000000000000000000000000000000000000',
+        minFinalityThreshold: '1000',
+        finalityThresholdExecuted: '1000',
+        messageBody: '0x000000010000000000000000000000001c7d4b196cb0c7b01d743fbc6116a902379c723800000000000000000000000023f9a5bea7b92a0638520607407bc7f0310aeed400000000000000000000000000000000000000000000000000000000000186a0000000000000000000000000c5567a5e3370d4dbfb0540025078e283e36a363d000000000000000000000000000000000000000000000000000000000000000b000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000001f6b158',
+        decodedMessageBody: {
+            burnToken: '0x1c7d4b196cb0c7b01d743fbc6116a902379c7238',
+            mintRecipient: '0x23f9a5bea7b92a0638520607407bc7f0310aeed4',
+            amount: '100000',
+            messageSender: '0xc5567a5e3370d4dbfb0540025078e283e36a363d',
+            maxFee: '11',
+            feeExecuted: '10',
+            expirationBlock: '32944472',
+            hookData: null,
+        },
+    },
+    delayReason: null,
+};
 
 /**
  * Ordered sequence of CCTP v2 bridge step executors.
@@ -4882,6 +5099,56 @@ function handleStepError(stepName, error, result) {
     });
 }
 
+/**
+ * Dispatch a bridge step event through the provider's action dispatcher.
+ *
+ * Constructs the appropriate action payload and dispatches it to any registered
+ * event listeners. Handles type-safe dispatching for different step types.
+ *
+ * @param name - The step name (approve, burn, fetchAttestation, or mint).
+ * @param step - The completed bridge step containing transaction details and explorerUrl.
+ * @param provider - The CCTP v2 provider with action dispatcher.
+ *
+ * @example
+ * ```typescript
+ * const step: BridgeStep = {
+ *   name: 'burn',
+ *   state: 'success',
+ *   txHash: '0xabc...',
+ *   explorerUrl: 'https://sepolia.etherscan.io/tx/0xabc...',
+ *   data: { ... }
+ * }
+ * dispatchStepEvent('burn', step, provider)
+ * ```
+ */
+function dispatchStepEvent(name, step, provider) {
+    if (!provider.actionDispatcher) {
+        return;
+    }
+    const actionValues = {
+        protocol: 'cctp',
+        version: 'v2',
+        values: step,
+    };
+    switch (name) {
+        case 'approve':
+        case 'burn':
+        case 'mint':
+            provider.actionDispatcher.dispatch(name, {
+                ...actionValues,
+                method: name,
+            });
+            break;
+        case 'fetchAttestation':
+            provider.actionDispatcher.dispatch(name, {
+                ...actionValues,
+                method: name,
+                values: step,
+            });
+            break;
+    }
+}
+
 /**
  * Execute a cross-chain USDC bridge using the CCTP v2 protocol.
  *
@@ -4938,34 +5205,19 @@ async function bridge(params, provider) {
         try {
             const step = await executor(params, provider, context);
             if (step.state === 'error') {
-                // Include error details from the step in the thrown error
-                const errorDetails = step.errorMessage ?? 'Unknown error';
+                // Include error details from the step in the thrown error. Fall back to step.error.
+                let fallbackErrorMessage = 'Unknown error';
+                if (step.error instanceof Error) {
+                    fallbackErrorMessage = step.error.message;
+                }
+                else if (typeof step.error === 'string') {
+                    fallbackErrorMessage = step.error;
+                }
+                const errorDetails = step.errorMessage ?? fallbackErrorMessage;
                 throw new Error(`${name} step failed: ${errorDetails}`);
             }
             context = updateContext?.(step);
-            const actionValues = {
-                protocol: 'cctp',
-                version: 'v2',
-                values: step,
-            };
-            // use a switch statement for type safety to separate the different step types
-            switch (name) {
-                case 'approve':
-                case 'burn':
-                case 'mint':
-                    provider.actionDispatcher?.dispatch(name, {
-                        ...actionValues,
-                        method: name,
-                    });
-                    break;
-                case 'fetchAttestation':
-                    provider.actionDispatcher?.dispatch(name, {
-                        ...actionValues,
-                        method: name,
-                        values: step,
-                    });
-                    break;
-            }
+            dispatchStepEvent(name, step, provider);
             result.steps.push(step);
         }
         catch (error) {
@@ -5261,10 +5513,12 @@ z.object({
  */
 const validateBalanceForTransaction = async (params) => {
     const { amount, adapter, token, tokenAddress, operationContext } = params;
-    const balancePrepared = await adapter.prepareAction('usdc.balanceOf', {}, operationContext);
+    const balancePrepared = await adapter.prepareAction('usdc.balanceOf', {
+        walletAddress: operationContext.address,
+    }, operationContext);
     const balance = await balancePrepared.execute();
     if (BigInt(balance) < BigInt(amount)) {
-        throw new InsufficientFundsError(balance.toString(), amount, token, tokenAddress, resolveChainIdentifier(operationContext.chain).chain);
+        throw new InsufficientFundsError(balance.toString(), amount, token, tokenAddress, operationContext.chain);
     }
 };
 
@@ -5632,12 +5886,7 @@ async function retry(result, context, provider) {
                 throw new Error(errorMessage);
             }
             stepContext = updateContext?.(step);
-            provider.actionDispatcher?.dispatch(name, {
-                protocol: 'cctp',
-                version: 'v2',
-                method: name,
-                values: step.data,
-            });
+            dispatchStepEvent(name, step, provider);
             result.steps.push(step);
         }
         catch (error) {
@@ -5833,22 +6082,22 @@ class CCTPV2BridgingProvider extends BridgingProvider {
     async estimate(params) {
         // CCTP-specific transfer params validation (includes base validation)
         assertCCTPv2BridgeParams(params);
-        const { source, destination, amount, token } = params;
-        // Extract operation context from source wallet context for balance validation
-        const operationContext = this.extractOperationContext(source);
-        // Validate balance for transaction
-        await validateBalanceForTransaction({
-            amount,
-            token,
-            tokenAddress: source.chain.usdcAddress,
-            adapter: source.adapter,
-            operationContext,
-        });
+        const { source, destination, amount } = params;
+        const estimateBurn = async () => {
+            const burn = await this.burn(params);
+            return await burn.estimate(undefined, await source.adapter.calculateTransactionFee(hasCustomContractSupport(source.chain, 'bridge')
+                ? CUSTOM_BURN_GAS_ESTIMATE_EVM
+                : DEPOSIT_FOR_BURN_GAS_ESTIMATE_EVM, undefined, source.chain));
+        };
+        const estimateMint = async () => {
+            const mint = await this.mint(source, destination, mockAttestationMessage);
+            return await mint.estimate(undefined, await destination.adapter.calculateTransactionFee(RECEIVE_MESSAGE_GAS_ESTIMATE_EVM, undefined, destination.chain));
+        };
         // Parallelize all independent async operations
         const [approveEstimate, depositForBurnFee, receiveMessageFee, maxFee] = await Promise.allSettled([
             this.approve(source, amount).then(async (approve) => approve.estimate()),
-            source.adapter.calculateTransactionFee(DEPOSIT_FOR_BURN_GAS_ESTIMATE_EVM, 500n, source.chain),
-            destination.adapter.calculateTransactionFee(RECEIVE_MESSAGE_GAS_ESTIMATE_EVM, 500n, destination.chain),
+            estimateBurn(),
+            estimateMint(),
             params.config?.transferSpeed === undefined ||
                 params.config?.transferSpeed === TransferSpeed.FAST
                 ? this.getMaxFee(params)
@@ -6015,14 +6264,7 @@ class CCTPV2BridgingProvider extends BridgingProvider {
             delegate: spenderAddress,
             chain: resolvedContext?.chain ?? chain,
         };
-        // Single call with or without context
-        if (resolvedContext) {
-            return await adapter.prepareAction('usdc.increaseAllowance', actionParams, resolvedContext);
-        }
-        else {
-            // Legacy fallback for adapters without capabilities
-            return await adapter.prepareAction('usdc.increaseAllowance', actionParams);
-        }
+        return await adapter.prepareAction('usdc.increaseAllowance', actionParams, resolvedContext);
     }
     /**
      * Prepares a CCTP v2 token minting transaction on the destination chain.
@@ -6066,14 +6308,8 @@ class CCTPV2BridgingProvider extends BridgingProvider {
         assertCCTPv2WalletContext(destination);
         // Extract operation context from destination wallet context
         const operationContext = this.extractOperationContext(destination);
-        // Resolve operation context to get concrete chain and address values
-        let resolvedContext;
-        try {
-            resolvedContext = await resolveOperationContext(destination.adapter, operationContext);
-        }
-        catch (error) {
-            throw new Error(`Failed to resolve operation context: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        // Use recipientAddress if provided, otherwise use destination.address
+        const destinationAddressForMint = destination.recipientAddress ?? destination.address;
         // Prepare action parameters
         const actionParams = {
             fromChain: source.chain,
@@ -6081,16 +6317,9 @@ class CCTPV2BridgingProvider extends BridgingProvider {
             message: attestation.message,
             attestation: attestation.attestation,
             eventNonce: attestation.eventNonce,
-            destinationAddress: destination.address,
+            destinationAddress: destinationAddressForMint,
         };
-        // Single call with or without context
-        if (resolvedContext) {
-            return await destination.adapter.prepareAction('cctp.v2.receiveMessage', actionParams, resolvedContext);
-        }
-        else {
-            // Legacy fallback for adapters without capabilities
-            return await destination.adapter.prepareAction('cctp.v2.receiveMessage', actionParams);
-        }
+        return await destination.adapter.prepareAction('cctp.v2.receiveMessage', actionParams, operationContext);
     }
     /**
      * Fetches attestation data for a burn transaction from the IRIS API.
@@ -6206,7 +6435,9 @@ class CCTPV2BridgingProvider extends BridgingProvider {
      *   - `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
@@ -6214,9 +6445,12 @@ class CCTPV2BridgingProvider extends BridgingProvider {
      * 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)
      * ```
@@ -6247,7 +6481,7 @@ class CCTPV2BridgingProvider extends BridgingProvider {
             maxFee = baseFee + baseFee / 10n;
         }
         else {
-            // Use the max fee from the config
+            // Use the max fee from the config (converted to minor units by BridgeKit)
             maxFee = BigInt(config.maxFee);
         }
         return maxFee;
@@ -6284,10 +6518,11 @@ class CCTPV2BridgingProvider extends BridgingProvider {
         // Get the min finality threshold based on the transfer speed
         const minFinalityThreshold = CCTPv2MinFinalityThreshold[transferSpeed];
         // Calculate the max fee
+        // Use recipientAddress if provided, otherwise use destination.address
+        const destinationAddressForMint = destination.recipientAddress ?? destination.address;
         const [maxFee, mintRecipient] = await Promise.all([
             this.getMaxFee(params),
-            getMintRecipientAccount(destination.chain.type, destination.address ??
-                (await destination.adapter.getAddress(destination.chain)), destination.chain.usdcAddress),
+            getMintRecipientAccount(destination.chain.type, destinationAddressForMint, destination.chain.usdcAddress),
         ]);
         const actionParams = {
             fromChain: source.chain,
@@ -6317,14 +6552,7 @@ class CCTPV2BridgingProvider extends BridgingProvider {
         const finalParams = useCustomBurn
             ? { ...actionParams, feeRecipient: recipientAddress, protocolFee }
             : actionParams;
-        // Single call with or without context
-        if (resolvedContext) {
-            return await source.adapter.prepareAction(actionType, finalParams, resolvedContext);
-        }
-        else {
-            // Legacy fallback for adapters without capabilities
-            return await source.adapter.prepareAction(actionType, finalParams);
-        }
+        return await source.adapter.prepareAction(actionType, finalParams, resolvedContext);
     }
     /**
      * Waits for a transaction to be mined and confirmed on the blockchain.
@@ -6352,5 +6580,5 @@ class CCTPV2BridgingProvider extends BridgingProvider {
     }
 }
 
-export { CCTPV2BridgingProvider };
+export { CCTPV2BridgingProvider, getMintRecipientAccount };
 //# sourceMappingURL=index.mjs.map