@hyperlane-xyz/core 6.1.0 → 7.0.0

package/contracts/PackageVersioned.sol

@@ -7,5 +7,5 @@ pragma solidity >=0.6.11;
  **/
 abstract contract PackageVersioned {
     // GENERATED CODE - DO NOT EDIT
-    string public constant PACKAGE_VERSION = "6.1.0";
+    string public constant PACKAGE_VERSION = "7.0.0";
 }

package/contracts/test/TestSendReceiver.sol

@@ -47,10 +47,21 @@ contract TestSendReceiver is IMessageRecipient {
         );
     }
 
-    function handle(uint32, bytes32, bytes calldata) external payable override {
+    function handle(
+        uint32,
+        bytes32,
+        bytes calldata _messageBody
+    ) external payable override {
+        bytes memory hardcodedFail = "failMessageBody";
+        require(
+            keccak256(_messageBody) != keccak256(hardcodedFail),
+            "failMessageBody"
+        );
+
         bytes32 blockHash = previousBlockHash();
         bool isBlockHashEndIn0 = uint256(blockHash) % 16 == 0;
         require(!isBlockHashEndIn0, "block hash ends in 0");
+
         emit Handled(blockHash);
     }
 

package/contracts/token/HypERC20.sol

@@ -64,7 +64,7 @@ contract HypERC20 is ERC20Upgradeable, FungibleTokenRouter {
      */
     function _transferFromSender(
         uint256 _amount
-    ) internal override returns (bytes memory) {
+    ) internal virtual override returns (bytes memory) {
         _burn(msg.sender, _amount);
         return bytes(""); // no metadata
     }

package/contracts/token/extensions/4626.md

@@ -0,0 +1,80 @@
+# Yield Routes
+
+Yield routes are a mechanism to transfer yield-bearing assets across chains using the ERC4626 standard.
+
+`HypERC4626Collateral` is a contract that implements `ERC4626` deposits upon transfer and withdrawal upon transfer back.
+
+`HypERC4646` is a contract that implements a rebasing `ERC20`. Balances are virtualized as vault shares times the total assets over the total shares in the `ERC4626` vault (on the collateral chain).
+
+## `HypERC4626Collateral.transferRemote`
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant ERC20
+    participant ERC4626
+    participant WarpRoute
+    participant Mailbox
+
+    User->>WarpRoute: transferRemote(dest, recipient, amount)
+    WarpRoute->>ERC20: transferFrom(User, WarpRoute, amount)
+    WarpRoute->>ERC20: approve(ERC4626, amount)
+    WarpRoute->>ERC4626: deposit(amount, WarpRoute)
+    ERC4626-->>WarpRoute: shares
+    WarpRoute->>ERC4626: convertToAssets(PRECISION)
+    ERC4626-->>WarpRoute: exchangeRate
+    WarpRoute->>WarpRoute: nonce += 1
+
+    WarpRoute->>Mailbox: dispatch(dest, router[dest], {recipient, shares, exchangeRate, nonce})
+```
+
+## `HypERC4626.handle`
+
+```mermaid
+sequenceDiagram
+    participant Recipient
+    participant WarpRoute
+    participant Mailbox
+
+    Mailbox->>WarpRoute: handle(origin, sender, {recipient, shares, exchangeRate, nonce})
+    alt nonce > latestNonce && origin = collateralChain
+        WarpRoute->>WarpRoute: latestNonce = nonce
+        WarpRoute->>WarpRoute: latestExchangeRate = exchangeRate
+    end
+
+    WarpRoute->>WarpRoute: mint(shares, recipient)
+    WarpRoute->>WarpRoute: balance[recipient] = shares
+    Recipient->>WarpRoute: balanceOf(recipient)
+    WarpRoute-->>WarpRoute: balance[recipient] * latestExchangeRate
+    WarpRoute-->>Recipient: amount
+```
+
+## `HypERC4626.transferRemote`
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant WarpRoute
+    participant Mailbox
+
+    User->>WarpRoute: transferRemote(dest, recipient, amount)
+    WarpRoute-->>WarpRoute: burn(shares, User)
+    WarpRoute->>Mailbox: dispatch(dest, router[dest], {recipient, shares})
+```
+
+## `HypERC4626Collateral.handle`
+
+```mermaid
+sequenceDiagram
+    participant Recipient
+    participant ERC20
+    participant ERC4626
+    participant WarpRoute
+    participant Mailbox
+
+    Mailbox->>WarpRoute: handle(orgn, sender, {recipient, shares})
+    WarpRoute->>ERC4626: redeem(shares, recipient, WarpRoute)
+    ERC4626-->>WarpRoute: amount
+    WarpRoute->>ERC20: transfer(recipient, amount)
+    ERC20-->>Recipient: amount
+```

package/contracts/token/extensions/HypERC4626.sol

@@ -19,6 +19,7 @@ import {HypERC20} from "../HypERC20.sol";
 import {Message} from "../../libs/Message.sol";
 import {TokenMessage} from "../libs/TokenMessage.sol";
 import {TokenRouter} from "../libs/TokenRouter.sol";
+import {FungibleTokenRouter} from "../libs/FungibleTokenRouter.sol";
 
 // ============ External Imports ============
 import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";
@@ -29,6 +30,10 @@ import {ERC20Upgradeable} from "@openzeppelin/contracts-upgradeable/token/ERC20/
  * @title Hyperlane ERC20 Rebasing Token
  * @author Abacus Works
  * @notice This contract implements a rebasing token that reflects yields from the origin chain
+ * @dev Messages contain amounts as shares of ERC4626 and exchange rate of assets per share.
+ * @dev internal ERC20 balances storage mapping is in share units
+ * @dev internal ERC20 allowances storage mapping is in asset units
+ * @dev public ERC20 interface is in asset units
  */
 contract HypERC4626 is HypERC20 {
     using Math for uint256;
@@ -55,31 +60,6 @@ contract HypERC4626 is HypERC20 {
 
     // ============ Public Functions ============
 
-    /// Override transfer to handle underlying amounts while using shares internally
-    /// @inheritdoc ERC20Upgradeable
-    /// @dev the Transfer event emitted from ERC20Upgradeable will be in terms of shares not assets, so it may be misleading
-    function transfer(
-        address to,
-        uint256 amount
-    ) public virtual override returns (bool) {
-        _transfer(_msgSender(), to, assetsToShares(amount));
-        return true;
-    }
-
-    /// Override transferFrom to handle underlying amounts while using shares internally
-    /// @inheritdoc ERC20Upgradeable
-    function transferFrom(
-        address sender,
-        address recipient,
-        uint256 amount
-    ) public virtual override returns (bool) {
-        address spender = _msgSender();
-        uint256 shares = assetsToShares(amount);
-        _spendAllowance(sender, spender, amount);
-        _transfer(sender, recipient, shares);
-        return true;
-    }
-
     /// Override totalSupply to return the total assets instead of shares. This reflects the actual circulating supply in terms of assets, accounting for rebasing
     /// @inheritdoc ERC20Upgradeable
     function totalSupply() public view virtual override returns (uint256) {
@@ -112,38 +92,37 @@ contract HypERC4626 is HypERC20 {
         return _shares.mulDiv(exchangeRate, PRECISION);
     }
 
-    // ============ Internal Functions ============
+    // @inheritdoc HypERC20
+    // @dev Amount specified by the user is in assets, but the internal accounting is in shares
+    function _transferFromSender(
+        uint256 _amount
+    ) internal virtual override returns (bytes memory) {
+        return HypERC20._transferFromSender(assetsToShares(_amount));
+    }
 
-    /// Override to send shares instead of assets from synthetic
-    /// @inheritdoc TokenRouter
-    function _transferRemote(
-        uint32 _destination,
-        bytes32 _recipient,
-        uint256 _amountOrId,
-        uint256 _value,
-        bytes memory _hookMetadata,
-        address _hook
-    ) internal virtual override returns (bytes32 messageId) {
-        uint256 _shares = assetsToShares(_amountOrId);
-        _transferFromSender(_shares);
-        bytes memory _tokenMessage = TokenMessage.format(
-            _recipient,
-            _shares,
-            bytes("")
-        );
-
-        messageId = _Router_dispatch(
-            _destination,
-            _value,
-            _tokenMessage,
-            _hookMetadata,
-            _hook
-        );
-
-        emit SentTransferRemote(_destination, _recipient, _amountOrId);
+    // @inheritdoc FungibleTokenRouter
+    // @dev Amount specified by user is in assets, but the message accounting is in shares
+    function _outboundAmount(
+        uint256 _localAmount
+    ) internal view virtual override returns (uint256) {
+        return
+            FungibleTokenRouter._outboundAmount(assetsToShares(_localAmount));
+    }
+
+    // @inheritdoc ERC20Upgradeable
+    // @dev Amount specified by user is in assets, but the internal accounting is in shares
+    function _transfer(
+        address _from,
+        address _to,
+        uint256 _amount
+    ) internal virtual override {
+        super._transfer(_from, _to, assetsToShares(_amount));
     }
 
-    /// override _handle to update exchange rate
+    // `_inboundAmount` implementation reused from `FungibleTokenRouter` unchanged because message
+    // accounting is in shares
+
+    // ========== TokenRouter extensions ============
     /// @inheritdoc TokenRouter
     function _handle(
         uint32 _origin,

package/contracts/token/extensions/HypERC4626Collateral.sol

@@ -17,6 +17,7 @@ pragma solidity >=0.8.0;
 import {TokenMessage} from "../libs/TokenMessage.sol";
 import {HypERC20Collateral} from "../HypERC20Collateral.sol";
 import {TypeCasts} from "../../libs/TypeCasts.sol";
+import {TokenRouter} from "../libs/TokenRouter.sol";
 
 // ============ External Imports ============
 import "@openzeppelin/contracts/token/ERC20/extensions/ERC4626.sol";
@@ -56,6 +57,12 @@ contract HypERC4626Collateral is HypERC20Collateral {
         _MailboxClient_initialize(_hook, _interchainSecurityModule, _owner);
     }
 
+    /**
+     * @inheritdoc TokenRouter
+     * @dev Override `_transferRemote` to send shares as amount and append {exchange rate, nonce} in the message.
+     *      This is preferred for readability and to avoid confusion with the amount of shares. The scaling factor
+     *      is applied to the shares returned by the deposit before sending the message.
+     */
     function _transferRemote(
         uint32 _destination,
         bytes32 _recipient,
@@ -67,6 +74,7 @@ contract HypERC4626Collateral is HypERC20Collateral {
         // Can't override _transferFromSender only because we need to pass shares in the token message
         _transferFromSender(_amount);
         uint256 _shares = _depositIntoVault(_amount);
+
         uint256 _exchangeRate = vault.convertToAssets(PRECISION);
 
         rateUpdateNonce++;
@@ -75,9 +83,10 @@ contract HypERC4626Collateral is HypERC20Collateral {
             rateUpdateNonce
         );
 
+        uint256 _outboundAmount = _outboundAmount(_shares);
         bytes memory _tokenMessage = TokenMessage.format(
             _recipient,
-            _shares,
+            _outboundAmount,
             _tokenMetadata
         );
 
@@ -89,7 +98,7 @@ contract HypERC4626Collateral is HypERC20Collateral {
             _hook
         );
 
-        emit SentTransferRemote(_destination, _recipient, _shares);
+        emit SentTransferRemote(_destination, _recipient, _outboundAmount);
     }
 
     /**
@@ -102,16 +111,15 @@ contract HypERC4626Collateral is HypERC20Collateral {
     }
 
     /**
-     * @dev Transfers `_amount` of `wrappedToken` from this contract to `_recipient`, and withdraws from vault
+     * @dev Withdraws `_shares` of `wrappedToken` from this contract to `_recipient`
      * @inheritdoc HypERC20Collateral
      */
     function _transferTo(
         address _recipient,
-        uint256 _amount,
+        uint256 _shares,
         bytes calldata
     ) internal virtual override {
-        // withdraw with the specified amount of shares
-        vault.redeem(_amount, _recipient, address(this));
+        vault.redeem(_shares, _recipient, address(this));
     }
 
     /**

package/contracts/token/libs/FungibleTokenRouter.sol

@@ -3,6 +3,10 @@ pragma solidity >=0.8.0;
 
 import {TokenRouter} from "./TokenRouter.sol";
 
+/**
+ * @title Hyperlane Fungible Token Router that extends TokenRouter with scaling logic for fungible tokens with different decimals.
+ * @author Abacus Works
+ */
 abstract contract FungibleTokenRouter is TokenRouter {
     uint256 public immutable scale;
 

package/contracts/token/libs/TokenRouter.sol

@@ -20,7 +20,7 @@ abstract contract TokenRouter is GasRouter {
      * @dev Emitted on `transferRemote` when a transfer message is dispatched.
      * @param destination The identifier of the destination chain.
      * @param recipient The address of the recipient on the destination chain.
-     * @param amount The amount of tokens burnt on the origin chain.
+     * @param amount The amount of tokens sent in to the remote recipient.
      */
     event SentTransferRemote(
         uint32 indexed destination,
@@ -32,7 +32,7 @@ abstract contract TokenRouter is GasRouter {
      * @dev Emitted on `_handle` when a transfer message is processed.
      * @param origin The identifier of the origin chain.
      * @param recipient The address of the recipient on the destination chain.
-     * @param amount The amount of tokens minted on the destination chain.
+     * @param amount The amount of tokens received from the remote sender.
      */
     event ReceivedTransferRemote(
         uint32 indexed origin,