test(fast-inbox): gas measurements for Inbox.sendL2Message and timestamp-key note (A-1377)

Author: spalladino

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

@@ -179,6 +179,10 @@ contract Inbox is IInbox {
     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. Post-merge
+    // Ethereum increases block.timestamp strictly per block, so one bucket corresponds to one L1 block. 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 equivalent to it.
     if (bucketSeq == 0 || bucket.timestamp < block.timestamp || bucket.msgCount == MAX_MSGS_PER_BUCKET) {
       bucketSeq += 1;
       currentBucketSeq = bucketSeq;

l1-contracts/test/InboxBuckets.t.sol

@@ -41,6 +41,19 @@ contract InboxBucketsTest is Test {
     return leaf;
   }
 
+  // Sends a message and returns the gas consumed by the external `sendL2Message` call alone. The
+  // recipient/content/secretHash are built before the measurement window so only the call is timed.
+  function _measureSend(InboxHarness _inbox, uint256 _salt) internal returns (uint256 gasUsed) {
+    DataStructures.L2Actor memory recipient =
+      DataStructures.L2Actor({actor: bytes32(uint256(0x1000 + _salt)), version: version});
+    bytes32 content = bytes32(uint256(0x2000 + _salt));
+    bytes32 secretHash = bytes32(uint256(0x3000 + _salt));
+
+    uint256 gasBefore = gasleft();
+    _inbox.sendL2Message(recipient, content, secretHash);
+    gasUsed = gasBefore - gasleft();
+  }
+
   // Shared test vectors for the rolling-hash chain, pinned across the noir circuits, the TS mirror,
   // and this L1 implementation. Generated from an independent sha256 implementation.
   function testRollingHashTestVectors() public pure {
@@ -213,4 +226,57 @@ contract InboxBucketsTest is Test {
     vm.expectRevert(abi.encodeWithSelector(Errors.Inbox__BucketOutOfWindow.selector, current + 1, current));
     smallRingInbox.getBucket(current + 1);
   }
+
+  // Gas cost of a message absorbed into an already-open bucket (the common per-message case): the
+  // second message of an L1 block updates the live bucket in place without opening a new ring slot.
+  function testGasSendIntoExistingBucket() public {
+    _send(inbox, 0);
+    assertEq(inbox.getCurrentBucketSeq(), 1, "warmup opened bucket 1");
+
+    uint256 gasUsed = _measureSend(inbox, 1);
+    emit log_named_uint("gas: absorb into existing bucket", gasUsed);
+
+    assertEq(inbox.getCurrentBucketSeq(), 1, "absorbed without opening a new bucket");
+  }
+
+  // Gas cost of the first message of a new L1 block: a larger timestamp opens the next bucket,
+  // writing a fresh ring slot on top of the per-message frontier-tree insert.
+  function testGasSendFirstMessageOfNewBlock() public {
+    _send(inbox, 0);
+    assertEq(inbox.getCurrentBucketSeq(), 1, "warmup opened bucket 1");
+
+    vm.roll(block.number + 1);
+    vm.warp(block.timestamp + 12);
+
+    uint256 gasUsed = _measureSend(inbox, 1);
+    emit log_named_uint("gas: first message of a new L1 block", gasUsed);
+
+    assertEq(inbox.getCurrentBucketSeq(), 2, "new block opened bucket 2");
+  }
+
+  // Gas cost of a rollover opening mid-block: once a bucket reaches MAX_MSGS_PER_BUCKET, the next
+  // message in the same L1 block opens a new bucket even though the timestamp is unchanged.
+  function testGasSendRolloverMidBlock() public {
+    uint256 cap = inbox.MAX_MSGS_PER_BUCKET();
+    for (uint256 i = 0; i < cap; i++) {
+      _send(inbox, i);
+    }
+    assertEq(inbox.getCurrentBucketSeq(), 1, "cap messages fit in bucket 1");
+
+    uint256 gasUsed = _measureSend(inbox, cap);
+    emit log_named_uint("gas: rollover open mid-block", gasUsed);
+
+    assertEq(inbox.getCurrentBucketSeq(), 2, "rollover opened bucket 2");
+  }
+
+  // Gas cost of the first-ever message against a freshly deployed Inbox: every touched slot is cold,
+  // including the state struct and bucket 1, so this is the worst-case single insert.
+  function testGasSendFirstEverMessage() public {
+    assertEq(inbox.getCurrentBucketSeq(), 0, "no message sent yet");
+
+    uint256 gasUsed = _measureSend(inbox, 0);
+    emit log_named_uint("gas: first-ever message", gasUsed);
+
+    assertEq(inbox.getCurrentBucketSeq(), 1, "first message opened bucket 1");
+  }
 }