Mailbox

caution

This protocol overview is from our v2 contract version.

v3 now includes post-dispatch hooks, with interchain gas payments (IGP) as one of the required hooks.

We are working to update it with the relevant content ASAP. In the meantime, see the fully updated v3 Reference tab for the latest contract interfaces.

The Hyperlane Mailbox smart contracts expose an on-chain API for sending and receiving interchain messages. There is a Mailbox contract deployed on every chain Hyperlane supports.

The network of Mailboxes facilitates the connective tissue between blockchains that developers leverage to create interchain applications, and add interchain functionality to their existing applications.

Interface

The IMailbox interface exposes two state-mutating functions; dispatch() and process(), which are used to send and receive messages, respectively.

// SPDX-License-Identifier: MIT OR Apache-2.0
pragma solidity >=0.8.0;

interface IMailbox {
    function dispatch(
        uint32 _destinationDomain,
        bytes32 _recipientAddress,
        bytes calldata _messageBody
    ) external returns (bytes32);

    function process(bytes calldata _metadata, bytes calldata _message)
        external;
}

Dispatch

To send interchain messages, developers call Mailbox.dispatch().

This function takes as parameters the message contents, the destination chain ID, and the recipient address. Each message get inserted as a leaf into an incremental merkle tree stored by the Mailbox.

Hyperlane's proof of stake protocol uses this merkle tree to verify fraud proofs.

Process

To deliver interchain messages, the relayer call Mailbox.process().

This function takes as parameters the message to deliver as well as arbitrary metadata that can be specified by the relayer.

The Mailbox will pass the message and metadata to the recipient's interchain security module for verification. If the ISM successfully verifies the message, the Mailbox delivers the message to the recipient by calling recipient.handle().

info

See Message.solfor more details on Hyperlane message encoding