@aztec/sequencer-client 3.0.0-nightly.20251221 → 3.0.0-nightly.20251223

package/src/sequencer/timetable.ts

@@ -1,13 +1,13 @@
 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 = 1;
+export const CHECKPOINT_INITIALIZATION_TIME = 1;
+export const CHECKPOINT_FINALIZATION_TIME = 1;
 
 export class SequencerTimetable {
   /**
@@ -22,19 +22,22 @@ export class SequencerTimetable {
    * 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 validating and processing a checkpoint after building it */
+  public readonly checkpointFinalizationTime: number = CHECKPOINT_FINALIZATION_TIME;
 
   /** Ethereum slot duration in seconds */
   public readonly ethereumSlotDuration: number;
@@ -42,18 +45,19 @@ 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;
+
   constructor(
     opts: {
       ethereumSlotDuration: number;
       aztecSlotDuration: number;
-      maxL1TxInclusionTimeIntoSlot: number;
-      attestationPropagationTime?: number;
+      l1PublishingTime: number;
+      p2pPropagationTime?: number;
+      blockDurationMs?: number;
       enforce: boolean;
     },
     private readonly metrics?: SequencerMetrics,
@@ -61,57 +65,57 @@ 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.minExecutionTime = MIN_EXECUTION_TIME;
     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.checkpointFinalizationTime = 0.5;
+      this.checkpointInitializationTime = 0.5;
     }
 
-    const allWorkToDo =
-      this.blockPrepareTime +
-      this.minExecutionTime * 2 +
-      this.attestationPropagationTime * 2 +
-      this.blockValidationTime +
-      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.checkpointInitializationTime +
+      this.minExecutionTime * 2 + // Execution and reexecution
+      this.checkpointFinalizationTime +
+      this.p2pPropagationTime * 2 + // Send proposal and receive attestations
+      this.l1PublishingTime; // Submit to L1
 
-    const initializeDeadline = this.aztecSlotDuration - allWorkToDo;
+    const initializeDeadline = this.aztecSlotDuration - minWorkToDo;
     this.initializeDeadline = initializeDeadline;
 
     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,
+      blockPrepareTime: this.checkpointInitializationTime,
+      p2pPropagationTime: this.p2pPropagationTime,
+      blockValidationTime: this.checkpointFinalizationTime,
       initializeDeadline: this.initializeDeadline,
       enforce: this.enforce,
-      allWorkToDo,
+      allWorkToDo: minWorkToDo,
     });
 
     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}).`,
+        `Block proposal initialize deadline cannot be negative (got ${initializeDeadline} from total time needed ${minWorkToDo} and a slot duration of ${this.aztecSlotDuration}).`,
       );
     }
   }
 
-  private get afterBlockBuildingTimeNeededWithoutReexec() {
-    return this.blockValidationTime + this.attestationPropagationTime * 2 + this.l1PublishingTime;
-  }
-
-  public getBlockProposalExecTimeEnd(secondsIntoSlot: number): number {
+  /** Deadline for a block proposal execution. Ensures we have enough time left for reexecution and publishing. */
+  public getProposerExecTimeEnd(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 afterBlockBuildingTimeNeededWithoutReexec =
+      this.checkpointFinalizationTime + this.p2pPropagationTime * 2 + this.l1PublishingTime;
+    const maxAllowed = this.aztecSlotDuration - afterBlockBuildingTimeNeededWithoutReexec;
     const available = maxAllowed - secondsIntoSlot;
     const executionTimeEnd = secondsIntoSlot + available / 2;
     this.log.debug(`Block proposal execution time deadline is ${executionTimeEnd}`, {
@@ -123,13 +127,11 @@ export class SequencerTimetable {
     return executionTimeEnd;
   }
 
-  private get afterBlockReexecTimeNeeded() {
-    return this.attestationPropagationTime + this.l1PublishingTime;
-  }
-
+  /** Deadline for block proposal reexecution. Ensures the proposer has enough time for publishing. */
   public getValidatorReexecTimeEnd(secondsIntoSlot?: number): number {
     // We need to leave for `afterBlockReexecTimeNeeded` seconds available.
-    const validationTimeEnd = this.aztecSlotDuration - this.afterBlockReexecTimeNeeded;
+    const afterBlockReexecTimeNeeded = this.p2pPropagationTime + this.l1PublishingTime;
+    const validationTimeEnd = this.aztecSlotDuration - afterBlockReexecTimeNeeded;
     this.log.debug(`Validator re-execution time deadline is ${validationTimeEnd}`, {
       secondsIntoSlot,
       validationTimeEnd,
@@ -152,13 +154,16 @@ export class SequencerTimetable {
       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.FINALIZING_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;
@@ -185,4 +190,34 @@ export class SequencerTimetable {
     this.metrics?.recordStateTransitionBufferMs(Math.floor(bufferSeconds * 1000), newState);
     this.log.trace(`Enough time to transition to ${newState}`, { maxAllowedTime, secondsIntoSlot });
   }
+
+  /**
+   * Get timing information for building blocks within a slot.
+   * @param secondsIntoSlot - Current seconds into the slot
+   * @returns Object containing:
+   *   - canStart: boolean - Whether there's time to start a block now
+   *   - deadline: number - Deadline (seconds into slot) for building the block
+   *   - isLastBlock: boolean - Whether the next block would be the last one in the checkpoint
+   */
+  public canStartNextBlock(secondsIntoSlot: number): {
+    canStart: boolean;
+    deadline: number | undefined;
+    isLastBlock: boolean;
+  } {
+    const minExecutionTime = this.minExecutionTime;
+    const deadline = this.enforce ? this.getProposerExecTimeEnd(secondsIntoSlot) : undefined;
+
+    // Always allow to start if we don't enforce the timetable
+    const canStart = !this.enforce || deadline === undefined || deadline - secondsIntoSlot >= minExecutionTime;
+
+    // Single block per slot
+    if (this.blockDuration === undefined) {
+      this.log.debug(`${canStart ? 'Can' : 'Cannot'} start single-block checkpoint at ${secondsIntoSlot}s into slot`);
+      return { deadline, canStart, isLastBlock: true };
+    }
+
+    // Multiple blocks per slot
+    // TODO(palla/mbps) Implement me
+    return { deadline, canStart, isLastBlock: true };
+  }
 }

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

@@ -9,22 +9,31 @@ export enum SequencerState {
   SYNCHRONIZING = 'SYNCHRONIZING',
   /** 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',
+  /** Finalizing and broadcasting the checkpoint. */
+  FINALIZING_CHECKPOINT = 'FINALIZING_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.FINALIZING_CHECKPOINT;
 
 export type SequencerStateCallback = () => SequencerState;
 

package/src/test/index.ts

@@ -6,6 +6,7 @@ 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_;