@hyperlane-xyz/sdk 25.5.0 → 26.0.0

package/dist/warp/WarpCore.js

@@ -1,4 +1,4 @@
-import { ProtocolType, assert, convertDecimalsToIntegerString, convertToProtocolAddress, convertToScaledAmount, isValidAddress, isZeroishAddress, rootLogger, } from '@hyperlane-xyz/utils';
+import { ProtocolType, assert, convertDecimalsToIntegerString, convertToProtocolAddress, convertToScaledAmount, isEVMLike, isValidAddress, isZeroishAddress, rootLogger, } from '@hyperlane-xyz/utils';
 import { estimateTransactionFeeEthersV5ForGasUnits, } from '../providers/transactionFeeEstimators.js';
 import { Token } from '../token/Token.js';
 import { TokenAmount } from '../token/TokenAmount.js';
@@ -60,7 +60,7 @@ export class WarpCore {
      * and for token fee quote if it exists.
      * Sender is only required for Sealevel origins.
      */
-    async getInterchainTransferFee({ originTokenAmount, destination, sender, recipient, }) {
+    async getInterchainTransferFee({ originTokenAmount, destination, sender, recipient, destinationToken, }) {
         this.logger.debug(`Fetching interchain transfer quote to ${destination}`);
         const { amount, token: originToken } = originTokenAmount;
         const originName = originToken.chainName;
@@ -77,15 +77,33 @@ export class WarpCore {
         }
         else {
             // Otherwise, compute IGP quote via the adapter
-            const hypAdapter = originToken.getHypAdapter(this.multiProvider, destinationName);
+            let quote;
             const destinationDomainId = this.multiProvider.getDomainId(destination);
-            const quote = await hypAdapter.quoteTransferRemoteGas({
-                destination: destinationDomainId,
-                sender,
-                customHook: originToken.igpTokenAddressOrDenom,
-                recipient,
-                amount,
-            });
+            if (this.isMultiCollateralTransfer(originToken, destinationToken)) {
+                const resolvedDestinationToken = this.resolveDestinationToken({
+                    originToken,
+                    destination,
+                    destinationToken,
+                });
+                assert(resolvedDestinationToken.addressOrDenom, 'Destination token missing addressOrDenom');
+                const multiCollateralAdapter = originToken.getHypAdapter(this.multiProvider, destinationName);
+                quote = await multiCollateralAdapter.quoteTransferRemoteToGas({
+                    destination: destinationDomainId,
+                    recipient,
+                    amount,
+                    targetRouter: resolvedDestinationToken.addressOrDenom,
+                });
+            }
+            else {
+                const hypAdapter = originToken.getHypAdapter(this.multiProvider, destinationName);
+                quote = await hypAdapter.quoteTransferRemoteGas({
+                    destination: destinationDomainId,
+                    sender,
+                    customHook: originToken.igpTokenAddressOrDenom,
+                    recipient,
+                    amount,
+                });
+            }
             gasAmount = BigInt(quote.igpQuote.amount);
             gasAddressOrDenom = quote.igpQuote.addressOrDenom;
             feeAmount = quote.tokenFeeQuote?.amount;
@@ -122,7 +140,7 @@ export class WarpCore {
     /**
      * Simulates a transfer to estimate 'local' gas fees on the origin chain
      */
-    async getLocalTransferFee({ originToken, destination, sender, senderPubKey, interchainFee, tokenFeeQuote, }) {
+    async getLocalTransferFee({ originToken, destination, sender, senderPubKey, interchainFee, tokenFeeQuote, destinationToken, }) {
         this.logger.debug(`Estimating local transfer gas to ${destination}`);
         const originMetadata = this.multiProvider.getChainMetadata(originToken.chainName);
         const destinationMetadata = this.multiProvider.getChainMetadata(destination);
@@ -150,6 +168,7 @@ export class WarpCore {
             recipient,
             interchainFee,
             tokenFeeQuote,
+            destinationToken,
         });
         // Starknet does not support gas estimation without starknet account
         if (originToken.protocol === ProtocolType.Starknet) {
@@ -173,8 +192,7 @@ export class WarpCore {
             }
         }
         // On ethereum, sometimes 2 txs are required (one approve, one transferRemote)
-        else if (txs.length === 2 &&
-            originToken.protocol === ProtocolType.Ethereum) {
+        else if (txs.length === 2 && isEVMLike(originToken.protocol)) {
             const provider = this.multiProvider.getEthersV5Provider(originMetadata.name);
             // We use a hard-coded const as an estimate for the transferRemote because we
             // cannot reliably simulate the tx when an approval tx is required first
@@ -192,7 +210,7 @@ export class WarpCore {
      * but it also resolves the native token and returns a TokenAmount
      * @todo: rename to getLocalTransferFee for consistency (requires breaking change)
      */
-    async getLocalTransferFeeAmount({ originToken, destination, sender, senderPubKey, interchainFee, tokenFeeQuote, }) {
+    async getLocalTransferFeeAmount({ originToken, destination, sender, senderPubKey, interchainFee, tokenFeeQuote, destinationToken, }) {
         const originMetadata = this.multiProvider.getChainMetadata(originToken.chainName);
         // If there's no native token, we can't represent local gas
         if (!originMetadata.nativeToken)
@@ -205,6 +223,7 @@ export class WarpCore {
             senderPubKey,
             interchainFee,
             tokenFeeQuote,
+            destinationToken,
         });
         // Get the local gas token. This assumes the chain's native token will pay for local gas
         // This will need to be smarter if more complex scenarios on Cosmos are supported
@@ -215,7 +234,19 @@ export class WarpCore {
      * Gets a list of populated transactions required to transfer a token to a remote chain
      * Typically just 1 transaction but sometimes more, like when an approval is required first
      */
-    async getTransferRemoteTxs({ originTokenAmount, destination, sender, recipient, interchainFee, tokenFeeQuote, }) {
+    async getTransferRemoteTxs({ originTokenAmount, destination, sender, recipient, interchainFee, tokenFeeQuote, destinationToken, }) {
+        // Check if this is a MultiCollateral transfer
+        if (destinationToken &&
+            this.isMultiCollateralTransfer(originTokenAmount.token, destinationToken)) {
+            return this.getMultiCollateralTransferTxs({
+                originTokenAmount,
+                destination,
+                sender,
+                recipient,
+                destinationToken,
+            });
+        }
+        // Standard warp route transfer
         const transactions = [];
         const { token, amount } = originTokenAmount;
         const destinationName = this.multiProvider.getChainName(destination);
@@ -228,6 +259,7 @@ export class WarpCore {
                 destination,
                 sender,
                 recipient,
+                destinationToken,
             });
             interchainFee = transferFee.igpQuote;
             tokenFeeQuote = transferFee.tokenFeeQuote;
@@ -320,11 +352,104 @@ export class WarpCore {
         transactions.push(transferTx);
         return transactions;
     }
+    /**
+     * Check if this is a MultiCollateral transfer.
+     * Returns true if both tokens are MultiCollateral tokens.
+     */
+    isMultiCollateralTransfer(originToken, destinationToken) {
+        if (!destinationToken)
+            return false;
+        return (originToken.isMultiCollateralToken() &&
+            destinationToken.isMultiCollateralToken());
+    }
+    /**
+     * Executes a MultiCollateral transfer between different collateral routers.
+     * Uses transferRemoteTo for both same-chain and cross-chain transfers.
+     * Same-chain: calls handle() directly on target router (atomic, no relay needed).
+     */
+    async getMultiCollateralTransferTxs({ originTokenAmount, destination, sender, recipient, destinationToken, }) {
+        const transactions = [];
+        const { token: originToken, amount } = originTokenAmount;
+        const destinationName = this.multiProvider.getChainName(destination);
+        const resolvedDestinationToken = this.resolveDestinationToken({
+            originToken,
+            destination,
+            destinationToken,
+        });
+        assert(originToken.collateralAddressOrDenom, 'Origin token missing collateralAddressOrDenom');
+        assert(resolvedDestinationToken.addressOrDenom, 'Destination token missing addressOrDenom');
+        const providerType = TOKEN_STANDARD_TO_PROVIDER_TYPE[originToken.standard];
+        const adapter = originToken.getHypAdapter(this.multiProvider, destinationName);
+        const transferQuote = await adapter.quoteTransferRemoteToGas({
+            destination: this.multiProvider.getDomainId(destination),
+            recipient,
+            amount,
+            targetRouter: resolvedDestinationToken.addressOrDenom,
+        });
+        assert(!transferQuote.igpQuote.addressOrDenom ||
+            isZeroishAddress(transferQuote.igpQuote.addressOrDenom), `MultiCollateral transferRemoteTo requires native IGP fee; got ${transferQuote.igpQuote.addressOrDenom}`);
+        const tokenFeeAmount = transferQuote.tokenFeeQuote?.amount ?? 0n;
+        const totalDebit = amount + tokenFeeAmount;
+        const [isApproveRequired, isRevokeApprovalRequired] = await Promise.all([
+            adapter.isApproveRequired(sender, originToken.addressOrDenom, totalDebit),
+            adapter.isRevokeApprovalRequired(sender, originToken.addressOrDenom),
+        ]);
+        if (isApproveRequired && isRevokeApprovalRequired) {
+            const revokeTxReq = await adapter.populateApproveTx({
+                weiAmountOrId: 0,
+                recipient: originToken.addressOrDenom,
+            });
+            transactions.push({
+                category: WarpTxCategory.Revoke,
+                type: providerType,
+                transaction: revokeTxReq,
+            });
+        }
+        if (isApproveRequired) {
+            const approveTxReq = await adapter.populateApproveTx({
+                weiAmountOrId: totalDebit,
+                recipient: originToken.addressOrDenom,
+            });
+            transactions.push({
+                category: WarpTxCategory.Approval,
+                type: providerType,
+                transaction: approveTxReq,
+            });
+        }
+        // transferRemoteTo works for both same-chain and cross-chain.
+        // Same-chain: calls handle() directly on target router (atomic, no relay needed).
+        const destinationDomainId = this.multiProvider.getDomainId(destination);
+        const txReq = await adapter.populateTransferRemoteToTx({
+            destination: destinationDomainId,
+            recipient,
+            amount,
+            targetRouter: resolvedDestinationToken.addressOrDenom,
+            interchainGas: transferQuote,
+        });
+        transactions.push({
+            category: WarpTxCategory.Transfer,
+            type: providerType,
+            transaction: txReq,
+        });
+        return transactions;
+    }
     /**
      * Fetch local and interchain fee estimates for a remote transfer
      */
-    async estimateTransferRemoteFees({ originTokenAmount, destination, recipient, sender, senderPubKey, }) {
+    async estimateTransferRemoteFees({ originTokenAmount, destination, recipient, sender, senderPubKey, destinationToken, }) {
         this.logger.debug('Fetching remote transfer fee estimates');
+        const { token: originToken } = originTokenAmount;
+        // Handle MultiCollateral fee estimation
+        if (this.isMultiCollateralTransfer(originToken, destinationToken)) {
+            return this.estimateMultiCollateralFees({
+                originTokenAmount,
+                destination,
+                destinationToken,
+                recipient,
+                sender,
+                senderPubKey,
+            });
+        }
         // First get interchain gas quote (aka IGP quote)
         // Start with this because it's used in the local fee estimation
         const { igpQuote, tokenFeeQuote } = await this.getInterchainTransferFee({
@@ -348,11 +473,43 @@ export class WarpCore {
             tokenFeeQuote,
         };
     }
+    /**
+     * Estimate fees for a MultiCollateral transfer.
+     */
+    async estimateMultiCollateralFees({ originTokenAmount, destination, destinationToken, recipient, sender, senderPubKey, }) {
+        const { token: originToken } = originTokenAmount;
+        const resolvedDestinationToken = this.resolveDestinationToken({
+            originToken,
+            destination,
+            destinationToken,
+        });
+        const { igpQuote: interchainQuote, tokenFeeQuote } = await this.getInterchainTransferFee({
+            originTokenAmount,
+            destination,
+            sender,
+            recipient,
+            destinationToken: resolvedDestinationToken,
+        });
+        const localQuote = await this.getLocalTransferFeeAmount({
+            originToken,
+            destination,
+            sender,
+            senderPubKey,
+            interchainFee: interchainQuote,
+            tokenFeeQuote,
+            destinationToken,
+        });
+        return {
+            interchainQuote,
+            localQuote,
+            tokenFeeQuote,
+        };
+    }
     /**
      * Computes the max transferrable amount of the from the given
      * token balance, accounting for local and interchain gas fees
      */
-    async getMaxTransferAmount({ balance, destination, recipient, sender, senderPubKey, feeEstimate, }) {
+    async getMaxTransferAmount({ balance, destination, recipient, sender, senderPubKey, feeEstimate, destinationToken, }) {
         const originToken = balance.token;
         if (!feeEstimate) {
             feeEstimate = await this.estimateTransferRemoteFees({
@@ -361,6 +518,7 @@ export class WarpCore {
                 recipient,
                 sender,
                 senderPubKey,
+                destinationToken,
             });
         }
         const { localQuote, interchainQuote, tokenFeeQuote } = feeEstimate;
@@ -377,6 +535,7 @@ export class WarpCore {
                 destination,
                 recipient,
                 sender,
+                destinationToken,
             });
             // Because tokenFeeQuote is calculated based on the amount, we need to recalculate
             // the tokenFeeQuote after subtracting the localQuote and IGP to get max transfer amount
@@ -403,26 +562,28 @@ export class WarpCore {
     /**
      * Checks if destination chain's collateral is sufficient to cover the transfer
      */
-    async isDestinationCollateralSufficient({ originTokenAmount, destination, }) {
+    async isDestinationCollateralSufficient({ originTokenAmount, destination, destinationToken, }) {
         const { token: originToken, amount } = originTokenAmount;
-        const destinationName = this.multiProvider.getChainName(destination);
         this.logger.debug(`Checking collateral for ${originToken.symbol} to ${destination}`);
-        const destinationToken = originToken.getConnectionForChain(destinationName)?.token;
-        assert(destinationToken, `No connection found for ${destinationName}`);
-        if (!TOKEN_COLLATERALIZED_STANDARDS.includes(destinationToken.standard)) {
-            this.logger.debug(`${destinationToken.symbol} is not collateralized, skipping`);
+        const resolvedDestinationToken = this.resolveDestinationToken({
+            originToken,
+            destination,
+            destinationToken,
+        });
+        if (!TOKEN_COLLATERALIZED_STANDARDS.includes(resolvedDestinationToken.standard)) {
+            this.logger.debug(`${resolvedDestinationToken.symbol} is not collateralized, skipping`);
             return true;
         }
-        const destinationBalance = await this.getTokenCollateral(destinationToken);
-        const destinationBalanceInOriginDecimals = convertDecimalsToIntegerString(destinationToken.decimals, originToken.decimals, destinationBalance.toString());
+        const destinationBalance = await this.getTokenCollateral(resolvedDestinationToken);
+        const destinationBalanceInOriginDecimals = convertDecimalsToIntegerString(resolvedDestinationToken.decimals, originToken.decimals, destinationBalance.toString());
         // check for scaling factor
         if (originToken.scale &&
-            destinationToken.scale &&
-            originToken.scale !== destinationToken.scale) {
+            resolvedDestinationToken.scale &&
+            originToken.scale !== resolvedDestinationToken.scale) {
             const precisionFactor = 100_000;
             const scaledAmount = convertToScaledAmount({
                 fromScale: originToken.scale,
-                toScale: destinationToken.scale,
+                toScale: resolvedDestinationToken.scale,
                 amount,
                 precisionFactor,
             });
@@ -446,26 +607,42 @@ export class WarpCore {
     /**
      * Ensure the remote token transfer would be valid for the given chains, amount, sender, and recipient
      */
-    async validateTransfer({ originTokenAmount, destination, recipient, sender, senderPubKey, }) {
+    async validateTransfer({ originTokenAmount, destination, recipient, sender, senderPubKey, destinationToken, }) {
         const chainError = this.validateChains(originTokenAmount.token.chainName, destination);
         if (chainError)
             return chainError;
         const recipientError = this.validateRecipient(recipient, destination);
         if (recipientError)
             return recipientError;
-        const amountError = await this.validateAmount(originTokenAmount, destination, recipient);
+        const resolvedDestinationToken = (() => {
+            try {
+                return this.resolveDestinationToken({
+                    originToken: originTokenAmount.token,
+                    destination,
+                    destinationToken,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : 'Invalid destination token';
+                return { error: message };
+            }
+        })();
+        if ('error' in resolvedDestinationToken) {
+            return { destinationToken: resolvedDestinationToken.error };
+        }
+        const amountError = await this.validateAmount(originTokenAmount, destination, recipient, resolvedDestinationToken);
         if (amountError)
             return amountError;
-        const destinationRateLimitError = await this.validateDestinationRateLimit(originTokenAmount, destination);
+        const destinationRateLimitError = await this.validateDestinationRateLimit(originTokenAmount, destination, resolvedDestinationToken);
         if (destinationRateLimitError)
             return destinationRateLimitError;
-        const destinationCollateralError = await this.validateDestinationCollateral(originTokenAmount, destination);
+        const destinationCollateralError = await this.validateDestinationCollateral(originTokenAmount, destination, resolvedDestinationToken);
         if (destinationCollateralError)
             return destinationCollateralError;
         const originCollateralError = await this.validateOriginCollateral(originTokenAmount);
         if (originCollateralError)
             return originCollateralError;
-        const balancesError = await this.validateTokenBalances(originTokenAmount, destination, sender, recipient, senderPubKey);
+        const balancesError = await this.validateTokenBalances(originTokenAmount, destination, sender, recipient, senderPubKey, resolvedDestinationToken);
         if (balancesError)
             return balancesError;
         return null;
@@ -516,21 +693,23 @@ export class WarpCore {
     /**
      * Ensure token amount is valid
      */
-    async validateAmount(originTokenAmount, destination, recipient) {
+    async validateAmount(originTokenAmount, destination, recipient, destinationToken) {
         if (!originTokenAmount.amount || originTokenAmount.amount < 0n) {
             const isNft = originTokenAmount.token.isNft();
             return { amount: isNft ? 'Invalid Token Id' : 'Invalid amount' };
         }
         // Check the transfer amount is sufficient on the destination side
         const originToken = originTokenAmount.token;
-        const destinationName = this.multiProvider.getChainName(destination);
-        const destinationToken = originToken.getConnectionForChain(destinationName)?.token;
-        assert(destinationToken, `No connection found for ${destinationName}`);
-        const destinationAdapter = destinationToken.getAdapter(this.multiProvider);
+        const resolvedDestinationToken = this.resolveDestinationToken({
+            originToken,
+            destination,
+            destinationToken,
+        });
+        const destinationAdapter = resolvedDestinationToken.getAdapter(this.multiProvider);
         // Get the min required destination amount
         const minDestinationTransferAmount = await destinationAdapter.getMinimumTransferAmount(recipient);
         // Convert the minDestinationTransferAmount to an origin amount
-        const minOriginTransferAmount = destinationToken.amount(convertDecimalsToIntegerString(originToken.decimals, destinationToken.decimals, minDestinationTransferAmount.toString()));
+        const minOriginTransferAmount = originToken.amount(convertDecimalsToIntegerString(resolvedDestinationToken.decimals, originToken.decimals, minDestinationTransferAmount.toString()));
         if (minOriginTransferAmount.amount > originTokenAmount.amount) {
             return {
                 amount: `Minimum transfer amount is ${minOriginTransferAmount.getDecimalFormattedAmount()} ${originToken.symbol}`,
@@ -541,7 +720,7 @@ export class WarpCore {
     /**
      * Ensure the sender has sufficient balances for transfer and interchain gas
      */
-    async validateTokenBalances(originTokenAmount, destination, sender, recipient, senderPubKey) {
+    async validateTokenBalances(originTokenAmount, destination, sender, recipient, senderPubKey, destinationToken) {
         const { token: originToken, amount } = originTokenAmount;
         const { amount: senderBalance } = await originToken.getBalance(this.multiProvider, sender);
         const senderBalanceAmount = originTokenAmount.token.amount(senderBalance);
@@ -555,6 +734,7 @@ export class WarpCore {
             destination,
             sender,
             recipient,
+            destinationToken,
         });
         // Get balance of the IGP fee token, which may be different from the transfer token
         const interchainQuoteTokenBalance = originToken.isFungibleWith(interchainQuote.token)
@@ -581,6 +761,7 @@ export class WarpCore {
             senderPubKey,
             interchainFee: interchainQuote,
             tokenFeeQuote,
+            destinationToken,
         });
         const feeEstimate = { interchainQuote, localQuote };
         // Check 5: Ensure balances can cover the COMBINED amount and fees
@@ -591,6 +772,7 @@ export class WarpCore {
             sender,
             senderPubKey,
             feeEstimate,
+            destinationToken,
         });
         if (amount > maxTransfer.amount) {
             return { amount: 'Insufficient balance for gas and transfer' };
@@ -600,10 +782,11 @@ export class WarpCore {
     /**
      * Ensure the sender has sufficient balances for transfer and interchain gas
      */
-    async validateDestinationCollateral(originTokenAmount, destination) {
+    async validateDestinationCollateral(originTokenAmount, destination, destinationToken) {
         const valid = await this.isDestinationCollateralSufficient({
             originTokenAmount,
             destination,
+            destinationToken,
         });
         if (!valid) {
             return { amount: 'Insufficient collateral on destination' };
@@ -613,24 +796,28 @@ export class WarpCore {
     /**
      * Ensure the sender has sufficient balances for minting
      */
-    async validateDestinationRateLimit(originTokenAmount, destination) {
+    async validateDestinationRateLimit(originTokenAmount, destination, destinationToken) {
         const { token: originToken, amount } = originTokenAmount;
-        const destinationName = this.multiProvider.getChainName(destination);
-        const destinationToken = originToken.getConnectionForChain(destinationName)?.token;
-        assert(destinationToken, `No connection found for ${destinationName}`);
-        if (!MINT_LIMITED_STANDARDS.includes(destinationToken.standard)) {
-            this.logger.debug(`${destinationToken.symbol} does not have rate limit constraint, skipping`);
+        const resolvedDestinationToken = this.resolveDestinationToken({
+            originToken,
+            destination,
+            destinationToken,
+        });
+        if (!MINT_LIMITED_STANDARDS.includes(resolvedDestinationToken.standard)) {
+            this.logger.debug(`${resolvedDestinationToken.symbol} does not have rate limit constraint, skipping`);
             return null;
         }
         let destinationMintLimit = 0n;
-        if (destinationToken.standard === TokenStandard.EvmHypVSXERC20 ||
-            destinationToken.standard === TokenStandard.EvmHypVSXERC20Lockbox ||
-            destinationToken.standard === TokenStandard.EvmHypXERC20 ||
-            destinationToken.standard === TokenStandard.EvmHypXERC20Lockbox) {
-            const adapter = destinationToken.getAdapter(this.multiProvider);
+        if (resolvedDestinationToken.standard === TokenStandard.EvmHypVSXERC20 ||
+            resolvedDestinationToken.standard ===
+                TokenStandard.EvmHypVSXERC20Lockbox ||
+            resolvedDestinationToken.standard === TokenStandard.EvmHypXERC20 ||
+            resolvedDestinationToken.standard === TokenStandard.EvmHypXERC20Lockbox) {
+            const adapter = resolvedDestinationToken.getAdapter(this.multiProvider);
             destinationMintLimit = await adapter.getMintLimit();
-            if (destinationToken.standard === TokenStandard.EvmHypVSXERC20 ||
-                destinationToken.standard === TokenStandard.EvmHypVSXERC20Lockbox) {
+            if (resolvedDestinationToken.standard === TokenStandard.EvmHypVSXERC20 ||
+                resolvedDestinationToken.standard ===
+                    TokenStandard.EvmHypVSXERC20Lockbox) {
                 const bufferCap = await adapter.getMintMaxLimit();
                 const max = bufferCap / 2n;
                 if (destinationMintLimit > max) {
@@ -639,11 +826,11 @@ export class WarpCore {
                 }
             }
         }
-        else if (destinationToken.standard === TokenStandard.EvmHypCollateralFiat) {
-            const adapter = destinationToken.getAdapter(this.multiProvider);
+        else if (resolvedDestinationToken.standard === TokenStandard.EvmHypCollateralFiat) {
+            const adapter = resolvedDestinationToken.getAdapter(this.multiProvider);
             destinationMintLimit = await adapter.getMintLimit();
         }
-        const destinationMintLimitInOriginDecimals = convertDecimalsToIntegerString(destinationToken.decimals, originToken.decimals, destinationMintLimit.toString());
+        const destinationMintLimitInOriginDecimals = convertDecimalsToIntegerString(resolvedDestinationToken.decimals, originToken.decimals, destinationMintLimit.toString());
         const isSufficient = BigInt(destinationMintLimitInOriginDecimals) >= amount;
         this.logger.debug(`${originTokenAmount.token.symbol} to ${destination} has ${isSufficient ? 'sufficient' : 'INSUFFICIENT'} rate limits`);
         if (!isSufficient)
@@ -664,6 +851,24 @@ export class WarpCore {
         }
         return null;
     }
+    resolveDestinationToken({ originToken, destination, destinationToken, }) {
+        const destinationName = this.multiProvider.getChainName(destination);
+        const destinationCandidates = originToken
+            .getConnections()
+            .filter((connection) => connection.token.chainName === destinationName)
+            .map((connection) => connection.token);
+        assert(destinationCandidates.length > 0, `No connection found for ${destinationName}`);
+        if (destinationToken) {
+            assert(destinationToken.chainName === destinationName, `Destination token chain mismatch for ${destinationName}`);
+            const matchedToken = destinationCandidates.find((candidate) => candidate.equals(destinationToken) ||
+                candidate.addressOrDenom.toLowerCase() ===
+                    destinationToken.addressOrDenom.toLowerCase());
+            assert(matchedToken, `Destination token ${destinationToken.addressOrDenom} is not connected from ${originToken.chainName} to ${destinationName}`);
+            return matchedToken;
+        }
+        assert(destinationCandidates.length === 1, `Ambiguous route to ${destinationName}; specify destination token`);
+        return destinationCandidates[0];
+    }
     /**
      * Search through token list to find token with matching chain and address
      */