@hyperlane-xyz/core 3.11.0-beta-0 → 3.11.1

package/contracts/client/MailboxClient.sol

@@ -92,6 +92,10 @@ abstract contract MailboxClient is OwnableUpgradeable {
         return mailbox.latestDispatchedId() == id;
     }
 
+    function _isDelivered(bytes32 id) internal view returns (bool) {
+        return mailbox.delivered(id);
+    }
+
     function _metadata(
         uint32 /*_destinationDomain*/
     ) internal view virtual returns (bytes memory) {
@@ -123,6 +127,24 @@ abstract contract MailboxClient is OwnableUpgradeable {
             );
     }
 
+    function _dispatch(
+        uint32 _destinationDomain,
+        bytes32 _recipient,
+        uint256 _value,
+        bytes memory _messageBody,
+        bytes memory _hookMetadata,
+        IPostDispatchHook _hook
+    ) internal virtual returns (bytes32) {
+        return
+            mailbox.dispatch{value: _value}(
+                _destinationDomain,
+                _recipient,
+                _messageBody,
+                _hookMetadata,
+                _hook
+            );
+    }
+
     function _quoteDispatch(
         uint32 _destinationDomain,
         bytes32 _recipient,
@@ -137,4 +159,21 @@ abstract contract MailboxClient is OwnableUpgradeable {
                 hook
             );
     }
+
+    function _quoteDispatch(
+        uint32 _destinationDomain,
+        bytes32 _recipient,
+        bytes memory _messageBody,
+        bytes calldata _hookMetadata,
+        IPostDispatchHook _hook
+    ) internal view virtual returns (uint256) {
+        return
+            mailbox.quoteDispatch(
+                _destinationDomain,
+                _recipient,
+                _messageBody,
+                _hookMetadata,
+                _hook
+            );
+    }
 }

package/contracts/hooks/warp-route/RateLimitedHook.sol

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.8.0;
+import {MailboxClient} from "contracts/client/MailboxClient.sol";
+import {IPostDispatchHook} from "contracts/interfaces/hooks/IPostDispatchHook.sol";
+import {Message} from "contracts/libs/Message.sol";
+import {TokenMessage} from "contracts/token/libs/TokenMessage.sol";
+import {RateLimited} from "contracts/libs/RateLimited.sol";
+
+contract RateLimitedHook is IPostDispatchHook, MailboxClient, RateLimited {
+    using Message for bytes;
+    using TokenMessage for bytes;
+
+    mapping(bytes32 messageId => bool validated) public messageValidated;
+
+    modifier validateMessageOnce(bytes calldata _message) {
+        bytes32 messageId = _message.id();
+        require(!messageValidated[messageId], "MessageAlreadyValidated");
+        _;
+        messageValidated[messageId] = true;
+    }
+
+    constructor(
+        address _mailbox,
+        uint256 _maxCapacity
+    ) MailboxClient(_mailbox) RateLimited(_maxCapacity) {}
+
+    /// @inheritdoc IPostDispatchHook
+    function hookType() external pure returns (uint8) {
+        return uint8(IPostDispatchHook.Types.Rate_Limited_Hook);
+    }
+
+    /// @inheritdoc IPostDispatchHook
+    function supportsMetadata(bytes calldata) external pure returns (bool) {
+        return false;
+    }
+
+    /**
+     * Verify a message, rate limit, and increment the sender's limit.
+     * @dev ensures that this gets called by the Mailbox
+     */
+    function postDispatch(
+        bytes calldata,
+        bytes calldata _message
+    ) external payable validateMessageOnce(_message) {
+        require(_isLatestDispatched(_message.id()), "InvalidDispatchedMessage");
+
+        uint256 newAmount = _message.body().amount();
+        validateAndConsumeFilledLevel(newAmount);
+    }
+
+    /// @inheritdoc IPostDispatchHook
+    function quoteDispatch(
+        bytes calldata,
+        bytes calldata
+    ) external pure returns (uint256) {
+        return 0;
+    }
+}

package/contracts/interfaces/hooks/IPostDispatchHook.sol

@@ -24,7 +24,8 @@ interface IPostDispatchHook {
         ID_AUTH_ISM,
         PAUSABLE,
         PROTOCOL_FEE,
-        LAYER_ZERO_V1
+        LAYER_ZERO_V1,
+        Rate_Limited_Hook
     }
 
     /**

package/contracts/isms/TrustedRelayerIsm.sol

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+pragma solidity >=0.8.0;
+
+// ============ Internal Imports ============
+import {IInterchainSecurityModule} from "../interfaces/IInterchainSecurityModule.sol";
+import {Message} from "../libs/Message.sol";
+import {Mailbox} from "../Mailbox.sol";
+
+contract TrustedRelayerIsm is IInterchainSecurityModule {
+    using Message for bytes;
+
+    uint8 public immutable moduleType = uint8(Types.NULL);
+    Mailbox public immutable mailbox;
+    address public immutable trustedRelayer;
+
+    constructor(address _mailbox, address _trustedRelayer) {
+        mailbox = Mailbox(_mailbox);
+        trustedRelayer = _trustedRelayer;
+    }
+
+    function verify(
+        bytes calldata,
+        bytes calldata message
+    ) external view returns (bool) {
+        return mailbox.processor(message.id()) == trustedRelayer;
+    }
+}

package/contracts/isms/warp-route/RateLimitedIsm.sol

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+pragma solidity >=0.8.0;
+
+import {IMailbox} from "contracts/interfaces/IMailbox.sol";
+import {MailboxClient} from "contracts/client/MailboxClient.sol";
+import {RateLimited} from "contracts/libs/RateLimited.sol";
+import {IInterchainSecurityModule} from "contracts/interfaces/IInterchainSecurityModule.sol";
+import {Message} from "contracts/libs/Message.sol";
+import {TokenMessage} from "contracts/token/libs/TokenMessage.sol";
+
+contract RateLimitedIsm is
+    MailboxClient,
+    RateLimited,
+    IInterchainSecurityModule
+{
+    using Message for bytes;
+    using TokenMessage for bytes;
+
+    mapping(bytes32 messageId => bool validated) public messageValidated;
+
+    modifier validateMessageOnce(bytes calldata _message) {
+        bytes32 messageId = _message.id();
+        require(!messageValidated[messageId], "MessageAlreadyValidated");
+        messageValidated[messageId] = true;
+        _;
+    }
+
+    constructor(
+        address _mailbox,
+        uint256 _maxCapacity
+    ) MailboxClient(_mailbox) RateLimited(_maxCapacity) {}
+
+    /// @inheritdoc IInterchainSecurityModule
+    function moduleType() external pure returns (uint8) {
+        return uint8(IInterchainSecurityModule.Types.UNUSED);
+    }
+
+    /**
+     * Verify a message, rate limit, and increment the sender's limit.
+     * @dev ensures that this gets called by the Mailbox
+     */
+    function verify(
+        bytes calldata,
+        bytes calldata _message
+    ) external validateMessageOnce(_message) returns (bool) {
+        require(_isDelivered(_message.id()), "InvalidDeliveredMessage");
+
+        uint256 newAmount = _message.body().amount();
+        validateAndConsumeFilledLevel(newAmount);
+
+        return true;
+    }
+}

package/contracts/libs/RateLimited.sol

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+pragma solidity >=0.8.0;
+import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
+
+/**
+ * @title RateLimited
+ * @notice A contract used to keep track of an address sender's token amount limits.
+ * @dev Implements a modified token bucket algorithm where the bucket is full in the beginning and gradually refills
+ * See: https://dev.to/satrobit/rate-limiting-using-the-token-bucket-algorithm-3cjh
+ **/
+contract RateLimited is OwnableUpgradeable {
+    uint256 public constant DURATION = 1 days; // 86400
+    uint256 public filledLevel; /// @notice Current filled level
+    uint256 public refillRate; /// @notice Tokens per second refill rate
+    uint256 public lastUpdated; /// @notice Timestamp of the last time an action has been taken TODO prob can be uint40
+
+    event RateLimitSet(uint256 _oldCapacity, uint256 _newCapacity);
+
+    constructor(uint256 _capacity) {
+        _transferOwnership(msg.sender);
+        setRefillRate(_capacity);
+        filledLevel = _capacity;
+    }
+
+    error RateLimitExceeded(uint256 newLimit, uint256 targetLimit);
+
+    /**
+     * @return The max capacity where the bucket will no longer refill
+     */
+    function maxCapacity() public view returns (uint256) {
+        return refillRate * DURATION;
+    }
+
+    /**
+     * Calculates the refilled amount based on time and refill rate
+     *
+     * Consider an example where there is a 1e18 max token limit per day (86400s)
+     * If half of the tokens has been used, and half a day (43200s) has passed,
+     * then there should be a refill of 0.5e18
+     *
+     * To calculate:
+     *   Refilled = Elapsed * RefilledRate
+     *   Elapsed = timestamp - Limit.lastUpdated
+     *   RefilledRate = Capacity / DURATION
+     *
+     *   If half of the day (43200) has passed, then
+     *   (86400 - 43200) * (1e18 / 86400)  = 0.5e18
+     */
+    function calculateRefilledAmount() internal view returns (uint256) {
+        uint256 elapsed = block.timestamp - lastUpdated;
+        return elapsed * refillRate;
+    }
+
+    /**
+     * Calculates the adjusted fill level based on time
+     */
+    function calculateCurrentLevel() public view returns (uint256) {
+        uint256 _capacity = maxCapacity();
+        require(_capacity > 0, "RateLimitNotSet");
+
+        if (block.timestamp > lastUpdated + DURATION) {
+            // If last update is in the previous window, return the max capacity
+            return _capacity;
+        } else {
+            // If within the window, refill the capacity
+            uint256 replenishedLevel = filledLevel + calculateRefilledAmount();
+
+            // Only return _capacity, in the case where newCurrentCapcacity overflows
+            return replenishedLevel > _capacity ? _capacity : replenishedLevel;
+        }
+    }
+
+    /**
+     * Sets the refill rate by giving a capacity
+     * @param _capacity new maximum capacity to set
+     */
+    function setRefillRate(
+        uint256 _capacity
+    ) public onlyOwner returns (uint256) {
+        uint256 _oldRefillRate = refillRate;
+        uint256 _newRefillRate = _capacity / DURATION;
+        refillRate = _newRefillRate;
+
+        emit RateLimitSet(_oldRefillRate, _newRefillRate);
+
+        return _newRefillRate;
+    }
+
+    /**
+     * Validate an amount and decreases the currentCapacity
+     * @param _newAmount The amount to consume the fill level
+     * @return The new filled level
+     */
+    function validateAndConsumeFilledLevel(
+        uint256 _newAmount
+    ) public returns (uint256) {
+        uint256 adjustedFilledLevel = calculateCurrentLevel();
+        require(_newAmount <= adjustedFilledLevel, "RateLimitExceeded");
+
+        // Reduce the filledLevel and update lastUpdated
+        uint256 _filledLevel = adjustedFilledLevel - _newAmount;
+        filledLevel = _filledLevel;
+        lastUpdated = block.timestamp;
+
+        return _filledLevel;
+    }
+}

package/contracts/test/ERC20Test.sol

@@ -3,6 +3,9 @@ pragma solidity >=0.8.0;
 
 import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
 
+import "../token/interfaces/IXERC20.sol";
+import "../token/interfaces/IFiatToken.sol";
+
 contract ERC20Test is ERC20 {
     uint8 public immutable _decimals;
 
@@ -28,3 +31,38 @@ contract ERC20Test is ERC20 {
         _mint(account, amount);
     }
 }
+
+contract FiatTokenTest is ERC20Test, IFiatToken {
+    constructor(
+        string memory name,
+        string memory symbol,
+        uint256 totalSupply,
+        uint8 __decimals
+    ) ERC20Test(name, symbol, totalSupply, __decimals) {}
+
+    function burn(uint256 amount) public override {
+        _burn(msg.sender, amount);
+    }
+
+    function mint(address account, uint256 amount) public returns (bool) {
+        _mint(account, amount);
+        return true;
+    }
+}
+
+contract XERC20Test is ERC20Test, IXERC20 {
+    constructor(
+        string memory name,
+        string memory symbol,
+        uint256 totalSupply,
+        uint8 __decimals
+    ) ERC20Test(name, symbol, totalSupply, __decimals) {}
+
+    function mint(address account, uint256 amount) public override {
+        _mint(account, amount);
+    }
+
+    function burn(address account, uint256 amount) public override {
+        _burn(account, amount);
+    }
+}

package/contracts/test/TestPostDispatchHook.sol

@@ -1,15 +1,21 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 pragma solidity >=0.8.0;
+import {Message} from "../libs/Message.sol";
 
 import {IPostDispatchHook} from "../interfaces/hooks/IPostDispatchHook.sol";
 import {AbstractPostDispatchHook} from "../hooks/libs/AbstractPostDispatchHook.sol";
 
 contract TestPostDispatchHook is AbstractPostDispatchHook {
+    using Message for bytes;
+
     // ============ Public Storage ============
 
     // test fees for quoteDispatch
     uint256 public fee = 0;
 
+    // used to keep track of dispatched message
+    mapping(bytes32 messageId => bool dispatched) public messageDispatched;
+
     // ============ External Functions ============
 
     /// @inheritdoc IPostDispatchHook
@@ -29,16 +35,14 @@ contract TestPostDispatchHook is AbstractPostDispatchHook {
 
     // ============ Internal functions ============
     function _postDispatch(
-        bytes calldata,
-        /*metadata*/
-        bytes calldata /*message*/
-    ) internal pure override {
-        // test - empty
+        bytes calldata /*metadata*/,
+        bytes calldata message
+    ) internal override {
+        messageDispatched[message.id()] = true;
     }
 
     function _quoteDispatch(
-        bytes calldata,
-        /*metadata*/
+        bytes calldata /*metadata*/,
         bytes calldata /*message*/
     ) internal view override returns (uint256) {
         return fee;

package/contracts/token/HypNative.sol

@@ -45,7 +45,15 @@ contract HypNative is TokenRouter {
     ) public payable virtual override returns (bytes32 messageId) {
         require(msg.value >= _amount, "Native: amount exceeds msg.value");
         uint256 gasPayment = msg.value - _amount;
-        return _transferRemote(_destination, _recipient, _amount, gasPayment);
+        return
+            _transferRemote(
+                _destination,
+                _recipient,
+                _amount,
+                gasPayment,
+                bytes(""),
+                address(0)
+            );
     }
 
     function balanceOf(

package/contracts/token/{HypERC20CollateralVaultDeposit.sol → extensions/HypERC20CollateralVaultDeposit.sol}

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 pragma solidity >=0.8.0;
 import "@openzeppelin/contracts/token/ERC20/extensions/ERC4626.sol";
-import {HypERC20Collateral} from "./HypERC20Collateral.sol";
+import {HypERC20Collateral} from "../HypERC20Collateral.sol";
 
 /**
  * @title Hyperlane ERC20 Token Collateral with deposits collateral to a vault

package/contracts/token/extensions/HypFiatTokenCollateral.sol

@@ -0,0 +1,32 @@
+pragma solidity >=0.8.0;
+
+import {IFiatToken} from "../interfaces/IFiatToken.sol";
+import {HypERC20Collateral} from "../HypERC20Collateral.sol";
+
+// see https://github.com/circlefin/stablecoin-evm/blob/master/doc/tokendesign.md#issuing-and-destroying-tokens
+contract HypFiatTokenCollateral is HypERC20Collateral {
+    constructor(
+        address _fiatToken,
+        address _mailbox
+    ) HypERC20Collateral(_fiatToken, _mailbox) {}
+
+    function _transferFromSender(
+        uint256 _amount
+    ) internal override returns (bytes memory metadata) {
+        // transfer amount to address(this)
+        metadata = super._transferFromSender(_amount);
+        // burn amount of address(this) balance
+        IFiatToken(address(wrappedToken)).burn(_amount);
+    }
+
+    function _transferTo(
+        address _recipient,
+        uint256 _amount,
+        bytes calldata /*metadata*/
+    ) internal override {
+        require(
+            IFiatToken(address(wrappedToken)).mint(_recipient, _amount),
+            "FiatToken mint failed"
+        );
+    }
+}

package/contracts/token/extensions/HypNativeScaled.sol

@@ -30,7 +30,14 @@ contract HypNativeScaled is HypNative {
         uint256 gasPayment = msg.value - _amount;
         uint256 scaledAmount = _amount / scale;
         return
-            _transferRemote(_destination, _recipient, scaledAmount, gasPayment);
+            _transferRemote(
+                _destination,
+                _recipient,
+                scaledAmount,
+                gasPayment,
+                bytes(""),
+                address(0)
+            );
     }
 
     /**

package/contracts/token/extensions/HypXERC20Collateral.sol

@@ -0,0 +1,26 @@
+pragma solidity >=0.8.0;
+
+import {IXERC20} from "../interfaces/IXERC20.sol";
+import {HypERC20Collateral} from "../HypERC20Collateral.sol";
+
+contract HypXERC20Collateral is HypERC20Collateral {
+    constructor(
+        address _xerc20,
+        address _mailbox
+    ) HypERC20Collateral(_xerc20, _mailbox) {}
+
+    function _transferFromSender(
+        uint256 _amountOrId
+    ) internal override returns (bytes memory metadata) {
+        IXERC20(address(wrappedToken)).burn(msg.sender, _amountOrId);
+        return "";
+    }
+
+    function _transferTo(
+        address _recipient,
+        uint256 _amountOrId,
+        bytes calldata /*metadata*/
+    ) internal override {
+        IXERC20(address(wrappedToken)).mint(_recipient, _amountOrId);
+    }
+}

package/contracts/token/interfaces/IFiatToken.sol

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity >=0.8.0;
+
+// adapted from https://github.com/circlefin/stablecoin-evm
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+
+interface IFiatToken is IERC20 {
+    /**
+     * @notice Allows a minter to burn some of its own tokens.
+     * @dev The caller must be a minter, must not be blacklisted, and the amount to burn
+     * should be less than or equal to the account's balance.
+     * @param _amount the amount of tokens to be burned.
+     */
+    function burn(uint256 _amount) external;
+
+    /**
+     * @notice Mints fiat tokens to an address.
+     * @param _to The address that will receive the minted tokens.
+     * @param _amount The amount of tokens to mint. Must be less than or equal
+     * to the minterAllowance of the caller.
+     * @return True if the operation was successful.
+     */
+    function mint(address _to, uint256 _amount) external returns (bool);
+}

package/contracts/token/interfaces/IXERC20.sol

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity >=0.8.0;
+
+// adapted from https://github.com/defi-wonderland/xERC20
+
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+
+interface IXERC20 is IERC20 {
+    /**
+     * @notice Mints tokens for a user
+     * @dev Can only be called by a minter
+     * @param _user The address of the user who needs tokens minted
+     * @param _amount The amount of tokens being minted
+     */
+    function mint(address _user, uint256 _amount) external;
+
+    /**
+     * @notice Burns tokens for a user
+     * @dev Can only be called by a minter
+     * @param _user The address of the user who needs tokens burned
+     * @param _amount The amount of tokens being burned
+     */
+    function burn(address _user, uint256 _amount) external;
+}

package/contracts/token/libs/TokenRouter.sol

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 pragma solidity >=0.8.0;
 
+import {IPostDispatchHook} from "../../interfaces/hooks/IPostDispatchHook.sol";
 import {GasRouter} from "../../client/GasRouter.sol";
 import {MailboxClient} from "../../client/MailboxClient.sol";
 import {TypeCasts} from "../../libs/TypeCasts.sol";
@@ -56,31 +57,86 @@ abstract contract TokenRouter is GasRouter {
         uint256 _amountOrId
     ) external payable virtual returns (bytes32 messageId) {
         return
-            _transferRemote(_destination, _recipient, _amountOrId, msg.value);
+            _transferRemote(
+                _destination,
+                _recipient,
+                _amountOrId,
+                msg.value,
+                bytes(""),
+                address(0)
+            );
+    }
+
+    /**
+     * @notice Transfers `_amountOrId` token to `_recipient` on `_destination` domain with a specified hook
+     * @dev Delegates transfer logic to `_transferFromSender` implementation.
+     * @dev The metadata is the token metadata, and is DIFFERENT than the hook metadata.
+     * @dev Emits `SentTransferRemote` event on the origin chain.
+     * @param _destination The identifier of the destination chain.
+     * @param _recipient The address of the recipient on the destination chain.
+     * @param _amountOrId The amount or identifier of tokens to be sent to the remote recipient.
+     * @param _hookMetadata The metadata passed into the hook
+     * @param _hook The post dispatch hook to be called by the Mailbox
+     * @return messageId The identifier of the dispatched message.
+     */
+    function transferRemote(
+        uint32 _destination,
+        bytes32 _recipient,
+        uint256 _amountOrId,
+        bytes calldata _hookMetadata,
+        address _hook
+    ) external payable virtual returns (bytes32 messageId) {
+        return
+            _transferRemote(
+                _destination,
+                _recipient,
+                _amountOrId,
+                msg.value,
+                _hookMetadata,
+                _hook
+            );
     }
 
     /**
      * @notice Transfers `_amountOrId` token to `_recipient` on `_destination` domain.
      * @dev Delegates transfer logic to `_transferFromSender` implementation.
+     * @dev The metadata is the token metadata, and is DIFFERENT than the hook metadata.
      * @dev Emits `SentTransferRemote` event on the origin chain.
      * @param _destination The identifier of the destination chain.
      * @param _recipient The address of the recipient on the destination chain.
      * @param _amountOrId The amount or identifier of tokens to be sent to the remote recipient.
      * @param _gasPayment The amount of native token to pay for interchain gas.
+     * @param _hookMetadata The metadata passed into the hook
+     * @param _hook The post dispatch hook to be called by the Mailbox
      * @return messageId The identifier of the dispatched message.
      */
     function _transferRemote(
         uint32 _destination,
         bytes32 _recipient,
         uint256 _amountOrId,
-        uint256 _gasPayment
+        uint256 _gasPayment,
+        bytes memory _hookMetadata,
+        address _hook
     ) internal returns (bytes32 messageId) {
         bytes memory metadata = _transferFromSender(_amountOrId);
-        messageId = _dispatch(
-            _destination,
-            _gasPayment,
-            TokenMessage.format(_recipient, _amountOrId, metadata)
-        );
+
+        if (address(_hook) == address(0)) {
+            messageId = _dispatch(
+                _destination,
+                _gasPayment,
+                TokenMessage.format(_recipient, _amountOrId, metadata)
+            );
+        } else {
+            messageId = _dispatch(
+                _destination,
+                _recipient,
+                _gasPayment,
+                TokenMessage.format(_recipient, _amountOrId, metadata),
+                _hookMetadata,
+                IPostDispatchHook(_hook)
+            );
+        }
+
         emit SentTransferRemote(_destination, _recipient, _amountOrId);
     }
 

package/dist/buildArtifact.d.ts

@@ -0,0 +1 @@
+export const buildArtifact: any