feat(fast-inbox): rolling-hash buckets in the Inbox alongside frontier trees (A-1377)

AZIP-22 Fast Inbox, FI-07. First L1 PR of the series; a follow-up stacks the `propose`-side streaming validation on top of this branch.

Stacked on #24781 (`spl/a-1432-same-block-msgs`), the tip of the Fast Inbox circuits stack (#24587 → #24600 → #24603 → #24612 → #24759 → #24781). That stack already carries the small L1 changes this feature builds on — the header's `inboxRollingHash` field, the two epoch-proof public inputs, and the regenerated checkpoint fixtures — so this PR adds only the bucket machinery on top.

## What

`sendL2Message` additionally maintains the **consensus rolling hash** — the truncated-per-link sha256 chain the circuits recompute (`h' = sha256ToField(h || leaf)`, genesis zero; new `Hash.accumulateInboxRollingHash`) — and snapshots it into a fixed-size ring of **buckets**. Frontier trees, `LAG`, the legacy `consume()` flow, and the legacy `bytes16` keccak rolling hash are untouched (the legacy hash now carries a TODO to remove it at cleanup); buckets are completely inert for the legacy flow.

Per the pinned design decisions:

- **Bucket struct** `{rollingHash | totalMsgCount: uint64, timestamp: uint64, msgCount: uint32}` packs into two slots; `totalMsgCount` is the Inbox-wide cumulative count (what the censorship cap-escape check reads), `timestamp` is the bucket's opening L1 block timestamp (recency checks are done in seconds), `msgCount` sits in slot 2's spare bits so the per-bucket cap costs no extra storage access.
- **Ring** indexed by dense bucket sequence number (`seq % BUCKET_RING_SIZE`), 1024 entries in production, sized as an immutable constructor parameter. `getBucket(seq)` reverts with `Inbox__BucketOutOfWindow` outside the live window (`seq <= current < seq + ringSize`, same idiom as the Rollup's roundabout). Overwrite protection for unconsumed buckets is deliberately **not** enforced yet (happy path assumes the ring never wraps into live data).
- **Bucket boundaries**: a bucket only holds messages from a single L1 block; the first message of a new block opens the next bucket, and the 257th message within one block (`MAX_MSGS_PER_BUCKET = 256`, the post-flip per-L2-block insertion cap) **rolls over** into the next bucket with the same timestamp. New buckets inherit the rolling hash and cumulative count, so the chain is continuous across buckets.
- **Genesis base case**: bucket 0 is `{0, 0, deployTime}` and never absorbs (even for a message sent in the deployment block), so a checkpoint consuming nothing against an empty Inbox can always reference a bucket matching its parent's chain position — no special case at `propose`.
- **Event**: `MessageSent` gains `bytes32 inboxRollingHash` and `uint256 bucketSeq` after the legacy args.

## Archiver / TS

The generated `InboxAbi` picks up the new event signature at build time; `MessageSentArgs` and the decode in `ethereum/src/contracts/inbox.ts` carry the two new fields, and the archiver keeps relying only on the legacy args for now (`InboxMessage` unchanged). The archiver test fake fills the new fields with placeholders. Nothing on this branch consumes the new values yet — the node-side cross-check of its TS rolling hash against L1-emitted values comes with the archiver bucket-sync work.

## Testing

- New `InboxBuckets.t.sol` covers the roadmap done-when: accumulation within a block, snapshot freezing at block boundaries with chain continuity into the next bucket, 256-cap rollover within one block, ring wraparound + out-of-window reverts on a small ring, the genesis bucket (including a first message in the deploy block), and event contents.
- **Shared rolling-hash test vectors** pinned in #24587's noir tests (`chain(0,[11])`, `chain(0,[11,22,33])`, `chain(0,[1..=256])`, `chain(0x2a,[7])`, `chain(0x2a,[7,8])`) are asserted against the L1 implementation, so L1, TS, and the circuits provably compute the same chain.
- `forge test` at the current stack top: 890 passed, 0 failed, 3 skipped (the `testGetEpochProofPublicInputsVerifiesHeaders` failure previously inherited from the base has been fixed by the rebased base branches). The 13 `InboxBuckets.t.sol` tests all pass (9 behavioral + 4 gas measurements). Existing `MessageSent` expectations in Inbox/TokenPortal/FeeJuicePortal tests updated for the extended event.
- TS: the regenerated `@aztec/l1-artifacts` `InboxAbi` picks up the two new event fields, and `@aztec/ethereum` typechecks clean against it. `@aztec/archiver`'s full typecheck is blocked only by stale Noir-generated artifacts in a transitive dependency (base-branch circuit changes that require the Noir toolchain, not run in this workspace), so it runs in CI; the archiver change is decode-only and mechanical.

## Gas (`sendL2Message`)

Four Forge gas measurements in `InboxBuckets.t.sol` cover the bucket write paths (inline `gasleft()` deltas, matching the `RollupGetters.t.sol` convention). These feed the capacity analysis (max messages per L1 block from gas):

| Scenario | Gas |
|---|---|
| Absorb into an already-open bucket (common per-message case) | 34,468 |
| First message of a new L1 block (opens a bucket via timestamp) | 78,958 |
| Rollover opening mid-block (256-cap reached, same timestamp) | 55,593 |
| First-ever message (cold state struct + bucket 1) | 128,118 |

Caveat for downstream use: these are **warm execution gas including the CALL overhead** from the test harness. They exclude the 21k intrinsic tx cost, calldata gas, and the cold-access surcharge a standalone EOA transaction pays on its first touch of each slot — the capacity analysis must add those separately. The first-ever figure is the cold-storage case for the bucket/state slots, **not** the global worst-case insert: later frontier-tree leaf indices with more levels to hash can cost more.

Also documents the timestamp-key assumption in `_absorbIntoBucket` (post-merge Ethereum increases `block.timestamp` strictly per block; anvil manual-mining can collapse two blocks into one bucket, which is harmless because the consumption cutoff is timestamp-based).


## Ring-size floor

Raises the constructor guard from `_bucketRingSize > 1` to a floor of **512** (`MIN_BUCKET_RING_SIZE`); production stays at 1024. Rationale: the ring must cover the longest stall the chain recovers from on its own — the prune-and-repropose window of 64 checkpoints (2 epochs = 384 L1 blocks) at the natural one-bucket-per-L1-block cadence, so buckets it re-consumes after a prune are not overwritten first — 384 rounded up to the next power of two, kept at or below the production ring. `testRingWraparound` now exercises a real wraparound against a 512-slot ring, and a new `testConstructorRevertsBelowRingFloor` asserts that constructing below the floor reverts. The full capacity/liveness analysis behind this number feeds the AZIP-22 review.



Replaces #24771.

Author: spalladino

docs/examples/ts/aave_bridge/index.ts

@@ -351,6 +351,8 @@ const INBOX_ABI = [
       { name: "index", type: "uint256", indexed: false },
       { name: "hash", type: "bytes32", indexed: true },
       { name: "rollingHash", type: "bytes16", indexed: false },
+      { name: "inboxRollingHash", type: "bytes32", indexed: false },
+      { name: "bucketSeq", type: "uint256", indexed: false },
     ],
   },
 ] as const;

docs/examples/ts/example_swap/index.ts

@@ -263,6 +263,8 @@ const INBOX_ABI = [
       { name: "index", type: "uint256", indexed: false },
       { name: "hash", type: "bytes32", indexed: true },
       { name: "rollingHash", type: "bytes16", indexed: false },
+      { name: "inboxRollingHash", type: "bytes32", indexed: false },
+      { name: "bucketSeq", type: "uint256", indexed: false },
     ],
   },
 ] as const;

docs/examples/ts/token_bridge/index.ts

@@ -169,6 +169,8 @@ const INBOX_ABI = [
       { name: "index", type: "uint256", indexed: false },
       { name: "hash", type: "bytes32", indexed: true },
       { name: "rollingHash", type: "bytes16", indexed: false },
+      { name: "inboxRollingHash", type: "bytes32", indexed: false },
+      { name: "bucketSeq", type: "uint256", indexed: false },
     ],
   },
 ] as const;

l1-contracts/src/core/RollupCore.sol

@@ -27,7 +27,7 @@ import {ProposeArgs} from "@aztec/core/libraries/rollup/ProposeLib.sol";
 import {STFLib, GenesisState} from "@aztec/core/libraries/rollup/STFLib.sol";
 import {StakingLib} from "@aztec/core/libraries/rollup/StakingLib.sol";
 import {Timestamp, Slot, Epoch, TimeLib} from "@aztec/core/libraries/TimeLib.sol";
-import {Inbox} from "@aztec/core/messagebridge/Inbox.sol";
+import {Inbox, INBOX_BUCKET_RING_SIZE} from "@aztec/core/messagebridge/Inbox.sol";
 import {Outbox} from "@aztec/core/messagebridge/Outbox.sol";
 import {ISlasher} from "@aztec/core/slashing/Slasher.sol";
 import {GSE} from "@aztec/governance/GSE.sol";
@@ -621,7 +621,14 @@ contract RollupCore is EIP712("Aztec Rollup", "1"), Ownable, IStakingCore, IVali
 
     IInbox inbox = IInbox(
       address(
-        new Inbox(address(this), _feeAsset, _config.version, Constants.L1_TO_L2_MSG_SUBTREE_HEIGHT, _config.inboxLag)
+        new Inbox(
+          address(this),
+          _feeAsset,
+          _config.version,
+          Constants.L1_TO_L2_MSG_SUBTREE_HEIGHT,
+          _config.inboxLag,
+          INBOX_BUCKET_RING_SIZE
+        )
       )
     );
 

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

@@ -13,6 +13,8 @@ interface IInbox {
   struct InboxState {
     // Rolling hash of all messages inserted into the inbox.
     // Used by clients to check for consistency.
+    // TODO: remove once the streaming inbox (AZIP-22 Fast Inbox) flips on and clients rely on the
+    // consensus rolling hash tracked in the buckets instead.
     bytes16 rollingHash;
     // This value is not used much by the contract, but it is useful for synching the node faster
     // as it can more easily figure out if it can just skip looking for events for a time period.
@@ -21,14 +23,43 @@ interface IInbox {
     uint64 inProgress;
   }
 
+  /**
+   * @notice Snapshot of the consensus rolling hash over the messages inserted into the Inbox, stored in a
+   * fixed-size ring indexed by a dense bucket sequence number (`seq % ringSize`). A bucket only accumulates
+   * messages sent within a single L1 block, so its final state is the chain position as of the end of that
+   * block; the censorship check at `propose` compares the checkpoint header's rolling hash against these
+   * snapshots (AZIP-22 Fast Inbox).
+   */
+  struct InboxBucket {
+    // Rolling hash after the last message absorbed into this bucket. Each link is
+    // `sha256ToField(previousRollingHash || leaf)`; the genesis value is zero.
+    bytes32 rollingHash;
+    // Cumulative number of messages inserted into the Inbox up to and including this bucket.
+    uint64 totalMsgCount;
+    // L1 block timestamp at which this bucket was opened. Recency comparisons (message lag,
+    // censorship cutoff) are done in seconds against this value.
+    uint64 timestamp;
+    // Number of messages absorbed into this bucket, capped at the per-bucket maximum.
+    uint32 msgCount;
+  }
+
   /**
    * @notice Emitted when a message is sent
    * @param checkpointNumber - The checkpoint number in which the message is included
    * @param index - The index of the message in the L1 to L2 messages tree
    * @param hash - The hash of the message
    * @param rollingHash - The rolling hash of all messages inserted into the inbox
+   * @param inboxRollingHash - The consensus rolling hash (truncated sha256 chain) after this message
+   * @param bucketSeq - The sequence number of the bucket this message was absorbed into
    */
-  event MessageSent(uint256 indexed checkpointNumber, uint256 index, bytes32 indexed hash, bytes16 rollingHash);
+  event MessageSent(
+    uint256 indexed checkpointNumber,
+    uint256 index,
+    bytes32 indexed hash,
+    bytes16 rollingHash,
+    bytes32 inboxRollingHash,
+    uint256 bucketSeq
+  );
 
   // docs:start:send_l1_to_l2_message
   /**
@@ -68,4 +99,18 @@ interface IInbox {
   function getTotalMessagesInserted() external view returns (uint64);
 
   function getInProgress() external view returns (uint64);
+
+  /**
+   * @notice Returns the sequence number of the bucket currently accumulating messages
+   * @return The current bucket sequence number
+   */
+  function getCurrentBucketSeq() external view returns (uint64);
+
+  /**
+   * @notice Returns the bucket with the given sequence number
+   * @dev Reverts if the bucket is ahead of the current one or has already been overwritten in the ring
+   * @param _seq - The bucket sequence number
+   * @return The bucket
+   */
+  function getBucket(uint256 _seq) external view returns (InboxBucket memory);
 }

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

@@ -28,6 +28,7 @@ library Errors {
   error Inbox__ContentTooLarge(bytes32 content); // 0x47452014
   error Inbox__SecretHashTooLarge(bytes32 secretHash); // 0xecde7e2c
   error Inbox__MustBuildBeforeConsume(); // 0xc4901999
+  error Inbox__BucketOutOfWindow(uint256 seq, uint256 current); // 0xfee255b7
 
   // Outbox
   error Outbox__Unauthorized(); // 0x2c9490c2

l1-contracts/src/core/libraries/crypto/Hash.sol

@@ -49,4 +49,16 @@ library Hash {
   function sha256ToField(bytes memory _data) internal pure returns (bytes32) {
     return bytes32(bytes.concat(new bytes(1), bytes31(sha256(_data))));
   }
+
+  /**
+   * @notice Advances the Inbox consensus rolling hash by one message leaf
+   * @dev Truncated at every link so the value is always a field element; the rollup circuits recompute the
+   * identical chain over the message leaves they insert (AZIP-22 Fast Inbox). The genesis value is zero.
+   * @param _rollingHash - The current rolling hash
+   * @param _leaf - The message leaf to absorb
+   * @return The updated rolling hash
+   */
+  function accumulateInboxRollingHash(bytes32 _rollingHash, bytes32 _leaf) internal pure returns (bytes32) {
+    return sha256ToField(abi.encodePacked(_rollingHash, _leaf));
+  }
 }

l1-contracts/src/core/messagebridge/Inbox.sol

@@ -13,6 +13,17 @@ import {FeeJuicePortal} from "@aztec/core/messagebridge/FeeJuicePortal.sol";
 import {IERC20} from "@oz/token/ERC20/IERC20.sol";
 import {SafeCast} from "@oz/utils/math/SafeCast.sol";
 
+// Number of buckets in the rolling-hash ring. Sized far beyond normal consumption lag (the censorship
+// cutoff bounds it to roughly one build frame); outages longer than the ring are handled by overwrite
+// protection on unconsumed buckets, not by growing the ring.
+uint256 constant INBOX_BUCKET_RING_SIZE = 1024;
+
+// Constructor floor for the bucket ring. The ring must cover the longest stall the chain recovers from on
+// its own: the prune-and-repropose window of 64 checkpoints (2 epochs = 384 L1 blocks) at the natural cadence
+// of one bucket per L1 block, so the buckets it must re-consume after a prune have not been overwritten. 384
+// rounded up to the next power of two, kept at or below the production ring.
+uint256 constant MIN_BUCKET_RING_SIZE = 512;
+
 /**
  * @title Inbox
  * @author Aztec Labs
@@ -23,12 +34,19 @@ contract Inbox is IInbox {
   using FrontierLib for FrontierLib.Forest;
   using FrontierLib for FrontierLib.Tree;
 
+  // Maximum number of messages a single bucket can hold before further messages in the same L1 block
+  // spill over into the next bucket. Matches the number of L1 to L2 messages a single L2 block can
+  // insert once the streaming inbox is live, so any one bucket is always consumable by one block.
+  uint256 public constant MAX_MSGS_PER_BUCKET = 256;
+
   address public immutable ROLLUP;
   uint256 public immutable VERSION;
   address public immutable FEE_ASSET_PORTAL;
 
   uint256 public immutable LAG;
 
+  uint256 public immutable BUCKET_RING_SIZE;
+
   uint256 internal immutable HEIGHT;
   uint256 internal immutable SIZE;
   bytes32 internal immutable EMPTY_ROOT; // The root of an empty frontier tree
@@ -40,7 +58,20 @@ contract Inbox is IInbox {
 
   InboxState internal state;
 
-  constructor(address _rollup, IERC20 _feeAsset, uint256 _version, uint256 _height, uint256 _lag) {
+  // Ring of rolling-hash buckets, keyed by `bucketSeq % BUCKET_RING_SIZE`. Inert for the legacy
+  // frontier-tree flow; consumed by the streaming inbox checks at `propose` (AZIP-22 Fast Inbox).
+  mapping(uint256 ringIndex => InboxBucket bucket) internal buckets;
+
+  uint64 internal currentBucketSeq;
+
+  constructor(
+    address _rollup,
+    IERC20 _feeAsset,
+    uint256 _version,
+    uint256 _height,
+    uint256 _lag,
+    uint256 _bucketRingSize
+  ) {
     ROLLUP = _rollup;
     VERSION = _version;
 
@@ -50,10 +81,18 @@ contract Inbox is IInbox {
     require(_lag > 0, "LAG TOO SMALL");
     LAG = _lag;
 
+    require(_bucketRingSize >= MIN_BUCKET_RING_SIZE, "BUCKET RING TOO SMALL");
+    BUCKET_RING_SIZE = _bucketRingSize;
+
     state = InboxState({
       rollingHash: 0, totalMessagesInserted: 0, inProgress: SafeCast.toUint64(Constants.INITIAL_CHECKPOINT_NUMBER + LAG)
     });
 
+    // Genesis bucket: a checkpoint consuming no messages references the same bucket as its parent, so the
+    // first checkpoint against an empty Inbox references this one and no base case leaks into `propose`.
+    buckets[0] =
+      InboxBucket({rollingHash: 0, totalMsgCount: 0, timestamp: SafeCast.toUint64(block.timestamp), msgCount: 0});
+
     forest.initialize(_height);
     EMPTY_ROOT = trees[type(uint256).max].root(forest, HEIGHT, SIZE);
 
@@ -122,7 +161,9 @@ contract Inbox is IInbox {
       rollingHash: updatedRollingHash, totalMessagesInserted: totalMessagesInserted + 1, inProgress: inProgress
     });
 
-    emit MessageSent(inProgress, index, leaf, updatedRollingHash);
+    (uint64 bucketSeq, bytes32 inboxRollingHash) = _absorbIntoBucket(leaf);
+
+    emit MessageSent(inProgress, index, leaf, updatedRollingHash, inboxRollingHash, bucketSeq);
 
     return (leaf, index);
   }
@@ -177,4 +218,55 @@ contract Inbox is IInbox {
   function getInProgress() external view override(IInbox) returns (uint64) {
     return state.inProgress;
   }
+
+  function getCurrentBucketSeq() external view override(IInbox) returns (uint64) {
+    return currentBucketSeq;
+  }
+
+  function getBucket(uint256 _seq) external view override(IInbox) returns (InboxBucket memory) {
+    uint256 current = currentBucketSeq;
+    require(_seq <= current && current - _seq < BUCKET_RING_SIZE, Errors.Inbox__BucketOutOfWindow(_seq, current));
+    return buckets[_seq % BUCKET_RING_SIZE];
+  }
+
+  /**
+   * @notice Absorbs a message leaf into the consensus rolling hash and snapshots it into the bucket ring
+   *
+   * @dev A bucket only holds messages from a single L1 block, up to MAX_MSGS_PER_BUCKET; the first message
+   * of a new L1 block — or the message after a full bucket, spilling over within the same block — opens the
+   * next bucket, inheriting the rolling hash and cumulative count. Bucket 0 is the pristine genesis base
+   * case and never absorbs. Opening a bucket overwrites the ring entry from BUCKET_RING_SIZE buckets ago;
+   * protection against overwriting unconsumed buckets is not enforced yet.
+   *
+   * @param _leaf - The message leaf to absorb
+   *
+   * @return The sequence number of the bucket the leaf was absorbed into and the updated rolling hash
+   */
+  function _absorbIntoBucket(bytes32 _leaf) internal returns (uint64, bytes32) {
+    uint64 bucketSeq = currentBucketSeq;
+    InboxBucket memory bucket = buckets[bucketSeq % BUCKET_RING_SIZE];
+
+    // Buckets are keyed by L1 block timestamp: a strictly larger timestamp opens a new bucket (a full bucket
+    // also rolls over within the same block). Post-merge Ethereum increases block.timestamp strictly per block,
+    // so messages from different L1 blocks always land in different buckets. Under anvil with manual mining two
+    // blocks can share a timestamp and therefore a bucket; this is harmless because the consumption cutoff is
+    // computed over timestamps, so co-timestamped blocks are indistinguishable to it.
+    if (bucketSeq == 0 || bucket.timestamp < block.timestamp || bucket.msgCount == MAX_MSGS_PER_BUCKET) {
+      bucketSeq += 1;
+      currentBucketSeq = bucketSeq;
+      bucket = InboxBucket({
+        rollingHash: bucket.rollingHash,
+        totalMsgCount: bucket.totalMsgCount,
+        timestamp: SafeCast.toUint64(block.timestamp),
+        msgCount: 0
+      });
+    }
+
+    bucket.rollingHash = Hash.accumulateInboxRollingHash(bucket.rollingHash, _leaf);
+    bucket.totalMsgCount += 1;
+    bucket.msgCount += 1;
+    buckets[bucketSeq % BUCKET_RING_SIZE] = bucket;
+
+    return (bucketSeq, bucket.rollingHash);
+  }
 }

l1-contracts/test/Inbox.t.sol

@@ -30,7 +30,9 @@ contract InboxTest is Test {
   function setUp() public {
     address rollup = address(this);
     IERC20 feeAsset = new TestERC20("Fee Asset", "FA", address(this));
-    inbox = new InboxHarness(rollup, feeAsset, version, HEIGHT, TestConstants.AZTEC_INBOX_LAG);
+    inbox = new InboxHarness(
+      rollup, feeAsset, version, HEIGHT, TestConstants.AZTEC_INBOX_LAG, TestConstants.AZTEC_INBOX_BUCKET_RING_SIZE
+    );
     emptyTreeRoot = inbox.getEmptyRoot();
   }
 
@@ -96,9 +98,12 @@ contract InboxTest is Test {
 
     bytes32 leaf = message.sha256ToField();
     bytes16 expectedRollingHash = bytes16(keccak256(abi.encodePacked(stateBefore.rollingHash, leaf)));
+    bytes32 expectedInboxRollingHash = Hash.accumulateInboxRollingHash(bytes32(0), leaf);
     vm.expectEmit(true, true, true, true);
     // event we expect
-    emit IInbox.MessageSent(FIRST_REAL_TREE_NUM, globalLeafIndex, leaf, expectedRollingHash);
+    emit IInbox.MessageSent(
+      FIRST_REAL_TREE_NUM, globalLeafIndex, leaf, expectedRollingHash, expectedInboxRollingHash, 1
+    );
     // event we will get
     (bytes32 insertedLeaf, uint256 insertedIndex) =
       inbox.sendL2Message(message.recipient, message.content, message.secretHash);