Aggregate out hashes and set on L1 per epoch.

Author: LeilaWang

docs/docs/developers/docs/aztec-nr/framework-description/ethereum-aztec-messaging/outbox.md

@@ -10,20 +10,20 @@ The `Outbox` is a contract deployed on L1 that handles message passing from the
 
 ## `insert()`
 
-Inserts the root of a merkle tree containing all of the L2 to L1 messages in a checkpoint specified by checkpointNumber.
+Inserts the root of a merkle tree containing all of the L2 to L1 messages in an epoch specified by `epochNumber`.
 
 #include_code outbox_insert l1-contracts/src/core/interfaces/messagebridge/IOutbox.sol solidity
 
-| Name                | Type      | Description                                                            |
-| ------------------- | --------- | ---------------------------------------------------------------------- |
-| `_checkpointNumber` | `uint256` | The checkpoint Number in which the L2 to L1 messages reside            |
-| `_root`             | `bytes32` | The merkle root of the tree where all the L2 to L1 messages are leaves |
-| `_minHeight`        | `uint256` | The minimum height of the merkle tree that the root corresponds to     |
+| Name           | Type      | Description                                                            |
+| -------------- | --------- | ---------------------------------------------------------------------- |
+| `_epochNumber` | `uint256` | The epoch Number in which the L2 to L1 messages reside                 |
+| `_root`        | `bytes32` | The merkle root of the tree where all the L2 to L1 messages are leaves |
+| `_minHeight`   | `uint256` | The minimum height of the merkle tree that the root corresponds to     |
 
 #### Edge cases
 
 - Will revert with `Outbox__Unauthorized()` if `msg.sender != ROLLUP_CONTRACT`.
-- Will revert with `Errors.Outbox__RootAlreadySetAtCheckpoint(uint256 checkpointNumber)` if the root for the specific checkpoint has already been set.
+- Will revert with `Errors.Outbox__RootAlreadySetAtEpoch(uint256 epochNumber)` if the root for the specific epoch has already been set.
 - Will revert with `Errors.Outbox__InsertingInvalidRoot()` if the rollup is trying to insert bytes32(0) as the root.
 
 ## `consume()`
@@ -32,32 +32,34 @@ Allows a recipient to consume a message from the `Outbox`.
 
 #include_code outbox_consume l1-contracts/src/core/interfaces/messagebridge/IOutbox.sol solidity
 
-| Name                | Type        | Description                                                                                  |
-| ------------------- | ----------- | -------------------------------------------------------------------------------------------- |
-| `_message`          | `L2ToL1Msg` | The L2 to L1 message we want to consume                                                      |
-| `_checkpointNumber` | `uint256`   | The checkpoint number specifying the checkpoint that contains the message we want to consume |
-| `_leafIndex`        | `uint256`   | The index inside the merkle tree where the message is located                                |
-| `_path`             | `bytes32[]` | The sibling path used to prove inclusion of the message, the \_path length directly depends  |
+| Name           | Type        | Description                                                                                 |
+| -------------- | ----------- | ------------------------------------------------------------------------------------------- |
+| `_message`     | `L2ToL1Msg` | The L2 to L1 message we want to consume                                                     |
+| `_epochNumber` | `uint256`   | The epoch number specifying the epoch that contains the message we want to consume          |
+| `_leafIndex`   | `uint256`   | The index inside the merkle tree where the message is located                               |
+| `_path`        | `bytes32[]` | The sibling path used to prove inclusion of the message, the \_path length directly depends |
+
+For detailed information about the epoch message tree structure and leaf ID computation, see the [stdlib helpers](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/stdlib/src/messaging/l2_to_l1_membership.ts).
 
 #### Edge cases
 
 - Will revert with `Outbox__InvalidRecipient(address expected, address actual);` if `msg.sender != _message.recipient.actor`.
 - Will revert with `Outbox__InvalidChainId()` if `block.chainid != _message.recipient.chainId`.
-- Will revert with `Outbox__NothingToConsumeAtCheckpoint(uint256 checkpointNumber)` if the root for the checkpoint has not been set yet.
-- Will revert with `Outbox__AlreadyNullified(uint256 checkpointNumber, uint256 leafIndex)` if the message at leafIndex for the checkpoint has already been consumed.
+- Will revert with `Outbox__NothingToConsumeAtEpoch(uint256 epochNumber)` if the root for the epoch has not been set yet.
+- Will revert with `Outbox__AlreadyNullified(uint256 epochNumber, uint256 leafIndex)` if the message at leafIndex for the epoch has already been consumed.
 - Will revert with `Outbox__InvalidPathLength(uint256 expected, uint256 actual)` if the supplied height is less than the existing minimum height of the L2 to L1 message tree, or the supplied height is greater than the maximum (minimum height + log2(maximum messages)).
 - Will revert with `MerkleLib__InvalidRoot(bytes32 expected, bytes32 actual, bytes32 leaf, uint256 leafIndex)` if unable to verify the message existence in the tree. It returns the message as a leaf, as well as the index of the leaf to expose more info about the error.
 
-## `hasMessageBeenConsumedAtCheckpointAndIndex()`
+## `hasMessageBeenConsumedAtEpochAndIndex()`
 
-Checks to see if an index of the L2 to L1 message tree for a specific checkpoint has been consumed.
+Checks to see if an index of the L2 to L1 message tree for a specific epoch has been consumed.
 
-#include_code outbox_has_message_been_consumed_at_checkpoint_and_index l1-contracts/src/core/interfaces/messagebridge/IOutbox.sol solidity
+#include_code outbox_has_message_been_consumed_at_epoch_and_index l1-contracts/src/core/interfaces/messagebridge/IOutbox.sol solidity
 
-| Name                | Type      | Description                                                                                             |
-| ------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
-| `_checkpointNumber` | `uint256` | The checkpoint number specifying the checkpoint that contains the index of the message we want to check |
-| `_leafIndex`        | `uint256` | The index of the message inside the merkle tree                                                         |
+| Name           | Type      | Description                                                                                   |
+| -------------- | --------- | --------------------------------------------------------------------------------------------- |
+| `_epochNumber` | `uint256` | The epoch number specifying the epoch that contains the index of the message we want to check |
+| `_leafIndex`   | `uint256` | The index of the message inside the merkle tree                                               |
 
 #### Edge cases
 

docs/docs/developers/docs/resources/migration_notes.md

@@ -199,6 +199,35 @@ Additionally, any function or struct that previously referenced an L2 block numb
 
 Note: current node softwares still produce exactly one L2 block per checkpoint, so for now checkpoint numbers and L2 block numbers remain equal. This may change once multi-block checkpoints are enabled.
 
+### [L1 Contracts] L2-to-L1 messages are now grouped by epoch.
+
+L2-to-L1 messages are now aggregated and organized per epoch rather than per block. This change affects how you compute membership witnesses for consuming messages on L1. You now need to know the epoch number in which the message was emitted to retrieve and consume the message.
+
+**Note**: This is only an API change. The protocol behavior remains the same - messages can still only be consumed once an epoch is proven as before.
+
+#### What changed
+
+Previously, you might have computed the membership witness without explicitly needing the epoch:
+
+```typescript
+const witness = await computeL2ToL1MembershipWitness(
+  node,
+  l2TxReceipt.blockNumber,
+  l2ToL1Message
+);
+```
+
+Now, you should provide the epoch number:
+
+```typescript
+const epoch = await rollup.getEpochNumberForCheckpoint(l2TxReceipt.blockNumber);
+const witness = await computeL2ToL1MembershipWitness(
+  node,
+  epoch,
+  l2ToL1Message
+);
+```
+
 ### [Aztec.js] Wallet interface changes
 
 #### `simulateTx` is now batchable

l1-contracts/src/core/interfaces/IRollup.sol

@@ -26,6 +26,7 @@ import {IERC20} from "@oz/token/ERC20/IERC20.sol";
 struct PublicInputArgs {
   bytes32 previousArchive;
   bytes32 endArchive;
+  bytes32 outHash;
   address proverId;
 }
 

l1-contracts/src/core/interfaces/messagebridge/IOutbox.sol

@@ -3,6 +3,7 @@
 pragma solidity >=0.8.27;
 
 import {DataStructures} from "../../libraries/DataStructures.sol";
+import {Epoch} from "../../libraries/TimeLib.sol";
 
 /**
  * @title IOutbox
@@ -11,21 +12,18 @@ import {DataStructures} from "../../libraries/DataStructures.sol";
  * and will be consumed by the portal contracts.
  */
 interface IOutbox {
-  event RootAdded(uint256 indexed checkpointNumber, bytes32 indexed root);
-  event MessageConsumed(
-    uint256 indexed checkpointNumber, bytes32 indexed root, bytes32 indexed messageHash, uint256 leafId
-  );
+  event RootAdded(Epoch indexed epoch, bytes32 indexed root);
+  event MessageConsumed(Epoch indexed epoch, bytes32 indexed root, bytes32 indexed messageHash, uint256 leafId);
 
   // docs:start:outbox_insert
   /**
-   * @notice Inserts the root of a merkle tree containing all of the L2 to L1 messages in
-   * a checkpoint specified by _checkpointNumber.
+   * @notice Inserts the root of a merkle tree containing all of the L2 to L1 messages in an epoch specified by _epoch.
    * @dev Only callable by the rollup contract
    * @dev Emits `RootAdded` upon inserting the root successfully
-   * @param _checkpointNumber - The checkpoint number in which the L2 to L1 messages reside
+   * @param _epoch - The epoch in which the L2 to L1 messages reside
    * @param _root - The merkle root of the tree where all the L2 to L1 messages are leaves
    */
-  function insert(uint256 _checkpointNumber, bytes32 _root) external;
+  function insert(Epoch _epoch, bytes32 _root) external;
   // docs:end:outbox_insert
 
   // docs:start:outbox_consume
@@ -34,39 +32,36 @@ interface IOutbox {
    * @dev Only useable by portals / recipients of messages
    * @dev Emits `MessageConsumed` when consuming messages
    * @param _message - The L2 to L1 message
-   * @param _checkpointNumber - The checkpoint number specifying the checkpoint that contains the message we want to
-   * consume
-   * @param _leafIndex - The index inside the merkle tree where the message is located
-   * @param _path - The sibling path used to prove inclusion of the message, the _path length directly depends
-   * on the total amount of L2 to L1 messages in the checkpoint. i.e. the length of _path is equal to the depth of the
-   * L1 to L2 message tree.
+   * @param _epoch - The epoch that contains the message we want to consume
+   * @param _leafIndex - The index at the level in the epoch message tree where the message is located
+   * @param _path - The sibling path used to prove inclusion of the message, the _path length depends
+   * on the location of the L2 to L1 message in the epoch message tree.
    */
   function consume(
     DataStructures.L2ToL1Msg calldata _message,
-    uint256 _checkpointNumber,
+    Epoch _epoch,
     uint256 _leafIndex,
     bytes32[] calldata _path
   ) external;
   // docs:end:outbox_consume
 
-  // docs:start:outbox_has_message_been_consumed_at_checkpoint_and_index
+  // docs:start:outbox_has_message_been_consumed_at_epoch_and_index
   /**
-   * @notice Checks to see if an L2 to L1 message in a specific checkpoint has been consumed
+   * @notice Checks to see if an L2 to L1 message in a specific epoch has been consumed
    * @dev - This function does not throw. Out-of-bounds access is considered valid, but will always return false
-   * @param _checkpointNumber - The checkpoint number specifying the checkpoint that contains the message we want to
-   * check
+   * @param _epoch - The epoch that contains the message we want to check
    * @param _leafId - The unique id of the message leaf
    */
-  function hasMessageBeenConsumedAtCheckpoint(uint256 _checkpointNumber, uint256 _leafId) external view returns (bool);
-  // docs:end:outbox_has_message_been_consumed_at_checkpoint_and_index
+  function hasMessageBeenConsumedAtEpoch(Epoch _epoch, uint256 _leafId) external view returns (bool);
+  // docs:end:outbox_has_message_been_consumed_at_epoch_and_index
 
   /**
-   * @notice  Fetch the root data for a given checkpoint number
-   *          Returns (0, 0) if the checkpoint is not proven
+   * @notice  Fetch the root data for a given epoch
+   *          Returns (0, 0) if the epoch is not proven
    *
-   * @param _checkpointNumber - The checkpoint number to fetch the root data for
+   * @param _epoch - The epoch to fetch the root data for
    *
    * @return bytes32 - The root of the merkle tree containing the L2 to L1 messages
    */
-  function getRootData(uint256 _checkpointNumber) external view returns (bytes32);
+  function getRootData(Epoch _epoch) external view returns (bytes32);
 }

l1-contracts/src/core/libraries/ConstantsGen.sol

@@ -23,7 +23,7 @@ library Constants {
     14_269_942_583_723_164_841_365_114_274_712_143_548_835_546_030_057_296_325_580_016_468_921_911_294_613;
   uint256 internal constant FEE_JUICE_ADDRESS = 5;
   uint256 internal constant BLS12_POINT_COMPRESSED_BYTES = 48;
-  uint256 internal constant ROOT_ROLLUP_PUBLIC_INPUTS_LENGTH = 158;
+  uint256 internal constant ROOT_ROLLUP_PUBLIC_INPUTS_LENGTH = 159;
   uint256 internal constant NUM_MSGS_PER_BASE_PARITY = 256;
   uint256 internal constant NUM_BASE_PARITY_PER_ROOT_PARITY = 4;
 }

l1-contracts/src/core/libraries/Errors.sol

@@ -43,12 +43,9 @@ library Errors {
     uint32 storedDeadline,
     uint32 deadlinePassed
   ); // 0x5e789f34
-  error Outbox__RootAlreadySetAtCheckpoint(uint256 checkpointNumber); // 0x6eb83cef
   error Outbox__InvalidRecipient(address expected, address actual); // 0x57aad581
-  error Outbox__AlreadyNullified(uint256 checkpointNumber, uint256 leafIndex); // 0xfd71c2d4
-  error Outbox__NothingToConsumeAtCheckpoint(uint256 checkpointNumber); // 0x0279277d
-  error Outbox__CheckpointNotProven(uint256 checkpointNumber); // 0x104bcfc1
-  error Outbox__CheckpointAlreadyProven(uint256 checkpointNumber);
+  error Outbox__AlreadyNullified(Epoch epoch, uint256 leafIndex); // 0xfd71c2d4
+  error Outbox__NothingToConsumeAtEpoch(Epoch epoch); // 0x5e3d32ce
   error Outbox__PathTooLong();
   error Outbox__LeafIndexOutOfBounds(uint256 leafIndex, uint256 pathLength);
 

l1-contracts/src/core/libraries/rollup/EpochProofLib.sol

@@ -15,7 +15,6 @@ import {STFLib} from "@aztec/core/libraries/rollup/STFLib.sol";
 import {ValidatorSelectionLib} from "@aztec/core/libraries/rollup/ValidatorSelectionLib.sol";
 import {Timestamp, Slot, Epoch, TimeLib} from "@aztec/core/libraries/TimeLib.sol";
 import {CompressedSlot, CompressedTimeMath} from "@aztec/shared/libraries/CompressedTimeMath.sol";
-import {Math} from "@oz/utils/math/Math.sol";
 import {SafeCast} from "@oz/utils/math/SafeCast.sol";
 
 /**
@@ -116,7 +115,20 @@ library EpochProofLib {
     require(verifyEpochRootProof(_args), Errors.Rollup__InvalidProof());
 
     RollupStore storage rollupStore = STFLib.getStorage();
-    rollupStore.tips = rollupStore.tips.updateProven(Math.max(rollupStore.tips.getProven(), _args.end));
+
+    // Advance the proven block number and insert the out hash if the chain is extended.
+    if (_args.end > rollupStore.tips.getProven()) {
+      rollupStore.tips = rollupStore.tips.updateProven(_args.end);
+
+      // Handle L2->L1 message processing.
+      // The circuit outputs a zero out hash if the epoch contains no messages. It is also impossible for a partial
+      // epoch to produce a non-zero out hash, then later produce a zero out hash once more checkpoints are included.
+      // Therefore, we can safely skip the insertion for a zero out hash here.
+      if (_args.args.outHash != bytes32(0)) {
+        // Insert L2->L1 messages root into outbox for consumption.
+        rollupStore.config.outbox.insert(endEpoch, _args.args.outHash);
+      }
+    }
 
     RewardLib.handleRewardsAndFees(_args, endEpoch);
 
@@ -170,30 +182,33 @@ library EpochProofLib {
     // struct RootRollupPublicInputs {
     //   previous_archive_root: Field,
     //   end_archive_root: Field,
+    //   out_hash: Field,
     //   checkpointHeaderHashes: [Field; Constants.AZTEC_MAX_EPOCH_DURATION],
     //   fees: [FeeRecipient; Constants.AZTEC_MAX_EPOCH_DURATION],
     //   chain_id: Field,
     //   version: Field,
     //   vk_tree_root: Field,
     //   protocol_contracts_hash: Field,
     //   prover_id: Field,
-    //   blob_public_inputs: FinalBlobAccumulatorPublicInputs,
+    //   blob_public_inputs: FinalBlobAccumulator,
     // }
     {
       // previous_archive.root: the previous archive tree root
       publicInputs[0] = _args.previousArchive;
 
       // end_archive.root: the new archive tree root
       publicInputs[1] = _args.endArchive;
+
+      publicInputs[2] = _args.outHash;
     }
 
     uint256 numCheckpoints = _end - _start + 1;
 
     for (uint256 i = 0; i < numCheckpoints; i++) {
-      publicInputs[2 + i] = STFLib.getHeaderHash(_start + i);
+      publicInputs[3 + i] = STFLib.getHeaderHash(_start + i);
     }
 
-    uint256 offset = 2 + Constants.AZTEC_MAX_EPOCH_DURATION;
+    uint256 offset = 3 + Constants.AZTEC_MAX_EPOCH_DURATION;
 
     uint256 feesLength = Constants.AZTEC_MAX_EPOCH_DURATION * 2;
     // fees[2n to 2n + 1]: a fee element, which contains of a recipient and a value
@@ -248,7 +263,6 @@ library EpochProofLib {
     publicInputs[offset] = bytes32(uint256(uint248(bytes31((_blobPublicInputs[96:127])))));
     // c[1]
     publicInputs[offset + 1] = bytes32(uint256(uint136(bytes17((_blobPublicInputs[127:144])))));
-    offset += 2;
 
     return publicInputs;
   }