Skip to main content

Mailbox Contracts

Overview​

Mailbox contracts provide the core abstraction for cross-rollup message passing in Compose Network. They enable dApps to communicate across different rollups through a simple read/write interface, achieving composability similar to traditional contract function calls.

How Mailbox Contracts Work​

The Mailbox system operates through independent sequencers that coordinate message delivery:

  1. Message Writing: dApps call Mailbox.write() to store messages in the outbox
  2. Message Exchange: Sequencers exchange outbox messages with destination chain sequencers
  3. Message Reading: dApps read messages from the inbox using Mailbox.read()

Mailbox Interface​

The Mailbox contract provides three main functions:

write(dstChain, receiver, label, data)​

  • Stores a message in the outbox for delivery to the destination chain
  • Called by dApp contracts during transaction execution

read(srcChain, sender, label)​

  • Reads a message from the inbox
  • Reverts if the message doesn't exist
  • Returns the message data

addMessage(srcChain, dstChain, sender, receiver, label, data)​

  • Internal function called by sequencers
  • Adds messages to the inbox for dApps to read

Cross-Rollup Composability​

Mailbox contracts enable composability across rollups by abstracting cross-chain communication:

Traditional Composability (Single Chain):

function swapWithCondition(uint256 amount, uint256 threshold) {
    uint256 receivedDAI = uniswap.swap(ETH, DAI, amount);
    require(receivedDAI >= threshold, "Insufficient DAI");
}

Cross-Rollup Composability:

function swapWithCondition(uint256 amount, uint256 threshold) {
    // Equivalent to function call
    Mailbox.write(chainU, uniswapAddr, "SWAP", 
        abi.encode(msg.sender, ETH, DAI, amount));
    
    // Equivalent to function response
    bytes m = Mailbox.read(chainU, uniswapAddr, "SWAP ACK");
    (receivedDAI) = abi.decode(m, (uint256));
    
    require(receivedDAI >= threshold, "Insufficient DAI");
}

Protocol Integration​

The Mailbox contracts work with the Shared Publisher and Two-Phase Commit protocols to ensure atomic cross-rollup transactions. The Shared Publisher coordinates message delivery and ensures all related transactions either succeed or fail together.

Next: Composable Shared Bridge​

The mailbox contract interface provides the foundation for the Composable Shared Bridge, which uses these contracts to facilitate ERC20 token transfers between rollups. The bridge leverages the mailbox's read/write interface to create a seamless cross-rollup token transfer experience.