refactor(fast-inbox): extract shared inbox consumption predicate (A-1383)

Move the streaming-Inbox cutoff formula and the mandatory-consumption / cap-escape
rule into a shared `stdlib/messaging/inbox_consumption` module so the sequencer's
bucket selection and the validator's last-block censorship check share one source of
truth for the boundary semantics.

- `getInboxCutoffTimestamp(slot, l1Constants, lagSeconds)`: buildFrameStart(slot) -
  lagSeconds, mirroring `ProposeLib.validateInboxConsumption`. The sequencer's
  `selectStreamingBundle` now calls it instead of inlining the computation (behavior
  unchanged).
- `isInboxConsumptionSufficient(...)`: the none / past-cutoff (strict >) / cap-escape
  predicate.
- Tests pin the A-1371 section-13 cross-layer vectors (genesisTime=100000,
  slotDuration=36): the cutoff table and the S=10 mandatory-consumption boundary.

Author: spalladino

yarn-project/sequencer-client/src/sequencer/checkpoint_proposal_job.ts

@@ -52,7 +52,12 @@ import {
   type ResolvedSequencerConfig,
   type WorldStateSynchronizer,
 } from '@aztec/stdlib/interfaces/server';
-import { InboxBucketRef, type L1ToL2MessageSource, computeInHashFromL1ToL2Messages } from '@aztec/stdlib/messaging';
+import {
+  InboxBucketRef,
+  type L1ToL2MessageSource,
+  computeInHashFromL1ToL2Messages,
+  getInboxCutoffTimestamp,
+} from '@aztec/stdlib/messaging';
 import type {
   BlockProposal,
   BlockProposalOptions,
@@ -1127,9 +1132,7 @@ export class CheckpointProposalJob implements Traceable {
     isLastBlock: boolean,
     nowSeconds: number,
   ): Promise<InboxBucketSelection> {
-    // Mirror ProposeLib's cutoff exactly: buildFrameStart = toTimestamp(slot - 1), cutoff = buildFrameStart - lag.
-    const buildFrameStart = getTimestampForSlot(SlotNumber(this.targetSlot - 1), this.l1Constants);
-    const cutoffTimestamp = buildFrameStart - BigInt(INBOX_LAG_SECONDS);
+    const cutoffTimestamp = getInboxCutoffTimestamp(this.targetSlot, this.l1Constants, INBOX_LAG_SECONDS);
     return selectInboxBucketForBlock({
       messageSource: this.l1ToL2MessageSource,
       now: BigInt(Math.floor(nowSeconds)),

yarn-project/stdlib/src/messaging/inbox_consumption.test.ts

@@ -0,0 +1,95 @@
+import { SlotNumber } from '@aztec/foundation/branded-types';
+
+import { describe, expect, it } from '@jest/globals';
+
+import type { L1RollupConstants } from '../epoch-helpers/index.js';
+import { getInboxCutoffTimestamp, isInboxConsumptionSufficient } from './inbox_consumption.js';
+
+// Cross-layer test vectors pinned by A-1371 decision 13 (the `ProposeInboxConsumptionTest` Foundry harness values).
+// The same vectors are asserted against `ProposeLib.validateInboxConsumption` on L1; keeping them identical here makes
+// L1, TS, and the design doc agree on the cutoff formula and the mandatory-consumption boundary.
+const GENESIS_TIME = 100_000n;
+const SLOT_DURATION = 36;
+const LAG_SECONDS = 12;
+
+const l1Constants = { l1GenesisTime: GENESIS_TIME, slotDuration: SLOT_DURATION } as Pick<
+  L1RollupConstants,
+  'l1GenesisTime' | 'slotDuration'
+>;
+
+describe('inbox_consumption', () => {
+  describe('getInboxCutoffTimestamp', () => {
+    // buildFrameStart(S) = 100000 + (S - 1) * 36; cutoff(S) = buildFrameStart(S) - 12. Pinned in A-1371 §13.
+    it.each([
+      [1, 99_988n],
+      [2, 100_024n],
+      [10, 100_312n],
+      [11, 100_348n],
+    ])('matches the A-1371 §13 cutoff table for slot %i', (slot, expectedCutoff) => {
+      expect(getInboxCutoffTimestamp(SlotNumber(slot), l1Constants, LAG_SECONDS)).toBe(expectedCutoff);
+    });
+  });
+
+  describe('isInboxConsumptionSufficient', () => {
+    const base = { cutoffTimestamp: 100_312n, checkpointStartTotalMsgCount: 0n, perCheckpointCap: 1024 };
+
+    it('is sufficient when there is no next bucket (consumed everything)', () => {
+      expect(isInboxConsumptionSufficient({ ...base, nextBucket: undefined })).toBe(true);
+    });
+
+    // A-1371 §13 boundary at S=10 (cutoff = 100312): a bucket opened exactly at the cutoff is mandatory (strict `>`).
+    it('is insufficient when the next bucket opened exactly at the cutoff is left unconsumed', () => {
+      expect(isInboxConsumptionSufficient({ ...base, nextBucket: { timestamp: 100_312n, totalMsgCount: 5n } })).toBe(
+        false,
+      );
+    });
+
+    // A-1371 §13 boundary at S=10: a bucket opened at cutoff + 1 is past the cutoff and need not be consumed.
+    it('is sufficient when the next bucket opened at cutoff + 1 is left unconsumed', () => {
+      expect(isInboxConsumptionSufficient({ ...base, nextBucket: { timestamp: 100_313n, totalMsgCount: 5n } })).toBe(
+        true,
+      );
+    });
+
+    it('is sufficient via cap-escape when consuming through the next bucket would exceed the per-checkpoint cap', () => {
+      // Next bucket is at/before the cutoff (would otherwise be mandatory), but consuming through it consumes
+      // 1025 > 1024 messages, so leaving it unconsumed is allowed (the cap-escape branch).
+      expect(
+        isInboxConsumptionSufficient({
+          ...base,
+          nextBucket: { timestamp: 100_000n, totalMsgCount: 1025n },
+        }),
+      ).toBe(true);
+    });
+
+    it('is insufficient when consuming through the next bucket exactly reaches the per-checkpoint cap', () => {
+      // Delta of exactly 1024 does not escape (strict `>` on the cap), so a mandatory bucket must still be consumed.
+      expect(
+        isInboxConsumptionSufficient({
+          ...base,
+          nextBucket: { timestamp: 100_000n, totalMsgCount: 1024n },
+        }),
+      ).toBe(false);
+    });
+
+    it('measures the cap-escape delta from the checkpoint start, not from zero', () => {
+      // With a non-zero checkpoint start, only the delta consumed this checkpoint counts against the cap.
+      expect(
+        isInboxConsumptionSufficient({
+          cutoffTimestamp: 100_312n,
+          checkpointStartTotalMsgCount: 500n,
+          perCheckpointCap: 1024,
+          nextBucket: { timestamp: 100_000n, totalMsgCount: 1524n },
+        }),
+      ).toBe(false); // delta = 1024, not an escape
+      expect(
+        isInboxConsumptionSufficient({
+          cutoffTimestamp: 100_312n,
+          checkpointStartTotalMsgCount: 500n,
+          perCheckpointCap: 1024,
+          nextBucket: { timestamp: 100_000n, totalMsgCount: 1525n },
+        }),
+      ).toBe(true); // delta = 1025, escapes
+    });
+  });
+});

yarn-project/stdlib/src/messaging/inbox_consumption.ts

@@ -0,0 +1,53 @@
+import { SlotNumber } from '@aztec/foundation/branded-types';
+
+import { type L1RollupConstants, getTimestampForSlot } from '../epoch-helpers/index.js';
+import type { InboxBucket } from './inbox_bucket.js';
+
+/**
+ * Censorship cutoff timestamp for a checkpoint proposed in `slot` (AZIP-22 Fast Inbox), mirroring the cutoff in
+ * `ProposeLib.validateInboxConsumption`. A checkpoint proposed in slot `S` is built during slot `S - 1`, so
+ * `buildFrameStart(S) = toTimestamp(S - 1)` and `cutoff(S) = buildFrameStart(S) - lagSeconds`. Buckets opened at or
+ * before the cutoff are mandatory to consume by the checkpoint's last block; the strict `>` on the L1 "past cutoff"
+ * test (see {@link isInboxConsumptionSufficient}) makes a bucket opened exactly at the cutoff mandatory.
+ *
+ * This is the single source of truth for the cutoff formula shared by the sequencer's streaming bucket selection and
+ * the validator's last-block censorship check.
+ */
+export function getInboxCutoffTimestamp(
+  slot: SlotNumber,
+  l1Constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration'>,
+  lagSeconds: number,
+): bigint {
+  return getTimestampForSlot(SlotNumber(slot - 1), l1Constants) - BigInt(lagSeconds);
+}
+
+/**
+ * Whether a checkpoint whose last-consumed bucket is immediately followed by `nextBucket` meets the censorship floor,
+ * mirroring the mandatory-consumption assert in `ProposeLib.validateInboxConsumption` (AZIP-22 Fast Inbox).
+ * Consumption is sufficient when the first unconsumed bucket:
+ *  - does not exist (the checkpoint consumed everything the Inbox has), or
+ *  - was opened strictly after the cutoff (`timestamp > cutoffTimestamp`), or
+ *  - consuming through it would exceed the per-checkpoint cap (the cap-escape).
+ *
+ * The strict `>` matches L1: a bucket opened exactly at the cutoff must be consumed. This is the single source of
+ * truth for the minimum-consumption / cap-escape rule shared by the sequencer's selection floor and the validator.
+ */
+export function isInboxConsumptionSufficient(input: {
+  /** The first unconsumed bucket (the one after the checkpoint's last-consumed bucket), or undefined if none exists. */
+  nextBucket: Pick<InboxBucket, 'timestamp' | 'totalMsgCount'> | undefined;
+  /** Censorship cutoff timestamp from {@link getInboxCutoffTimestamp}. */
+  cutoffTimestamp: bigint;
+  /** Cumulative Inbox message count consumed as of the parent checkpoint; the per-checkpoint cap origin. */
+  checkpointStartTotalMsgCount: bigint;
+  /** Maximum number of messages the checkpoint may consume in total (`MAX_L1_TO_L2_MSGS_PER_CHECKPOINT`). */
+  perCheckpointCap: number;
+}): boolean {
+  const { nextBucket, cutoffTimestamp, checkpointStartTotalMsgCount, perCheckpointCap } = input;
+  if (nextBucket === undefined) {
+    return true;
+  }
+  if (nextBucket.timestamp > cutoffTimestamp) {
+    return true;
+  }
+  return nextBucket.totalMsgCount - checkpointStartTotalMsgCount > BigInt(perCheckpointCap);
+}

yarn-project/stdlib/src/messaging/index.ts

@@ -1,6 +1,7 @@
 export * from './append_l1_to_l2_messages.js';
 export * from './in_hash.js';
 export * from './inbox_bucket.js';
+export * from './inbox_consumption.js';
 export * from './inbox_leaf.js';
 export * from './inbox_rolling_hash.js';
 export * from './l1_to_l2_message_bundle.js';