Send a message
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.
Dispatch
Calling this function dispatches a message to the destination domain and recipient.
Hyperlane can only deliver messages to smart contracts that implement the handle
function. See the receive a message documentation for more information.
Depending on the post-dispatch
hook configuration, some payment may be required. See the quoteDispatch
section for more information.
- Solidity
function dispatch(
uint32 destinationDomain,
bytes32 recipientAddress,
bytes calldata messageBody
) external payable returns (bytes32 messageId);
Recipient addresses are left-padded to bytes32
for compatibility with virtual machines that are addressed differently. The following utility is provided in the TypeCasts
library for convenience.
// alignment preserving cast
function addressToBytes32(address _addr) internal pure returns (bytes32) {
return bytes32(uint256(uint160(_addr)));
}
Examples
- Solidity
- CosmWasm
- Sealevel
// send message from alfajores to arbitrumsepolia TestRecipient
IMailbox mailbox = IMailbox("0xEf9F292fcEBC3848bF4bB92a96a04F9ECBb78E59");
bytes32 messageId = mailbox.dispatch{value: msg.value}(
421614,
"0x0000000000000000000000006489d13AcAd3B8dce4c5B31f375DE4f9451E7b38",
bytes("Hello, world")
);
Quote Dispatch
Fees are often configured to cover IGP payments as well as protocol costs. These include transaction submission on the destination chain, security provisioning, and maintenance. To receive a quote for a corresponding dispatch
call, you can query the quoteDispatch
function.
- Solidity
* @notice Computes quote for dipatching a message to the destination domain & recipient
* using the default hook and empty metadata.
* @param destinationDomain Domain of destination chain
* @param recipientAddress Address of recipient on destination chain as bytes32
* @param messageBody Raw bytes content of message body
The quoted fee
must be passed as value to the dispatch
call to ensure it does not revert.
Examples
- Solidity
- CosmWasm
- Sealevel
// quote sending message from alfajores to arbitrumsepolia TestRecipient
IMailbox mailbox = IMailbox("0xEf9F292fcEBC3848bF4bB92a96a04F9ECBb78E59");
uint32 destination = 421614;
bytes32 recipient = "0x0000000000000000000000006489d13AcAd3B8dce4c5B31f375DE4f9451E7b38";
bytes memory body = bytes("Hello, world");
uint256 fee = mailbox.quoteDispatch(destination, recipient, body);
mailbox.dispatch{value: fee}(destination, recipient, body);
Underpayment to dispatch
will revert. If you are composing hooks together, overpayment may not be refunded to the message sender.
Post-Dispatch Hook Config
There are two hooks configured on a Mailbox
required
: invoked for alldispatch
calls with value that covers the required feedefault
: invoked (unless overridden) with remaining value afterrequired
hook
Required Hook
To query the required hook configuration, you can call the requiredHook
function.
- Solidity
function requiredHook() external view returns (IPostDispatchHook);
Default Hook
To query the default hook configuration, you can call the defaultHook
function.
- Solidity
function defaultHook() external view returns (IPostDispatchHook);
To override the default hook with a custom hook in the dispatch
call, see the Hooks Reference.