perf(fast-inbox): pack the inbox consumption counts into the slot-number slot (A-1384)

inboxMsgTotal and inboxConsumedBucket occupied a storage slot of their own in
CompressedTempCheckpointLog, costing an extra zero-to-nonzero SSTORE on every
propose and a cold SLOAD when reading the parent checkpoint's total. Declare
them next to CompressedSlot slotNumber so all three share one slot (20 of 32
bytes), which propose already touches for the slot-progression check; the
checkpoint record drops from nine slots to eight. Both counts keep their full
uint64 width, and feeHeader stays at its previous slot offset.

The pipelined-simulation state override writes that slot as a whole word, so it
now packs the two counts alongside the slot number instead of silently zeroing
them, and accepts them as override inputs.

Author: spalladino

l1-contracts/src/core/libraries/compressed-data/CheckpointLog.sol

@@ -34,14 +34,16 @@ struct TempCheckpointLog {
   bytes32 attestationsHash;
   bytes32 payloadDigest;
   Slot slotNumber;
-  FeeHeader feeHeader;
-  // Streaming Inbox consumption record (AZIP-22 Fast Inbox). `inboxRollingHash` is the consensus rolling hash the
-  // checkpoint header committed to; `inboxMsgTotal` is the cumulative Inbox message count consumed as of this
-  // checkpoint (the child's parent-total origin); `inboxConsumedBucket` is the bucket sequence number the header's
-  // rolling hash corresponds to. The two counts pack into a single storage slot.
-  bytes32 inboxRollingHash;
+  // Streaming Inbox consumption counts (AZIP-22 Fast Inbox). `inboxMsgTotal` is the cumulative Inbox message count
+  // consumed as of this checkpoint (the child's parent-total origin); `inboxConsumedBucket` is the bucket sequence
+  // number the header's rolling hash corresponds to. Declared next to the slot number so the three share one storage
+  // slot (4 + 8 + 8 of 32 bytes): propose writes and reads that slot for the slot-progression check anyway.
   uint64 inboxMsgTotal;
   uint64 inboxConsumedBucket;
+  FeeHeader feeHeader;
+  // The consensus Inbox rolling hash the checkpoint header committed to, in a slot of its own: epoch proofs anchor
+  // both ends of their consumed chain segment against it.
+  bytes32 inboxRollingHash;
 }
 
 struct CompressedTempCheckpointLog {
@@ -51,10 +53,10 @@ struct CompressedTempCheckpointLog {
   bytes32 attestationsHash;
   bytes32 payloadDigest;
   CompressedSlot slotNumber;
-  CompressedFeeHeader feeHeader;
-  bytes32 inboxRollingHash;
   uint64 inboxMsgTotal;
   uint64 inboxConsumedBucket;
+  CompressedFeeHeader feeHeader;
+  bytes32 inboxRollingHash;
 }
 
 library CompressedTempCheckpointLogLib {
@@ -71,10 +73,10 @@ library CompressedTempCheckpointLogLib {
       attestationsHash: _checkpoint.attestationsHash,
       payloadDigest: _checkpoint.payloadDigest,
       slotNumber: _checkpoint.slotNumber.compress(),
-      feeHeader: _checkpoint.feeHeader.compress(),
-      inboxRollingHash: _checkpoint.inboxRollingHash,
       inboxMsgTotal: _checkpoint.inboxMsgTotal,
-      inboxConsumedBucket: _checkpoint.inboxConsumedBucket
+      inboxConsumedBucket: _checkpoint.inboxConsumedBucket,
+      feeHeader: _checkpoint.feeHeader.compress(),
+      inboxRollingHash: _checkpoint.inboxRollingHash
     });
   }
 
@@ -90,10 +92,10 @@ library CompressedTempCheckpointLogLib {
       attestationsHash: _compressedCheckpoint.attestationsHash,
       payloadDigest: _compressedCheckpoint.payloadDigest,
       slotNumber: _compressedCheckpoint.slotNumber.decompress(),
-      feeHeader: _compressedCheckpoint.feeHeader.decompress(),
-      inboxRollingHash: _compressedCheckpoint.inboxRollingHash,
       inboxMsgTotal: _compressedCheckpoint.inboxMsgTotal,
-      inboxConsumedBucket: _compressedCheckpoint.inboxConsumedBucket
+      inboxConsumedBucket: _compressedCheckpoint.inboxConsumedBucket,
+      feeHeader: _compressedCheckpoint.feeHeader.decompress(),
+      inboxRollingHash: _compressedCheckpoint.inboxRollingHash
     });
   }
 }

yarn-project/ethereum/src/contracts/chain_state_override.ts

@@ -21,6 +21,8 @@ export type PendingCheckpointOverrideState = {
   outHash?: Fr;
   payloadDigest?: Buffer32;
   slotNumber?: SlotNumber;
+  inboxMsgTotal?: bigint;
+  inboxConsumedBucket?: bigint;
 };
 
 export type ChainTipsOverride = {
@@ -93,11 +95,12 @@ export class SimulationOverridesBuilder {
 
   /**
    * Overrides one or more `tempCheckpointLogs` cell fields for the configured pending checkpoint.
-   * Fields are independent: any subset can be provided. The translator (`makeTempCheckpointLogOverride`)
-   * emits a stateDiff entry per field actually set, so unspecified fields stay at their on-chain
-   * values.
+   * Any subset can be provided. The translator (`makeTempCheckpointLogOverride`) emits a stateDiff
+   * entry per storage word touched, so fields in untouched words stay at their on-chain values;
+   * `slotNumber`, `inboxMsgTotal` and `inboxConsumedBucket` share a word, so setting any of them
+   * zeroes the others unless they are supplied too.
    *
-   * `slotNumber` is load-bearing for `STFLib.canPruneAtTime`: when the simulation overrides `pending`
+   * `slotNumber` is required for `STFLib.canPruneAtTime`: when the simulation overrides `pending`
    * to a checkpoint that has no on-chain `tempCheckpointLogs` entry yet, the missing slotNumber falls
    * back to 0 and the contract treats the pending tip as belonging to epoch 0, triggering a phantom
    * prune that silently undoes the `pending` override.
@@ -107,6 +110,8 @@ export class SimulationOverridesBuilder {
     outHash?: Fr;
     payloadDigest?: Buffer32;
     slotNumber?: SlotNumber;
+    inboxMsgTotal?: bigint;
+    inboxConsumedBucket?: bigint;
   }): this {
     this.assertPendingCheckpointNumber();
     this.pendingCheckpointState = { ...(this.pendingCheckpointState ?? {}), ...fields };
@@ -174,6 +179,8 @@ export async function buildSimulationOverridesStateOverride(
           outHash: plan.pendingCheckpointState.outHash,
           payloadDigest: plan.pendingCheckpointState.payloadDigest,
           slotNumber: plan.pendingCheckpointState.slotNumber,
+          inboxMsgTotal: plan.pendingCheckpointState.inboxMsgTotal,
+          inboxConsumedBucket: plan.pendingCheckpointState.inboxConsumedBucket,
           feeHeader: plan.pendingCheckpointState.feeHeader,
         }),
       ),

yarn-project/ethereum/src/contracts/rollup.test.ts

@@ -487,6 +487,26 @@ describe('Rollup', () => {
       );
     });
 
+    it('packs the inbox consumption counts into the slot-number word', async () => {
+      const checkpointNumber = CheckpointNumber(13);
+      const override = await rollup.makeTempCheckpointLogOverride(checkpointNumber, {
+        slotNumber: SlotNumber(7),
+        inboxMsgTotal: 300n,
+        inboxConsumedBucket: 5n,
+      });
+      const { map, slotFor } = getDiffMap(checkpointNumber, override);
+      expect(override[0].stateDiff).toHaveLength(1);
+      expect(map.get(await slotFor(TempCheckpointLogField.SlotNumber))).toBe(
+        `0x${(7n | (300n << 32n) | (5n << 96n)).toString(16).padStart(64, '0')}`.toLowerCase(),
+      );
+    });
+
+    it('throws when an inbox consumption count overflows uint64', async () => {
+      await expect(
+        rollup.makeTempCheckpointLogOverride(CheckpointNumber(3), { inboxMsgTotal: 1n << 64n }),
+      ).rejects.toThrow(/does not fit in uint64/);
+    });
+
     it('partial override returns an empty array when no fields are supplied', async () => {
       const override = await rollup.makeTempCheckpointLogOverride(CheckpointNumber(13), {});
       expect(override).toEqual([]);

yarn-project/ethereum/src/contracts/rollup.ts

@@ -139,7 +139,10 @@ export type L1FeeData = {
   blobFee: bigint;
 };
 
-/** Field offsets within the CompressedTempCheckpointLog struct in Solidity storage. */
+/**
+ * Field offsets within the CompressedTempCheckpointLog struct in Solidity storage. The `SlotNumber`
+ * word also packs the inbox consumption counts, which Solidity places in the same slot.
+ */
 export enum TempCheckpointLogField {
   HeaderHash = 0,
   BlobCommitmentsHash = 1,
@@ -148,19 +151,27 @@ export enum TempCheckpointLogField {
   PayloadDigest = 4,
   SlotNumber = 5,
   FeeHeader = 6,
+  InboxRollingHash = 7,
 }
 
 /**
  * Field-level override input for `tempCheckpointLogs[checkpointNumber]`. Covers the fields the
  * `propose()` path actually reads back. `payloadDigest` is `Buffer32` because it carries an
  * arbitrary `bytes32` value rather than a BN254 scalar. `slotNumber` carries the uint32 portion
  * of the on-chain `CompressedSlot`.
+ *
+ * `slotNumber`, `inboxMsgTotal` and `inboxConsumedBucket` share a single storage word, so supplying
+ * any one of them rewrites all three; the ones left out land as zero.
  */
 export type TempCheckpointLogOverrideFields = {
   headerHash?: Fr;
   outHash?: Fr;
   payloadDigest?: Buffer32;
   slotNumber?: SlotNumber;
+  /** Cumulative Inbox message count consumed as of this checkpoint. */
+  inboxMsgTotal?: bigint;
+  /** Inbox bucket sequence number this checkpoint's rolling hash corresponds to. */
+  inboxConsumedBucket?: bigint;
   feeHeader?: FeeHeader;
 };
 
@@ -266,6 +277,13 @@ function isHexString(value: unknown): value is Hex {
   return typeof value === 'string' && value.startsWith('0x');
 }
 
+function requireUintFits(value: bigint, bits: number, name: string): bigint {
+  if (value < 0n || value >= 1n << BigInt(bits)) {
+    throw new Error(`${name} ${value} does not fit in uint${bits}`);
+  }
+  return value;
+}
+
 export class RollupContract {
   private readonly rollup: GetContractReturnType<typeof RollupAbi, ViemClient>;
   private readonly logger = createLogger('ethereum:rollup');
@@ -936,6 +954,9 @@ export class RollupContract {
    *
    * `blobCommitmentsHash` and `attestationsHash` are intentionally not exposed here — the propose path
    * never asserts against them, so leaving them at storage zero is harmless.
+   *
+   * One diff entry is emitted per storage word touched, so words left out keep their on-chain values.
+   * `slotNumber` and the two inbox consumption counts share a word: any of them rewrites all three.
    */
   public async makeTempCheckpointLogOverride(
     checkpointNumber: CheckpointNumber,
@@ -960,14 +981,22 @@ export class RollupContract {
         value: fields.payloadDigest.toString() as `0x${string}`,
       });
     }
-    if (fields.slotNumber !== undefined) {
-      // CompressedSlot is uint32 on L1 (SafeCast.toUint32 reverts on overflow). Match that behavior here
-      // so a malformed override surfaces immediately rather than silently truncating into a wrong slot.
-      const slotNumber = BigInt(fields.slotNumber);
-      if (slotNumber < 0n || slotNumber > 0xffffffffn) {
-        throw new Error(`slotNumber ${slotNumber} does not fit in uint32`);
-      }
-      stateDiff.push({ slot: slotAt(TempCheckpointLogField.SlotNumber), value: word(slotNumber) });
+    if (
+      fields.slotNumber !== undefined ||
+      fields.inboxMsgTotal !== undefined ||
+      fields.inboxConsumedBucket !== undefined
+    ) {
+      // The L1 struct packs the slot number and the two inbox consumption counts into one word, so this
+      // diff always writes all three. Widths are enforced here because the L1 writers cast through
+      // SafeCast and revert on overflow; a malformed override must surface rather than silently truncate
+      // into a neighbouring field.
+      const slotNumber = requireUintFits(BigInt(fields.slotNumber ?? 0), 32, 'slotNumber');
+      const inboxMsgTotal = requireUintFits(fields.inboxMsgTotal ?? 0n, 64, 'inboxMsgTotal');
+      const inboxConsumedBucket = requireUintFits(fields.inboxConsumedBucket ?? 0n, 64, 'inboxConsumedBucket');
+      stateDiff.push({
+        slot: slotAt(TempCheckpointLogField.SlotNumber),
+        value: word(slotNumber | (inboxMsgTotal << 32n) | (inboxConsumedBucket << 96n)),
+      });
     }
     if (fields.feeHeader) {
       stateDiff.push({