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

package/CHANGELOG.md

@@ -0,0 +1,106 @@
+# @circle-fin/provider-cctp-v2
+
+## 1.0.3
+
+### Patch Changes
+
+- Improves the Solana CCTP v2 custom burn flow to ensure developer fee payouts never fail due to a missing associated token account (ATA). The instruction builder now checks for the existence of the developer fee recipient's ATA and, if absent, emits an idempotent creation instruction.
+
+## 1.0.2
+
+### Patch Changes
+
+- Fix CommonJS compatibility by correcting file extensions and package exports. This resolves a "ReferenceError: require is not defined" error that occurred when using packages in CommonJS projects with ts-node.
+
+- Fixes a bug where custom recipient addresses were not respected in cross-chain USDC transfers. Previously, when using `recipientAddress` to specify a different destination address than the signer (common in custody solutions or when bridging to third-party addresses), the provider would incorrectly use the signer's address as the mint recipient, causing transfers to fail or mint to the wrong address.
+
+  With this fix, the provider now correctly uses `recipientAddress` when provided, while still using the signer's address for transaction authorization. This enables:
+  - **Third-party transfers**: Bridge USDC to any address without requiring them to sign
+  - **Custody integrations**: Separate signing authority from fund destination
+  - **Developer-controlled flows**: API-based signers can bridge to user-specified recipients
+
+  **No changes required** for existing code - the fix is backward compatible. If you don't provide `recipientAddress`, transfers work exactly as before. If you were previously experiencing failures when specifying a custom recipient, this update resolves those issues.
+
+- Improves static gas estimate values for contract calls. Updates adapters' `prepare()` method so that transaction simulation is now performed only during `execute()`, not during `estimate()`. Adds an optional fallback parameter to `estimate()` for cases where gas estimation fails.
+
+## 1.0.1
+
+### Patch Changes
+
+- Standardize `maxFee` parameter to accept human-readable values. The `maxFee` parameter in `BridgeConfig` now correctly accepts human-readable token amounts (e.g., `"1"` for 1 USDC, `"0.5"` for 0.5 USDC), matching the behavior of `customFee.value`. This resolves an undocumented inconsistency in the API. If you were previously passing values in smallest units, update to human-readable format: use `"1"` instead of `"1000000"` for 1 USDC.
+- Add support for Arc Testnet chain definition. Arc is Circle's EVM-compatible Layer-1 blockchain designed for stablecoin finance and asset
+  tokenization, featuring USDC as the native gas token and sub-second finality via the Malachite BFT consensus engine.
+- Fix bridge event dispatching in retry flow to include complete step metadata. The retry flow was incorrectly dispatching only step.data instead of the full step object, causing retry events to miss critical metadata like txHash, explorerUrl, name, and state. This change also introduces a shared dispatchStepEvent utility to eliminate code duplication between bridge and retry flows.
+- These changes standardize and clarifiy error handling across bridge steps, make all bridge steps only need 1 blockchain confirmation when waiting for the step transaction, refactor burn transfer speed logic for simplicity, and improve polling configuration for slow attestation fetches.
+- Update Sonic Testnet chain definition to canonical network. The `SonicTestnet` chain definition now points to the official Sonic Testnet (chainId: 14601) instead of the deprecated Sonic Blaze Testnet (chainId: 57054). The RPC endpoint has been updated to `https://rpc.testnet.soniclabs.com`, the display name simplified to "Sonic Testnet", and the USDC contract address updated to the new deployment.
+
+  **Breaking Changes:**
+  - **Chain ID:** 57054 → 14601
+  - **RPC Endpoint:** `https://rpc.blaze.soniclabs.com` → `https://rpc.testnet.soniclabs.com`
+  - **USDC Address:** `0xA4879Fed32Ecbef99399e5cbC247E533421C4eC6` → `0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51`
+
+  **Migration:** If you were using `SonicTestnet`, your application will automatically connect to the new network upon upgrading. Any accounts, contracts, or transactions on the old Blaze testnet (chainId: 57054) will need to be recreated on the new testnet.
+
+## 1.0.0
+
+### Major Changes
+
+- # CCTP v2 Provider 1.0.0 Release 🎉
+
+  Circle's Cross-Chain Transfer Protocol (CCTP) v2 integration - the primary transport layer for secure, native USDC transfers across supported blockchain networks.
+
+  ## 🚀 Core CCTP Features
+  - **Native USDC Bridging**: Direct integration with Circle's official CCTP v2 protocol
+  - **Multi-chain Support**: Seamless transfers between EVM chains and Solana
+  - **Attestation Management**: Automatic handling of Circle's attestation service
+
+  ## ⚡ Transfer Speed Options
+
+  **FAST Transfers**
+  - Optimized for speed with Circle's fast liquidity network
+  - Dynamic fee calculation based on transfer amount and network conditions
+  - Automatic fee estimation with 10% buffer for fluctuations
+  - Typical completion time: ~1 minute
+
+  **SLOW Transfers**
+  - Zero protocol fees for cost-optimized transfers
+  - Standard CCTP attestation flow
+  - Typical completion time: 10-20 minutes
+
+  ```typescript
+  // Fast transfer with automatic fee calculation
+  const result = await provider.bridge({
+    source: { adapter: sourceAdapter, chain: 'Ethereum' },
+    destination: { adapter: destAdapter, chain: 'Base' },
+    amount: '10.0',
+    config: { transferSpeed: 'FAST' },
+  })
+
+  // Slow transfer with zero fees
+  const result = await provider.bridge({
+    source: { adapter: sourceAdapter, chain: 'Ethereum' },
+    destination: { adapter: destAdapter, chain: 'Base' },
+    amount: '10.0',
+    config: { transferSpeed: 'SLOW' },
+  })
+  ```
+
+  ## 🔄 Advanced Retry Support
+  - **Step-by-step Recovery**: Resume from burn, attestation, or mint phases
+  - **Automatic State Analysis**: Intelligent detection of completion status
+  - **Network Resilience**: Handle temporary API and RPC failures
+  - **Transaction Resubmission**: Retry failed blockchain transactions
+
+  ## 💰 Fee Management
+  - **Dynamic Fee Calculation**: Real-time fee estimation from Circle's API
+  - **Custom Fee Limits**: Set maximum fees to control costs
+  - **Protocol Fee Transparency**: Clear breakdown of all fees involved
+  - **Multi-chain Fee Support**: Different fee structures per chain pair
+
+  ## 🛡️ Security & Reliability
+  - **No Custom Cryptography**: Uses only Circle's audited smart contracts
+  - **Deterministic Operations**: Predictable outcomes and gas estimation
+  - **Comprehensive Validation**: Runtime parameter validation and type safety
+  - **Production Ready**: Battle-tested protocol with institutional adoption
+
+  This provider implements Circle's official CCTP v2 specification, ensuring maximum security and compatibility with the broader USDC ecosystem.

package/{index.cjs.js → index.cjs}

@@ -20,7 +20,7 @@
 
 // Buffer polyfill setup - executes before any other code
 // Ensures globalThis.Buffer is available for @solana/spl-token and other Solana libraries
-import { Buffer } from 'buffer';
+const { Buffer } = require('buffer');
 if (typeof globalThis !== 'undefined' && typeof globalThis.Buffer === 'undefined') {
     globalThis.Buffer = Buffer;
 }
@@ -30,10 +30,10 @@ if (typeof window !== 'undefined' && typeof window.Buffer === 'undefined') {
 
 
 var zod = require('zod');
+var units = require('@ethersproject/units');
 var bytes = require('@ethersproject/bytes');
 var address = require('@ethersproject/address');
 var bs58 = require('bs58');
-var units = require('@ethersproject/units');
 
 function _interopDefault (e) { return e && e.__esModule ? e.default : e; }
 
@@ -2997,6 +2997,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 units.formatUnits(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.
@@ -3004,7 +3082,7 @@ const pollApiGet = async (url, isValidType, config) => {
 class InsufficientFundsError extends Error {
     balance;
     amount;
-    tokenName;
+    token;
     tokenAddress;
     chain;
     /**
@@ -3012,16 +3090,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';
@@ -3400,39 +3489,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 units.formatUnits(value, decimals);
-};
-
 /**
  * Build a complete explorer URL from a chain definition and transaction hash.
  *
@@ -3858,9 +3914,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.
  *
@@ -4675,7 +4733,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') {
@@ -4933,6 +4993,35 @@ async function bridgeMint({ params, provider, }, attestation) {
         request: await provider.mint(params.source, params.destination, attestation),
     });
 }
+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.
@@ -5430,10 +5519,12 @@ zod.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);
     }
 };
 
@@ -5997,22 +6088,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)
@@ -6179,14 +6270,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.
@@ -6230,14 +6314,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,
@@ -6245,16 +6323,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.
@@ -6453,10 +6524,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,
@@ -6486,14 +6558,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.
@@ -6523,4 +6588,4 @@ class CCTPV2BridgingProvider extends BridgingProvider {
 
 exports.CCTPV2BridgingProvider = CCTPV2BridgingProvider;
 exports.getMintRecipientAccount = getMintRecipientAccount;
-//# sourceMappingURL=index.cjs.js.map
+//# sourceMappingURL=index.cjs.map

package/index.cjs.map

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

package/index.d.ts

@@ -594,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.
      *
@@ -675,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>;
 }
@@ -707,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.
@@ -1965,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.
      *
@@ -2050,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.
      *
@@ -2435,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.
  */
@@ -2448,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) */
@@ -3150,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.
      */
@@ -3523,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.
      *

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
@@ -2991,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.
@@ -2998,7 +3076,7 @@ const pollApiGet = async (url, isValidType, config) => {
 class InsufficientFundsError extends Error {
     balance;
     amount;
-    tokenName;
+    token;
     tokenAddress;
     chain;
     /**
@@ -3006,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';
@@ -3394,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.
  *
@@ -3852,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.
  *
@@ -4669,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') {
@@ -4927,6 +4987,35 @@ async function bridgeMint({ params, provider, }, attestation) {
         request: await provider.mint(params.source, params.destination, attestation),
     });
 }
+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.
@@ -5424,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);
     }
 };
 
@@ -5991,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)
@@ -6173,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.
@@ -6224,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,
@@ -6239,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.
@@ -6447,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,
@@ -6480,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.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@circle-fin/provider-cctp-v2",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Circle's official Cross-Chain Transfer Protocol v2 provider for native USDC bridging",
-  "main": "./index.cjs.js",
+  "main": "./index.cjs",
   "module": "./index.mjs",
   "types": "./index.d.ts",
   "dependencies": {
@@ -34,12 +34,14 @@
     ".": {
       "types": "./index.d.ts",
       "import": "./index.mjs",
-      "default": "./index.cjs.js"
+      "require": "./index.cjs",
+      "default": "./index.cjs"
     }
   },
   "files": [
     "index.*",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "package.json"
   ],

package/index.cjs.js.map

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