@aztec/stdlib 6.0.0-nightly.20260810 → 6.0.0-nightly.20260821

package/src/messaging/inbox_bucket.ts

@@ -0,0 +1,125 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { type ZodFor, schemas } from '@aztec/foundation/schemas';
+import { BufferReader, bigintToUInt64BE, serializeToBuffer } from '@aztec/foundation/serialize';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { z } from 'zod';
+
+/**
+ * Snapshot of an Inbox rolling-hash bucket as tracked by the archiver.
+ *
+ * A bucket accumulates the message leaves inserted into the Inbox within a single L1 block (up to a per-bucket
+ * maximum, after which further messages in the same block spill into the next bucket). Buckets are identified by
+ * a dense, monotonically increasing sequence number and keyed for recency lookups by the L1 block timestamp at
+ * which they were opened. Mirrors the on-chain `InboxBucket` struct plus the fields the archiver derives while
+ * syncing.
+ */
+export type InboxBucket = {
+  /** Dense, monotonically increasing sequence number of this bucket in the Inbox ring. */
+  seq: bigint;
+  /** Consensus rolling hash (truncated sha256 chain) after the last message absorbed into this bucket. */
+  inboxRollingHash: Fr;
+  /** Cumulative number of messages inserted into the Inbox up to and including this bucket. */
+  totalMsgCount: bigint;
+  /** L1 block timestamp at which this bucket was opened; the recency key for lag/cutoff comparisons, in seconds. */
+  timestamp: bigint;
+  /** Number of messages absorbed into this bucket. */
+  msgCount: number;
+  /** Global leaf index of the last message absorbed into this bucket. */
+  lastMessageIndex: bigint;
+};
+
+export const InboxBucketSchema = z.object({
+  seq: schemas.BigInt,
+  inboxRollingHash: Fr.schema,
+  totalMsgCount: schemas.BigInt,
+  timestamp: schemas.BigInt,
+  msgCount: schemas.Integer,
+  lastMessageIndex: schemas.BigInt,
+}) satisfies z.ZodType<InboxBucket>;
+
+/**
+ * Reference to a settled Inbox rolling-hash bucket, carried alongside a block proposal so a
+ * validator can look the bucket up in its own Inbox view and derive the consumed-message bundle itself, rather than
+ * trusting a proposer-supplied message list. Pins the bucket by its dense sequence number and recency-key timestamp
+ * and asserts the expected consensus rolling hash. A wrong reference can only cause a lookup miss or hash mismatch; it
+ * can never change what a validator accepts, because the checkpoint header's `inboxRollingHash` remains the signed
+ * consensus commitment (mirrors the unsigned bucket hint on L1's `Rollup.propose`).
+ */
+export class InboxBucketRef {
+  constructor(
+    /** Dense, monotonically increasing sequence number of the referenced bucket in the Inbox ring. */
+    public readonly bucketSeq: bigint,
+    /** L1 block timestamp (in seconds) at which the referenced bucket was opened; its recency key. */
+    public readonly bucketTimestamp: bigint,
+    /** Consensus rolling hash (truncated sha256 chain) after the last message absorbed into the referenced bucket. */
+    public readonly inboxRollingHash: Fr,
+  ) {}
+
+  /** Serialized size in bytes: two uint64 fields plus one field element. */
+  static readonly SIZE = 8 + 8 + Fr.SIZE_IN_BYTES;
+
+  static get schema(): ZodFor<InboxBucketRef> {
+    return z
+      .object({
+        bucketSeq: schemas.BigInt,
+        bucketTimestamp: schemas.BigInt,
+        inboxRollingHash: Fr.schema,
+      })
+      .transform(InboxBucketRef.from);
+  }
+
+  static from(fields: FieldsOf<InboxBucketRef>): InboxBucketRef {
+    return new InboxBucketRef(fields.bucketSeq, fields.bucketTimestamp, fields.inboxRollingHash);
+  }
+
+  /** Derives a wire reference from a bucket snapshot as tracked by the archiver. */
+  static fromBucket(bucket: InboxBucket): InboxBucketRef {
+    return new InboxBucketRef(bucket.seq, bucket.timestamp, bucket.inboxRollingHash);
+  }
+
+  toBuffer(): Buffer {
+    return serializeToBuffer([
+      bigintToUInt64BE(this.bucketSeq),
+      bigintToUInt64BE(this.bucketTimestamp),
+      this.inboxRollingHash,
+    ]);
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader): InboxBucketRef {
+    const reader = BufferReader.asReader(buffer);
+    return new InboxBucketRef(reader.readUInt64(), reader.readUInt64(), reader.readObject(Fr));
+  }
+
+  getSize(): number {
+    return InboxBucketRef.SIZE;
+  }
+
+  equals(other: InboxBucketRef): boolean {
+    return (
+      this.bucketSeq === other.bucketSeq &&
+      this.bucketTimestamp === other.bucketTimestamp &&
+      this.inboxRollingHash.equals(other.inboxRollingHash)
+    );
+  }
+
+  static empty(): InboxBucketRef {
+    return new InboxBucketRef(0n, 0n, Fr.ZERO);
+  }
+
+  static random(): InboxBucketRef {
+    return new InboxBucketRef(
+      BigInt(Math.floor(Math.random() * 1000)),
+      BigInt(Math.floor(Math.random() * 1_000_000)),
+      Fr.random(),
+    );
+  }
+
+  toInspect() {
+    return {
+      bucketSeq: this.bucketSeq.toString(),
+      bucketTimestamp: this.bucketTimestamp.toString(),
+      inboxRollingHash: this.inboxRollingHash.toString(),
+    };
+  }
+}

package/src/messaging/inbox_consumption.ts

@@ -0,0 +1,74 @@
+import { MAX_L1_TO_L2_MSGS_PER_BLOCK, MAX_L1_TO_L2_MSGS_PER_CHECKPOINT } from '@aztec/constants';
+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`, mirroring the cutoff in
+ * `ProposeLib.validateInboxConsumption`, which is `TimeLib.getBuildFrameStart(slot)`. A checkpoint proposed in slot
+ * `S` is built during slot `S - 1`, and the build frame opens one Ethereum slot before that slot starts, since the
+ * builder works from the L1 state as of the preceding L1 block: `cutoff(S) = toTimestamp(S - 1) - E`. Buckets opened
+ * at or before the cutoff were visible to every node for the whole build frame and 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' | 'ethereumSlotDuration'>,
+): bigint {
+  return getTimestampForSlot(SlotNumber(slot - 1), l1Constants) - BigInt(l1Constants.ethereumSlotDuration);
+}
+
+/**
+ * Smallest number of blocks a checkpoint must be able to build for the streaming Inbox to be guaranteed to clear any
+ * mandatory backlog, and therefore the floor on a network's `maxBlocksPerCheckpoint`.
+ *
+ * Blocks consume whole buckets — a bucket is never split — so a block can only consume a bucket prefix whose message
+ * count fits `MAX_L1_TO_L2_MSGS_PER_BLOCK`. The worst case alternates a one-message bucket with a full
+ * `MAX_L1_TO_L2_MSGS_PER_BLOCK`-message bucket: each such pair needs two blocks (the pair's `cap + 1` messages
+ * overflow one block), and the backlog only stops being mandatory once consuming the next bucket would exceed
+ * `MAX_L1_TO_L2_MSGS_PER_CHECKPOINT` (the cap-escape). That bounds the backlog at `cap + 1` messages per block-pair
+ * and yields `2 * ceil((MAX_L1_TO_L2_MSGS_PER_CHECKPOINT + 1) / (MAX_L1_TO_L2_MSGS_PER_BLOCK + 1)) - 1` blocks (the
+ * final pair needs only its first block).
+ *
+ * A network configured below this floor can be halted permanently: an adversary posts that bucket pattern, no
+ * checkpoint can reach the censorship floor within its block budget, every checkpoint is rejected, and because a
+ * rejected checkpoint never advances the consumed position the next checkpoint faces the identical backlog.
+ */
+export const MIN_BLOCKS_FOR_INBOX_CATCHUP =
+  2 * Math.ceil((MAX_L1_TO_L2_MSGS_PER_CHECKPOINT + 1) / (MAX_L1_TO_L2_MSGS_PER_BLOCK + 1)) - 1;
+
+/**
+ * Whether a checkpoint whose last-consumed bucket is immediately followed by `nextBucket` meets the censorship floor,
+ * mirroring the mandatory-consumption assert in `ProposeLib.validateInboxConsumption`.
+ * 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);
+}

package/src/messaging/inbox_rolling_hash.ts

@@ -0,0 +1,24 @@
+import { DomainSeparator } from '@aztec/constants';
+import { sha256ToField } from '@aztec/foundation/crypto/sha256';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { numToUInt32BE } from '@aztec/foundation/serialize';
+
+/**
+ * Extends the Inbox rolling-hash chain by a single message leaf, returning the new rolling hash.
+ *
+ * Each link is `sha256ToField(DOM_SEP__INBOX_ROLLING_HASH || prev || leaf)` over the 4-byte big-endian domain
+ * separator followed by the two 32-byte big-endian values, matching the truncated-to-field sha256 the L1 Inbox
+ * accumulates and the noir `accumulate_inbox_rolling_hash` helper. The separator distinguishes a chain link from the
+ * untagged `outHash` merkle node hash, which absorbs the same two-field preimage shape.
+ */
+export function updateInboxRollingHash(prev: Fr, leaf: Fr): Fr {
+  return sha256ToField([numToUInt32BE(DomainSeparator.INBOX_ROLLING_HASH), prev.toBuffer(), leaf.toBuffer()]);
+}
+
+/**
+ * Extends the Inbox rolling-hash chain by a list of message leaves, in order, returning the new rolling hash.
+ * The genesis rolling hash is `Fr.ZERO`, and an empty list returns `start` unchanged.
+ */
+export function accumulateInboxRollingHash(start: Fr, leaves: Fr[]): Fr {
+  return leaves.reduce(updateInboxRollingHash, start);
+}

package/src/messaging/index.ts

@@ -1,6 +1,9 @@
 export * from './append_l1_to_l2_messages.js';
-export * from './in_hash.js';
-export * from './inbox_leaf.js';
+export * from './inbox_bucket.js';
+export * from './inbox_consumption.js';
+export * from './inbox_rolling_hash.js';
+export * from './l1_to_l2_message_bundle.js';
+export * from './l1_to_l2_message_sponge.js';
 export * from './l1_to_l2_message.js';
 export * from './l1_to_l2_message_source.js';
 export * from './l1_actor.js';

package/src/messaging/l1_to_l2_message_bundle.ts

@@ -0,0 +1,65 @@
+import { MAX_L1_TO_L2_MSGS_PER_BLOCK } from '@aztec/constants';
+import { padArrayEnd } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { bufferSchemaFor } from '@aztec/foundation/schemas';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
+
+/**
+ * A block's L1-to-L2 message bundle: the real message leaves it inserts into the L1-to-L2 message tree and the count
+ * that drives both the compact (unpadded) tree append and the message-sponge absorb. See the Noir
+ * `L1ToL2MessageBundle`.
+ */
+export class L1ToL2MessageBundle {
+  constructor(
+    /** The real message leaves in the leading lanes, padded with zeros to `MAX_L1_TO_L2_MSGS_PER_BLOCK`. Kept as a
+     * plain array (not a tuple) to avoid TS's deep-instantiation limit on the wide type. */
+    public readonly messages: Fr[],
+    /** Number of real messages: drives both the compact tree append and the sponge absorb. */
+    public readonly numMsgs: number,
+  ) {}
+
+  /** An empty bundle: no leaves inserted, nothing absorbed. */
+  static empty(): L1ToL2MessageBundle {
+    return new L1ToL2MessageBundle(
+      Array.from({ length: MAX_L1_TO_L2_MSGS_PER_BLOCK }, () => Fr.ZERO),
+      0,
+    );
+  }
+
+  toBuffer() {
+    return serializeToBuffer(this.messages, this.numMsgs);
+  }
+
+  toString() {
+    return bufferToHex(this.toBuffer());
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    // Array.from (not readArray with the literal cap) keeps the type `Fr[]` and avoids TS's deep-tuple instantiation.
+    const messages = Array.from({ length: MAX_L1_TO_L2_MSGS_PER_BLOCK }, () => Fr.fromBuffer(reader));
+    return new L1ToL2MessageBundle(messages, reader.readNumber());
+  }
+
+  static fromString(str: string) {
+    return L1ToL2MessageBundle.fromBuffer(hexToBuffer(str));
+  }
+
+  toJSON() {
+    return this.toBuffer();
+  }
+
+  static get schema() {
+    return bufferSchemaFor(L1ToL2MessageBundle);
+  }
+}
+
+/** Wraps `messages` (the real leaves) into a bundle: the leaves fill the leading lanes, the count is the real count. */
+export function makeL1ToL2MessageBundle(messages: Fr[]): L1ToL2MessageBundle {
+  // Explicit `<Fr, number>` keeps the result `Fr[]`; padding to the literal cap would otherwise infer a deep tuple.
+  return new L1ToL2MessageBundle(
+    padArrayEnd<Fr, number>(messages, Fr.ZERO, MAX_L1_TO_L2_MSGS_PER_BLOCK),
+    messages.length,
+  );
+}

package/src/messaging/l1_to_l2_message_source.ts

@@ -1,21 +1,12 @@
-import type { CheckpointNumber } from '@aztec/foundation/branded-types';
 import type { Fr } from '@aztec/foundation/curves/bn254';
 
 import type { L2Tips } from '../block/l2_block_source.js';
+import type { InboxBucket } from './inbox_bucket.js';
 
 /**
  * Interface of classes allowing for the retrieval of L1 to L2 messages.
  */
 export interface L1ToL2MessageSource {
-  /**
-   * Gets new L1 to L2 message (to be) included in a given checkpoint.
-   * @param checkpointNumber - Checkpoint number to get messages for.
-   * @returns The L1 to L2 messages/leaves of the messages subtree.
-   * @throws If the message tree for the given checkpoint has not yet been sealed on L1
-   * (i.e., checkpointNumber >= inbox treeInProgress).
-   */
-  getL1ToL2Messages(checkpointNumber: CheckpointNumber): Promise<Fr[]>;
-
   /**
    * Gets the L1 to L2 message index in the L1 to L2 message tree.
    * @param l1ToL2Message - The L1 to L2 message.
@@ -23,6 +14,53 @@ export interface L1ToL2MessageSource {
    */
   getL1ToL2MessageIndex(l1ToL2Message: Fr): Promise<bigint | undefined>;
 
+  /**
+   * Returns the latest Inbox bucket opened at or before the given L1 timestamp, or undefined if no such bucket
+   * exists (i.e., every synced bucket was opened strictly after the timestamp). Used by the sequencer/validator
+   * to resolve the censorship cutoff and message-lag boundaries.
+   * @param timestamp - The L1 timestamp (in seconds) to look up at-or-before.
+   */
+  getLatestInboxBucketAtOrBefore(timestamp: bigint): Promise<InboxBucket | undefined>;
+
+  /**
+   * Returns the Inbox bucket with the given sequence number, or undefined if it has not been synced. Validators use
+   * this to resolve the bucket a proposal references and check its rolling hash.
+   * @param seq - The bucket sequence number.
+   */
+  getInboxBucket(seq: bigint): Promise<InboxBucket | undefined>;
+
+  /**
+   * Returns the Inbox bucket whose cumulative message total equals `totalMsgCount`, or undefined if no synced bucket
+   * sits on that boundary. A block's or checkpoint's L1-to-L2 tree leaf count equals the cumulative total of the last
+   * bucket it consumed (messages are indexed compactly, with no padding), so validators use this to resolve the
+   * bucket a block consumed through from the block's leaf count, without trusting a wire hint. `totalMsgCount === 0`
+   * resolves the genesis sentinel bucket (sequence 0); a total that does not land on a bucket boundary returns
+   * undefined.
+   * @param totalMsgCount - The cumulative Inbox message count (leaf count) to resolve to a bucket boundary.
+   */
+  getInboxBucketByTotalMsgCount(totalMsgCount: bigint): Promise<InboxBucket | undefined>;
+
+  /**
+   * Returns the message leaves absorbed into buckets in the range `(fromExclusive, toInclusive]`, in insertion
+   * order, for streaming message-bundle derivation. Both bounds must name buckets the source
+   * has synced; it throws otherwise, so that an empty result means the range holds no messages instead of hiding an
+   * unsynced bound. Callers that can tolerate an unsynced source resolve both bounds first, or map the failure to
+   * their own catch-up handling.
+   * @param fromExclusive - The lower bucket sequence bound, exclusive (0 means from the start of the Inbox).
+   * @param toInclusive - The upper bucket sequence bound, inclusive.
+   */
+  getL1ToL2MessagesBetweenBuckets(fromExclusive: bigint, toInclusive: bigint): Promise<Fr[]>;
+
+  /**
+   * Returns the message leaves in the cumulative Inbox message-count range `[startLeafCount, endLeafCount)`, in
+   * insertion order. The bounds are compact L1-to-L2 tree leaf counts, which every block header
+   * carries, so a consumer can ask for the messages a block or checkpoint consumed without resolving Inbox buckets
+   * itself. Both bounds must land on a bucket boundary the source has synced; it throws otherwise.
+   * @param startLeafCount - The cumulative Inbox message count the range starts at, inclusive.
+   * @param endLeafCount - The cumulative Inbox message count the range ends at, exclusive.
+   */
+  getL1ToL2MessagesBetweenLeafCounts(startLeafCount: bigint, endLeafCount: bigint): Promise<Fr[]>;
+
   /**
    * Returns the tips of the L2 chain.
    */

package/src/messaging/l1_to_l2_message_sponge.ts

@@ -0,0 +1,69 @@
+import { Poseidon2Sponge } from '@aztec/blob-lib/types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+/**
+ * An absorb-only Poseidon2 sponge over L1-to-L2 message leaves.
+ *
+ * Mirrors `L1ToL2MessageSponge` in
+ * `noir-projects/fnd/noir-protocol-circuits/crates/rollup-lib/src/abis/l1_to_l2_message_sponge.nr`. Each block of a
+ * checkpoint absorbs its message bundle into the sponge it inherited from the previous block; the checkpoint root
+ * recomputes the sponge over the checkpoint's whole message list and asserts the accumulated states are equal.
+ */
+export class L1ToL2MessageSponge {
+  constructor(
+    /** Sponge accumulating the absorbed message leaves. */
+    public readonly sponge: Poseidon2Sponge,
+    /** Number of message leaves absorbed so far. */
+    public numAbsorbed: number,
+  ) {}
+
+  /** A fresh, empty sponge (matching noir's `L1ToL2MessageSponge::new()` / `empty()`, i.e. `Poseidon2Sponge::new(0)`). */
+  static empty(): L1ToL2MessageSponge {
+    return new L1ToL2MessageSponge(Poseidon2Sponge.empty(), 0);
+  }
+
+  /** Absorb the given message leaves in order. */
+  async absorb(leaves: Fr[]) {
+    await this.sponge.absorb(leaves);
+    this.numAbsorbed += leaves.length;
+  }
+
+  clone() {
+    return L1ToL2MessageSponge.fromBuffer(this.toBuffer());
+  }
+
+  static getFields(fields: FieldsOf<L1ToL2MessageSponge>) {
+    return [fields.sponge, fields.numAbsorbed] as const;
+  }
+
+  toBuffer() {
+    return serializeToBuffer(...L1ToL2MessageSponge.getFields(this));
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader): L1ToL2MessageSponge {
+    const reader = BufferReader.asReader(buffer);
+    return new L1ToL2MessageSponge(reader.readObject(Poseidon2Sponge), reader.readNumber());
+  }
+
+  toFields(): Fr[] {
+    return serializeToFields(...L1ToL2MessageSponge.getFields(this));
+  }
+
+  static fromFields(fields: Fr[] | FieldReader): L1ToL2MessageSponge {
+    const reader = FieldReader.asReader(fields);
+    return new L1ToL2MessageSponge(reader.readObject(Poseidon2Sponge), reader.readField().toNumber());
+  }
+}
+
+/**
+ * Accumulates a fresh message sponge over `leaves`, in order. This is the value the inbox parity proof commits to and
+ * the checkpoint's block roots reach, starting from the empty sponge. Every leaf passed in is absorbed, so any padding
+ * the caller includes is part of the accumulated state.
+ */
+export async function accumulateL1ToL2MessageSponge(leaves: Fr[]): Promise<L1ToL2MessageSponge> {
+  const sponge = L1ToL2MessageSponge.empty();
+  await sponge.absorb(leaves);
+  return sponge;
+}

package/src/noir/index.ts

@@ -4,7 +4,6 @@ import type {
   AbiErrorType,
   AbiNamedValue,
   AbiType,
-  AbiValue,
   DebugFileMap,
   DebugInfo,
 } from '../abi/abi.js';
@@ -74,7 +73,7 @@ export interface NoirCompiledContract {
   /** The events of the contract */
   outputs: {
     structs: Record<string, AbiType[]>;
-    globals: Record<string, (AbiNamedValue | AbiValue)[]>;
+    globals: Record<string, AbiNamedValue[]>;
   };
   /** The map of file ID to the source code and path of the file. */
   file_map: DebugFileMap;