@aztec/sequencer-client 0.0.1-commit.c2eed6949 → 0.0.1-commit.c52d6e7

package/src/sequencer/checkpoint_proposal_job_metrics.ts

@@ -0,0 +1,128 @@
+import {
+  Attributes,
+  type Gauge,
+  type Histogram,
+  type Meter,
+  Metrics,
+  type TelemetryClient,
+} from '@aztec/telemetry-client';
+
+type CheckpointProposalJobInstruments = {
+  checkpointAttestationDelay: Histogram;
+  checkpointBuildDuration: Histogram;
+  checkpointStartToFirstBlockDuration: Histogram;
+  checkpointLastBlockToBroadcastDuration: Histogram;
+  pipelinedCheckpointBuildStartOffsetFromSlotBoundary: Histogram;
+  checkpointBlockCount: Gauge;
+  checkpointTxCount: Gauge;
+  checkpointTotalMana: Gauge;
+};
+
+/**
+ * Per-job recording surface used by {@link CheckpointProposalJob}.
+ *
+ * Ownership split:
+ * - {@link CheckpointProposalJobMetrics} owns the OpenTelemetry meter and instruments and should live for the
+ *   lifetime of the sequencer process.
+ * - A recorder owns only mutable timing state for one checkpoint proposal job so overlapping jobs cannot
+ *   overwrite each other's timing markers.
+ */
+export interface CheckpointProposalJobMetricsRecorder {
+  recordCheckpointAttestationDelay(durationMs: number): void;
+  recordCheckpointBuild(durationMs: number, blockCount: number, txCount: number, totalMana: number): void;
+  recordPipelinedCheckpointBuildStartOffsetFromSlotBoundary(offsetMs: number): void;
+  startCheckpointTiming(nowMs: number): void;
+  noteCheckpointBlockBuilt(nowMs: number, opts: { isFirstBlock: boolean; isLastBlock: boolean }): void;
+  noteCheckpointBroadcast(nowMs: number): void;
+}
+
+/**
+ * Concrete per-job recorder.
+ *
+ * This class should be short-lived: create one recorder per checkpoint proposal job and discard it when the job
+ * completes. It intentionally does not create instruments; it only holds the job-local timestamps needed to derive
+ * timing metrics safely.
+ */
+class CheckpointProposalJobMetricsRecorderImpl implements CheckpointProposalJobMetricsRecorder {
+  private checkpointStartedAt?: number;
+  private checkpointLastBlockBuiltAt?: number;
+
+  constructor(private readonly instruments: CheckpointProposalJobInstruments) {}
+
+  public recordCheckpointAttestationDelay(durationMs: number) {
+    this.instruments.checkpointAttestationDelay.record(Math.ceil(durationMs));
+  }
+
+  public recordCheckpointBuild(durationMs: number, blockCount: number, txCount: number, totalMana: number) {
+    this.instruments.checkpointBuildDuration.record(Math.ceil(durationMs));
+    this.instruments.checkpointBlockCount.record(blockCount);
+    this.instruments.checkpointTxCount.record(txCount);
+    this.instruments.checkpointTotalMana.record(totalMana);
+  }
+
+  public recordPipelinedCheckpointBuildStartOffsetFromSlotBoundary(offsetMs: number) {
+    this.instruments.pipelinedCheckpointBuildStartOffsetFromSlotBoundary.record(Math.ceil(Math.abs(offsetMs)), {
+      [Attributes.SLOT_BOUNDARY_SIDE]: offsetMs < 0 ? 'before' : 'after',
+    });
+  }
+
+  public startCheckpointTiming(nowMs: number) {
+    this.checkpointStartedAt = nowMs;
+    this.checkpointLastBlockBuiltAt = undefined;
+  }
+
+  public noteCheckpointBlockBuilt(nowMs: number, opts: { isFirstBlock: boolean; isLastBlock: boolean }) {
+    if (opts.isFirstBlock && this.checkpointStartedAt !== undefined) {
+      this.instruments.checkpointStartToFirstBlockDuration.record(Math.ceil(nowMs - this.checkpointStartedAt));
+    }
+
+    if (opts.isLastBlock) {
+      this.checkpointLastBlockBuiltAt = nowMs;
+    }
+  }
+
+  public noteCheckpointBroadcast(nowMs: number) {
+    if (this.checkpointLastBlockBuiltAt !== undefined) {
+      this.instruments.checkpointLastBlockToBroadcastDuration.record(
+        Math.ceil(nowMs - this.checkpointLastBlockBuiltAt),
+      );
+    }
+
+    this.checkpointLastBlockBuiltAt = undefined;
+  }
+}
+
+/**
+ * Long-lived owner of checkpoint proposal job telemetry instruments.
+ *
+ * The sequencer should construct this once and reuse it across jobs. Each call to {@link createRecorder} returns a
+ * lightweight recorder with isolated mutable state for a single checkpoint proposal job.
+ */
+export class CheckpointProposalJobMetrics {
+  private readonly meter: Meter;
+  private readonly instruments: CheckpointProposalJobInstruments;
+
+  constructor(client: TelemetryClient, name = 'CheckpointProposalJob') {
+    this.meter = client.getMeter(name);
+    this.instruments = {
+      checkpointAttestationDelay: this.meter.createHistogram(Metrics.SEQUENCER_CHECKPOINT_ATTESTATION_DELAY),
+      checkpointBuildDuration: this.meter.createHistogram(Metrics.SEQUENCER_CHECKPOINT_BUILD_DURATION),
+      checkpointStartToFirstBlockDuration: this.meter.createHistogram(
+        Metrics.SEQUENCER_CHECKPOINT_START_TO_FIRST_BLOCK_DURATION,
+      ),
+      checkpointLastBlockToBroadcastDuration: this.meter.createHistogram(
+        Metrics.SEQUENCER_CHECKPOINT_LAST_BLOCK_TO_BROADCAST_DURATION,
+      ),
+      pipelinedCheckpointBuildStartOffsetFromSlotBoundary: this.meter.createHistogram(
+        Metrics.SEQUENCER_PIPELINED_CHECKPOINT_BUILD_START_OFFSET_FROM_SLOT_BOUNDARY,
+      ),
+      checkpointBlockCount: this.meter.createGauge(Metrics.SEQUENCER_CHECKPOINT_BLOCK_COUNT),
+      checkpointTxCount: this.meter.createGauge(Metrics.SEQUENCER_CHECKPOINT_TX_COUNT),
+      checkpointTotalMana: this.meter.createGauge(Metrics.SEQUENCER_CHECKPOINT_TOTAL_MANA),
+    };
+  }
+
+  public createRecorder(): CheckpointProposalJobMetricsRecorder {
+    return new CheckpointProposalJobMetricsRecorderImpl(this.instruments);
+  }
+}

package/src/sequencer/checkpoint_voter.ts

@@ -2,7 +2,6 @@ import type { SlotNumber } from '@aztec/foundation/branded-types';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import type { Logger } from '@aztec/foundation/log';
 import type { SlasherClientInterface } from '@aztec/slasher';
-import { getTimestampForSlot } from '@aztec/stdlib/epoch-helpers';
 import type { ResolvedSequencerConfig } from '@aztec/stdlib/interfaces/server';
 import type { ValidatorClient } from '@aztec/validator-client';
 import { DutyAlreadySignedError } from '@aztec/validator-ha-signer/errors';
@@ -18,7 +17,6 @@ import type { SequencerRollupConstants } from './types.js';
  * Handles governance and slashing voting for a given slot.
  */
 export class CheckpointVoter {
-  private slotTimestamp: bigint;
   private governanceSigner: (msg: TypedDataDefinition) => Promise<`0x${string}`>;
   private slashingSigner: (msg: TypedDataDefinition) => Promise<`0x${string}`>;
 
@@ -33,8 +31,6 @@ export class CheckpointVoter {
     private readonly metrics: SequencerMetrics,
     private readonly log: Logger,
   ) {
-    this.slotTimestamp = getTimestampForSlot(this.slot, this.l1Constants);
-
     // Create separate signers with appropriate duty contexts for governance and slashing votes
     // These use HA protection to ensure only one node signs per slot/duty
     const governanceContext: SigningContext = { slot: this.slot, dutyType: DutyType.GOVERNANCE_VOTE };
@@ -77,7 +73,6 @@ export class CheckpointVoter {
       return await this.publisher.enqueueGovernanceCastSignal(
         governanceProposerPayload,
         this.slot,
-        this.slotTimestamp,
         this.attestorAddress,
         this.governanceSigner,
       );
@@ -108,13 +103,7 @@ export class CheckpointVoter {
 
       this.metrics.recordSlashingAttempt(actions.length);
 
-      return await this.publisher.enqueueSlashingActions(
-        actions,
-        this.slot,
-        this.slotTimestamp,
-        this.attestorAddress,
-        this.slashingSigner,
-      );
+      return await this.publisher.enqueueSlashingActions(actions, this.slot, this.attestorAddress, this.slashingSigner);
     } catch (err) {
       if (err instanceof DutyAlreadySignedError) {
         this.log.info(`Slashing vote already signed by another node`, {

package/src/sequencer/events.ts

@@ -1,20 +1,76 @@
-import type { BlockNumber, CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import type { BlockNumber, CheckpointNumber, IndexWithinCheckpoint, SlotNumber } from '@aztec/foundation/branded-types';
+import type { BlockHash } from '@aztec/stdlib/block';
 
 import type { Action } from '../publisher/sequencer-publisher.js';
 import type { SequencerState } from './utils.js';
 
 export type SequencerEvents = {
+  /**
+   * Emitted on every sequencer state transition (including no-op transitions to the same state). The
+   * timing fields are anchored to the build frame of the slot being proposed for, not to wall-clock
+   * slot boundaries, because the proposer builds for `targetSlot` during the previous (build) slot.
+   *
+   * - `oldState` / `newState` are the previous and new {@link SequencerState}.
+   * - `secondsIntoBuildFrame` is the wall-clock seconds elapsed since the build-frame start of
+   *   `targetSlot` (`now − getBuildFrameStart(targetSlot)`). Undefined for lifecycle states with no
+   *   associated slot (e.g. IDLE/STOPPING). It can be negative if the transition happens before the
+   *   build frame opens.
+   * - `targetSlot` is the slot the checkpoint is being proposed for (the submission slot, one ahead of
+   *   the wall-clock build slot under pipelining). Undefined for lifecycle states with no slot.
+   */
   ['state-changed']: (args: {
     oldState: SequencerState;
     newState: SequencerState;
-    secondsIntoSlot?: number;
-    slot?: SlotNumber;
+    secondsIntoBuildFrame?: number;
+    targetSlot?: SlotNumber;
+  }) => void;
+  /**
+   * Emitted by the sequencer once it has decided it is going to attempt to build a
+   * checkpoint for `targetSlot`, after computing the L1 simulation overrides used by
+   * `canProposeAt`. Fired BEFORE the L1 simulation is run, so consumers can observe the
+   * decision regardless of whether the propose ultimately lands.
+   *
+   * - `hadProposedParent` indicates whether the build saw a proposed (pipelined) parent
+   *   checkpoint that hasn't landed on L1 yet.
+   * - `provenOverride` is the assumed proven checkpoint number pinned for the L1
+   *   simulation. The plan always pins both chain tips to short-circuit `canPruneAtTime`,
+   *   so this is populated whenever a simulation plan was built — the value either
+   *   matches the on-chain proven snapshot (defensive pin) or the assumed-proven
+   *   checkpoint when building optimistically across a pruning boundary.
+   * - `simulatedPending` is the pending checkpoint passed to L1 simulation. The plan
+   *   always pins both chain tips to short-circuit `canPruneAtTime`, so this reflects
+   *   either the pipelined/invalidated tip or the on-chain pending snapshot.
+   */
+  ['preparing-checkpoint']: (args: {
+    targetSlot: SlotNumber;
+    checkpointNumber: CheckpointNumber;
+    hadProposedParent: boolean;
+    provenOverride: CheckpointNumber | undefined;
+    simulatedPending: CheckpointNumber | undefined;
   }) => void;
   ['proposer-rollup-check-failed']: (args: { reason: string; slot: SlotNumber }) => void;
-  ['block-tx-count-check-failed']: (args: { minTxs: number; availableTxs: number; slot: SlotNumber }) => void;
+  ['block-tx-count-check-failed']: (args: { minTxs: number; slot: SlotNumber }) => void;
   ['block-build-failed']: (args: { reason: string; slot: SlotNumber }) => void;
-  ['block-proposed']: (args: { blockNumber: BlockNumber; slot: SlotNumber; buildSlot: SlotNumber }) => void;
+  ['block-proposed']: (args: {
+    blockNumber: BlockNumber;
+    blockHash: BlockHash;
+    checkpointNumber: CheckpointNumber;
+    indexWithinCheckpoint: IndexWithinCheckpoint;
+    slot: SlotNumber;
+    buildSlot: SlotNumber;
+  }) => void;
   ['checkpoint-empty']: (args: { slot: SlotNumber }) => void;
+  /**
+   * Emitted when the proposer's pre-broadcast `validateBlockHeader` simulation fails. This is a
+   * last-chance check before we gossip a checkpoint proposal: a failure here means the header
+   * would not be accepted by L1 (e.g. archive mismatch, stale chain tip, or some other state
+   * drift between when we built the checkpoint and when we are about to broadcast it).
+   */
+  ['header-validation-failed']: (args: {
+    slot: SlotNumber;
+    checkpointNumber: CheckpointNumber;
+    reason: string;
+  }) => void;
   ['checkpoint-publish-failed']: (args: {
     slot: SlotNumber;
     successfulActions?: Action[];
@@ -24,4 +80,9 @@ export type SequencerEvents = {
   }) => void;
   ['checkpoint-published']: (args: { checkpoint: CheckpointNumber; slot: SlotNumber }) => void;
   ['checkpoint-error']: (args: { error: Error }) => void;
+  ['pipelined-checkpoint-discarded']: (args: {
+    slot: SlotNumber;
+    checkpointNumber: CheckpointNumber;
+    reason: string;
+  }) => void;
 };

package/src/sequencer/metrics.ts

@@ -26,6 +26,7 @@ export class SequencerMetrics {
   private blockBuildDuration: Histogram;
   private blockBuildManaPerSecond: Gauge;
   private stateTransitionBufferDuration: Histogram;
+  private stateDuration: Histogram;
 
   // these are gauges because for individual sequencers building a block is not something that happens often enough to warrant a histogram
   private timeToCollectAttestations: Gauge;
@@ -44,13 +45,9 @@ export class SequencerMetrics {
   private checkpointProposalFailed: UpDownCounter;
   private checkpointSuccess: UpDownCounter;
   private slashingAttempts: UpDownCounter;
-  private checkpointAttestationDelay: Histogram;
-  private checkpointBuildDuration: Histogram;
-  private checkpointBlockCount: Gauge;
-  private checkpointTxCount: Gauge;
-  private checkpointTotalMana: Gauge;
   private pipelineDepth: Gauge;
   private pipelineDiscards: UpDownCounter;
+  private pipelineParentCheckpointMismatches: UpDownCounter;
 
   // Fisherman fee analysis metrics
   private fishermanWouldBeIncluded: UpDownCounter;
@@ -68,6 +65,10 @@ export class SequencerMetrics {
   private fishermanMinedBlobTxPriorityFee: Histogram;
   private fishermanMinedBlobTxTotalCost: Histogram;
 
+  private blockInterBlockTime: Histogram;
+  private lastBlockBuiltTimestamp?: number;
+  private lastBlockBuiltSlot?: SlotNumber;
+
   private lastSeenSlot?: SlotNumber;
 
   constructor(
@@ -86,9 +87,11 @@ export class SequencerMetrics {
 
     this.blockBuildManaPerSecond = this.meter.createGauge(Metrics.SEQUENCER_BLOCK_BUILD_MANA_PER_SECOND);
 
+    this.blockInterBlockTime = this.meter.createHistogram(Metrics.SEQUENCER_BLOCK_INTER_BLOCK_TIME);
+
     this.stateTransitionBufferDuration = this.meter.createHistogram(Metrics.SEQUENCER_STATE_TRANSITION_BUFFER_DURATION);
 
-    this.checkpointAttestationDelay = this.meter.createHistogram(Metrics.SEQUENCER_CHECKPOINT_ATTESTATION_DELAY);
+    this.stateDuration = this.meter.createHistogram(Metrics.SEQUENCER_STATE_DURATION);
 
     this.rewards = this.meter.createGauge(Metrics.SEQUENCER_CURRENT_SLOT_REWARDS);
 
@@ -138,15 +141,23 @@ export class SequencerMetrics {
       Metrics.SEQUENCER_CHECKPOINT_PROPOSAL_FAILED_COUNT,
     );
 
-    this.checkpointBuildDuration = this.meter.createHistogram(Metrics.SEQUENCER_CHECKPOINT_BUILD_DURATION);
-    this.checkpointBlockCount = this.meter.createGauge(Metrics.SEQUENCER_CHECKPOINT_BLOCK_COUNT);
-    this.checkpointTxCount = this.meter.createGauge(Metrics.SEQUENCER_CHECKPOINT_TX_COUNT);
-    this.checkpointTotalMana = this.meter.createGauge(Metrics.SEQUENCER_CHECKPOINT_TOTAL_MANA);
-
     this.slashingAttempts = createUpDownCounterWithDefault(this.meter, Metrics.SEQUENCER_SLASHING_ATTEMPTS_COUNT);
 
     this.pipelineDepth = this.meter.createGauge(Metrics.SEQUENCER_PIPELINE_DEPTH);
     this.pipelineDiscards = createUpDownCounterWithDefault(this.meter, Metrics.SEQUENCER_PIPELINE_DISCARDS_COUNT);
+    this.pipelineParentCheckpointMismatches = createUpDownCounterWithDefault(
+      this.meter,
+      Metrics.SEQUENCER_PIPELINE_PARENT_CHECKPOINT_MISMATCH_COUNT,
+      {
+        [Attributes.ERROR_TYPE]: [
+          'archiver-sync-timeout',
+          'parent-not-on-l1',
+          'parent-hash-mismatch',
+          'parent-invalid-attestations',
+          'unexpected-parent-appeared',
+        ],
+      },
+    );
     this.pipelineDepth.record(0);
 
     // Fisherman fee analysis metrics
@@ -211,21 +222,25 @@ export class SequencerMetrics {
     this.timeToCollectAttestations.record(0);
   }
 
-  public recordCheckpointAttestationDelay(duration: number) {
-    this.checkpointAttestationDelay.record(duration);
-  }
-
   public recordCollectedAttestations(count: number, durationMs: number) {
     this.collectedAttestions.record(count);
     this.timeToCollectAttestations.record(Math.ceil(durationMs));
   }
 
-  recordBuiltBlock(buildDurationMs: number, totalMana: number) {
+  recordBuiltBlock(buildDurationMs: number, totalMana: number, slot: SlotNumber) {
     this.blockCounter.add(1, {
       [Attributes.STATUS]: 'built',
     });
     this.blockBuildDuration.record(Math.ceil(buildDurationMs));
     this.blockBuildManaPerSecond.record(Math.ceil((totalMana * 1000) / buildDurationMs));
+
+    // Only record inter-block time between blocks built within the same slot.
+    const now = Date.now();
+    if (this.lastBlockBuiltTimestamp !== undefined && this.lastBlockBuiltSlot === slot) {
+      this.blockInterBlockTime.record(now - this.lastBlockBuiltTimestamp);
+    }
+    this.lastBlockBuiltTimestamp = now;
+    this.lastBlockBuiltSlot = slot;
   }
 
   recordFailedBlock() {
@@ -240,6 +255,12 @@ export class SequencerMetrics {
     });
   }
 
+  recordStateDuration(durationMs: number, state: SequencerState) {
+    this.stateDuration.record(Math.ceil(durationMs), {
+      [Attributes.SEQUENCER_STATE]: state,
+    });
+  }
+
   recordPipelineDepth(depth: number) {
     this.pipelineDepth.record(depth);
   }
@@ -248,6 +269,12 @@ export class SequencerMetrics {
     this.pipelineDiscards.add(count);
   }
 
+  recordPipelineParentCheckpointMismatch(reason: string) {
+    this.pipelineParentCheckpointMismatches.add(1, {
+      [Attributes.ERROR_TYPE]: reason,
+    });
+  }
+
   incOpenSlot(slot: SlotNumber, proposer: string) {
     // sequencer went through the loop a second time. Noop
     if (slot === this.lastSeenSlot) {
@@ -306,14 +333,6 @@ export class SequencerMetrics {
     });
   }
 
-  /** Records aggregate metrics for a completed checkpoint build. */
-  recordCheckpointBuild(durationMs: number, blockCount: number, txCount: number, totalMana: number) {
-    this.checkpointBuildDuration.record(Math.ceil(durationMs));
-    this.checkpointBlockCount.record(blockCount);
-    this.checkpointTxCount.record(txCount);
-    this.checkpointTotalMana.record(totalMana);
-  }
-
   recordSlashingAttempt(actionCount: number) {
     this.slashingAttempts.add(actionCount);
   }

package/src/sequencer/missing_committee.ts

@@ -0,0 +1,192 @@
+import type { EpochCache } from '@aztec/epoch-cache';
+import type { RollupContract } from '@aztec/ethereum/contracts';
+import { EpochNumber, type SlotNumber } from '@aztec/foundation/branded-types';
+import { timesParallel } from '@aztec/foundation/collection';
+import type { Logger } from '@aztec/foundation/log';
+import { formatSeconds } from '@aztec/foundation/string';
+import type { DateProvider } from '@aztec/foundation/timer';
+import type { L2BlockSource } from '@aztec/stdlib/block';
+import { type L1RollupConstants, getStartTimestampForEpoch } from '@aztec/stdlib/epoch-helpers';
+
+/** Collaborators {@link logMissingCommittee} needs to diagnose and report why no committee exists. */
+export interface MissingCommitteeContext {
+  epochCache: Pick<EpochCache, 'getL1Constants' | 'getLagInEpochsForValidatorSet'>;
+  rollupContract: Pick<RollupContract, 'getActiveAttesterCount' | 'getAttesterCountAtTime'>;
+  l2BlockSource: Pick<L2BlockSource, 'getBlockNumber'>;
+  l1Constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'epochDuration'>;
+  dateProvider: Pick<DateProvider, 'nowInSeconds'>;
+  logger: Pick<Logger, 'info' | 'warn' | 'debug'>;
+}
+
+/**
+ * Why the sequencer cannot find a validator committee for an upcoming slot. A committee for an epoch is
+ * sampled from the validator set as of `lagInEpochsForValidatorSet` epochs earlier, and L1 refuses to
+ * produce one until at least `targetCommitteeSize` validators were staked at that sampling time.
+ */
+export type MissingCommitteeCause =
+  /** Enough validators are staked now; the committee is just waiting for the sampling window to advance. */
+  | 'awaiting-sampling-lag'
+  /** The chain has not produced any block yet and too few validators are staked: normal bootstrap state. */
+  | 'awaiting-first-validators'
+  /** The chain has produced blocks before but the validator set has since dropped below the required size. */
+  | 'validator-set-shrank';
+
+export interface MissingCommitteeDiagnosis {
+  cause: MissingCommitteeCause;
+  /** Log severity: bootstrap and lag are expected (`info`); a shrunken set on a live chain is not (`warn`). */
+  severity: 'info' | 'warn';
+}
+
+/**
+ * Logs why no validator committee exists for the given slot. Rather than the cryptic "committee does not
+ * exist on L1", it diagnoses the cause from the live attester count and whether the chain has ever produced
+ * a block: a bootstrapping chain waiting for validators to stake, a full set still waiting for the sampling
+ * lag to elapse, or a validator set that has shrunk below the required size on a live chain. Only the last is
+ * a genuine problem, so only it is logged at `warn`.
+ *
+ * Best-effort: if the diagnostic L1 reads fail we fall back to a neutral message so this never throws on the
+ * propose path.
+ */
+export async function logMissingCommittee(
+  targetSlot: SlotNumber,
+  targetEpoch: EpochNumber,
+  ctx: MissingCommitteeContext,
+): Promise<void> {
+  const targetCommitteeSize = ctx.epochCache.getL1Constants().targetCommitteeSize;
+  const lag = ctx.epochCache.getLagInEpochsForValidatorSet();
+
+  let attesterCount: number;
+  let hasProducedBlocks: boolean;
+  try {
+    [attesterCount, hasProducedBlocks] = await Promise.all([
+      ctx.rollupContract.getActiveAttesterCount(),
+      ctx.l2BlockSource.getBlockNumber().then(n => n > 0),
+    ]);
+  } catch (err) {
+    ctx.logger.warn(`No committee found for slot ${targetSlot}; could not determine validator set size`, {
+      targetSlot,
+      targetEpoch,
+      targetCommitteeSize,
+      err,
+    });
+    return;
+  }
+
+  const diagnosis = classifyMissingCommittee({ attesterCount, targetCommitteeSize, hasProducedBlocks });
+  const logCtx = { targetSlot, targetEpoch, attesterCount, targetCommitteeSize, cause: diagnosis.cause };
+
+  switch (diagnosis.cause) {
+    case 'awaiting-sampling-lag': {
+      const firstCommitteeEpoch = await estimateFirstCommitteeEpoch(targetEpoch, lag, targetCommitteeSize, ctx);
+      const staked = `${attesterCount} validators are staked (>= ${targetCommitteeSize} required)`;
+      const forming = `the committee is still forming as the ${lag}-epoch sampling window advances`;
+      // When we could not pin the exact epoch, report the safe upper bound rather than a misleading ETA.
+      const epoch = firstCommitteeEpoch ?? EpochNumber(targetEpoch + lag + 1);
+      const expectation =
+        firstCommitteeEpoch === undefined
+          ? `A committee should exist no later than epoch ${epoch}.`
+          : `The first committee is expected at epoch ${epoch}${formatEpochEta(epoch, ctx)}.`;
+      ctx.logger.info(`No committee for slot ${targetSlot} yet: ${staked}, ${forming}. ${expectation}`, {
+        ...logCtx,
+        firstCommitteeEpoch: epoch,
+      });
+      break;
+    }
+    case 'awaiting-first-validators':
+      ctx.logger.info(
+        `No committee for slot ${targetSlot}: the chain has not started producing blocks and only ${attesterCount} ` +
+          `of the ${targetCommitteeSize} required validators are staked. Block production begins once at least ` +
+          `${targetCommitteeSize} validators stake and the ${lag}-epoch sampling lag elapses.`,
+        logCtx,
+      );
+      break;
+    case 'validator-set-shrank':
+      ctx.logger.warn(
+        `No committee for slot ${targetSlot}: the validator set has dropped to ${attesterCount}, below the ` +
+          `${targetCommitteeSize} required to form a committee. The chain cannot progress until enough validators ` +
+          `are staked again — check for validators exiting or being slashed.`,
+        logCtx,
+      );
+      break;
+  }
+}
+
+/**
+ * Classifies why no committee exists for a slot, using only cheap live signals: the current attester count
+ * and whether the chain has ever produced a block. See {@link MissingCommitteeCause} for the reasoning.
+ */
+export function classifyMissingCommittee(args: {
+  attesterCount: number;
+  targetCommitteeSize: number;
+  hasProducedBlocks: boolean;
+}): MissingCommitteeDiagnosis {
+  const { attesterCount, targetCommitteeSize, hasProducedBlocks } = args;
+
+  if (attesterCount >= targetCommitteeSize) {
+    return { cause: 'awaiting-sampling-lag', severity: 'info' };
+  }
+
+  if (hasProducedBlocks) {
+    return { cause: 'validator-set-shrank', severity: 'warn' };
+  }
+
+  return { cause: 'awaiting-first-validators', severity: 'info' };
+}
+
+/**
+ * Given each candidate epoch after the one we failed to propose at, paired with the attester count staked at
+ * that epoch's validator-set sample time (`undefined` when the sample time is still in the future), returns
+ * the earliest epoch that will have a committee, or `undefined` if none qualifies.
+ *
+ * Candidates must be ordered ascending by epoch. A committee for epoch `E` exists iff at least
+ * `targetCommitteeSize` validators were staked at `E`'s sample time, so the first candidate whose sampled
+ * count meets the target is the answer; a candidate whose sample time is still in the future is assumed to
+ * have a committee if the set holds and wins as soon as it is reached. The predicate is not monotone in `E`
+ * (the set can dip below target between sample times), so this must scan ascending rather than binary-search.
+ */
+export function findFirstEpochWithCommittee(args: {
+  candidates: { epoch: EpochNumber; sampledAttesterCount: number | undefined }[];
+  targetCommitteeSize: number;
+}): EpochNumber | undefined {
+  return args.candidates.find(
+    c => c.sampledAttesterCount === undefined || c.sampledAttesterCount >= args.targetCommitteeSize,
+  )?.epoch;
+}
+
+/**
+ * Earliest epoch expected to have a committee, replaying L1's validator-set sampling rule: a committee for
+ * epoch `E` exists iff at least `targetCommitteeSize` attesters were staked at `E`'s sample time
+ * (`epochStart(E) - lag * epochDuration`). Only epochs after the one we failed at can qualify, and the set
+ * must have crossed the target within the last `lag` epochs' sample window, so the answer lies in
+ * `(targetEpoch, targetEpoch + lag + 1]`. Reads the historical attester count at each candidate's sample time
+ * (at most `lag` on-chain reads; future sample times are assumed to hold). Returns `undefined` if no candidate
+ * qualifies or the reads fail, leaving the caller to report a bound instead of an ETA.
+ */
+async function estimateFirstCommitteeEpoch(
+  targetEpoch: EpochNumber,
+  lag: number,
+  targetCommitteeSize: number,
+  ctx: MissingCommitteeContext,
+): Promise<EpochNumber | undefined> {
+  try {
+    const epochDurationSeconds = BigInt(ctx.l1Constants.epochDuration * ctx.l1Constants.slotDuration);
+    const nowSeconds = BigInt(ctx.dateProvider.nowInSeconds());
+    const candidates = await timesParallel(lag + 1, async i => {
+      const epoch = EpochNumber(targetEpoch + 1 + i);
+      const sampleTime = getStartTimestampForEpoch(epoch, ctx.l1Constants) - epochDurationSeconds * BigInt(lag);
+      const sampledAttesterCount =
+        sampleTime > nowSeconds ? undefined : await ctx.rollupContract.getAttesterCountAtTime(sampleTime);
+      return { epoch, sampledAttesterCount };
+    });
+    return findFirstEpochWithCommittee({ candidates, targetCommitteeSize });
+  } catch (err) {
+    ctx.logger.debug(`Could not estimate first committee epoch after epoch ${targetEpoch}`, { targetEpoch, err });
+    return undefined;
+  }
+}
+
+/** Formats the ETA to the start of the given epoch as ` (~12m from now)`, or empty if it is in the past. */
+function formatEpochEta(epoch: EpochNumber, ctx: MissingCommitteeContext): string {
+  const secondsUntil = Number(getStartTimestampForEpoch(epoch, ctx.l1Constants)) - ctx.dateProvider.nowInSeconds();
+  return secondsUntil > 0 ? ` (~${formatSeconds(secondsUntil)} from now)` : '';
+}

package/src/sequencer/requests_tracker.ts

@@ -0,0 +1,43 @@
+/** A tracked request: the awaitable to wait on, plus an optional interrupt to cancel it early. */
+type TrackedRequest = { promise: Promise<unknown>; interrupt?: () => void };
+
+/**
+ * Tracks fire-and-forget requests so a shutdown path can interrupt any in-flight work and await it to
+ * settle. Each tracked request is a promise plus an optional interrupt callback; the entry removes itself
+ * from the bag once its promise settles, so the tracker only ever holds requests that are still in flight.
+ */
+export class RequestsTracker {
+  private readonly requests = new Map<number, TrackedRequest>();
+  private nextId = 0;
+
+  /** Number of in-flight requests currently tracked. */
+  public get size(): number {
+    return this.requests.size;
+  }
+
+  /**
+   * Tracks a fire-and-forget request. `interrupt`, when provided, is invoked by {@link interruptRequests}
+   * to cancel the in-flight work so its promise settles promptly. The entry auto-removes once `promise`
+   * settles, whether it resolves or rejects.
+   */
+  public trackRequest(promise: Promise<unknown>, interrupt?: () => void): void {
+    const id = this.nextId++;
+    const settled = promise.then(
+      () => this.requests.delete(id),
+      () => this.requests.delete(id),
+    );
+    this.requests.set(id, { promise: settled, interrupt });
+  }
+
+  /** Interrupts every in-flight request that was tracked with an interrupt callback. */
+  public interruptRequests(): void {
+    for (const { interrupt } of this.requests.values()) {
+      interrupt?.();
+    }
+  }
+
+  /** Awaits every currently in-flight request to settle. */
+  public async awaitRequests(): Promise<void> {
+    await Promise.all([...this.requests.values()].map(request => request.promise));
+  }
+}