Mailbox Contract

The UniversalBridgeMailbox contract is the messaging layer used by the Ethera bridge for transfers between rollups. It stores outbound bridge messages, receives inbound messages from the coordinator, and allows authorized bridge contracts to consume those messages during execution.

Overview

The mailbox contract is responsible for:

• Storing outbound messages written by authorized bridge contracts
• Receiving inbound messages from the coordinator
• Generating deterministic message keys from message headers
• Tracking per-chain inbox and outbox roots
• Preventing a message from being consumed more than once

Incoming messages are consumed on use, preventing the same bridge message from being processed more than once.

Contract Interface

contract UniversalBridgeMailbox is IUniversalBridgeMailbox {
    address public immutable COORDINATOR;
    address public immutable owner;
    mapping(address => bool) public authorizedBridges;

    function authorizeBridge(address _bridge) external;
    function revokeBridge(address _bridge) external;
    function getKey(...) public pure returns (bytes32 key);
    function putInbox(...) external;
    function readMessage(...) external returns (bytes memory message);
    function writeMessage(...) external;
    function computeKey(uint256 id) external view returns (bytes32);
}

Functions

authorizeBridge(_bridge)

Description: Authorizes a bridge contract to write outbound messages and consume inbound messages through the mailbox.

Parameter	Type	Description
_bridge	address	Bridge contract address to authorize

Requirements:

• Only the mailbox owner can call this function
• _bridge cannot be the zero address

Process:

1. Validates that the caller is the mailbox owner
2. Validates that the bridge address is not the zero address
3. Marks the bridge as authorized

---

revokeBridge(_bridge)

Description: Removes bridge authorization from a contract address.

Parameter	Type	Description
_bridge	address	Bridge contract address to revoke

Requirements:

• Only the mailbox owner can call this function

Process:

1. Validates that the caller is the mailbox owner
2. Removes bridge authorization for the provided address

---

getKey(chainMessageSender, chainMessageRecipient, sender, receiver, sessionId, label)

Description: Computes the deterministic key used to store and retrieve a mailbox message.

Parameter	Type	Description
chainMessageSender	uint256	Source chain ID
chainMessageRecipient	uint256	Destination chain ID
sender	address	Sender address recorded in the message header
receiver	address	Receiver address recorded in the message header
sessionId	uint256	Unique identifier for the transfer session
label	string	Message label, such as SEND_TOKENS, SEND_ETH, or ACK

Returns:

• key (bytes32): Deterministic message key derived from the full header

Use Cases:

• Generate the same key on different chains for the same message header
• Inspect or verify mailbox storage entries
• Recompute message identifiers during debugging or integration work

---

putInbox(chainMessageSender, sender, receiver, sessionId, label, data)

Description: Writes an inbound message into the mailbox inbox on the destination chain.

Parameter	Type	Description
chainMessageSender	uint256	Source chain ID
sender	address	Sender address recorded on the source chain
receiver	address	Receiver address on the destination chain
sessionId	uint256	Unique identifier for the transfer session
label	string	Message label
data	bytes	Message payload

Requirements:

• Only the coordinator can call this function
• The computed inbox key must not already exist

Process:

1. Computes the inbox key from the message header
2. Stores the payload in the inbox
3. Tracks the key as created
4. Updates the inbox root for the source chain
5. Emits NewInboxKey

Events:

• NewInboxKey(uint256 indexed index, bytes32 key)

---

readMessage(header)

Description: Reads and consumes an inbound message from the inbox.

Parameter	Type	Description
header	MessageHeader	Full message header used to identify the inbox entry

Returns:

• message (bytes memory): The stored payload for the provided message header

Requirements:

• Only authorized bridge contracts can call this function
• The message must exist in the inbox
• The message must not already have been consumed

Process:

1. Recomputes the message key from the provided header
2. Verifies that the message exists
3. Verifies that the message has not already been consumed
4. Marks the message as consumed
5. Deletes the inbox entry
6. Returns the payload

---

writeMessage(message)

Description: Writes an outbound message into the mailbox outbox.

Parameter	Type	Description
message	Message	Full mailbox message, including header and payload

Requirements:

• Only authorized bridge contracts can call this function

Process:

1. Computes the outbox key from the supplied message header
2. Records block.chainid as the source chain
3. Records msg.sender as the sending bridge contract
4. Stores the payload in the outbox
5. Tracks the key as created
6. Updates the outbox root for the destination chain
7. Emits NewOutboxKey

When writing the message, the mailbox records:

• block.chainid as the source chain
• msg.sender as the sending bridge contract
• the destination chain, receiver, session ID, and label from the supplied message header

Events:

• NewOutboxKey(uint256 indexed index, bytes32 key)

---

computeKey(id)

Description: Recomputes an inbox message key from the stored inbox header at the given index.

Parameter	Type	Description
id	uint256	Index in messageHeaderListInbox

Returns:

• key (bytes32): Deterministic key for the indexed inbox message header

Requirements:

• id must be a valid inbox header index

Use Cases:

• Recompute the key for an inbox entry by index
• Cross-reference inbox headers with stored message data
• Inspect mailbox contents during debugging

Events

NewInboxKey

event NewInboxKey(uint256 indexed index, bytes32 key)

Emitted when the coordinator inserts a new inbound message into the mailbox inbox.

NewOutboxKey

event NewOutboxKey(uint256 indexed index, bytes32 key)

Emitted when an authorized bridge contract writes a new outbound message into the mailbox outbox.