Skip to main content

Interchain Security Module Interface

Hyperlane modularizes interchain message security through a generic smart contract interface. Implementations are responsible for verifying that messages being delivered on the destination chain were actually sent on the origin chain using some proof metadata.

Message recipients can specify custom security constraints by specifying an InterchainSecurityModule address. This implementation can be configured, composed, and customized according to the needs of their application.

IInterchainSecurityModule Interface
// SPDX-License-Identifier: MIT OR Apache-2.0
pragma solidity >=0.6.11;

interface IInterchainSecurityModule {
    enum Types {
        UNUSED,
        ROUTING,
        AGGREGATION,
        LEGACY_MULTISIG,
        MERKLE_ROOT_MULTISIG,
        MESSAGE_ID_MULTISIG,
        NULL, // used with relayer carrying no metadata
        CCIP_READ,
        ARB_L2_TO_L1,
        WEIGHTED_MERKLE_ROOT_MULTISIG,
        WEIGHTED_MESSAGE_ID_MULTISIG,
        OP_L2_TO_L1
    }

    /**
     * @notice Returns an enum that represents the type of security model
     * encoded by this ISM.
     * @dev Relayers infer how to fetch and format metadata.
     */
    function moduleType() external view returns (uint8);

    /**
     * @notice Defines a security model responsible for verifying interchain
     * messages based on the provided metadata.
     * @param _metadata Off-chain metadata provided by a relayer, specific to
     * the security model encoded by the module (e.g. validator signatures)
     * @param _message Hyperlane encoded interchain message
     * @return True if the message was verified
     */
    function verify(
        bytes calldata _metadata,
        bytes calldata _message
    ) external returns (bool);
}

interface ISpecifiesInterchainSecurityModule {
    function interchainSecurityModule()
        external
        view
        returns (IInterchainSecurityModule);
}

Verify​

* the security model encoded by the module (e.g. validator signatures)
* @param _message Hyperlane encoded interchain message
* @return True if the message was verified
*/

The Mailbox will call verify before delivering a message to its recipient. If verify reverts or returns false, the message will not be delivered.

  • _metadata consists of arbitrary bytes provided by the Relayer. Typically, these bytes are specific to the ISM. For example, for a Multisig ISM, _metadata must include validator signatures.

  • _message consists of the Hyperlane message being verified. ISMs can use this to inspect details about the message being verified. For example, a Multisig ISM could change validator sets based on the origin chain of the message.

Module Type​

* @notice Returns an enum that represents the type of security model

This is used to signal to the Relayer how to encode _metadata. ISMs must return one of the supported module types:

enum Types {
    UNUSED,
    ROUTING,
    AGGREGATION,
    LEGACY_MULTISIG,
    MERKLE_ROOT_MULTISIG,
    MESSAGE_ID_MULTISIG,
    NULL, // used with relayer carrying no metadata
    CCIP_READ,
    ARB_L2_TO_L1,
note

To accomplish this, all ISM contracts implement the ISM interface, which requires moduleType to be defined. This type is branched on by the Relayer in order to determine the required metadata for that ISM. For more information on module types and their metadata formats, see Protocol.

Specifying an ISM​

To specify the ISM they would like to use, developers implement the ISpecifiesInterchainSecurityModule interface in any contract that receives interchain messages via handle().

interface ISpecifiesInterchainSecurityModule {
    function interchainSecurityModule()
        external
        view
        returns (IInterchainSecurityModule);
}

If no ISM is specified, or if the specified ISM is the null address, whatever ISM is configured as the default on the destination chain Mailbox will be used.

Sequence Diagram​

Here is a detailed sequence diagram of an interchain message being verified and delivered on the destination chain.

info

If the recipient does not implement ISpecifiesInterchainSecurityModule or recipient.interchainSecurityModule() returns address(0), the default ISM configured on the Mailbox will be used to verify the message.