@hyperlane-xyz/core 5.8.3 → 5.9.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 = "5.8.3";
+    string public constant PACKAGE_VERSION = "5.9.0";
 }

package/contracts/client/MailboxClient.sol

@@ -58,7 +58,7 @@ abstract contract MailboxClient is OwnableUpgradeable, PackageVersioned {
     }
 
     /**
-     * @notice Only accept messages from an Hyperlane Mailbox contract
+     * @notice Only accept messages from a Hyperlane Mailbox contract
      */
     modifier onlyMailbox() {
         require(

package/contracts/client/Router.sol

@@ -145,7 +145,7 @@ abstract contract Router is MailboxClient, IMessageRecipient {
     }
 
     /**
-     * @notice Assert that the given domain has a Application Router registered and return its address
+     * @notice Assert that the given domain has an Application Router registered and return its address
      * @param _domain The domain of the chain for which to get the Application Router
      * @return _router The address of the remote Application Router on _domain
      */

package/contracts/hooks/README.md

@@ -0,0 +1,58 @@
+# Post-Dispatch Hooks
+
+Post-dispatch hooks allow developers to configure additional origin chain behavior with message content dispatched via the Mailbox.
+
+```mermaid
+flowchart TB
+    subgraph Origin
+      Sender
+      M_O[(Mailbox)]
+      Hook[IPostDispatchHook]
+
+      Sender -- "dispatch(..., metadata, hook)\n{value}" --> M_O
+      M_O -- "postDispatch(message, metadata)\n{value}" --> Hook
+    end
+```
+
+If the `postDispatch` function receives insufficient payment, it may revert.
+
+> [!WARNING]
+> Post-Dispatch Hooks may be replayable. Developers creating custom hooks should implement safe checks to prevent this behavior. [Here](./warp-route/RateLimitedHook.sol#L16) is an example implementation.
+
+### Quote Dispatch (Fees)
+
+Fees are often charged in `postDispatch` to cover costs such as destination chain transaction submission and security provisioning. To receive a quote for a corresponding `postDispatch` call, you can query the `quoteDispatch` function.
+
+The Mailbox has a `quoteDispatch` function that returns the aggregate fee required for a `dispatch` call to be successful.
+
+```mermaid
+flowchart TB
+    subgraph Origin
+      Sender
+      M_O[(Mailbox)]
+      R_H[RequiredHook]
+      Hook[Hook]
+
+      Sender -- "quoteDispatch(..., metadata, hook)" --> M_O
+      M_O -- "required = quoteDispatch(message, metadata)" --> R_H
+      M_O -- "fee = hook.quoteDispatch(message, metadata)" --> Hook
+      M_O -- "required + fee" --> Sender
+    end
+```
+
+The custom `metadata` will be passed to the required hook's `quoteDispatch` and `postDispatch` functions, before being passed to the default hook's `postDispatch` function.
+
+```mermaid
+flowchart LR
+    subgraph Origin Chain
+      Sender
+      M_O[(Mailbox)]
+      R_H[RequiredHook]
+      D_H[DefaultHook]
+      Sender -- "dispatch(..., metadata){value}" --> M_O
+
+      M_O -. "fee = quoteDispatch(...)" .- R_H
+      M_O -- "postDispatch(metadata, ...)\n{fee}" --> R_H
+      M_O -. "postDispatch(metadata, ...)\n{value - fee}" ..-> D_H
+    end
+```

package/contracts/isms/README.md

@@ -0,0 +1,20 @@
+# Interchain Security Modules
+
+Interchain security modules allow developers to configure additional security checks for message content dispatched via the Mailbox.
+
+```mermaid
+flowchart LR
+    subgraph Destination Chain
+      ISM[InterchainSecurityModule]
+      Recipient[Recipient]
+      M_D[(Mailbox)]
+
+      M_D -- "verify(metadata, message)" --> ISM
+      ISM -. "interchainSecurityModule()" .- Recipient
+      M_D -- "handle(origin, sender, body)" --> Recipient
+
+    end
+```
+
+> [!WARNING]
+> Interchain security modules may be replayable. Developers creating custom modules should include replay protection if necessary. [Here](./warp-route/RateLimitedIsm.sol#L23) is an example implementation.

package/contracts/isms/hook/AbstractMessageIdAuthorizedIsm.sol

@@ -27,7 +27,7 @@ import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Ini
 
 /**
  * @title AbstractMessageIdAuthorizedIsm
- * @notice Uses external verification options to verify interchain messages which need a authorized caller
+ * @notice Uses external verification options to verify interchain messages which need an authorized caller
  */
 abstract contract AbstractMessageIdAuthorizedIsm is
     IInterchainSecurityModule,
@@ -78,28 +78,13 @@ abstract contract AbstractMessageIdAuthorizedIsm is
     ) external virtual returns (bool) {
         bool verified = isVerified(message);
         if (verified) {
-            releaseValueToRecipient(message);
+            _releaseValueToRecipient(message);
         }
         return verified;
     }
 
     // ============ Public Functions ============
 
-    /**
-     * @notice Release the value to the recipient if the message is verified.
-     * @param message Message to release value for.
-     */
-    function releaseValueToRecipient(bytes calldata message) public {
-        bytes32 messageId = message.id();
-        uint256 _msgValue = verifiedMessages[messageId].clearBit(
-            VERIFIED_MASK_INDEX
-        );
-        if (_msgValue > 0) {
-            verifiedMessages[messageId] -= _msgValue;
-            payable(message.recipientAddress()).sendValue(_msgValue);
-        }
-    }
-
     /**
      * @notice Check if a message is verified through preVerifyMessage first.
      * @param message Message to check.
@@ -138,6 +123,21 @@ abstract contract AbstractMessageIdAuthorizedIsm is
 
     // ============ Internal Functions ============
 
+    /**
+     * @notice Release the value to the recipient if the message is verified.
+     * @param message Message to release value for.
+     */
+    function _releaseValueToRecipient(bytes calldata message) internal {
+        bytes32 messageId = message.id();
+        uint256 _msgValue = verifiedMessages[messageId].clearBit(
+            VERIFIED_MASK_INDEX
+        );
+        if (_msgValue > 0) {
+            verifiedMessages[messageId] -= _msgValue;
+            payable(message.recipientAddress()).sendValue(_msgValue);
+        }
+    }
+
     /**
      * @notice Check if sender is authorized to message `preVerifyMessage`.
      */

package/contracts/isms/hook/ArbL2ToL1Ism.sol

@@ -69,7 +69,7 @@ contract ArbL2ToL1Ism is
             _verifyWithOutboxCall(metadata, message);
             require(isVerified(message), "ArbL2ToL1Ism: message not verified");
         }
-        releaseValueToRecipient(message);
+        _releaseValueToRecipient(message);
         return true;
     }
 

package/contracts/isms/hook/OPL2ToL1Ism.sol

@@ -70,7 +70,7 @@ contract OPL2ToL1Ism is
             _verifyWithPortalCall(metadata, message);
             require(isVerified(message), "OPL2ToL1Ism: message not verified");
         }
-        releaseValueToRecipient(message);
+        _releaseValueToRecipient(message);
         return true;
     }