@aztec/sequencer-client 0.0.0-test.1 → 0.0.1-commit.0b941701

package/src/sequencer/timetable.ts

@@ -1,86 +1,186 @@
-import { createLogger } from '@aztec/aztec.js';
+import { createLogger } from '@aztec/aztec.js/log';
 
+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';
 
-export class SequencerTimetable {
-  /** How late into the slot can we be to start working */
-  public readonly initialTime = 3;
+export const MIN_EXECUTION_TIME = 2;
+export const CHECKPOINT_INITIALIZATION_TIME = 1;
+export const CHECKPOINT_ASSEMBLE_TIME = 1;
 
-  /** How long it takes to get ready to start building */
-  public readonly blockPrepareTime = 1;
+export class SequencerTimetable {
+  /**
+   * How late into the slot can we be to start working. Computed as the total time needed for assembling and publishing a block,
+   * assuming an execution time equal to `minExecutionTime`, subtracted from the slot duration. This means that, if the proposer
+   * starts building at this time, and all times hold, it will have at least `minExecutionTime` to execute txs for the block.
+   */
+  public readonly initializeDeadline: number;
 
-  /** How long it takes to for proposals and attestations to travel across the p2p layer (one-way) */
-  public readonly attestationPropagationTime = 2;
+  /**
+   * 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;
 
-  /** How much time we spend validating and processing a block after building it, and assembling the proposal to send to attestors */
-  public readonly blockValidationTime = 1;
+  /**
+   * 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)
+   * 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 checkpointInitializationTime: number = CHECKPOINT_INITIALIZATION_TIME;
+
+  /** How long it takes to for proposals and attestations to travel across the p2p layer (one-way) */
+  public readonly p2pPropagationTime: number;
+
+  /** 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;
+
+  /** Aztec slot duration in seconds (must be multiple of ethereum slot duration) */
+  public readonly aztecSlotDuration: 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(
-    private readonly ethereumSlotDuration: number,
-    private readonly aztecSlotDuration: number,
-    private readonly maxL1TxInclusionTimeIntoSlot: number,
-    private readonly enforce: boolean = true,
+    opts: {
+      ethereumSlotDuration: number;
+      aztecSlotDuration: number;
+      l1PublishingTime: number;
+      p2pPropagationTime?: number;
+      blockDurationMs?: number;
+      enforce: boolean;
+    },
     private readonly metrics?: SequencerMetrics,
     private readonly log = createLogger('sequencer:timetable'),
   ) {
-    this.l1PublishingTime = this.ethereumSlotDuration - this.maxL1TxInclusionTimeIntoSlot;
-  }
+    this.ethereumSlotDuration = opts.ethereumSlotDuration;
+    this.aztecSlotDuration = opts.aztecSlotDuration;
+    this.l1PublishingTime = opts.l1PublishingTime;
+    this.p2pPropagationTime = opts.p2pPropagationTime ?? DEFAULT_P2P_PROPAGATION_TIME;
+    this.blockDuration = opts.blockDurationMs ? opts.blockDurationMs / 1000 : undefined;
+    this.enforce = opts.enforce;
 
-  private get afterBlockBuildingTimeNeededWithoutReexec() {
-    return this.blockValidationTime + this.attestationPropagationTime * 2 + this.l1PublishingTime;
-  }
+    // Assume zero-cost propagation time and faster runs in test environments where L1 slot duration is shortened
+    if (this.ethereumSlotDuration < 8) {
+      this.p2pPropagationTime = 0;
+      this.checkpointAssembleTime = 0.5;
+      this.checkpointInitializationTime = 0.5;
+      this.minExecutionTime = 1;
+    }
 
-  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;
-  }
+    // Min execution time cannot be less than the block duration if set
+    if (this.blockDuration !== undefined && this.minExecutionTime > this.blockDuration) {
+      this.minExecutionTime = this.blockDuration;
+    }
 
-  private get afterBlockReexecTimeNeeded() {
-    return this.attestationPropagationTime + this.l1PublishingTime;
-  }
+    // Calculate initialization offset - estimate of time needed for sync + proposer check
+    // This is the baseline for all sub-slot deadlines
+    this.initializationOffset = this.checkpointInitializationTime;
 
-  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;
+    // Calculate total checkpoint finalization time (assembly + attestations + L1 publishing)
+    this.checkpointFinalizationTime =
+      this.checkpointAssembleTime +
+      this.p2pPropagationTime * 2 + // Round-trip propagation
+      this.l1PublishingTime; // L1 publishing
+
+    // 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);
+    }
+
+    // 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;
+
+    const initializeDeadline = this.aztecSlotDuration - minWorkToDo;
+    this.initializeDeadline = initializeDeadline;
+
+    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,
+      },
+    );
+
+    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:
-      case SequencerState.PROPOSER_CHECK:
         return; // We don't really care about times for this states
-      case SequencerState.INITIALIZING_PROPOSAL:
-        return this.initialTime;
+      case SequencerState.PROPOSER_CHECK:
+      case SequencerState.INITIALIZING_CHECKPOINT:
+        return this.initializeDeadline;
+      case SequencerState.WAITING_FOR_TXS:
       case SequencerState.CREATING_BLOCK:
-        return this.initialTime + 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;
@@ -107,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,74 +1,42 @@
-import type { EthAddress } from '@aztec/foundation/eth-address';
-import { Signature } from '@aztec/foundation/eth-signature';
-import type { BlockAttestation } from '@aztec/stdlib/p2p';
-
 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_CHECKPOINT
+  | SequencerState.WAITING_FOR_TXS
+  | SequencerState.CREATING_BLOCK
+  | SequencerState.WAITING_UNTIL_NEXT_BLOCK
+  | SequencerState.COLLECTING_ATTESTATIONS
+  | SequencerState.PUBLISHING_CHECKPOINT
+  | SequencerState.PROPOSER_CHECK
+  | SequencerState.ASSEMBLING_CHECKPOINT;
+
 export type SequencerStateCallback = () => SequencerState;
 
 export function sequencerStateToNumber(state: SequencerState): number {
   return Object.values(SequencerState).indexOf(state);
 }
-
-/** Order Attestations
- *
- * Returns attestation signatures in the order of a series of provided ethereum addresses
- * The rollup smart contract expects attestations to appear in the order of the committee
- *
- * @todo: perform this logic within the memory attestation store instead?
- */
-export async function orderAttestations(
-  attestations: BlockAttestation[],
-  orderAddresses: EthAddress[],
-): Promise<Signature[]> {
-  // Create a map of sender addresses to BlockAttestations
-  const attestationMap = new Map<string, BlockAttestation>();
-
-  for (const attestation of attestations) {
-    const sender = await attestation.getSender();
-    if (sender) {
-      attestationMap.set(sender.toString(), attestation);
-    }
-  }
-
-  // Create the ordered array based on the orderAddresses, else return an empty signature
-  const orderedAttestations = orderAddresses.map(address => {
-    const addressString = address.toString();
-    return attestationMap.get(addressString)?.signature || Signature.empty();
-  });
-
-  return orderedAttestations;
-}

package/src/test/index.ts

@@ -1,20 +1,28 @@
+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 { FullNodeCheckpointsBuilder, 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 { Sequencer } from '../sequencer/sequencer.js';
 import type { SequencerTimetable } from '../sequencer/timetable.js';
 
 class TestSequencer_ extends Sequencer {
-  public override publicProcessorFactory!: PublicProcessorFactory;
-  public override timetable!: SequencerTimetable;
-  public override publisher!: SequencerPublisher;
+  declare public publicProcessorFactory: PublicProcessorFactory;
+  declare public timetable: SequencerTimetable;
+  declare public publisher: SequencerPublisher;
+  declare public publisherFactory: SequencerPublisherFactory;
+  declare public validatorClient: ValidatorClient;
+  declare public checkpointsBuilder: FullNodeCheckpointsBuilder;
 }
 
 export type TestSequencer = TestSequencer_;
 
 class TestSequencerClient_ extends SequencerClient {
-  public override sequencer!: TestSequencer;
+  declare public sequencer: TestSequencer;
+  declare public publisherManager: PublisherManager<L1TxUtilsWithBlobs>;
 }
 
 export type TestSequencerClient = TestSequencerClient_;