@hyperlane-xyz/multicollateral 0.2.0 → 1.0.0

package/contracts/{MultiCollateral.sol → CrossCollateralRouter.sol}

@@ -24,21 +24,24 @@ import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol
 import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
 
 // ============ Local Imports ============
-import {IMultiCollateralFee} from "./interfaces/IMultiCollateralFee.sol";
+import {ICrossCollateralFee} from "./interfaces/ICrossCollateralFee.sol";
 
 /**
- * @title MultiCollateral
+ * @title CrossCollateralRouter
  * @notice Multi-router collateral: direct 1-message atomic transfers between
  * collateral routers, both cross-chain and same-chain.
  * @dev Extends HypERC20Collateral. Each deployed instance holds collateral for
- * one ERC20. Enrolled routers are other MultiCollateral instances (same or
+ * one ERC20. Enrolled routers are other CrossCollateralRouter instances (same or
  * different token) that this instance trusts to send/receive transfers.
+ * CrossCollateralRouter assumes standard ERC20 behavior with exact transfer
+ * amounts. Rebasing tokens, fee-on-transfer tokens, and ERC777 tokens are not
+ * supported due to exact-amount accounting in transfer/handle flows.
  *
  * Overrides:
  *  - handle(): accepts messages from the mailbox (cross-chain) or directly
  *    from enrolled routers on the same chain.
  */
-contract MultiCollateral is HypERC20Collateral, IMultiCollateralFee {
+contract CrossCollateralRouter is HypERC20Collateral, ICrossCollateralFee {
     using TypeCasts for address;
     using TypeCasts for bytes32;
     using SafeERC20 for IERC20;
@@ -47,18 +50,24 @@ contract MultiCollateral is HypERC20Collateral, IMultiCollateralFee {
 
     // ============ Events ============
 
-    event RouterEnrolled(uint32 indexed domain, bytes32 indexed router);
-    event RouterUnenrolled(uint32 indexed domain, bytes32 indexed router);
+    event CrossCollateralRouterEnrolled(
+        uint32 indexed domain,
+        bytes32 indexed router
+    );
+    event CrossCollateralRouterUnenrolled(
+        uint32 indexed domain,
+        bytes32 indexed router
+    );
 
     // ============ Storage ============
 
     /// @notice Additional enrolled routers by domain (beyond the standard
     /// enrolled remote router). Local routers use localDomain as key.
-    mapping(uint32 => EnumerableSet.Bytes32Set) private _enrolledRouters;
+    mapping(uint32 => EnumerableSet.Bytes32Set) private _crossCollateralRouters;
 
-    /// @notice Tracks which domains have at least one MC-enrolled router,
+    /// @notice Tracks which domains have at least one CrossCollateral-enrolled router,
     /// enabling on-chain enumeration for the SDK reader.
-    EnumerableSet.UintSet private _enrolledDomains;
+    EnumerableSet.UintSet private _crossCollateralDomains;
 
     // ============ Constructor ============
 
@@ -71,73 +80,73 @@ contract MultiCollateral is HypERC20Collateral, IMultiCollateralFee {
 
     // ============ Router Management (onlyOwner) ============
 
-    function enrollRouters(
+    function enrollCrossCollateralRouters(
         uint32[] calldata _domains,
         bytes32[] calldata _routers
     ) external onlyOwner {
-        require(_domains.length == _routers.length, "MC: length mismatch");
+        require(_domains.length == _routers.length, "CCR: length mismatch");
         for (uint256 i = 0; i < _domains.length; i++) {
-            if (_enrolledRouters[_domains[i]].add(_routers[i])) {
-                _enrolledDomains.add(uint256(_domains[i]));
-                emit RouterEnrolled(_domains[i], _routers[i]);
+            if (_crossCollateralRouters[_domains[i]].add(_routers[i])) {
+                _crossCollateralDomains.add(uint256(_domains[i]));
+                emit CrossCollateralRouterEnrolled(_domains[i], _routers[i]);
             }
         }
     }
 
-    function unenrollRouters(
+    function unenrollCrossCollateralRouters(
         uint32[] calldata _domains,
         bytes32[] calldata _routers
     ) external onlyOwner {
-        require(_domains.length == _routers.length, "MC: length mismatch");
+        require(_domains.length == _routers.length, "CCR: length mismatch");
         for (uint256 i = 0; i < _domains.length; i++) {
-            if (_enrolledRouters[_domains[i]].remove(_routers[i])) {
-                if (_enrolledRouters[_domains[i]].length() == 0) {
-                    _enrolledDomains.remove(uint256(_domains[i]));
+            if (_crossCollateralRouters[_domains[i]].remove(_routers[i])) {
+                if (_crossCollateralRouters[_domains[i]].length() == 0) {
+                    _crossCollateralDomains.remove(uint256(_domains[i]));
                 }
-                emit RouterUnenrolled(_domains[i], _routers[i]);
+                emit CrossCollateralRouterUnenrolled(_domains[i], _routers[i]);
             }
         }
     }
 
-    function enrolledRouters(
+    function crossCollateralRouters(
         uint32 _domain,
         bytes32 _router
     ) external view returns (bool) {
-        return _enrolledRouters[_domain].contains(_router);
+        return _crossCollateralRouters[_domain].contains(_router);
     }
 
     // ============ Enumeration ============
 
-    function getEnrolledRouters(
+    function getCrossCollateralRouters(
         uint32 _domain
     ) external view returns (bytes32[] memory) {
-        return _enrolledRouters[_domain].values();
+        return _crossCollateralRouters[_domain].values();
     }
 
-    /// @notice Returns all domains that have at least one MC-enrolled router.
-    function getEnrolledDomains()
+    /// @notice Returns all domains that have at least one CrossCollateral-enrolled router.
+    function getCrossCollateralDomains()
         external
         view
         returns (uint32[] memory domains)
     {
-        uint256 len = _enrolledDomains.length();
+        uint256 len = _crossCollateralDomains.length();
         domains = new uint32[](len);
         for (uint256 i = 0; i < len; i++) {
-            domains[i] = uint32(_enrolledDomains.at(i));
+            domains[i] = uint32(_crossCollateralDomains.at(i));
         }
     }
 
     // ============ Destination Gas Override ============
 
-    /// @dev Overrides GasRouter._setDestinationGas to also accept MC-enrolled
+    /// @dev Overrides GasRouter._setDestinationGas to also accept CrossCollateral-enrolled
     /// domains (not just default Router._routers). Excludes localDomain since
     /// same-chain transfers skip mailbox dispatch.
     function _setDestinationGas(uint32 domain, uint256 gas) internal override {
-        require(domain != localDomain, "MC: no gas for local domain");
+        require(domain != localDomain, "CCR: no gas for local domain");
         require(
             routers(domain) != bytes32(0) ||
-                _enrolledRouters[domain].length() > 0,
-            "MC: domain has no routers"
+                _crossCollateralRouters[domain].length() > 0,
+            "CCR: domain has no routers"
         );
         destinationGas[domain] = gas;
         emit GasSet(domain, gas);
@@ -146,15 +155,15 @@ contract MultiCollateral is HypERC20Collateral, IMultiCollateralFee {
     // ============ Internal Helpers ============
 
     /// @dev Reverts unless `_router` is enrolled for `_domain` (either via the
-    /// standard Router._routers map or via the MC-specific _enrolledRouters set).
+    /// standard Router._routers map or via the CrossCollateral-specific _crossCollateralRouters set).
     function _requireAuthorizedRouter(
         uint32 _domain,
         bytes32 _router
     ) internal view {
         require(
             _isRemoteRouter(_domain, _router) ||
-                _enrolledRouters[_domain].contains(_router),
-            "MC: unauthorized router"
+                _crossCollateralRouters[_domain].contains(_router),
+            "CCR: unauthorized router"
         );
     }
 
@@ -176,10 +185,10 @@ contract MultiCollateral is HypERC20Collateral, IMultiCollateralFee {
         } else {
             // Same-chain direct call: caller must be an enrolled router
             require(
-                _enrolledRouters[localDomain].contains(
+                _crossCollateralRouters[localDomain].contains(
                     TypeCasts.addressToBytes32(msg.sender)
                 ),
-                "MC: unauthorized router"
+                "CCR: unauthorized router"
             );
         }
         _handle(_origin, _sender, _message);
@@ -187,7 +196,7 @@ contract MultiCollateral is HypERC20Collateral, IMultiCollateralFee {
 
     // ============ Per-Router Fee Lookup ============
     // Mirrors TokenRouter._feeRecipientAndAmount but routes through
-    // IMultiCollateralFee.quoteTransferRemoteTo (which includes _targetRouter)
+    // ICrossCollateralFee.quoteTransferRemoteTo (which includes _targetRouter)
     // instead of ITokenFee.quoteTransferRemote (destination-only).
 
     function _feeRecipientAndAmountForRouter(
@@ -200,7 +209,7 @@ contract MultiCollateral is HypERC20Collateral, IMultiCollateralFee {
         if (_feeRecipient == address(0)) return (_feeRecipient, 0);
 
         // Only difference from base: quoteTransferRemoteTo with _targetRouter
-        Quote[] memory quotes = IMultiCollateralFee(_feeRecipient)
+        Quote[] memory quotes = ICrossCollateralFee(_feeRecipient)
             .quoteTransferRemoteTo(
                 _destination,
                 _recipient,
@@ -211,7 +220,7 @@ contract MultiCollateral is HypERC20Collateral, IMultiCollateralFee {
 
         require(
             quotes.length == 1 && quotes[0].token == token(),
-            "MC: fee must match token"
+            "CCR: fee must match token"
         );
         feeAmount = quotes[0].amount;
     }
@@ -281,10 +290,10 @@ contract MultiCollateral is HypERC20Collateral, IMultiCollateralFee {
     /**
      * @notice Transfers tokens to the primary enrolled router for `_destination`.
      * @dev Uses the enrolled primary remote router for `_destination` and routes through
-     * router-aware fee lookup (`IMultiCollateralFee`) via `transferRemoteTo`.
+     * router-aware fee lookup (`ICrossCollateralFee`) via `transferRemoteTo`.
      * @dev This override is required because TokenRouter's `_feeRecipientAndAmount`
      * is non-virtual and hardcodes `ITokenFee`. Delegating through
-     * `transferRemoteTo` keeps both transfer paths on `IMultiCollateralFee`.
+     * `transferRemoteTo` keeps both transfer paths on `ICrossCollateralFee`.
      */
     function transferRemote(
         uint32 _destination,
@@ -317,7 +326,7 @@ contract MultiCollateral is HypERC20Collateral, IMultiCollateralFee {
         if (_destination == localDomain) {
             // Local transfers call handle() directly without mailbox dispatch,
             // so any msg.value would be stuck in this contract permanently.
-            require(msg.value == 0, "MC: local transfer no msg.value");
+            require(msg.value == 0, "CCR: local transfer no msg.value");
         }
 
         (, uint256 remainingValue) = _calculateFeesAndChargeForRouter(
@@ -334,8 +343,8 @@ contract MultiCollateral is HypERC20Collateral, IMultiCollateralFee {
         if (_destination == localDomain) {
             // Same-domain: call target router's handle directly
             address target = _targetRouter.bytes32ToAddress();
-            require(target.code.length > 0, "MC: target router not contract");
-            MultiCollateral(target).handle(
+            require(target.code.length > 0, "CCR: target router not contract");
+            CrossCollateralRouter(target).handle(
                 localDomain,
                 TypeCasts.addressToBytes32(address(this)),
                 tokenMsg
@@ -358,18 +367,18 @@ contract MultiCollateral is HypERC20Collateral, IMultiCollateralFee {
     // Differences: (1) router-aware fee lookup, (2) same-domain returns 0 gas
     // since handle() is called directly without mailbox dispatch.
 
-    /// @inheritdoc IMultiCollateralFee
+    /// @inheritdoc ICrossCollateralFee
     function quoteTransferRemoteTo(
         uint32 _destination,
         bytes32 _recipient,
         uint256 _amount,
         bytes32 _targetRouter
-    ) external view override returns (Quote[] memory quotes) {
+    ) public view override returns (Quote[] memory quotes) {
         _requireAuthorizedRouter(_destination, _targetRouter);
         if (_destination == localDomain) {
             require(
                 _targetRouter.bytes32ToAddress().code.length > 0,
-                "MC: target router not contract"
+                "CCR: target router not contract"
             );
         }
 

package/contracts/{MultiCollateralRoutingFee.sol → CrossCollateralRoutingFee.sol}

@@ -1,18 +1,21 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 pragma solidity >=0.8.0;
 
-import {IMultiCollateralFee} from "./interfaces/IMultiCollateralFee.sol";
+import {ICrossCollateralFee} from "./interfaces/ICrossCollateralFee.sol";
 import {ITokenFee, Quote} from "@hyperlane-xyz/core/interfaces/ITokenBridge.sol";
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
 
 /**
- * @title MultiCollateralRoutingFee
+ * @title CrossCollateralRoutingFee
  * @notice Routes fee lookups by destination + target router. Delegates to
  * existing ITokenFee (3-param) fee contracts (LinearFee, ProgressiveFee, etc.).
+ * @dev This contract assumes standard ERC20 behavior for fee balances and
+ * transfers. Rebasing, fee-on-transfer, and ERC777 tokens are not supported
+ * for deterministic fee accounting.
  */
-contract MultiCollateralRoutingFee is IMultiCollateralFee, ITokenFee, Ownable {
+contract CrossCollateralRoutingFee is ICrossCollateralFee, ITokenFee, Ownable {
     using SafeERC20 for IERC20;
 
     /// @notice Sentinel key for destination-level default fee contracts.
@@ -34,7 +37,7 @@ contract MultiCollateralRoutingFee is IMultiCollateralFee, ITokenFee, Ownable {
         _transferOwnership(_owner);
     }
 
-    function setRouterFeeContracts(
+    function setCrossCollateralRouterFeeContracts(
         uint32[] calldata destinations,
         bytes32[] calldata targetRouters,
         address[] calldata _feeContracts
@@ -42,7 +45,7 @@ contract MultiCollateralRoutingFee is IMultiCollateralFee, ITokenFee, Ownable {
         require(
             destinations.length == targetRouters.length &&
                 destinations.length == _feeContracts.length,
-            "MCF: length mismatch"
+            "CCRF: length mismatch"
         );
 
         for (uint256 i = 0; i < destinations.length; i++) {
@@ -79,7 +82,7 @@ contract MultiCollateralRoutingFee is IMultiCollateralFee, ITokenFee, Ownable {
     }
 
     /**
-     * @inheritdoc IMultiCollateralFee
+     * @inheritdoc ICrossCollateralFee
      * @dev Routes: specific router → destination default (DEFAULT_ROUTER).
      */
     function quoteTransferRemoteTo(

package/contracts/TokenBridgeOft.sol

@@ -0,0 +1,338 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+pragma solidity >=0.8.0;
+
+import {ITokenBridge, ITokenFee, Quote} from "@hyperlane-xyz/core/interfaces/ITokenBridge.sol";
+import {IOFT, SendParam, MessagingFee, MessagingReceipt, OFTReceipt} from "./interfaces/layerzero/IOFT.sol";
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {IERC20Metadata} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {EnumerableMap} from "@openzeppelin/contracts/utils/structs/EnumerableMap.sol";
+import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";
+import {Address} from "@openzeppelin/contracts/utils/Address.sol";
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+import {PackageVersioned} from "@hyperlane-xyz/core/PackageVersioned.sol";
+
+/**
+ * @title TokenBridgeOft
+ * @notice Warp route adapter for LayerZero OFT (Omnichain Fungible Token) contracts.
+ *
+ * @dev This contract implements ITokenBridge directly with Ownable for admin.
+ *  It does NOT use Hyperlane messaging for transfers. Instead, transferRemote bridges
+ *  via OFT.send() and there is no inbound message handling.
+ *
+ * @dev Dust and decimal handling:
+ *  OFTs use "sharedDecimals" (typically 6) as a wire format, regardless of the
+ *  token's local decimals. When localDecimals > sharedDecimals, the OFT truncates
+ *  sub-sharedDecimals precision ("dust") via _removeDust() before sending. This
+ *  contract stores the decimalConversionRate (10^(localDecimals - sharedDecimals))
+ *  as an immutable and uses it to:
+ *    1. Round grossAmount UP to the next dust-free boundary after fee inversion,
+ *       preventing SlippageExceeded reverts from the OFT.
+ *    2. Round minAmountLD DOWN to a dust-free value, since the OFT cannot deliver
+ *       sub-dust precision anyway.
+ *
+ * Supports all OFT patterns:
+ *  - Native OFT (burn/mint, approvalRequired=false)
+ *  - OFTAdapter (lock/unlock, approvalRequired=true)
+ *  - OFTWrapper (Paxos-style burn/mint, approvalRequired=false)
+ *
+ * Token support:
+ *  - Fee-on-transfer tokens: NOT supported — amount mismatches between
+ *    safeTransferFrom and OFT.send will cause failures or loss.
+ *  - Rebasing tokens: NOT supported — amounts may diverge across chains.
+ *  - ERC-777: NOT explicitly supported — hook reentrancy not guarded.
+ */
+contract TokenBridgeOft is ITokenBridge, Ownable, PackageVersioned {
+    using SafeERC20 for IERC20;
+    using EnumerableMap for EnumerableMap.UintToUintMap;
+
+    // ============ Errors ============
+
+    error LzEidNotConfigured(uint32 hyperlaneDomain);
+
+    // ============ Events ============
+
+    event SentTransferRemote(
+        uint32 indexed destination,
+        bytes32 indexed recipient,
+        uint256 amount
+    );
+    event DomainAdded(uint32 indexed hyperlaneDomain, uint32 lzEid);
+    event DomainRemoved(uint32 indexed hyperlaneDomain);
+    event ExtraOptionsSet(bytes extraOptions);
+
+    // ============ Storage ============
+
+    /// @notice The LayerZero OFT contract to bridge through
+    IOFT public immutable oft;
+
+    /// @notice The underlying ERC20 token
+    IERC20 public immutable wrappedToken;
+
+    /// @notice 10^(localDecimals - sharedDecimals). Amounts are only meaningful
+    /// at multiples of this value; sub-dust precision is truncated by the OFT.
+    /// Equals 1 when localDecimals == sharedDecimals (no dust).
+    uint256 public immutable decimalConversionRate;
+
+    /// @notice Enumerable mapping from Hyperlane domain ID to LayerZero endpoint ID
+    EnumerableMap.UintToUintMap private _domainToLzEid;
+
+    /// @notice Configurable LayerZero extra options (e.g., destination gas limits)
+    bytes public extraOptions;
+
+    // ============ Constructor ============
+
+    /**
+     * @param _oft Address of the OFT / OFTAdapter / OFTWrapper contract
+     * @param _owner Initial owner of the contract
+     */
+    constructor(address _oft, address _owner) {
+        require(_oft != address(0), "TokenBridgeOft: zero OFT address");
+
+        oft = IOFT(_oft);
+        address _token = IOFT(_oft).token();
+        wrappedToken = IERC20(_token);
+
+        uint8 localDecimals = IERC20Metadata(_token).decimals();
+        uint8 sharedDecimals = IOFT(_oft).sharedDecimals();
+        require(
+            localDecimals >= sharedDecimals,
+            "TokenBridgeOft: localDecimals < sharedDecimals"
+        );
+        decimalConversionRate = 10 ** (localDecimals - sharedDecimals);
+
+        _transferOwnership(_owner);
+        wrappedToken.safeApprove(address(oft), type(uint256).max);
+    }
+
+    // ============ ITokenBridge ============
+
+    /// @notice Returns the address of the underlying ERC20 token.
+    function token() public view returns (address) {
+        return address(wrappedToken);
+    }
+
+    /// @inheritdoc ITokenFee
+    function quoteTransferRemote(
+        uint32 _destination,
+        bytes32 _recipient,
+        uint256 _amount
+    ) external view override returns (Quote[] memory quotes) {
+        uint256 nativeFee = _quoteGasPayment(_destination, _recipient, _amount);
+        uint256 externalFee = _externalFeeAmount(
+            _destination,
+            _recipient,
+            _amount
+        );
+
+        quotes = new Quote[](2);
+        quotes[0] = Quote({token: address(0), amount: nativeFee});
+        quotes[1] = Quote({
+            token: address(wrappedToken),
+            amount: _amount + externalFee
+        });
+    }
+
+    /// @inheritdoc ITokenBridge
+    function transferRemote(
+        uint32 _destination,
+        bytes32 _recipient,
+        uint256 _amount
+    ) external payable override returns (bytes32 messageId) {
+        // 1. Calculate OFT fee and pull total from sender
+        uint256 externalFee = _externalFeeAmount(
+            _destination,
+            _recipient,
+            _amount
+        );
+        uint256 grossAmount = _amount + externalFee;
+        wrappedToken.safeTransferFrom(msg.sender, address(this), grossAmount);
+
+        // 2. Build OFT send params: send grossAmount, enforce dust-free _amount as minimum received.
+        SendParam memory sendParam = _buildSendParam(
+            _destination,
+            _recipient,
+            grossAmount,
+            _removeDust(_amount)
+        );
+
+        // 3. Quote native gas fee and send via OFT
+        uint256 nativeFee = _quoteGasPayment(_destination, _recipient, _amount);
+
+        MessagingFee memory msgFee = MessagingFee({
+            nativeFee: nativeFee,
+            lzTokenFee: 0
+        });
+
+        emit SentTransferRemote(_destination, _recipient, _amount);
+
+        (MessagingReceipt memory msgReceipt, ) = oft.send{value: nativeFee}(
+            sendParam,
+            msgFee,
+            msg.sender
+        );
+
+        // 4. Refund excess native value back to caller
+        uint256 excessNative = msg.value - nativeFee;
+        if (excessNative > 0) {
+            Address.sendValue(payable(msg.sender), excessNative);
+        }
+
+        return msgReceipt.guid;
+    }
+
+    // ============ Admin ============
+
+    function addDomain(
+        uint32 _hyperlaneDomain,
+        uint32 _lzEid
+    ) external onlyOwner {
+        require(_lzEid != 0, "TokenBridgeOft: zero LZ EID");
+        _domainToLzEid.set(uint256(_hyperlaneDomain), uint256(_lzEid));
+        emit DomainAdded(_hyperlaneDomain, _lzEid);
+    }
+
+    function removeDomain(uint32 _hyperlaneDomain) external onlyOwner {
+        bool removed = _domainToLzEid.remove(uint256(_hyperlaneDomain));
+        require(removed, "TokenBridgeOft: domain not configured");
+        emit DomainRemoved(_hyperlaneDomain);
+    }
+
+    function setExtraOptions(bytes calldata _options) external onlyOwner {
+        extraOptions = _options;
+        emit ExtraOptionsSet(_options);
+    }
+
+    // ============ Views ============
+
+    /// @notice Look up the LZ endpoint ID for a given Hyperlane domain.
+    function hyperlaneDomainToLzEid(
+        uint32 _domain
+    ) external view returns (uint32) {
+        return _getLzEid(_domain);
+    }
+
+    /// @notice Returns all configured domain mappings as parallel arrays.
+    function getDomainMappings()
+        external
+        view
+        returns (uint32[] memory domains, uint32[] memory lzEids)
+    {
+        uint256 len = _domainToLzEid.length();
+        domains = new uint32[](len);
+        lzEids = new uint32[](len);
+        for (uint256 i = 0; i < len; i++) {
+            (uint256 domain, uint256 eid) = _domainToLzEid.at(i);
+            domains[i] = uint32(domain);
+            lzEids[i] = uint32(eid);
+        }
+    }
+
+    // ============ Internal ============
+
+    function _getLzEid(uint32 _domain) internal view returns (uint32) {
+        (bool exists, uint256 eid) = _domainToLzEid.tryGet(uint256(_domain));
+        if (!exists) revert LzEidNotConfigured(_domain);
+        return uint32(eid);
+    }
+
+    function _buildSendParam(
+        uint32 _destination,
+        bytes32 _recipient,
+        uint256 _amount,
+        uint256 _minAmountLD
+    ) internal view returns (SendParam memory) {
+        return
+            SendParam({
+                dstEid: _getLzEid(_destination),
+                to: _recipient,
+                amountLD: _amount,
+                minAmountLD: _minAmountLD,
+                extraOptions: extraOptions,
+                composeMsg: "",
+                oftCmd: ""
+            });
+    }
+
+    /// @dev Return the LZ native fee for sending via OFT.
+    function _quoteGasPayment(
+        uint32 _destination,
+        bytes32 _recipient,
+        uint256 _amount
+    ) internal view returns (uint256) {
+        SendParam memory sendParam = _buildSendParam(
+            _destination,
+            _recipient,
+            _amount,
+            0
+        );
+        MessagingFee memory msgFee = oft.quoteSend(sendParam, false);
+        return msgFee.nativeFee;
+    }
+
+    /// @dev Return the OFT token fee (difference between gross input and net output).
+    function _externalFeeAmount(
+        uint32 _destination,
+        bytes32 _recipient,
+        uint256 _amount
+    ) internal view returns (uint256) {
+        return _grossOftAmount(_destination, _recipient, _amount) - _amount;
+    }
+
+    /**
+     * @dev Analytically invert the OFT fee to compute the gross input amount
+     * such that the recipient receives at least _amount after OFT deductions.
+     *
+     * OFT fees are linear (percentage-based), so the inversion is:
+     *   grossAmount = ceil(_amount * amountSentLD / amountReceivedLD)
+     *
+     * After inversion, grossAmount is rounded UP to the next dust-free boundary.
+     * This is necessary because OFTs internally call _removeDust() which truncates
+     * sub-sharedDecimals precision. Without this rounding, the truncated gross
+     * amount after fee deduction can fall below _amount, causing SlippageExceeded.
+     *
+     * Example with 18 local / 6 shared decimals and 1% fee:
+     *   _amount = 1e18, probe gives sent=1e18, received=0.99e18
+     *   ceilDiv → 1010101010101010102 (has dust in last 12 digits)
+     *   OFT would truncate to 1010101000000000000, then deduct 1% → 0.99999999e18 < 1e18
+     *   Rounding up to 1010102000000000000 ensures post-fee amount >= 1e18
+     *
+     * If the OFT charges no fee (amountSentLD == amountReceivedLD), returns _amount
+     * rounded up to the nearest dust-free value (to handle dusty input amounts).
+     */
+    function _grossOftAmount(
+        uint32 _destination,
+        bytes32 _recipient,
+        uint256 _amount
+    ) internal view returns (uint256) {
+        SendParam memory probeParam = _buildSendParam(
+            _destination,
+            _recipient,
+            _amount,
+            0
+        );
+        (, , OFTReceipt memory receipt) = oft.quoteOFT(probeParam);
+
+        uint256 sent = receipt.amountSentLD;
+        uint256 received = receipt.amountReceivedLD;
+
+        // No fee (or zero amount): return _amount rounded up to dust-free boundary
+        if (sent == received) return _roundUpDust(_amount);
+
+        // Analytical inversion, then round up to dust-free boundary
+        // If received == 0 (100% fee), Math.mulDiv reverts with division by zero
+        uint256 gross = Math.mulDiv(_amount, sent, received, Math.Rounding.Up);
+        return _roundUpDust(gross);
+    }
+
+    /// @dev Round `_amount` DOWN to the nearest dust-free value (mirrors OFT._removeDust).
+    function _removeDust(uint256 _amount) internal view returns (uint256) {
+        return (_amount / decimalConversionRate) * decimalConversionRate;
+    }
+
+    /// @dev Round `_amount` UP to the nearest dust-free value.
+    function _roundUpDust(uint256 _amount) internal view returns (uint256) {
+        uint256 rate = decimalConversionRate;
+        return ((_amount + rate - 1) / rate) * rate;
+    }
+}

package/contracts/interfaces/{IMultiCollateralFee.sol → ICrossCollateralFee.sol}

@@ -3,7 +3,7 @@ pragma solidity >=0.8.0;
 
 import {Quote} from "@hyperlane-xyz/core/interfaces/ITokenBridge.sol";
 
-interface IMultiCollateralFee {
+interface ICrossCollateralFee {
     function quoteTransferRemoteTo(
         uint32 _destination,
         bytes32 _recipient,