@aztec/sequencer-client 4.0.0-nightly.20250907 → 4.0.0-nightly.20260108

package/src/sequencer/timetable.ts

@@ -1,12 +1,13 @@
-import { createLogger } from '@aztec/aztec.js';
+import { createLogger } from '@aztec/aztec.js/log';
 
-import { DEFAULT_ATTESTATION_PROPAGATION_TIME } from '../config.js';
+import { DEFAULT_ATTESTATION_PROPAGATION_TIME as DEFAULT_P2P_PROPAGATION_TIME } from '../config.js';
+import { SequencerTooSlowError } from './errors.js';
 import type { SequencerMetrics } from './metrics.js';
 import { SequencerState } from './utils.js';
 
-const MIN_EXECUTION_TIME = 1;
-const BLOCK_PREPARE_TIME = 1;
-const BLOCK_VALIDATION_TIME = 1;
+export const MIN_EXECUTION_TIME = 2;
+export const CHECKPOINT_INITIALIZATION_TIME = 1;
+export const CHECKPOINT_ASSEMBLE_TIME = 1;
 
 export class SequencerTimetable {
   /**
@@ -16,24 +17,42 @@ export class SequencerTimetable {
    */
   public readonly initializeDeadline: number;
 
+  /**
+   * Fixed time offset (in seconds) when the first sub-slot starts, used as baseline for all block deadlines.
+   * This is an estimate of how long initialization (sync + proposer check) typically takes.
+   * If actual initialization takes longer/shorter, blocks just get less/more time accordingly.
+   */
+  public readonly initializationOffset: number;
+
+  /**
+   * Total time needed to finalize and publish a checkpoint, including:
+   * - Assembling the checkpoint
+   * - Round-trip p2p propagation for the checkpoint proposal and its corresponding attestations
+   * - Publishing to L1
+   */
+  public readonly checkpointFinalizationTime: number;
+
   /**
    * How long it takes to get a published block into L1. L1 builders typically accept txs up to 4 seconds into their slot,
    * but we'll timeout sooner to give it more time to propagate (remember we also have blobs!). Still, when working in anvil,
    * we can just post in the very last second of the L1 slot and still expect the tx to be accepted.
    */
-  public readonly l1PublishingTime;
+  public readonly l1PublishingTime: number;
 
-  /** What's the minimum time we want to leave available for execution and reexecution (used to derive init deadline) */
+  /**
+   * What's the minimum time we want to leave available for execution and reexecution (used to derive init deadline)
+   * Defaults to half of the block duration if set, otherwise a constant.
+   */
   public readonly minExecutionTime: number = MIN_EXECUTION_TIME;
 
   /** How long it takes to get ready to start building */
-  public readonly blockPrepareTime: number = BLOCK_PREPARE_TIME;
+  public readonly checkpointInitializationTime: number = CHECKPOINT_INITIALIZATION_TIME;
 
   /** How long it takes to for proposals and attestations to travel across the p2p layer (one-way) */
-  public readonly attestationPropagationTime: number;
+  public readonly p2pPropagationTime: number;
 
-  /** How much time we spend validating and processing a block after building it, and assembling the proposal to send to attestors */
-  public readonly blockValidationTime: number = BLOCK_VALIDATION_TIME;
+  /** How much time we spend assembling a checkpoint after building the last block */
+  public readonly checkpointAssembleTime: number = CHECKPOINT_ASSEMBLE_TIME;
 
   /** Ethereum slot duration in seconds */
   public readonly ethereumSlotDuration: number;
@@ -41,18 +60,22 @@ export class SequencerTimetable {
   /** Aztec slot duration in seconds (must be multiple of ethereum slot duration) */
   public readonly aztecSlotDuration: number;
 
-  /** How late into an L1 slot we can send a tx to make sure it gets included in the immediate next block. Complement of l1PublishingTime. */
-  public readonly maxL1TxInclusionTimeIntoSlot: number;
-
   /** Whether assertTimeLeft will throw if not enough time. */
   public readonly enforce: boolean;
 
+  /** Duration per block when building multiple blocks per slot (undefined = single block per slot) */
+  public readonly blockDuration: number | undefined;
+
+  /** Maximum number of blocks that can be built in this slot configuration */
+  public readonly maxNumberOfBlocks: number;
+
   constructor(
     opts: {
       ethereumSlotDuration: number;
       aztecSlotDuration: number;
-      maxL1TxInclusionTimeIntoSlot: number;
-      attestationPropagationTime?: number;
+      l1PublishingTime: number;
+      p2pPropagationTime?: number;
+      blockDurationMs?: number;
       enforce: boolean;
     },
     private readonly metrics?: SequencerMetrics,
@@ -60,96 +83,104 @@ export class SequencerTimetable {
   ) {
     this.ethereumSlotDuration = opts.ethereumSlotDuration;
     this.aztecSlotDuration = opts.aztecSlotDuration;
-    this.maxL1TxInclusionTimeIntoSlot = opts.maxL1TxInclusionTimeIntoSlot;
-    this.attestationPropagationTime = opts.attestationPropagationTime ?? DEFAULT_ATTESTATION_PROPAGATION_TIME;
-    this.l1PublishingTime = this.ethereumSlotDuration - this.maxL1TxInclusionTimeIntoSlot;
+    this.l1PublishingTime = opts.l1PublishingTime;
+    this.p2pPropagationTime = opts.p2pPropagationTime ?? DEFAULT_P2P_PROPAGATION_TIME;
+    this.blockDuration = opts.blockDurationMs ? opts.blockDurationMs / 1000 : undefined;
     this.enforce = opts.enforce;
 
     // Assume zero-cost propagation time and faster runs in test environments where L1 slot duration is shortened
     if (this.ethereumSlotDuration < 8) {
-      this.attestationPropagationTime = 0;
-      this.blockValidationTime = 0.5;
-      this.blockPrepareTime = 0.5;
+      this.p2pPropagationTime = 0;
+      this.checkpointAssembleTime = 0.5;
+      this.checkpointInitializationTime = 0.5;
+      this.minExecutionTime = 1;
     }
 
-    const allWorkToDo =
-      this.blockPrepareTime +
-      this.minExecutionTime * 2 +
-      this.attestationPropagationTime * 2 +
-      this.blockValidationTime +
-      this.l1PublishingTime;
+    // Min execution time cannot be less than the block duration if set
+    if (this.blockDuration !== undefined && this.minExecutionTime > this.blockDuration) {
+      this.minExecutionTime = this.blockDuration;
+    }
 
-    const initializeDeadline = this.aztecSlotDuration - allWorkToDo;
-    this.initializeDeadline = initializeDeadline;
+    // Calculate initialization offset - estimate of time needed for sync + proposer check
+    // This is the baseline for all sub-slot deadlines
+    this.initializationOffset = this.checkpointInitializationTime;
 
-    this.log.verbose(`Sequencer timetable initialized (${this.enforce ? 'enforced' : 'not enforced'})`, {
-      ethereumSlotDuration: this.ethereumSlotDuration,
-      aztecSlotDuration: this.aztecSlotDuration,
-      maxL1TxInclusionTimeIntoSlot: this.maxL1TxInclusionTimeIntoSlot,
-      l1PublishingTime: this.l1PublishingTime,
-      minExecutionTime: this.minExecutionTime,
-      blockPrepareTime: this.blockPrepareTime,
-      attestationPropagationTime: this.attestationPropagationTime,
-      blockValidationTime: this.blockValidationTime,
-      initializeDeadline: this.initializeDeadline,
-      enforce: this.enforce,
-      allWorkToDo,
-    });
+    // Calculate total checkpoint finalization time (assembly + attestations + L1 publishing)
+    this.checkpointFinalizationTime =
+      this.checkpointAssembleTime +
+      this.p2pPropagationTime * 2 + // Round-trip propagation
+      this.l1PublishingTime; // L1 publishing
 
-    if (initializeDeadline <= 0) {
-      throw new Error(
-        `Block proposal initialize deadline cannot be negative (got ${initializeDeadline} from total time needed ${allWorkToDo} and a slot duration of ${this.aztecSlotDuration}).`,
-      );
+    // Calculate maximum number of blocks that fit in this slot
+    if (!this.blockDuration) {
+      this.maxNumberOfBlocks = 1; // Single block per slot
+    } else {
+      const timeReservedAtEnd =
+        this.blockDuration + // Last sub-slot for validator re-execution
+        this.checkpointFinalizationTime; // Checkpoint finalization
+      const timeAvailableForBlocks = this.aztecSlotDuration - this.initializationOffset - timeReservedAtEnd;
+      this.maxNumberOfBlocks = Math.floor(timeAvailableForBlocks / this.blockDuration);
     }
-  }
 
-  private get afterBlockBuildingTimeNeededWithoutReexec() {
-    return this.blockValidationTime + this.attestationPropagationTime * 2 + this.l1PublishingTime;
-  }
+    // Minimum work to do within a slot for building a block with the minimum time for execution and publishing its checkpoint
+    const minWorkToDo =
+      this.initializationOffset +
+      this.minExecutionTime * 2 + // Execution and reexecution
+      this.checkpointFinalizationTime;
 
-  public getBlockProposalExecTimeEnd(secondsIntoSlot: number): number {
-    // We are N seconds into the slot. We need to account for `afterBlockBuildingTimeNeededWithoutReexec` seconds,
-    // send then split the remaining time between the re-execution and the block building.
-    const maxAllowed = this.aztecSlotDuration - this.afterBlockBuildingTimeNeededWithoutReexec;
-    const available = maxAllowed - secondsIntoSlot;
-    const executionTimeEnd = secondsIntoSlot + available / 2;
-    this.log.debug(`Block proposal execution time deadline is ${executionTimeEnd}`, {
-      secondsIntoSlot,
-      maxAllowed,
-      available,
-      executionTimeEnd,
-    });
-    return executionTimeEnd;
-  }
+    const initializeDeadline = this.aztecSlotDuration - minWorkToDo;
+    this.initializeDeadline = initializeDeadline;
 
-  private get afterBlockReexecTimeNeeded() {
-    return this.attestationPropagationTime + this.l1PublishingTime;
-  }
+    this.log.verbose(
+      `Sequencer timetable initialized with ${this.maxNumberOfBlocks} blocks per slot (${this.enforce ? 'enforced' : 'not enforced'})`,
+      {
+        ethereumSlotDuration: this.ethereumSlotDuration,
+        aztecSlotDuration: this.aztecSlotDuration,
+        l1PublishingTime: this.l1PublishingTime,
+        minExecutionTime: this.minExecutionTime,
+        blockPrepareTime: this.checkpointInitializationTime,
+        p2pPropagationTime: this.p2pPropagationTime,
+        blockAssembleTime: this.checkpointAssembleTime,
+        initializeDeadline: this.initializeDeadline,
+        enforce: this.enforce,
+        minWorkToDo,
+        blockDuration: this.blockDuration,
+        maxNumberOfBlocks: this.maxNumberOfBlocks,
+      },
+    );
 
-  public getValidatorReexecTimeEnd(secondsIntoSlot?: number): number {
-    // We need to leave for `afterBlockReexecTimeNeeded` seconds available.
-    const validationTimeEnd = this.aztecSlotDuration - this.afterBlockReexecTimeNeeded;
-    this.log.debug(`Validator re-execution time deadline is ${validationTimeEnd}`, {
-      secondsIntoSlot,
-      validationTimeEnd,
-    });
-    return validationTimeEnd;
+    if (initializeDeadline <= 0) {
+      throw new Error(
+        `Block proposal initialize deadline cannot be negative (got ${initializeDeadline} from total time needed ${minWorkToDo} and a slot duration of ${this.aztecSlotDuration}).`,
+      );
+    }
   }
 
+  public getMaxAllowedTime(
+    state: Extract<SequencerState, SequencerState.STOPPED | SequencerState.IDLE | SequencerState.SYNCHRONIZING>,
+  ): undefined;
+  public getMaxAllowedTime(
+    state: Exclude<SequencerState, SequencerState.STOPPED | SequencerState.IDLE | SequencerState.SYNCHRONIZING>,
+  ): number;
+  public getMaxAllowedTime(state: SequencerState): number | undefined;
   public getMaxAllowedTime(state: SequencerState): number | undefined {
     switch (state) {
       case SequencerState.STOPPED:
+      case SequencerState.STOPPING:
       case SequencerState.IDLE:
       case SequencerState.SYNCHRONIZING:
         return; // We don't really care about times for this states
       case SequencerState.PROPOSER_CHECK:
-      case SequencerState.INITIALIZING_PROPOSAL:
+      case SequencerState.INITIALIZING_CHECKPOINT:
         return this.initializeDeadline;
+      case SequencerState.WAITING_FOR_TXS:
       case SequencerState.CREATING_BLOCK:
-        return this.initializeDeadline + this.blockPrepareTime;
+      case SequencerState.WAITING_UNTIL_NEXT_BLOCK:
+        return this.initializeDeadline + this.checkpointInitializationTime;
+      case SequencerState.ASSEMBLING_CHECKPOINT:
       case SequencerState.COLLECTING_ATTESTATIONS:
-        return this.aztecSlotDuration - this.l1PublishingTime - 2 * this.attestationPropagationTime;
-      case SequencerState.PUBLISHING_BLOCK:
+        return this.aztecSlotDuration - this.l1PublishingTime - 2 * this.p2pPropagationTime;
+      case SequencerState.PUBLISHING_CHECKPOINT:
         return this.aztecSlotDuration - this.l1PublishingTime;
       default: {
         const _exhaustiveCheck: never = state;
@@ -176,17 +207,76 @@ export class SequencerTimetable {
     this.metrics?.recordStateTransitionBufferMs(Math.floor(bufferSeconds * 1000), newState);
     this.log.trace(`Enough time to transition to ${newState}`, { maxAllowedTime, secondsIntoSlot });
   }
-}
 
-export class SequencerTooSlowError extends Error {
-  constructor(
-    public readonly proposedState: SequencerState,
-    public readonly maxAllowedTime: number,
-    public readonly currentTime: number,
-  ) {
-    super(
-      `Too far into slot for ${proposedState} (time into slot ${currentTime}s greater than ${maxAllowedTime}s allowance)`,
-    );
-    this.name = 'SequencerTooSlowError';
+  /**
+   * Determines if we can start building the next block and returns its deadline.
+   *
+   * The timetable divides the slot into fixed sub-slots. This method finds the next
+   * available sub-slot that has enough time remaining to build a block.
+   *
+   * @param secondsIntoSlot - Current time (seconds into the slot)
+   * @returns Object with canStart flag, deadline, and whether this is the last block
+   */
+  public canStartNextBlock(
+    secondsIntoSlot: number,
+  ):
+    | { canStart: true; deadline: undefined; isLastBlock: true }
+    | { canStart: false; deadline: undefined; isLastBlock: false }
+    | { canStart: boolean; deadline: number; isLastBlock: boolean } {
+    // When timetable enforcement is disabled, always allow starting,
+    // and build a single block with no deadline. This is here just to
+    // satisfy a subset of e2e tests and the sandbox that assume that the
+    // sequencer is permanently mining every tx sent.
+    if (!this.enforce) {
+      return { canStart: true, deadline: undefined, isLastBlock: true };
+    }
+
+    // If no block duration is set, then we're in single-block mode, which
+    // is handled for backwards compatibility towards another subset of e2e tests.
+    if (this.blockDuration === undefined) {
+      // In single block mode, execution and re-execution happen sequentially, so we need to
+      // split the available time between them. After building, we need time for attestations and L1.
+      const maxAllowed = this.aztecSlotDuration - this.checkpointFinalizationTime;
+      const available = (maxAllowed - secondsIntoSlot) / 2; // Split remaining time: half for execution, half for re-execution
+      const canStart = available >= this.minExecutionTime;
+      const deadline = secondsIntoSlot + available;
+
+      this.log.verbose(
+        `${canStart ? 'Can' : 'Cannot'} start single-block checkpoint at ${secondsIntoSlot}s into slot`,
+        { secondsIntoSlot, maxAllowed, available, deadline },
+      );
+      return { canStart, deadline, isLastBlock: true };
+    }
+
+    // Otherwise, we're in multi-block-per-slot mode, the default when running in production
+    // Find the next available sub-slot that has enough time remaining
+    for (let subSlot = 1; subSlot <= this.maxNumberOfBlocks; subSlot++) {
+      // Calculate end for this sub-slot
+      const deadline = this.initializationOffset + subSlot * this.blockDuration;
+
+      // Check if we have enough time to build a block with this deadline
+      const timeUntilDeadline = deadline - secondsIntoSlot;
+
+      if (timeUntilDeadline >= this.minExecutionTime) {
+        // Found an available sub-slot! Is this the last one?
+        const isLastBlock = subSlot === this.maxNumberOfBlocks;
+
+        this.log.verbose(
+          `Can start ${isLastBlock ? 'last block' : 'block'} in sub-slot ${subSlot} with deadline ${deadline}s`,
+          { secondsIntoSlot, deadline, timeUntilDeadline, subSlot, maxBlocks: this.maxNumberOfBlocks },
+        );
+
+        return { canStart: true, deadline, isLastBlock };
+      }
+    }
+
+    // No sub-slots available with enough time
+    this.log.verbose(`No time left to start any more blocks`, {
+      secondsIntoSlot,
+      maxBlocks: this.maxNumberOfBlocks,
+      initializationOffset: this.initializationOffset,
+    });
+
+    return { canStart: false, deadline: undefined, isLastBlock: false };
   }
 }

package/src/sequencer/types.ts

@@ -0,0 +1,6 @@
+import type { L1RollupConstants } from '@aztec/stdlib/epoch-helpers';
+
+export type SequencerRollupConstants = Pick<
+  L1RollupConstants,
+  'ethereumSlotDuration' | 'l1GenesisTime' | 'slotDuration'
+>;

package/src/sequencer/utils.ts

@@ -1,44 +1,39 @@
 export enum SequencerState {
-  /**
-   * Sequencer is stopped and not processing any txs from the pool.
-   */
+  /** Sequencer is stopped and not processing any txs from the pool. */
   STOPPED = 'STOPPED',
-  /**
-   * Sequencer is awaiting the next call to work().
-   */
+  /** Sequencer is being stopped. Will move to STOPPED shortly. */
+  STOPPING = 'STOPPING',
+  /** Sequencer is awaiting the next call to work(). */
   IDLE = 'IDLE',
-  /**
-   * Synchronizing with the L2 chain.
-   */
+  /** Synchronizing with the L2 chain. */
   SYNCHRONIZING = 'SYNCHRONIZING',
-  /**
-   * Checking if we are the proposer for the current slot.
-   */
+  /** Checking if we are the proposer for the current slot. */
   PROPOSER_CHECK = 'PROPOSER_CHECK',
-  /**
-   * Initializing the block proposal. Will move to CREATING_BLOCK if there are valid txs to include, or back to SYNCHRONIZING otherwise.
-   */
-  INITIALIZING_PROPOSAL = 'INITIALIZING_PROPOSAL',
-  /**
-   * Creating a new L2 block. Includes processing public function calls and running rollup circuits. Will move to PUBLISHING_CONTRACT_DATA.
-   */
+  /** Initializing the checkpoint proposal. */
+  INITIALIZING_CHECKPOINT = 'INITIALIZING_CHECKPOINT',
+  /** Waiting for transactions to arrive in the pool. */
+  WAITING_FOR_TXS = 'WAITING_FOR_TXS',
+  /** Creating a new L2 block. Includes processing public function calls. */
   CREATING_BLOCK = 'CREATING_BLOCK',
-  /**
-   * Collecting attestations from its peers. Will move to PUBLISHING_BLOCK.
-   */
+  /** Waiting until the next block can be created. */
+  WAITING_UNTIL_NEXT_BLOCK = 'WAITING_UNTIL_NEXT_BLOCK',
+  /** Assembling and broadcasting the checkpoint. */
+  ASSEMBLING_CHECKPOINT = 'ASSEMBLING_CHECKPOINT',
+  /** Collecting attestations from its peers. */
   COLLECTING_ATTESTATIONS = 'COLLECTING_ATTESTATIONS',
-  /**
-   * Sending the tx to L1 with the L2 block data and awaiting it to be mined. Will move to SYNCHRONIZING.
-   */
-  PUBLISHING_BLOCK = 'PUBLISHING_BLOCK',
+  /** Sending the tx to L1 with the L2 checkpoint data and awaiting it to be mined.. */
+  PUBLISHING_CHECKPOINT = 'PUBLISHING_CHECKPOINT',
 }
 
 export type SequencerStateWithSlot =
-  | SequencerState.INITIALIZING_PROPOSAL
+  | SequencerState.INITIALIZING_CHECKPOINT
+  | SequencerState.WAITING_FOR_TXS
   | SequencerState.CREATING_BLOCK
+  | SequencerState.WAITING_UNTIL_NEXT_BLOCK
   | SequencerState.COLLECTING_ATTESTATIONS
-  | SequencerState.PUBLISHING_BLOCK
-  | SequencerState.PROPOSER_CHECK;
+  | SequencerState.PUBLISHING_CHECKPOINT
+  | SequencerState.PROPOSER_CHECK
+  | SequencerState.ASSEMBLING_CHECKPOINT;
 
 export type SequencerStateCallback = () => SequencerState;
 

package/src/test/index.ts

@@ -1,11 +1,12 @@
-import type { PublisherManager } from '@aztec/ethereum';
 import type { L1TxUtilsWithBlobs } from '@aztec/ethereum/l1-tx-utils-with-blobs';
+import type { PublisherManager } from '@aztec/ethereum/publisher-manager';
 import type { PublicProcessorFactory } from '@aztec/simulator/server';
 import type { ValidatorClient } from '@aztec/validator-client';
 
 import { SequencerClient } from '../client/sequencer-client.js';
 import type { SequencerPublisherFactory } from '../publisher/sequencer-publisher-factory.js';
 import type { SequencerPublisher } from '../publisher/sequencer-publisher.js';
+import type { FullNodeCheckpointsBuilder } from '../sequencer/checkpoint_builder.js';
 import { Sequencer } from '../sequencer/sequencer.js';
 import type { SequencerTimetable } from '../sequencer/timetable.js';
 
@@ -15,6 +16,7 @@ class TestSequencer_ extends Sequencer {
   declare public publisher: SequencerPublisher;
   declare public publisherFactory: SequencerPublisherFactory;
   declare public validatorClient: ValidatorClient;
+  declare public checkpointsBuilder: FullNodeCheckpointsBuilder;
 }
 
 export type TestSequencer = TestSequencer_;