Mailbox Contract

The Mailbox contract is a core component of the Compose Network that enables cross-chain communication between different rollups. It implements a message passing system where contracts can send messages to other chains and receive messages from other chains through a coordinator-managed inbox and outbox system.

Overview

The Mailbox contract facilitates secure cross-chain communication by:

• Managing inbox and outbox for cross-chain messages
• Providing key-based message storage and retrieval
• Enabling coordinator-controlled message population
• Supporting chain-specific message roots for efficient verification
• Implementing session-based message organization

Contract Interface

contract Mailbox is IMailbox {
    address public immutable COORDINATOR;
    uint256[] public chainIDsInbox;
    uint256[] public chainIDsOutbox;
    mapping(uint256 => bytes32) public inboxRootPerChain;
    mapping(uint256 => bytes32) public outboxRootPerChain;
    mapping(bytes32 => bytes) public inbox;
    mapping(bytes32 => bytes) public outbox;
    mapping(bytes32 => bool) public createdKeys;
    MessageHeader[] public messageHeaderListInbox;
    MessageHeader[] public messageHeaderListOutbox;
    
    constructor(address _coordinator);
    function getKey(...) public pure returns (bytes32);
    function read(...) external view returns (bytes memory);
    function write(...) external;
    function putInbox(...) external;
    function computeKey(uint256 id) external view returns (bytes32);
}

Functions

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

Description: Creates a unique key for storing and retrieving messages in the inbox and outbox. This key is generated using a hash of all message parameters to ensure uniqueness and prevent collisions.

Parameter	Type	Description
chainMessageSender	uint256	The chain ID of the source chain
chainMessageRecipient	uint256	The chain ID of the destination chain
sender	address	The address of the sender on the source chain
receiver	address	The address of the recipient on the destination chain
sessionId	uint256	Unique identifier for the user session
label	bytes	Label to differentiate between different operations within the same session

Returns:

• key (bytes32): The computed hash key for message storage

Use Cases:

• Generate consistent keys for message storage
• Enable message lookup across different contract calls
• Support session-based message organization

---

read(chainMessageSender, sender, sessionId, label)

Description: Reads messages from the inbox. Messages can be read by any contract any number of times without being consumed.

Parameter	Type	Description
chainMessageSender	uint256	The chain ID that sent the message
sender	address	The address of the sender on the source chain
sessionId	uint256	The session ID of the message
label	bytes	The label used to identify the specific message

Returns:

• message (bytes memory): The message data, or reverts if message not found

Requirements:

• The message must exist in the inbox (either populated or key created)
• The caller must provide the correct parameters to generate the message key

Process:

1. Generates the message key using the provided parameters
2. Checks if the message exists in the inbox
3. Returns the message data or reverts with MessageNotFound

Events:

• None (view function)

---

write(chainMessageRecipient, receiver, sessionId, label, data)

Description: Writes messages to the outbox for cross-chain delivery. Any contract can write to the outbox, with the sender automatically populated as msg.sender.

Parameter	Type	Description
chainMessageRecipient	uint256	The chain ID of the destination chain
receiver	address	The address of the recipient on the destination chain
sessionId	uint256	The session ID for this message
label	bytes	Label to differentiate between different operations within the same session
data	bytes	The message data to be sent

Requirements:

• None (any contract can call this function)

Process:

1. Generates the message key using current chain ID as sender
2. Stores the message data in the outbox mapping
3. Marks the key as created
4. Adds message header to the outbox list
5. Updates the chain-specific outbox root
6. Emits NewOutboxKey event

Events:

• NewOutboxKey(uint256 indexed messageIndex, bytes32 indexed key)

---

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

Description: Writes messages to the inbox. Only the coordinator can call this function to populate incoming cross-chain messages.

Parameter	Type	Description
chainMessageSender	uint256	The chain ID of the source chain
sender	address	The address of the sender on the source chain
receiver	address	The address of the recipient on this chain
sessionId	uint256	The session ID of the message
label	bytes	The label used to identify the specific message
data	bytes	The message data to be stored

Requirements:

• Only the coordinator can call this function
• The coordinator must be authorized and trusted

Process:

1. Validates that the caller is the coordinator
2. Generates the message key using the provided parameters
3. Stores the message data in the inbox mapping
4. Marks the key as created
5. Adds message header to the inbox list
6. Updates the chain-specific inbox root
7. Emits NewInboxKey event

Events:

• NewInboxKey(uint256 indexed messageIndex, bytes32 indexed key)

---

computeKey(id)

Description: Computes the key for a message in the inbox using its index in the message header list. Useful for verification and debugging purposes.

Parameter	Type	Description
id	uint256	The index of the message in the messageHeaderListInbox array

Returns:

• bytes32: The computed key for the message at the given index

Requirements:

• The provided ID must be valid (less than the length of messageHeaderListInbox)

Use Cases:

• Verify message keys for debugging
• Implement message verification systems
• Cross-reference message headers with stored data

Events:

• None (view function)

Events

NewOutboxKey

event NewOutboxKey(uint256 indexed messageIndex, bytes32 indexed key)

Emitted when a new message is written to the outbox. The messageIndex corresponds to the position in the messageHeaderListOutbox array.

NewInboxKey

event NewInboxKey(uint256 indexed messageIndex, bytes32 indexed key)

Emitted when a new message is added to the inbox by the coordinator. The messageIndex corresponds to the position in the messageHeaderListInbox array.