@hyperlane-xyz/multicollateral 0.1.0 → 1.0.0

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

@@ -24,36 +24,50 @@ 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;
     using EnumerableSet for EnumerableSet.Bytes32Set;
+    using EnumerableSet for EnumerableSet.UintSet;
 
     // ============ 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 CrossCollateral-enrolled router,
+    /// enabling on-chain enumeration for the SDK reader.
+    EnumerableSet.UintSet private _crossCollateralDomains;
 
     // ============ Constructor ============
 
@@ -66,43 +80,91 @@ 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])) {
-                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])) {
-                emit RouterUnenrolled(_domains[i], _routers[i]);
+            if (_crossCollateralRouters[_domains[i]].remove(_routers[i])) {
+                if (_crossCollateralRouters[_domains[i]].length() == 0) {
+                    _crossCollateralDomains.remove(uint256(_domains[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 CrossCollateral-enrolled router.
+    function getCrossCollateralDomains()
+        external
+        view
+        returns (uint32[] memory domains)
+    {
+        uint256 len = _crossCollateralDomains.length();
+        domains = new uint32[](len);
+        for (uint256 i = 0; i < len; i++) {
+            domains[i] = uint32(_crossCollateralDomains.at(i));
+        }
+    }
+
+    // ============ Destination Gas Override ============
+
+    /// @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, "CCR: no gas for local domain");
+        require(
+            routers(domain) != bytes32(0) ||
+                _crossCollateralRouters[domain].length() > 0,
+            "CCR: domain has no routers"
+        );
+        destinationGas[domain] = gas;
+        emit GasSet(domain, gas);
+    }
+
+    // ============ Internal Helpers ============
+
+    /// @dev Reverts unless `_router` is enrolled for `_domain` (either via the
+    /// standard Router._routers map or via the CrossCollateral-specific _crossCollateralRouters set).
+    function _requireAuthorizedRouter(
+        uint32 _domain,
+        bytes32 _router
+    ) internal view {
+        require(
+            _isRemoteRouter(_domain, _router) ||
+                _crossCollateralRouters[_domain].contains(_router),
+            "CCR: unauthorized router"
+        );
     }
 
     // ============ Handle Override ============
@@ -119,18 +181,14 @@ contract MultiCollateral is HypERC20Collateral, IMultiCollateralFee {
     ) external payable override {
         if (msg.sender == address(mailbox)) {
             // Cross-chain via mailbox: sender must be enrolled
-            require(
-                _isRemoteRouter(_origin, _sender) ||
-                    _enrolledRouters[_origin].contains(_sender),
-                "MC: unauthorized router"
-            );
+            _requireAuthorizedRouter(_origin, _sender);
         } 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);
@@ -138,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(
@@ -151,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,
@@ -162,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;
     }
@@ -197,11 +255,12 @@ contract MultiCollateral is HypERC20Collateral, IMultiCollateralFee {
         // Same-domain transferRemoteTo calls handle() directly and does not dispatch
         // through mailbox hooks, so do not charge hook fees in that path.
         if (_feeHook != address(0) && _destination != localDomain) {
-            uint256 hookFee = _quoteGasPayment(
+            uint256 hookFee = _quoteGasPaymentTo(
                 _destination,
                 _recipient,
-                _amount,
-                _token
+                _outboundAmount(_amount),
+                _token,
+                _targetRouter
             );
             if (hookFee > 0) {
                 if (_token != address(this)) {
@@ -231,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,
@@ -263,13 +322,11 @@ contract MultiCollateral is HypERC20Collateral, IMultiCollateralFee {
         uint256 _amount,
         bytes32 _targetRouter
     ) public payable returns (bytes32 messageId) {
-        require(
-            _isRemoteRouter(_destination, _targetRouter) ||
-                _enrolledRouters[_destination].contains(_targetRouter),
-            "MC: unauthorized router"
-        );
+        _requireAuthorizedRouter(_destination, _targetRouter);
         if (_destination == localDomain) {
-            require(msg.value == 0, "MC: local transfer no msg.value");
+            // Local transfers call handle() directly without mailbox dispatch,
+            // so any msg.value would be stuck in this contract permanently.
+            require(msg.value == 0, "CCR: local transfer no msg.value");
         }
 
         (, uint256 remainingValue) = _calculateFeesAndChargeForRouter(
@@ -286,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
@@ -310,24 +367,33 @@ 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,
+                "CCR: target router not contract"
+            );
+        }
+
         quotes = new Quote[](3);
 
         // Same-domain: handle() called directly, no interchain gas
         uint256 gasQuote = 0;
         address _feeToken = feeToken();
         if (_destination != localDomain) {
-            gasQuote = _quoteGasPayment(
+            gasQuote = _quoteGasPaymentTo(
                 _destination,
                 _recipient,
                 _outboundAmount(_amount),
-                _feeToken
+                _feeToken,
+                _targetRouter
             );
         }
         quotes[0] = Quote({token: _feeToken, amount: gasQuote});
@@ -346,4 +412,23 @@ contract MultiCollateral is HypERC20Collateral, IMultiCollateralFee {
             amount: _externalFeeAmount(_destination, _recipient, _amount)
         });
     }
+
+    /// @dev Target-router-aware gas quote helper. Avoids Router._mustHaveRemoteRouter().
+    /// Caller must validate `_targetRouter` is authorized for `_destination`.
+    function _quoteGasPaymentTo(
+        uint32 _destination,
+        bytes32 _recipient,
+        uint256 _amount,
+        address _feeToken,
+        bytes32 _targetRouter
+    ) internal view returns (uint256) {
+        return
+            mailbox.quoteDispatch(
+                _destination,
+                _targetRouter,
+                TokenMessage.format(_recipient, _amount),
+                _generateHookMetadata(_destination, _feeToken),
+                IPostDispatchHook(address(hook))
+            );
+    }
 }

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(