Skip to main content

Inbox

The Inbox is a contract deployed on L1 that handles message passing from L1 to the rollup (L2)

Links: Interface, Implementation.

sendL2Message()

Sends a message from L1 to L2.

send_l1_to_l2_message
/**
* @notice Inserts an entry into the Inbox
* @dev Will emit `MessageAdded` with data for easy access by the sequencer
* @dev msg.value - The fee provided to sequencer for including the entry
* @param _recipient - The recipient of the entry
* @param _deadline - The deadline to consume a message. Only after it, can a message be cancelled.
* @param _content - The content of the entry (application specific)
* @param _secretHash - The secret hash of the entry (make it possible to hide when a specific entry is consumed on L2)
* @return The key of the entry in the set
*/
function sendL2Message(
DataStructures.L2Actor memory _recipient,
uint32 _deadline,
bytes32 _content,
bytes32 _secretHash
) external payable returns (bytes32);
Source code: /l1-contracts/src/core/interfaces/messagebridge/IInbox.sol#L27-L44 (aztec-packages-v0.24.0)
NameTypeDescription
RecipientL2ActorThe recipient of the message. This MUST match the rollup version and an Aztec contract that is attached to the contract making this call. If the recipient is not attached to the caller, the message cannot be consumed by it.
Deadlineuint256The message consumption deadline. If the message have not been removed from the Inbox and included in a rollup block by this point, it can be canceled by the portal (the portal must implement logic to cancel).
Contentfield (~254 bits)The content of the message. This is the data that will be passed to the recipient. The content is limited to be a single field for rollup purposes. If the content is small enough it can just be passed along, otherwise it should be hashed and the hash passed along (you can use our Hash utilities with sha256ToField functions)
Secret Hashfield (~254 bits)A hash of a secret that is used when consuming the message on L2. Keep this preimage a secret to make the consumption private. To consume the message the caller must know the pre-image (the value that was hashed) - so make sure your app keeps track of the pre-images! Use the computeMessageSecretHash to compute it from a secret.
Fee (msg.value)uint256The fee to the sequencer for including the message. This is the amount of ETH that the sequencer will receive for including the message. Note that only values that can fit in uint64 will be accepted
ReturnValuebytes32The message hash, used as an identifier

Edge cases

  • Will revert with Inbox__ActorTooLarge(bytes32 actor) if the recipient is larger than the field size (~254 bits).
  • Will revert with Inbox__DeadlineBeforeNow() if the deadline is before the current block.
  • Will revert with Inbox__ContentTooLarge(bytes32 content) if the content is larger than the field size (~254 bits).
  • Will revert with Inbox__SecretHashTooLarge(bytes32 secretHash) if the secret hash is larger than the field size (~254 bits).
  • Will revert with Inbox__FeeTooHigh() if the fee is larger than type(uint64).max.
  • Will revert Inbox__IncompatibleEntryArguments(bytes32 entryKey, uint64 storedFee, uint64 feePassed, uint32 storedVersion, uint32 versionPassed, uint32 storedDeadline, uint32 deadlinePassed) if insertion is not possible due to invalid entry arguments.

cancelL2Message()

Cancels a message that has not yet been consumed.

pending_l2_cancel
/**
* @notice Cancel a pending L2 message
* @dev Will revert if the deadline have not been crossed - message only cancellable past the deadline
* so it cannot be yanked away while the sequencer is building a block including it
* @dev Must be called by portal that inserted the entry
* @param _message - The content of the entry (application specific)
* @param _feeCollector - The address to receive the "fee"
* @return entryKey - The key of the entry removed
*/
function cancelL2Message(DataStructures.L1ToL2Msg memory _message, address _feeCollector)
external
returns (bytes32 entryKey);
Source code: /l1-contracts/src/core/interfaces/messagebridge/IInbox.sol#L46-L59 (aztec-packages-v0.24.0)
NameTypeDescription
_messageL1ToL2MsgThe message to cancel
_feeCollectoraddressThe address to refund the fee to
ReturnValuebytes32The hash of the message

Edge cases

  • Will revert with Inbox__Unauthorized() if msg.sender != _message.sender.actor.
  • Will revert with Inbox__NotPastDeadline() if block.timestamp <= _message.deadline.
  • Will revert with Inbox__NothingToConsume(bytes32 entryKey) if the message does not exist.

batchConsume()

Allows the Rollup to consume multiple messages in a single transaction.

inbox_batch_consume
/**
* @notice Batch consumes entries from the Inbox
* @dev Only callable by the rollup contract
* @dev Will revert if the message is already past deadline
* @param _entryKeys - Array of entry keys (hash of the messages)
* @param _feeCollector - The address to receive the "fee"
*/
function batchConsume(bytes32[] memory _entryKeys, address _feeCollector) external;
Source code: /l1-contracts/src/core/interfaces/messagebridge/IInbox.sol#L61-L70 (aztec-packages-v0.24.0)
NameTypeDescription
_entryKeysbytes32[]The entry keys (message hashes) to consume
ReturnValueEntryThe entry for the given key

Edge cases

  • Will revert with Registry__RollupNotRegistered(address rollup) if msg.sender is not registered as a rollup on the Registry.
  • Will revert with Inbox__InvalidVersion(uint256 entry, uint256 rollup) if the rollup version does not match the version specified in the message.
  • Will revert with Inbox__PastDeadline() if the message deadline has passed.
  • Will revert with Inbox__NothingToConsume(bytes32 entryKey) if the message does not exist.

withdrawFees()

Will claim the fees that has accrued to the msg.sender from consuming messages.

Let the sequencer withdraw fees from the inbox.

inbox_withdraw_fees
/**
* @notice Withdraws fees accrued by the sequencer
*/
function withdrawFees() external;
Source code: /l1-contracts/src/core/interfaces/messagebridge/IInbox.sol#L72-L77 (aztec-packages-v0.24.0)

Edge cases

  • Will revert with Inbox__FailedToWithdrawFees() if the transfer call fails.

get()

Retrieves the entry for a given message. The entry contains fee, number of occurrences, deadline and version information.

inbox_get
/**
* @notice Fetch an entry
* @param _entryKey - The key to lookup
* @return The entry matching the provided key
*/
function get(bytes32 _entryKey) external view returns (DataStructures.Entry memory);
Source code: /l1-contracts/src/core/interfaces/messagebridge/IInbox.sol#L79-L86 (aztec-packages-v0.24.0)
NameTypeDescription
_entryKeybytes32The entry key (message hash)
ReturnValueEntryThe entry object for the given key

Edge cases

  • Will revert with Inbox__NothingToConsume(bytes32 entryKey) if the message does not exist.

contains()

Returns whether the key exists in the inbox.

inbox_contains
/**
* @notice Check if entry exists
* @param _entryKey - The key to lookup
* @return True if entry exists, false otherwise
*/
function contains(bytes32 _entryKey) external view returns (bool);
Source code: /l1-contracts/src/core/interfaces/messagebridge/IInbox.sol#L88-L95 (aztec-packages-v0.24.0)
NameTypeDescription
_entryKeybytes32The entry key (message hash)
ReturnValueboolTrue if contained, false otherwise

computeEntryKey()

Computes the hash of a message.

inbox_compute_entry_key
/// @notice Given a message, computes an entry key for the Inbox
function computeEntryKey(DataStructures.L1ToL2Msg memory _message)
external
pure
returns (bytes32);
Source code: /l1-contracts/src/core/interfaces/messagebridge/IInbox.sol#L97-L103 (aztec-packages-v0.24.0)
NameTypeDescription
_messageL1ToL2MsgThe message to compute hash for
ReturnValuebytes32The hash of the message