Component: Mailbox

Description

Mailbox is the chain-local endpoint of Hyperlane messaging. It is responsible for dispatching outbound messages and running any configured hooks, and processing inbound messages after the configured Interchain Security Module (ISM) verifies them.

Mailbox provides a public interface for following actions:

1. Dispatch : Users invoke a dispatch function in order to send interchain messages. When called, it constructs a HyperlaneMessage from the arguments passed, including the nonce, the domain identifier of the source chain, the domain identifier of the destination chain, the sender's address, the recipient's address, and the message to be sent. It then invokes the configured post-dispatch hooks, emit events to notify that a message is sent, and returns any leftover payment buckets to the caller.

2. Process : Relayers invoke a process function in order to deliver interchain messages to this component. When called, it passes the message and metadata to the recipient's ISM to verify the message. If the message is verified, the recipient's handle function will be invoked with the delivered message as an argument, finalizing the delivery.

3. Quote : Users can call the quote_dispatch function to check the fee incurred when invoking dispatch.

On instantiation, the component reserves its address, mints a 1-of-1 owner badge, and sets authentication on methods so that only the owner can change the configured addresses of the ISM and hooks.

Invariants

• The destination domain of the message must be equal to the Mailbox's local_domain. This is enforced by a check in the process function, preventing any mis-routed messages to be processed.

• Each message can be processed only once. This is enforced by a check in the process function, preventing replay of messages.

• The sender of the message must be equal to the address of the account or component that called the dispatch function. This is enforced by a check in the dispatch function, preventing the sender of the message from being spoofed.

Test coverage

Cases covered

• Instantiation of the Mailbox component

• process : Domain mismatch is rejected

• process : Unsupported message version is rejected

• process : Revert when recipient doesn't implement expected app/ISM interface

• dispatch : Message is successfully dispatched

• dispatch : Forged sender address is rejected

Cases not covered

• process : Replay protection

• dispatch : Hook interaction

• set_default_ism/set_default_hook/set_required_hook : Access control

After the primary audit period, Hyperlane introduced negative tests covering these cases in PR 29↗ to improve the project's test coverage.

Attack surface

• Externally controllable inputs to dispatch function :

  • destination_domain, recipient_address and message_body affect message ID, hook execution, and emitted events. Malicious payloads can target the recipient app and should be gated by recipient logic on the destination chain.

  • Callers can route payment through setting arbitrary hook and hook_metadata when calling this function; a malicious hook can steal the caller's own payment. The owner-set required_hook is always invoked; if the owner configures a malicious hook, it can overly extract the user payments. However, this is an expected centralization risk akin to setting fee collectors.

  • Hooks can consume the payment provided by the caller. If the payment is insufficient to cover the gas, the transaction will be reverted.

  • If claimed_account_sender is forged, the verify_message_sender function prevents spoofing by asserting rules against the current caller's proofs or global-caller context.

• Externally controllable inputs to process function :

  • metadata and raw_message are fully controlled by an attacker or relayer. The check for the destination chain and replay protection are performed as mentioned above, and the final verification is carried out by the recipient's ISM.

  • visible_components is forwarded to the recipient. Recipients may require specific component addresses, e.g., for deposits. A malicious relayer can pass arbitrary addresses, and the recipients are responsible for rejecting those with their own logic.

• Owner-controlled configuration risk : The owner can set or modify default_ism, default_hook and required_hook. If compromised or malicious, they can weaken verification or overly extract user payments.