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.
- To send interchain messages, call the
dispatch
function. - To receive interchain messages, implement the
handle
function.
Interface
TheIMailbox
interface exposes two state-mutating functions; dispatch()
and process()
, which are used to send and receive messages, respectively.
IMailbox Interface
IMailbox Interface
Message Headers
The Mailbox prepends message bodies with a header containing the following fields:Field | Description |
---|---|
version | The version of the Mailbox contract |
nonce | A unique identifier for each message sent from a given Mailbox |
origin | The domain of the origin chain |
sender | The address of the sender on the origin chain |
destination | The domain of the destination chain |
recipient | The address of the recipient on the destination chain |
Message
library for more information on the message encoding.
Uniqueness
Thenonce
is a monotonically increasing integer for each message sent from a given Mailbox. It is incremented each time a message is dispatched to serve as a separator for otherwise identical messages.
messageId
is a globally unique message identifier, returned from the dispatch
call, computed as the keccak256
hash of the message (with headers).
Replay Protection
The Mailbox maintains a mapping of already deliveredmessageId
values to prevent replay attacks. If a message is received with a messageId
that has already been delivered, the message is rejected.
Dispatch
To send interchain messages, developers callMailbox.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 callsMailbox.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()
.
See
Message.sol
for more details on Hyperlane message encoding