@aztec/stdlib 5.0.0-private.20260319 → 5.0.0-rc.1

package/src/timetable/budgets.ts

@@ -0,0 +1,87 @@
+/** Default block sub-slot duration (`D`) in seconds, used to derive how many blocks fit in a slot. */
+export const DEFAULT_BLOCK_DURATION = 3;
+
+/** Default minimum block-building duration (`min_block_duration`) in seconds. */
+export const DEFAULT_MIN_BLOCK_DURATION = 2;
+
+/** Default one-way P2P propagation time (`p2p_propagation_time`) for proposals and attestations in seconds. */
+export const DEFAULT_P2P_PROPAGATION_TIME = 2;
+
+/** Default local checkpoint proposal preparation time (`checkpoint_proposal_prepare_time`) in seconds. */
+export const DEFAULT_CHECKPOINT_PROPOSAL_PREPARE_TIME = 1;
+
+/** Default local tolerance for archiver orphan-prune checks when no checkpoint proposal was received. */
+export const DEFAULT_ORPHAN_PRUNE_NO_PROPOSAL_TOLERANCE = 1;
+
+/**
+ * Default proposer initialization time (`checkpoint_proposal_init_time`) in seconds: the budget reserved at
+ * the start of the build frame for sync, the proposer check, and checkpoint initialization before the first
+ * block sub-slot opens. The proposer rarely starts building exactly at `build_frame_start`; this offset
+ * shifts the sub-slot grid so the first sub-slot still has its full duration once the prologue completes.
+ */
+export const DEFAULT_CHECKPOINT_PROPOSAL_INIT_TIME = 1;
+
+/**
+ * Ethereum slot duration (seconds) below which a network is treated as a fast local/e2e profile with mocked
+ * p2p. Profiles at or above this keep the production operational budgets. Mainnet is 12s; fast anvil-style
+ * local profiles run at 4s.
+ */
+export const FAST_PROFILE_ETHEREUM_SLOT_DURATION = 8;
+
+/**
+ * Operational timing budgets for the fast local/e2e profile (mocked p2p), per the README's "Local e2e with
+ * mocked p2p" section. When `ethereum_slot_duration < FAST_PROFILE_ETHEREUM_SLOT_DURATION`, these cap the
+ * proposer's operational budgets so a fast network does not inherit the conservative production budgets,
+ * which would shrink the per-checkpoint build window and under-pack checkpoints. Explicitly configured
+ * budgets below these caps are kept as-is (the budgets are clamped down, never raised).
+ */
+export const FAST_PROFILE_P2P_PROPAGATION_TIME = 0.5;
+
+/** Fast-profile checkpoint proposal preparation budget (seconds). See {@link FAST_PROFILE_P2P_PROPAGATION_TIME}. */
+export const FAST_PROFILE_CHECKPOINT_PROPOSAL_PREPARE_TIME = 0.5;
+
+/** Fast-profile minimum block-building budget (seconds). See {@link FAST_PROFILE_P2P_PROPAGATION_TIME}. */
+export const FAST_PROFILE_MIN_BLOCK_DURATION = 1;
+
+/** Resolved operational timing budgets used to size the proposer build window. */
+export type ResolvedTimingBudgets = {
+  minBlockDuration: number;
+  p2pPropagationTime: number;
+  checkpointProposalPrepareTime: number;
+  checkpointProposalInitTime: number;
+};
+
+/** Default consensus grace for received checkpoint proposals to materialize locally. */
+export function getDefaultCheckpointProposalSyncGrace(blockDuration: number): number {
+  return 2 * blockDuration;
+}
+
+/**
+ * Resolves the operational timing budgets, applying the fast local/e2e profile when
+ * `ethereumSlotDuration < FAST_PROFILE_ETHEREUM_SLOT_DURATION`.
+ *
+ * Production profiles (`ethereumSlotDuration >= FAST_PROFILE_ETHEREUM_SLOT_DURATION`) use the configured
+ * budgets verbatim. Fast profiles clamp `p2pPropagationTime`, `checkpointProposalPrepareTime`, and
+ * `minBlockDuration` down to the fast-profile caps so a fast network (mocked p2p) gets a build window sized
+ * for local timing rather than the conservative production budgets. The clamp only lowers budgets, so an
+ * operator that explicitly configured a smaller value keeps it. `checkpointProposalInitTime` is unchanged by
+ * the profile: it is a proposer prologue budget, not a propagation/preparation budget.
+ */
+export function resolveTimingBudgets(ethereumSlotDuration: number, opts: ResolvedTimingBudgets): ResolvedTimingBudgets {
+  const { minBlockDuration, p2pPropagationTime, checkpointProposalPrepareTime, checkpointProposalInitTime } = opts;
+
+  const isFastProfile = ethereumSlotDuration < FAST_PROFILE_ETHEREUM_SLOT_DURATION;
+  if (!isFastProfile) {
+    return { minBlockDuration, p2pPropagationTime, checkpointProposalPrepareTime, checkpointProposalInitTime };
+  }
+
+  return {
+    minBlockDuration: Math.min(minBlockDuration, FAST_PROFILE_MIN_BLOCK_DURATION),
+    p2pPropagationTime: Math.min(p2pPropagationTime, FAST_PROFILE_P2P_PROPAGATION_TIME),
+    checkpointProposalPrepareTime: Math.min(
+      checkpointProposalPrepareTime,
+      FAST_PROFILE_CHECKPOINT_PROPOSAL_PREPARE_TIME,
+    ),
+    checkpointProposalInitTime,
+  };
+}

package/src/timetable/build_proposer_timetable.ts

@@ -0,0 +1,42 @@
+import {
+  DEFAULT_BLOCK_DURATION,
+  DEFAULT_CHECKPOINT_PROPOSAL_INIT_TIME,
+  DEFAULT_CHECKPOINT_PROPOSAL_PREPARE_TIME,
+  DEFAULT_MIN_BLOCK_DURATION,
+  DEFAULT_P2P_PROPAGATION_TIME,
+} from './budgets.js';
+import type { SlotTimingConstants } from './consensus_timetable.js';
+import { ProposerTimetable } from './proposer_timetable.js';
+
+/**
+ * Subset of the sequencer/p2p config the proposer timetable derives its operational budgets from. Both
+ * {@link SequencerConfig} and {@link P2PConfig} structurally satisfy this, so the same builder is used by
+ * the sequencer, the p2p layer, and the node's `getNodeInfo`.
+ */
+export type ProposerTimetableConfig = {
+  blockDurationMs?: number;
+  minBlockDuration?: number;
+  attestationPropagationTime?: number;
+  checkpointProposalPrepareTime?: number;
+  checkpointProposalSyncGraceSeconds?: number;
+};
+
+/**
+ * Builds the proposer timetable from a sequencer/p2p config and the slot-timing protocol constants,
+ * applying the shared stdlib budget defaults. Single source of truth shared by the sequencer, the p2p
+ * layer, and the node's `getNodeInfo` so they all derive the same `maxBlocksPerCheckpoint`.
+ */
+export function buildProposerTimetable(
+  config: ProposerTimetableConfig,
+  l1Constants: SlotTimingConstants,
+): ProposerTimetable {
+  return new ProposerTimetable({
+    l1Constants,
+    blockDuration: config.blockDurationMs !== undefined ? config.blockDurationMs / 1000 : DEFAULT_BLOCK_DURATION,
+    minBlockDuration: config.minBlockDuration ?? DEFAULT_MIN_BLOCK_DURATION,
+    p2pPropagationTime: config.attestationPropagationTime ?? DEFAULT_P2P_PROPAGATION_TIME,
+    checkpointProposalPrepareTime: config.checkpointProposalPrepareTime ?? DEFAULT_CHECKPOINT_PROPOSAL_PREPARE_TIME,
+    checkpointProposalInitTime: DEFAULT_CHECKPOINT_PROPOSAL_INIT_TIME,
+    checkpointProposalSyncGrace: config.checkpointProposalSyncGraceSeconds,
+  });
+}

package/src/timetable/consensus_timetable.ts

@@ -0,0 +1,126 @@
+import type { SlotNumber } from '@aztec/foundation/branded-types';
+
+import { type L1RollupConstants, getTimestampForSlot } from '../epoch-helpers/index.js';
+import { getDefaultCheckpointProposalSyncGrace } from './budgets.js';
+
+/** Slot-timing protocol constants the timetables derive wall-clock times from. */
+export type SlotTimingConstants = Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'ethereumSlotDuration'>;
+
+/**
+ * Consensus acceptance bounds for the pipelined timetable.
+ *
+ * Returns the deadlines and matching receive-window lower bounds that validators and p2p use to decide
+ * whether a proposal or attestation is acceptable for a given target slot. All getters take a target slot
+ * and return an absolute wall-clock timestamp in seconds.
+ *
+ * Inputs are protocol slot-timing constants only (`genesis`, `aztec_slot_duration`,
+ * `ethereum_slot_duration`, `block_duration`, `checkpoint_proposal_sync_grace`); no operational budgets, so every
+ * node agrees on these bounds. See `stdlib/src/timetable/README.md` for the timing model.
+ */
+export class ConsensusTimetable {
+  /** Aztec slot duration (`S`) in seconds. */
+  public readonly aztecSlotDuration: number;
+
+  /** Ethereum slot duration (`E`) in seconds. */
+  public readonly ethereumSlotDuration: number;
+
+  /** Block sub-slot duration (`D`) in seconds. */
+  public readonly blockDuration: number;
+
+  /** L1 genesis timestamp in seconds (`genesis`), the anchor all slot timings derive from. */
+  public readonly genesisTime: bigint;
+
+  /** Consensus grace for received checkpoint proposals to materialize into local proposed state. */
+  public readonly checkpointProposalSyncGrace: number;
+
+  constructor(opts: { l1Constants: SlotTimingConstants; blockDuration: number; checkpointProposalSyncGrace?: number }) {
+    const { l1Constants, blockDuration } = opts;
+    const checkpointProposalSyncGrace =
+      opts.checkpointProposalSyncGrace ?? getDefaultCheckpointProposalSyncGrace(blockDuration);
+    if (l1Constants.slotDuration <= 0) {
+      throw new Error(`aztecSlotDuration must be positive (got ${l1Constants.slotDuration})`);
+    }
+    if (l1Constants.ethereumSlotDuration <= 0) {
+      throw new Error(`ethereumSlotDuration must be positive (got ${l1Constants.ethereumSlotDuration})`);
+    }
+    if (blockDuration <= 0) {
+      throw new Error(`blockDuration must be positive (got ${blockDuration})`);
+    }
+    if (checkpointProposalSyncGrace < 0) {
+      throw new Error(`checkpointProposalSyncGrace must be non-negative (got ${checkpointProposalSyncGrace})`);
+    }
+
+    this.aztecSlotDuration = l1Constants.slotDuration;
+    this.ethereumSlotDuration = l1Constants.ethereumSlotDuration;
+    this.blockDuration = blockDuration;
+    this.genesisTime = l1Constants.l1GenesisTime;
+    this.checkpointProposalSyncGrace = checkpointProposalSyncGrace;
+  }
+
+  /**
+   * Build-frame start for the target slot: `target_slot_start - S - E`. Anchors all sub-slot timings.
+   * Computed directly (not via a `slot - 1` hop) so it is well-defined for slot 0, whose build frame
+   * predates genesis; p2p validators evaluate acceptance windows for arbitrary peer-supplied slots.
+   */
+  public getBuildFrameStart(slot: SlotNumber): number {
+    return this.getTargetSlotStart(slot) - this.aztecSlotDuration - this.ethereumSlotDuration;
+  }
+
+  /** Start of the target slot: `genesis + slot * S`. */
+  public getTargetSlotStart(slot: SlotNumber): number {
+    return Number(getTimestampForSlot(slot, this.getL1Constants()));
+  }
+
+  /**
+   * Earliest acceptable arrival for a checkpoint proposal: `target_slot_start - S - E` (the build frame
+   * opening). Nothing legitimate for this slot exists before its build frame opens.
+   */
+  public getCheckpointProposalReceiveStart(slot: SlotNumber): number {
+    return this.getBuildFrameStart(slot);
+  }
+
+  /**
+   * Hard consensus receive deadline for a checkpoint proposal: `target_slot_start - E - D`. Validators
+   * reject proposals arriving after this, and the next proposer does not build on them.
+   */
+  public getCheckpointProposalReceiveDeadline(slot: SlotNumber): number {
+    return this.getTargetSlotStart(slot) - this.ethereumSlotDuration - this.blockDuration;
+  }
+
+  /**
+   * Wall-clock deadline by which a received checkpoint proposal should have materialized into local proposed
+   * state. This is `next_proposer_build_frame_start + checkpointProposalSyncGrace`, rounded up to the next
+   * integer second because L1 timestamps and archiver comparisons are second-granularity.
+   */
+  public getCheckpointProposalSyncedDeadline(slot: SlotNumber): number {
+    return Math.ceil(
+      this.getCheckpointProposalReceiveDeadline(slot) + this.blockDuration + this.checkpointProposalSyncGrace,
+    );
+  }
+
+  /**
+   * Earliest acceptable arrival for an attestation: `target_slot_start - S - E` (the build frame
+   * opening). Deliberately liberal; attestations are attributed by content, not timing.
+   */
+  public getAttestationReceiveStart(slot: SlotNumber): number {
+    return this.getBuildFrameStart(slot);
+  }
+
+  /**
+   * Single hard consensus deadline: `target_slot_start + S - 2E`. The latest the checkpoint can still
+   * land on L1 in the target slot, and the cutoff by which every block and the checkpoint must be
+   * re-executed, validated, and signed. Consensus-driven (used for inactivity/slashing decisions).
+   */
+  public getAttestationDeadline(slot: SlotNumber): number {
+    return this.getTargetSlotStart(slot) + this.aztecSlotDuration - 2 * this.ethereumSlotDuration;
+  }
+
+  /** Slot-timing protocol constants this timetable derives wall-clock times from. */
+  public getL1Constants(): SlotTimingConstants {
+    return {
+      l1GenesisTime: this.genesisTime,
+      slotDuration: this.aztecSlotDuration,
+      ethereumSlotDuration: this.ethereumSlotDuration,
+    };
+  }
+}

package/src/timetable/index.ts

@@ -1,66 +1,4 @@
-/**
- * Timetable constants used for sequencer timing calculations.
- * These define the time budgets for various phases of block production.
- *
- * The sequencer slot is divided into phases:
- * 1. Checkpoint initialization (sync + proposer check)
- * 2. Block building (execution)
- * 3. Checkpoint assembly
- * 4. P2P propagation for proposal and attestations (round-trip)
- * 5. L1 publishing
- */
-
-/** Time budget for checkpoint initialization (sync + proposer check) in seconds */
-export const CHECKPOINT_INITIALIZATION_TIME = 1;
-
-/** Time budget for assembling a checkpoint after building the last block in seconds */
-export const CHECKPOINT_ASSEMBLE_TIME = 1;
-
-/** Default one-way P2P propagation time for proposals and attestations in seconds */
-export const DEFAULT_P2P_PROPAGATION_TIME = 2;
-
-/** Default L1 publishing time (matches Ethereum slot duration on mainnet) in seconds */
-export const DEFAULT_L1_PUBLISHING_TIME = 12;
-
-/** Minimum execution time for building a block in seconds */
-export const MIN_EXECUTION_TIME = 2;
-
-/**
- * Calculates the maximum number of blocks that can be built in a slot.
- * Used by both the sequencer timetable and p2p gossipsub scoring.
- *
- * @param aztecSlotDurationSec - Aztec slot duration in seconds
- * @param blockDurationSec - Duration per block in seconds (undefined = single block mode)
- * @param opts - Optional overrides for timing constants
- * @returns Maximum number of blocks per slot
- */
-export function calculateMaxBlocksPerSlot(
-  aztecSlotDurationSec: number,
-  blockDurationSec: number | undefined,
-  opts: {
-    checkpointInitializationTime?: number;
-    checkpointAssembleTime?: number;
-    p2pPropagationTime?: number;
-    l1PublishingTime?: number;
-  } = {},
-): number {
-  if (!blockDurationSec) {
-    return 1; // Single block per slot
-  }
-
-  const initOffset = opts.checkpointInitializationTime ?? CHECKPOINT_INITIALIZATION_TIME;
-  const assembleTime = opts.checkpointAssembleTime ?? CHECKPOINT_ASSEMBLE_TIME;
-  const p2pTime = opts.p2pPropagationTime ?? DEFAULT_P2P_PROPAGATION_TIME;
-  const l1Time = opts.l1PublishingTime ?? DEFAULT_L1_PUBLISHING_TIME;
-
-  // Calculate checkpoint finalization time (assembly + round-trip propagation + L1 publishing)
-  const checkpointFinalizationTime = assembleTime + p2pTime * 2 + l1Time;
-
-  // Time reserved at end for last sub-slot (validator re-execution) + finalization
-  const timeReservedAtEnd = blockDurationSec + checkpointFinalizationTime;
-
-  // Time available for building blocks
-  const timeAvailableForBlocks = aztecSlotDurationSec - initOffset - timeReservedAtEnd;
-
-  return Math.max(1, Math.floor(timeAvailableForBlocks / blockDurationSec));
-}
+export * from './budgets.js';
+export * from './build_proposer_timetable.js';
+export * from './consensus_timetable.js';
+export * from './proposer_timetable.js';

package/src/timetable/proposer_timetable.ts

@@ -0,0 +1,190 @@
+import type { SlotNumber } from '@aztec/foundation/branded-types';
+import type { Logger } from '@aztec/foundation/log';
+
+import { type ResolvedTimingBudgets, getDefaultCheckpointProposalSyncGrace, resolveTimingBudgets } from './budgets.js';
+import { ConsensusTimetable, type SlotTimingConstants } from './consensus_timetable.js';
+
+/** Result of selecting the next block sub-slot to build. */
+export type SubslotSelection =
+  | { canStart: false; index: undefined; deadline: undefined; isLastBlock: false }
+  | { canStart: true; index: number; deadline: number; isLastBlock: boolean };
+
+/**
+ * Proposer ideal/happy-path schedule and block sub-slot timetable.
+ *
+ * Composes a {@link ConsensusTimetable} and adds the operational budgets that only the proposer needs
+ * (`min_block_duration`, `p2p_propagation_time`, `checkpoint_proposal_prepare_time`). Used by the
+ * sequencer and checkpoint-proposal job. All getters take a target slot and return an absolute
+ * wall-clock timestamp in seconds (or sub-slot deadlines in seconds for {@link selectNextSubslot}).
+ *
+ * The single hard deadline {@link getAttestationDeadline} is inherited from the composed
+ * {@link ConsensusTimetable}, so the proposer uses one object.
+ *
+ * `maxBlocksPerCheckpoint` is computed from the local operational budgets and then clamped down to the optional
+ * network-provided value when that value is lower; a network value at or above the computed count leaves the
+ * computed count in effect. When clamping down occurs and a logger is supplied, a warning is emitted.
+ */
+export class ProposerTimetable extends ConsensusTimetable {
+  /** Minimum block-building time (`min_block_duration`) in seconds. */
+  public readonly minBlockDuration: number;
+
+  /** One-way proposal/attestation propagation budget (`p2p_propagation_time`) in seconds. */
+  public readonly p2pPropagationTime: number;
+
+  /** Local checkpoint proposal preparation budget (`checkpoint_proposal_prepare_time`) in seconds. */
+  public readonly checkpointProposalPrepareTime: number;
+
+  /** Proposer initialization budget (`checkpoint_proposal_init_time`) reserved before the first sub-slot, in seconds. */
+  public readonly checkpointProposalInitTime: number;
+
+  /**
+   * Effective maximum number of block sub-slots per checkpoint: the value the local operational budgets compute,
+   * clamped down to the explicit network value when that value is lower. A network value above the computed
+   * count has no effect (the computed count is used) and is not logged.
+   */
+  public readonly maxBlocksPerCheckpoint: number;
+
+  constructor(opts: {
+    l1Constants: SlotTimingConstants;
+    blockDuration: number;
+    minBlockDuration: number;
+    p2pPropagationTime: number;
+    checkpointProposalPrepareTime: number;
+    checkpointProposalInitTime: number;
+    checkpointProposalSyncGrace?: number;
+    /** Explicit network max blocks per checkpoint; the effective value is clamped down to this when it is lower. */
+    maxBlocksPerCheckpoint?: number;
+    /** Optional logger; warns when the local budgets compute more blocks than the network value allows. */
+    logger?: Logger;
+  }) {
+    super({
+      l1Constants: opts.l1Constants,
+      blockDuration: opts.blockDuration,
+      checkpointProposalSyncGrace:
+        opts.checkpointProposalSyncGrace ?? getDefaultCheckpointProposalSyncGrace(opts.blockDuration),
+    });
+
+    // Resolve operational budgets, applying the fast local/e2e profile for low ethereum slot durations so a
+    // fast network does not inherit the conservative production budgets (which would shrink the build window).
+    const budgets: ResolvedTimingBudgets = resolveTimingBudgets(this.ethereumSlotDuration, {
+      minBlockDuration: opts.minBlockDuration,
+      p2pPropagationTime: opts.p2pPropagationTime,
+      checkpointProposalPrepareTime: opts.checkpointProposalPrepareTime,
+      checkpointProposalInitTime: opts.checkpointProposalInitTime,
+    });
+    this.p2pPropagationTime = budgets.p2pPropagationTime;
+    this.checkpointProposalPrepareTime = budgets.checkpointProposalPrepareTime;
+    this.checkpointProposalInitTime = budgets.checkpointProposalInitTime;
+
+    // Clamp min block duration to the block duration so a single sub-slot is always startable.
+    this.minBlockDuration = Math.min(budgets.minBlockDuration, this.blockDuration);
+
+    const computed = this.computeMaxBlocksPerCheckpoint();
+    this.maxBlocksPerCheckpoint =
+      opts.maxBlocksPerCheckpoint !== undefined ? Math.min(computed, opts.maxBlocksPerCheckpoint) : computed;
+    if (opts.maxBlocksPerCheckpoint !== undefined && opts.maxBlocksPerCheckpoint < computed) {
+      opts.logger?.warn(`Locally computed max blocks per checkpoint clamped down to the network-provided value`, {
+        computed,
+        maxBlocksPerCheckpoint: opts.maxBlocksPerCheckpoint,
+      });
+    }
+    if (this.maxBlocksPerCheckpoint < 1) {
+      throw new Error(
+        `Invalid timing configuration: derived ${this.maxBlocksPerCheckpoint} blocks per checkpoint for ` +
+          `slot duration ${this.aztecSlotDuration}s and block duration ${this.blockDuration}s.`,
+      );
+    }
+  }
+
+  /**
+   * Computes the maximum number of full-duration block sub-slots in a checkpoint from the already-resolved
+   * budgets. Derived from the spec's `max_blocks_per_checkpoint = floor((last_block_build_time -
+   * first_subslot_start) / D)`, where the first sub-slot starts one `checkpoint_proposal_init_time` (`init`)
+   * after `build_frame_start`, so it simplifies to `floor((S - init - D - 2P - prepCp) / D)`.
+   */
+  private computeMaxBlocksPerCheckpoint(): number {
+    // last_block_build_time - (build_frame_start + init) = S - init - D - 2P - prepCp.
+    const timeAvailableForBlocks =
+      this.aztecSlotDuration -
+      this.checkpointProposalInitTime -
+      this.blockDuration -
+      2 * this.p2pPropagationTime -
+      this.checkpointProposalPrepareTime;
+    return Math.floor(timeAvailableForBlocks / this.blockDuration);
+  }
+
+  /**
+   * Ideal time the last block must finish building by to make the ideal L1 publish path:
+   * `target_slot_start - E - D - 2P - prepCp` (= `checkpoint_proposal_send_time - prepCp`). Single value;
+   * the proposer sizes block production around the ideal L1-publish path only.
+   */
+  public getLastBlockBuildTime(slot: SlotNumber): number {
+    return (
+      this.getTargetSlotStart(slot) -
+      this.ethereumSlotDuration -
+      this.blockDuration -
+      2 * this.p2pPropagationTime -
+      this.checkpointProposalPrepareTime
+    );
+  }
+
+  /**
+   * Latest start at which the proposer can still squeeze in a minimum-duration block.
+   *
+   * Multi-block mode: `last_block_build_time - min_block_duration`, an ideal-derived cutoff
+   * intentionally earlier (by `P`) than the consensus receive gate would strictly allow, and
+   * conservatively no later than the final sub-slot's start cutoff in {@link selectNextSubslot}.
+   *
+   */
+  public getBuildStartDeadline(slot: SlotNumber): number {
+    return this.getLastBlockBuildTime(slot) - this.minBlockDuration;
+  }
+
+  /** Ideal L1 publish/send time: `target_slot_start - E`. Also the ideal attestation-receipt target. */
+  public getL1PublishIdealTime(slot: SlotNumber): number {
+    return this.getTargetSlotStart(slot) - this.ethereumSlotDuration;
+  }
+
+  /**
+   * Build deadline for sub-slot `k` (zero-based): `build_frame_start + init + (k + 1) * D`.
+   *
+   * The `init` (`checkpoint_proposal_init_time`) offset reserves the proposer's sync/proposer-check/init
+   * budget at the start of the build frame, so the first sub-slot still has its full duration once the
+   * prologue finishes rather than being eaten by it.
+   */
+  public getBlockBuildDeadline(slot: SlotNumber, blockIndex: number): number {
+    return this.getBuildFrameStart(slot) + this.checkpointProposalInitTime + (blockIndex + 1) * this.blockDuration;
+  }
+
+  /** Latest time to keep waiting for txs for sub-slot `k`: `block_build_deadline(k) - min_block_duration`. */
+  public getWaitForTxsDeadline(slot: SlotNumber, blockIndex: number): number {
+    return this.getBlockBuildDeadline(slot, blockIndex) - this.minBlockDuration;
+  }
+
+  /** Maximum number of full-duration block sub-slots for this timing config. */
+  public getMaxBlocksPerCheckpoint(): number {
+    return this.maxBlocksPerCheckpoint;
+  }
+
+  /**
+   * Selects the next block sub-slot to build for the target slot given the current wall-clock time.
+   *
+   * Scans sub-slots in order and picks the first whose build deadline is at least `min_block_duration`
+   * in the future. Sub-slots with insufficient remaining headroom are skipped.
+   *
+   * @param slot - Target slot the checkpoint commits to.
+   * @param now - Current wall-clock time in seconds.
+   */
+  public selectNextSubslot(slot: SlotNumber, now: number): SubslotSelection {
+    const maxBlocks = this.maxBlocksPerCheckpoint;
+    for (let index = 0; index < maxBlocks; index++) {
+      const deadline = this.getBlockBuildDeadline(slot, index);
+      if (deadline - now >= this.minBlockDuration) {
+        const isLastBlock = index === maxBlocks - 1;
+        return { canStart: true, index, deadline, isLastBlock };
+      }
+    }
+
+    return { canStart: false, index: undefined, deadline: undefined, isLastBlock: false };
+  }
+}

package/src/timetable/timetable-example.svg

@@ -0,0 +1,108 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg viewBox="0 0 1080 460" width="1080" height="460" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, Segoe UI, Helvetica, Arial, sans-serif" role="img" aria-label="Proportional example timetable">
+  <rect x="0" y="0" width="1080" height="460" fill="#ffffff"/>
+  <text x="540" y="28" text-anchor="middle" font-size="16" font-weight="700" fill="#1e293b">Example timetable — offsets from build_frame_start (S=72,E=12,D=6,P=2,prepCp=1)</text>
+
+  <!-- phase bands -->
+  <rect x="70" y="244" width="427" height="32" rx="4" fill="#dbeafe"/>
+  <rect x="497" y="244" width="77" height="32" fill="#fde68a"/>
+  <rect x="574" y="244" width="84" height="32" fill="#e9d5ff"/>
+  <rect x="658" y="244" width="352" height="32" rx="4" fill="#dcfce7"/>
+
+  <text x="283" y="236" text-anchor="middle" font-size="12" fill="#1e40af">block building</text>
+  <text x="535" y="236" text-anchor="middle" font-size="10.5" fill="#92400e">dead zone</text>
+  <text x="616" y="236" text-anchor="middle" font-size="10.5" fill="#6b21a8">send lead</text>
+  <text x="834" y="236" text-anchor="middle" font-size="12" fill="#166534">target L2 slot →</text>
+
+  <!-- ethereum-slot ticks (12s) -->
+  <g stroke="#94a3b8" stroke-width="1" opacity="0.45">
+    <line x1="154" y1="246" x2="154" y2="274"/>
+    <line x1="238" y1="246" x2="238" y2="274"/>
+    <line x1="322" y1="246" x2="322" y2="274"/>
+    <line x1="406" y1="246" x2="406" y2="274"/>
+    <line x1="490" y1="246" x2="490" y2="274"/>
+    <line x1="574" y1="246" x2="574" y2="274"/>
+    <line x1="658" y1="246" x2="658" y2="274"/>
+    <line x1="742" y1="246" x2="742" y2="274"/>
+    <line x1="826" y1="246" x2="826" y2="274"/>
+    <line x1="910" y1="246" x2="910" y2="274"/>
+    <line x1="994" y1="246" x2="994" y2="274"/>
+  </g>
+
+  <line x1="70" y1="260" x2="1010" y2="260" stroke="#475569" stroke-width="1.5"/>
+
+  <!-- slot boundaries (dashed) -->
+  <line x1="154" y1="242" x2="154" y2="296" stroke="#94a3b8" stroke-width="1.2" stroke-dasharray="4 3"/>
+  <text x="154" y="310" text-anchor="middle" font-size="10" fill="#64748b">build slot start (+12)</text>
+  <line x1="658" y1="218" x2="658" y2="302" stroke="#64748b" stroke-width="1.4" stroke-dasharray="5 3"/>
+  <text x="658" y="212" text-anchor="middle" font-size="10.5" fill="#334155">target slot start (+84)</text>
+
+  <!-- build frame opens (+0) -->
+  <line x1="70" y1="255" x2="70" y2="222" stroke="#94a3b8" stroke-width="1"/>
+  <circle cx="70" cy="260" r="5" fill="#2563eb" stroke="#fff" stroke-width="1.5"/>
+  <text x="64" y="216" text-anchor="start" font-size="11" fill="#1e3a5f">Build frame opens (+0)</text>
+
+  <!-- block 1 build deadline (+6) -->
+  <line x1="112" y1="265" x2="112" y2="300" stroke="#94a3b8" stroke-width="1"/>
+  <circle cx="112" cy="260" r="4" fill="#2563eb" stroke="#fff" stroke-width="1.5"/>
+  <text x="112" y="314" text-anchor="middle" font-size="10" fill="#64748b">block 1 build deadline (+6)</text>
+
+  <!-- start_deadline (+59) -->
+  <line x1="483" y1="265" x2="483" y2="332" stroke="#94a3b8" stroke-width="1"/>
+  <circle cx="483" cy="260" r="5" fill="#2563eb" stroke="#fff" stroke-width="1.5"/>
+  <text x="483" y="346" text-anchor="middle" font-size="11" fill="#1e3a5f">start_deadline (+59)</text>
+
+  <!-- last_block_build_time (+61, single value) -->
+  <line x1="497" y1="265" x2="497" y2="362" stroke="#94a3b8" stroke-width="1"/>
+  <circle cx="497" cy="260" r="5" fill="#2563eb" stroke="#fff" stroke-width="1.5"/>
+  <text x="497" y="376" text-anchor="middle" font-size="11" fill="#1e3a5f">last_block_build_time (+61)</text>
+
+  <!-- checkpoint_proposal_send_time (+62) -->
+  <line x1="504" y1="255" x2="504" y2="190" stroke="#94a3b8" stroke-width="1"/>
+  <circle cx="504" cy="260" r="5" fill="#2563eb" stroke="#fff" stroke-width="1.5"/>
+  <text x="504" y="184" text-anchor="middle" font-size="11" fill="#1e3a5f">checkpoint_proposal_send_time (+62)</text>
+
+  <!-- checkpoint_proposal_receive_ideal (+64) -->
+  <line x1="518" y1="255" x2="518" y2="146" stroke="#16a34a" stroke-width="1"/>
+  <circle cx="518" cy="260" r="5" fill="#16a34a" stroke="#fff" stroke-width="1.5"/>
+  <text x="518" y="140" text-anchor="middle" font-size="11" fill="#14532d">checkpoint_proposal_receive_ideal (+64)</text>
+
+  <!-- checkpoint_proposal_receive_deadline (+66) -->
+  <line x1="532" y1="255" x2="532" y2="92" stroke="#dc2626" stroke-width="1"/>
+  <circle cx="532" cy="260" r="5" fill="#dc2626" stroke="#fff" stroke-width="1.5"/>
+  <text x="532" y="72" text-anchor="middle" font-size="11" fill="#7f1d1d">checkpoint_proposal</text>
+  <text x="532" y="86" text-anchor="middle" font-size="11" fill="#7f1d1d">receive_deadline (+66)</text>
+
+  <!-- next proposer frame opens / l1_publish_ideal / attestation_receive_ideal (+72) -->
+  <line x1="574" y1="255" x2="574" y2="116" stroke="#16a34a" stroke-width="1"/>
+  <circle cx="574" cy="260" r="5" fill="#16a34a" stroke="#fff" stroke-width="1.5"/>
+  <text x="574" y="96" text-anchor="middle" font-size="11" fill="#6b21a8">Next proposer frame opens (+72)</text>
+  <text x="574" y="110" text-anchor="middle" font-size="11" fill="#14532d">l1_publish_ideal = attestation_receive_ideal</text>
+
+  <!-- single attestation_deadline (+132) -->
+  <line x1="994" y1="255" x2="994" y2="176" stroke="#dc2626" stroke-width="1.4"/>
+  <circle cx="994" cy="260" r="5.5" fill="#dc2626" stroke="#fff" stroke-width="1.5"/>
+  <text x="994" y="148" text-anchor="middle" font-size="11" font-weight="700" fill="#7f1d1d">attestation_deadline (+132)</text>
+  <text x="994" y="162" text-anchor="middle" font-size="10.5" fill="#7f1d1d">single deadline: validation / re-exec / signing</text>
+  <text x="994" y="176" text-anchor="middle" font-size="10" fill="#991b1b">+ collection cutoff · latest useful L1 send · tx timeout</text>
+
+  <!-- acceptance windows — both open at build_frame_start (+0, x=70) -->
+  <text x="70" y="397" text-anchor="start" font-size="10" fill="#7f1d1d">acceptance windows open at build_frame_start (+0):</text>
+  <!-- proposal acceptance: +0 .. +66 (checkpoint_proposal_receive_deadline) -->
+  <rect x="70" y="402" width="462" height="9" rx="3" fill="#fee2e2" stroke="#dc2626" stroke-width="0.8"/>
+  <text x="538" y="410" text-anchor="start" font-size="9.5" fill="#991b1b">proposal accept [+0 .. +66] (narrow, non-overlapping)</text>
+  <!-- attestation acceptance: +0 .. +132 (attestation_deadline) -->
+  <rect x="70" y="414" width="924" height="9" rx="3" fill="#dcfce7" stroke="#16a34a" stroke-width="0.8"/>
+  <text x="70" y="436" text-anchor="start" font-size="9.5" fill="#166534">attestation accept [+0 .. +132] (wide, liberal)</text>
+
+  <!-- legend -->
+  <g font-size="11">
+    <circle cx="540" cy="432" r="5" fill="#2563eb"/>
+    <text x="552" y="436" fill="#334155">build / structural</text>
+    <circle cx="682" cy="432" r="5" fill="#16a34a"/>
+    <text x="694" y="436" fill="#334155">ideal path</text>
+    <circle cx="782" cy="432" r="5" fill="#dc2626"/>
+    <text x="794" y="436" fill="#334155">late-acceptance deadline</text>
+    <text x="540" y="453" text-anchor="middle" fill="#64748b">dashed = slot boundary · ticks = 12s Ethereum slots · time → seconds from build_frame_start</text>
+  </g>
+</svg>

package/src/trees/append_only_tree_snapshot.ts

@@ -1,6 +1,6 @@
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { schemas } from '@aztec/foundation/schemas';
-import { BufferReader, FieldReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, FieldReader, serializeToSink } from '@aztec/foundation/serialize';
 import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
 
 import { inspect } from 'util';
@@ -44,8 +44,13 @@ export class AppendOnlyTreeSnapshot {
     return this.root.size + 4;
   }
 
-  toBuffer() {
-    return serializeToBuffer(this.root, this.nextAvailableLeafIndex);
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.root, this.nextAvailableLeafIndex);
   }
 
   toFields(): Fr[] {