@hyperlane-xyz/core 1.5.4-beta0 → 1.5.6-beta0

package/contracts/Mailbox.sol

@@ -3,51 +3,53 @@ pragma solidity >=0.8.0;
 
 // ============ Internal Imports ============
 import {Versioned} from "./upgrade/Versioned.sol";
-import {MerkleLib} from "./libs/Merkle.sol";
+import {Indexed} from "./libs/Indexed.sol";
 import {Message} from "./libs/Message.sol";
 import {TypeCasts} from "./libs/TypeCasts.sol";
-import {IMessageRecipient} from "./interfaces/IMessageRecipient.sol";
 import {IInterchainSecurityModule, ISpecifiesInterchainSecurityModule} from "./interfaces/IInterchainSecurityModule.sol";
+import {IPostDispatchHook} from "./interfaces/hooks/IPostDispatchHook.sol";
+import {IMessageRecipient} from "./interfaces/IMessageRecipient.sol";
 import {IMailbox} from "./interfaces/IMailbox.sol";
-import {PausableReentrancyGuardUpgradeable} from "./PausableReentrancyGuard.sol";
 
 // ============ External Imports ============
 import {Address} from "@openzeppelin/contracts/utils/Address.sol";
 import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
 
-contract Mailbox is
-    IMailbox,
-    OwnableUpgradeable,
-    PausableReentrancyGuardUpgradeable,
-    Versioned
-{
+contract Mailbox is IMailbox, Indexed, Versioned, OwnableUpgradeable {
     // ============ Libraries ============
 
-    using MerkleLib for MerkleLib.Tree;
     using Message for bytes;
     using TypeCasts for bytes32;
     using TypeCasts for address;
 
     // ============ Constants ============
 
-    // Maximum bytes per message = 2 KiB (somewhat arbitrarily set to begin)
-    uint256 public constant MAX_MESSAGE_BODY_BYTES = 2 * 2**10;
     // Domain of chain on which the contract is deployed
     uint32 public immutable localDomain;
 
     // ============ Public Storage ============
 
+    // A monotonically increasing nonce for outbound unique message IDs.
+    uint32 public nonce;
+
+    // The latest dispatched message ID used for auth in post-dispatch hooks.
+    bytes32 public latestDispatchedId;
+
     // The default ISM, used if the recipient fails to specify one.
     IInterchainSecurityModule public defaultIsm;
-    // An incremental merkle tree used to store outbound message IDs.
-    MerkleLib.Tree public tree;
-    // Mapping of message ID to whether or not that message has been delivered.
-    mapping(bytes32 => bool) public delivered;
 
-    // ============ Upgrade Gap ============
+    // The default post dispatch hook, used for post processing of opting-in dispatches.
+    IPostDispatchHook public defaultHook;
+
+    // The required post dispatch hook, used for post processing of ALL dispatches.
+    IPostDispatchHook public requiredHook;
 
-    // gap for upgrade safety
-    uint256[47] private __GAP;
+    // Mapping of message ID to delivery context that processed the message.
+    struct Delivery {
+        address processor;
+        uint48 blockNumber;
+    }
+    mapping(bytes32 => Delivery) internal deliveries;
 
     // ============ Events ============
 
@@ -58,45 +60,40 @@ contract Mailbox is
     event DefaultIsmSet(address indexed module);
 
     /**
-     * @notice Emitted when Mailbox is paused
+     * @notice Emitted when the default hook is updated
+     * @param hook The new default hook
      */
-    event Paused();
+    event DefaultHookSet(address indexed hook);
 
     /**
-     * @notice Emitted when Mailbox is unpaused
+     * @notice Emitted when the required hook is updated
+     * @param hook The new required hook
      */
-    event Unpaused();
+    event RequiredHookSet(address indexed hook);
 
     // ============ Constructor ============
-
     constructor(uint32 _localDomain) {
         localDomain = _localDomain;
     }
 
     // ============ Initializers ============
-
-    function initialize(address _owner, address _defaultIsm)
-        external
-        initializer
-    {
-        __PausableReentrancyGuard_init();
+    function initialize(
+        address _owner,
+        address _defaultIsm,
+        address _defaultHook,
+        address _requiredHook
+    ) external initializer {
         __Ownable_init();
+        setDefaultIsm(_defaultIsm);
+        setDefaultHook(_defaultHook);
+        setRequiredHook(_requiredHook);
         transferOwnership(_owner);
-        _setDefaultIsm(_defaultIsm);
     }
 
     // ============ External Functions ============
-
     /**
-     * @notice Sets the default ISM for the Mailbox.
-     * @param _module The new default ISM. Must be a contract.
-     */
-    function setDefaultIsm(address _module) external onlyOwner {
-        _setDefaultIsm(_module);
-    }
-
-    /**
-     * @notice Dispatches a message to the destination domain & recipient.
+     * @notice Dispatches a message to the destination domain & recipient
+     * using the default hook and empty metadata.
      * @param _destinationDomain Domain of destination chain
      * @param _recipientAddress Address of recipient on destination chain as bytes32
      * @param _messageBody Raw bytes content of message body
@@ -106,30 +103,86 @@ contract Mailbox is
         uint32 _destinationDomain,
         bytes32 _recipientAddress,
         bytes calldata _messageBody
-    ) external override notPaused returns (bytes32) {
-        require(_messageBody.length <= MAX_MESSAGE_BODY_BYTES, "msg too long");
-        // Format the message into packed bytes.
-        bytes memory _message = Message.formatMessage(
-            VERSION,
-            count(),
-            localDomain,
-            msg.sender.addressToBytes32(),
-            _destinationDomain,
-            _recipientAddress,
-            _messageBody
-        );
+    ) external payable override returns (bytes32) {
+        return
+            dispatch(
+                _destinationDomain,
+                _recipientAddress,
+                _messageBody,
+                _messageBody[0:0],
+                defaultHook
+            );
+    }
 
-        // Insert the message ID into the merkle tree.
-        bytes32 _id = _message.id();
-        tree.insert(_id);
-        emit Dispatch(
-            msg.sender,
-            _destinationDomain,
-            _recipientAddress,
-            _message
-        );
-        emit DispatchId(_id);
-        return _id;
+    /**
+     * @notice Dispatches a message to the destination domain & recipient.
+     * @param destinationDomain Domain of destination chain
+     * @param recipientAddress Address of recipient on destination chain as bytes32
+     * @param messageBody Raw bytes content of message body
+     * @param hookMetadata Metadata used by the post dispatch hook
+     * @return The message ID inserted into the Mailbox's merkle tree
+     */
+    function dispatch(
+        uint32 destinationDomain,
+        bytes32 recipientAddress,
+        bytes calldata messageBody,
+        bytes calldata hookMetadata
+    ) external payable override returns (bytes32) {
+        return
+            dispatch(
+                destinationDomain,
+                recipientAddress,
+                messageBody,
+                hookMetadata,
+                defaultHook
+            );
+    }
+
+    /**
+     * @notice Computes quote for dipatching a message to the destination domain & recipient
+     * using the default hook and empty metadata.
+     * @param destinationDomain Domain of destination chain
+     * @param recipientAddress Address of recipient on destination chain as bytes32
+     * @param messageBody Raw bytes content of message body
+     * @return fee The payment required to dispatch the message
+     */
+    function quoteDispatch(
+        uint32 destinationDomain,
+        bytes32 recipientAddress,
+        bytes calldata messageBody
+    ) external view returns (uint256 fee) {
+        return
+            quoteDispatch(
+                destinationDomain,
+                recipientAddress,
+                messageBody,
+                messageBody[0:0],
+                defaultHook
+            );
+    }
+
+    /**
+     * @notice Computes quote for dispatching a message to the destination domain & recipient.
+     * @param destinationDomain Domain of destination chain
+     * @param recipientAddress Address of recipient on destination chain as bytes32
+     * @param messageBody Raw bytes content of message body
+     * @param defaultHookMetadata Metadata used by the default post dispatch hook
+     * @return fee The payment required to dispatch the message
+     */
+    function quoteDispatch(
+        uint32 destinationDomain,
+        bytes32 recipientAddress,
+        bytes calldata messageBody,
+        bytes calldata defaultHookMetadata
+    ) external view returns (uint256 fee) {
+        return
+            quoteDispatch(
+                destinationDomain,
+                recipientAddress,
+                messageBody,
+                defaultHookMetadata,
+                defaultHook
+            );
     }
 
     /**
@@ -140,82 +193,196 @@ contract Mailbox is
      */
     function process(bytes calldata _metadata, bytes calldata _message)
         external
+        payable
         override
-        nonReentrantAndNotPaused
     {
+        /// CHECKS ///
+
         // Check that the message was intended for this mailbox.
-        require(_message.version() == VERSION, "!version");
-        require(_message.destination() == localDomain, "!destination");
+        require(_message.version() == VERSION, "Mailbox: bad version");
+        require(
+            _message.destination() == localDomain,
+            "Mailbox: unexpected destination"
+        );
 
         // Check that the message hasn't already been delivered.
         bytes32 _id = _message.id();
-        require(delivered[_id] == false, "delivered");
-        delivered[_id] = true;
+        require(delivered(_id) == false, "Mailbox: already delivered");
+
+        // Get the recipient's ISM.
+        address recipient = _message.recipientAddress();
+        IInterchainSecurityModule ism = recipientIsm(recipient);
+
+        /// EFFECTS ///
 
-        // Verify the message via the ISM.
-        IInterchainSecurityModule _ism = IInterchainSecurityModule(
-            recipientIsm(_message.recipientAddress())
+        deliveries[_id] = Delivery({
+            processor: msg.sender,
+            blockNumber: uint48(block.number)
+        });
+        emit Process(_message.origin(), _message.sender(), recipient);
+        emit ProcessId(_id);
+
+        /// INTERACTIONS ///
+
+        // Verify the message via the interchain security module.
+        require(
+            ism.verify(_metadata, _message),
+            "Mailbox: ISM verification failed"
         );
-        require(_ism.verify(_metadata, _message), "!module");
 
         // Deliver the message to the recipient.
-        uint32 origin = _message.origin();
-        bytes32 sender = _message.sender();
-        address recipient = _message.recipientAddress();
-        IMessageRecipient(recipient).handle(origin, sender, _message.body());
-        emit Process(origin, sender, recipient);
-        emit ProcessId(_id);
+        IMessageRecipient(recipient).handle{value: msg.value}(
+            _message.origin(),
+            _message.sender(),
+            _message.body()
+        );
+    }
+
+    /**
+     * @notice Returns the account that processed the message.
+     * @param _id The message ID to check.
+     * @return The account that processed the message.
+     */
+    function processor(bytes32 _id) external view returns (address) {
+        return deliveries[_id].processor;
+    }
+
+    /**
+     * @notice Returns the account that processed the message.
+     * @param _id The message ID to check.
+     * @return The number of the block that the message was processed at.
+     */
+    function processedAt(bytes32 _id) external view returns (uint48) {
+        return deliveries[_id].blockNumber;
     }
 
     // ============ Public Functions ============
 
     /**
-     * @notice Calculates and returns tree's current root
+     * @notice Dispatches a message to the destination domain & recipient.
+     * @param destinationDomain Domain of destination chain
+     * @param recipientAddress Address of recipient on destination chain as bytes32
+     * @param messageBody Raw bytes content of message body
+     * @param metadata Metadata used by the post dispatch hook
+     * @param hook Custom hook to use instead of the default
+     * @return The message ID inserted into the Mailbox's merkle tree
      */
-    function root() public view returns (bytes32) {
-        return tree.root();
+    function dispatch(
+        uint32 destinationDomain,
+        bytes32 recipientAddress,
+        bytes calldata messageBody,
+        bytes calldata metadata,
+        IPostDispatchHook hook
+    ) public payable virtual returns (bytes32) {
+        if (address(hook) == address(0)) {
+            hook = defaultHook;
+        }
+
+        /// CHECKS ///
+
+        // Format the message into packed bytes.
+        bytes memory message = _buildMessage(
+            destinationDomain,
+            recipientAddress,
+            messageBody
+        );
+        bytes32 id = message.id();
+
+        /// EFFECTS ///
+
+        latestDispatchedId = id;
+        nonce += 1;
+        emit Dispatch(msg.sender, destinationDomain, recipientAddress, message);
+        emit DispatchId(id);
+
+        /// INTERACTIONS ///
+        uint256 requiredValue = requiredHook.quoteDispatch(metadata, message);
+        // if underpaying, defer to required hook's reverting behavior
+        if (msg.value < requiredValue) {
+            requiredValue = msg.value;
+        }
+        requiredHook.postDispatch{value: requiredValue}(metadata, message);
+        hook.postDispatch{value: msg.value - requiredValue}(metadata, message);
+
+        return id;
     }
 
     /**
-     * @notice Returns the number of inserted leaves in the tree
+     * @notice Computes quote for dispatching a message to the destination domain & recipient.
+     * @param destinationDomain Domain of destination chain
+     * @param recipientAddress Address of recipient on destination chain as bytes32
+     * @param messageBody Raw bytes content of message body
+     * @param metadata Metadata used by the post dispatch hook
+     * @param hook Custom hook to use instead of the default
+     * @return fee The payment required to dispatch the message
      */
-    function count() public view returns (uint32) {
-        // count cannot exceed 2**TREE_DEPTH, see MerkleLib.sol
-        return uint32(tree.count);
+    function quoteDispatch(
+        uint32 destinationDomain,
+        bytes32 recipientAddress,
+        bytes calldata messageBody,
+        bytes calldata metadata,
+        IPostDispatchHook hook
+    ) public view returns (uint256 fee) {
+        if (address(hook) == address(0)) {
+            hook = defaultHook;
+        }
+
+        bytes memory message = _buildMessage(
+            destinationDomain,
+            recipientAddress,
+            messageBody
+        );
+        return
+            requiredHook.quoteDispatch(metadata, message) +
+            hook.quoteDispatch(metadata, message);
     }
 
     /**
-     * @notice Returns a checkpoint representing the current merkle tree.
-     * @return root The root of the Mailbox's merkle tree.
-     * @return index The index of the last element in the tree.
+     * @notice Returns true if the message has been processed.
+     * @param _id The message ID to check.
+     * @return True if the message has been delivered.
      */
-    function latestCheckpoint() external view returns (bytes32, uint32) {
-        return (root(), count() - 1);
+    function delivered(bytes32 _id) public view override returns (bool) {
+        return deliveries[_id].blockNumber > 0;
     }
 
     /**
-     * @notice Pauses mailbox and prevents further dispatch/process calls
-     * @dev Only `owner` can pause the mailbox.
+     * @notice Sets the default ISM for the Mailbox.
+     * @param _module The new default ISM. Must be a contract.
      */
-    function pause() external onlyOwner {
-        _pause();
-        emit Paused();
+    function setDefaultIsm(address _module) public onlyOwner {
+        require(
+            Address.isContract(_module),
+            "Mailbox: default ISM not contract"
+        );
+        defaultIsm = IInterchainSecurityModule(_module);
+        emit DefaultIsmSet(_module);
     }
 
     /**
-     * @notice Unpauses mailbox and allows for message processing.
-     * @dev Only `owner` can unpause the mailbox.
+     * @notice Sets the default post dispatch hook for the Mailbox.
+     * @param _hook The new default post dispatch hook. Must be a contract.
      */
-    function unpause() external onlyOwner {
-        _unpause();
-        emit Unpaused();
+    function setDefaultHook(address _hook) public onlyOwner {
+        require(
+            Address.isContract(_hook),
+            "Mailbox: default hook not contract"
+        );
+        defaultHook = IPostDispatchHook(_hook);
+        emit DefaultHookSet(_hook);
     }
 
     /**
-     * @notice Returns whether mailbox is paused.
+     * @notice Sets the required post dispatch hook for the Mailbox.
+     * @param _hook The new default post dispatch hook. Must be a contract.
      */
-    function isPaused() external view returns (bool) {
-        return _isPaused();
+    function setRequiredHook(address _hook) public onlyOwner {
+        require(
+            Address.isContract(_hook),
+            "Mailbox: required hook not contract"
+        );
+        requiredHook = IPostDispatchHook(_hook);
+        emit RequiredHookSet(_hook);
     }
 
     /**
@@ -229,32 +396,41 @@ contract Mailbox is
         view
         returns (IInterchainSecurityModule)
     {
-        // Use a default interchainSecurityModule if one is not specified by the
-        // recipient.
-        // This is useful for backwards compatibility and for convenience as
-        // recipients are not mandated to specify an ISM.
-        try
-            ISpecifiesInterchainSecurityModule(_recipient)
-                .interchainSecurityModule()
-        returns (IInterchainSecurityModule _val) {
-            // If the recipient specifies a zero address, use the default ISM.
-            if (address(_val) != address(0)) {
-                return _val;
+        // use low-level staticcall in case of revert or empty return data
+        (bool success, bytes memory returnData) = _recipient.staticcall(
+            abi.encodeCall(
+                ISpecifiesInterchainSecurityModule.interchainSecurityModule,
+                ()
+            )
+        );
+        // check if call was successful and returned data
+        if (success && returnData.length != 0) {
+            // check if returnData is a valid address
+            address ism = abi.decode(returnData, (address));
+            // check if the ISM is a contract
+            if (ism != address(0)) {
+                return IInterchainSecurityModule(ism);
             }
-            // solhint-disable-next-line no-empty-blocks
-        } catch {}
+        }
+        // Use the default if a valid one is not specified by the recipient.
         return defaultIsm;
     }
 
     // ============ Internal Functions ============
-
-    /**
-     * @notice Sets the default ISM for the Mailbox.
-     * @param _module The new default ISM. Must be a contract.
-     */
-    function _setDefaultIsm(address _module) internal {
-        require(Address.isContract(_module), "!contract");
-        defaultIsm = IInterchainSecurityModule(_module);
-        emit DefaultIsmSet(_module);
+    function _buildMessage(
+        uint32 destinationDomain,
+        bytes32 recipientAddress,
+        bytes calldata messageBody
+    ) internal view returns (bytes memory) {
+        return
+            Message.formatMessage(
+                VERSION,
+                nonce,
+                localDomain,
+                msg.sender.addressToBytes32(),
+                destinationDomain,
+                recipientAddress,
+                messageBody
+            );
     }
 }

package/contracts/client/GasRouter.sol

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+pragma solidity >=0.6.11;
+
+import {Router} from "./Router.sol";
+import {StandardHookMetadata} from "../hooks/libs/StandardHookMetadata.sol";
+
+abstract contract GasRouter is Router {
+    // ============ Mutable Storage ============
+    mapping(uint32 => uint256) public destinationGas;
+
+    struct GasRouterConfig {
+        uint32 domain;
+        uint256 gas;
+    }
+
+    constructor(address _mailbox) Router(_mailbox) {}
+
+    /**
+     * @notice Sets the gas amount dispatched for each configured domain.
+     * @param gasConfigs The array of GasRouterConfig structs
+     */
+    function setDestinationGas(GasRouterConfig[] calldata gasConfigs)
+        external
+        onlyOwner
+    {
+        for (uint256 i = 0; i < gasConfigs.length; i += 1) {
+            _setDestinationGas(gasConfigs[i].domain, gasConfigs[i].gas);
+        }
+    }
+
+    /**
+     * @notice Sets the gas amount dispatched for each configured domain.
+     * @param domain The destination domain ID
+     * @param gas The gas limit
+     */
+    function setDestinationGas(uint32 domain, uint256 gas) external onlyOwner {
+        _setDestinationGas(domain, gas);
+    }
+
+    /**
+     * @notice Returns the gas payment required to dispatch a message to the given domain's router.
+     * @param _destinationDomain The domain of the router.
+     * @return _gasPayment Payment computed by the registered InterchainGasPaymaster.
+     */
+    function quoteGasPayment(uint32 _destinationDomain)
+        external
+        view
+        returns (uint256 _gasPayment)
+    {
+        return _quoteDispatch(_destinationDomain, "");
+    }
+
+    function _refundAddress(uint32) internal view virtual returns (address) {
+        return msg.sender;
+    }
+
+    function _metadata(uint32 _destination)
+        internal
+        view
+        virtual
+        override
+        returns (bytes memory)
+    {
+        return
+            StandardHookMetadata.formatMetadata(
+                destinationGas[_destination],
+                _refundAddress(_destination)
+            );
+    }
+
+    function _setDestinationGas(uint32 domain, uint256 gas) internal {
+        destinationGas[domain] = gas;
+    }
+}