Mailbox
Hyperlane's generalized message passing (GMP) interface is implemented as a smart contract called the Mailbox. This contract encodes and decodes message headers, ensures global message uniqueness, and prevents replay attacks.
To send interchain messages, call the dispatch
function.
To receive interchain messages, implement the handle
function.
IMailbox
Interface
- Solidity
// SPDX-License-Identifier: MIT OR Apache-2.0
pragma solidity >=0.8.0;
import {IInterchainSecurityModule} from "./IInterchainSecurityModule.sol";
import {IPostDispatchHook} from "./hooks/IPostDispatchHook.sol";
interface IMailbox {
// ============ Events ============
/**
* @notice Emitted when a new message is dispatched via Hyperlane
* @param sender The address that dispatched the message
* @param destination The destination domain of the message
* @param recipient The message recipient address on `destination`
* @param message Raw bytes of message
*/
event Dispatch(
address indexed sender,
uint32 indexed destination,
bytes32 indexed recipient,
bytes message
);
/**
* @notice Emitted when a new message is dispatched via Hyperlane
* @param messageId The unique message identifier
*/
event DispatchId(bytes32 indexed messageId);
/**
* @notice Emitted when a Hyperlane message is processed
* @param messageId The unique message identifier
*/
event ProcessId(bytes32 indexed messageId);
/**
* @notice Emitted when a Hyperlane message is delivered
* @param origin The origin domain of the message
* @param sender The message sender address on `origin`
* @param recipient The address that handled the message
*/
event Process(
uint32 indexed origin,
bytes32 indexed sender,
address indexed recipient
);
function localDomain() external view returns (uint32);
function delivered(bytes32 messageId) external view returns (bool);
function defaultIsm() external view returns (IInterchainSecurityModule);
function defaultHook() external view returns (IPostDispatchHook);
function requiredHook() external view returns (IPostDispatchHook);
function latestDispatchedId() external view returns (bytes32);
function dispatch(
uint32 destinationDomain,
bytes32 recipientAddress,
bytes calldata messageBody
) external payable returns (bytes32 messageId);
function quoteDispatch(
uint32 destinationDomain,
bytes32 recipientAddress,
bytes calldata messageBody
) external view returns (uint256 fee);
function dispatch(
uint32 destinationDomain,
bytes32 recipientAddress,
bytes calldata body,
bytes calldata defaultHookMetadata
) external payable returns (bytes32 messageId);
function quoteDispatch(
uint32 destinationDomain,
bytes32 recipientAddress,
bytes calldata messageBody,
bytes calldata defaultHookMetadata
) external view returns (uint256 fee);
function dispatch(
uint32 destinationDomain,
bytes32 recipientAddress,
bytes calldata body,
bytes calldata customHookMetadata,
IPostDispatchHook customHook
) external payable returns (bytes32 messageId);
function quoteDispatch(
uint32 destinationDomain,
bytes32 recipientAddress,
bytes calldata messageBody,
bytes calldata customHookMetadata,
IPostDispatchHook customHook
) external view returns (uint256 fee);
function process(
bytes calldata metadata,
bytes calldata message
) external payable;
function recipientIsm(
address recipient
) external view returns (IInterchainSecurityModule module);
}
Message Headers
The Mailbox prepends message bodies with a header containing the following fields:
version
: The version of the Mailbox contractnonce
: A unique identifier for each message sent from a given Mailboxorigin
: The domain of the origin chainsender
: The address of the sender on the origin chaindestination
: The domain of the destination chainrecipient
: The address of the recipient on the destination chain
See the Message
library for more information on the message encoding.
Uniqueness
The nonce
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.
- Solidity
- CosmWasm
- Sealevel
function delivered(bytes32 messageId) external view returns (bool);
🚧 Coming soon! 🚧
🚧 Coming soon! 🚧
The 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 delivered messageId
values to prevent replay attacks. If a message is received with a messageId
that has already been delivered, the message is rejected.
- Solidity
- CosmWasm
- Sealevel
function defaultIsm() external view returns (IInterchainSecurityModule);
🚧 Coming soon! 🚧
🚧 Coming soon! 🚧