@aztec/sequencer-client 3.0.0-rc.5 → 4.0.0-nightly.20260107

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 = 2;
+export const CHECKPOINT_INITIALIZATION_TIME = 1;
+export const CHECKPOINT_ASSEMBLE_TIME = 1;
 
 export class SequencerTimetable {
   /**
@@ -17,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;
@@ -42,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,
@@ -61,80 +83,77 @@ 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(
@@ -152,13 +171,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.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;
@@ -185,4 +207,76 @@ export class SequencerTimetable {
     this.metrics?.recordStateTransitionBufferMs(Math.floor(bufferSeconds * 1000), newState);
     this.log.trace(`Enough time to transition to ${newState}`, { maxAllowedTime, secondsIntoSlot });
   }
+
+  /**
+   * 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

@@ -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',
+  /** 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

@@ -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_;

package/src/test/mock_checkpoint_builder.ts

@@ -0,0 +1,247 @@
+import { type BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { Timer } from '@aztec/foundation/timer';
+import type { FunctionsOf } from '@aztec/foundation/types';
+import { L2BlockNew } from '@aztec/stdlib/block';
+import { Checkpoint } from '@aztec/stdlib/checkpoint';
+import { Gas } from '@aztec/stdlib/gas';
+import type { FullNodeBlockBuilderConfig, PublicProcessorLimits } from '@aztec/stdlib/interfaces/server';
+import { CheckpointHeader } from '@aztec/stdlib/rollup';
+import { makeAppendOnlyTreeSnapshot } from '@aztec/stdlib/testing';
+import type { CheckpointGlobalVariables, Tx } from '@aztec/stdlib/tx';
+
+import type {
+  BuildBlockInCheckpointResult,
+  CheckpointBuilder,
+  FullNodeCheckpointsBuilder,
+} from '../sequencer/checkpoint_builder.js';
+
+/**
+ * A fake CheckpointBuilder for testing that implements the same interface as the real one.
+ * Can be seeded with blocks to return sequentially on each `buildBlock` call.
+ */
+export class MockCheckpointBuilder implements FunctionsOf<CheckpointBuilder> {
+  private blocks: L2BlockNew[] = [];
+  private builtBlocks: L2BlockNew[] = [];
+  private usedTxsPerBlock: Tx[][] = [];
+  private blockIndex = 0;
+
+  /** Optional function to dynamically provide the block (alternative to seedBlocks) */
+  private blockProvider: (() => L2BlockNew) | undefined = undefined;
+
+  /** Track calls for assertions */
+  public buildBlockCalls: Array<{
+    blockNumber: BlockNumber;
+    timestamp: bigint;
+    opts: PublicProcessorLimits;
+  }> = [];
+  public completeCheckpointCalled = false;
+  public getCheckpointCalled = false;
+
+  /** Set to an error to make buildBlock throw on next call */
+  public errorOnBuild: Error | undefined = undefined;
+
+  constructor(
+    private readonly constants: CheckpointGlobalVariables,
+    private readonly checkpointNumber: CheckpointNumber,
+  ) {}
+
+  /** Seed the builder with blocks to return on successive buildBlock calls */
+  seedBlocks(blocks: L2BlockNew[], usedTxsPerBlock?: Tx[][]): this {
+    this.blocks = blocks;
+    this.usedTxsPerBlock = usedTxsPerBlock ?? blocks.map(() => []);
+    this.blockIndex = 0;
+    this.blockProvider = undefined;
+    return this;
+  }
+
+  /**
+   * Set a function that provides blocks dynamically.
+   * Useful for tests where the block is determined at call time (e.g., sequencer tests).
+   */
+  setBlockProvider(provider: () => L2BlockNew): this {
+    this.blockProvider = provider;
+    this.blocks = [];
+    return this;
+  }
+
+  getConstantData(): CheckpointGlobalVariables {
+    return this.constants;
+  }
+
+  buildBlock(
+    _pendingTxs: Iterable<Tx> | AsyncIterable<Tx>,
+    blockNumber: BlockNumber,
+    timestamp: bigint,
+    opts: PublicProcessorLimits,
+  ): Promise<BuildBlockInCheckpointResult> {
+    this.buildBlockCalls.push({ blockNumber, timestamp, opts });
+
+    if (this.errorOnBuild) {
+      return Promise.reject(this.errorOnBuild);
+    }
+
+    let block: L2BlockNew;
+    let usedTxs: Tx[];
+
+    if (this.blockProvider) {
+      // Dynamic mode: get block from provider
+      block = this.blockProvider();
+      usedTxs = [];
+      this.builtBlocks.push(block);
+    } else {
+      // Seeded mode: get block from pre-seeded list
+      block = this.blocks[this.blockIndex];
+      usedTxs = this.usedTxsPerBlock[this.blockIndex] ?? [];
+      this.blockIndex++;
+      this.builtBlocks.push(block);
+    }
+
+    return Promise.resolve({
+      block,
+      publicGas: Gas.empty(),
+      publicProcessorDuration: 0,
+      numTxs: block?.body?.txEffects?.length ?? usedTxs.length,
+      blockBuildingTimer: new Timer(),
+      usedTxs,
+      failedTxs: [],
+    });
+  }
+
+  completeCheckpoint(): Promise<Checkpoint> {
+    this.completeCheckpointCalled = true;
+    const allBlocks = this.blockProvider ? this.builtBlocks : this.blocks;
+    const lastBlock = allBlocks[allBlocks.length - 1];
+    // Create a CheckpointHeader from the last block's header for testing
+    const checkpointHeader = this.createCheckpointHeader(lastBlock);
+    return Promise.resolve(
+      new Checkpoint(
+        makeAppendOnlyTreeSnapshot(lastBlock.header.globalVariables.blockNumber + 1),
+        checkpointHeader,
+        allBlocks,
+        this.checkpointNumber,
+      ),
+    );
+  }
+
+  getCheckpoint(): Promise<Checkpoint> {
+    this.getCheckpointCalled = true;
+    const builtBlocks = this.blockProvider ? this.builtBlocks : this.blocks.slice(0, this.blockIndex);
+    const lastBlock = builtBlocks[builtBlocks.length - 1];
+    if (!lastBlock) {
+      throw new Error('No blocks built yet');
+    }
+    // Create a CheckpointHeader from the last block's header for testing
+    const checkpointHeader = this.createCheckpointHeader(lastBlock);
+    return Promise.resolve(
+      new Checkpoint(
+        makeAppendOnlyTreeSnapshot(lastBlock.header.globalVariables.blockNumber + 1),
+        checkpointHeader,
+        builtBlocks,
+        this.checkpointNumber,
+      ),
+    );
+  }
+
+  /**
+   * Creates a CheckpointHeader from a block's header for testing.
+   * This is a simplified version that creates a minimal CheckpointHeader.
+   */
+  private createCheckpointHeader(block: L2BlockNew): CheckpointHeader {
+    const header = block.header;
+    const gv = header.globalVariables;
+    return CheckpointHeader.empty({
+      lastArchiveRoot: header.lastArchive.root,
+      blockHeadersHash: Fr.random(), // Use random for testing
+      slotNumber: gv.slotNumber,
+      timestamp: gv.timestamp,
+      coinbase: gv.coinbase,
+      feeRecipient: gv.feeRecipient,
+      gasFees: gv.gasFees,
+      totalManaUsed: header.totalManaUsed,
+    });
+  }
+
+  /** Reset for reuse in another test */
+  reset(): void {
+    this.blocks = [];
+    this.builtBlocks = [];
+    this.usedTxsPerBlock = [];
+    this.blockIndex = 0;
+    this.buildBlockCalls = [];
+    this.completeCheckpointCalled = false;
+    this.getCheckpointCalled = false;
+    this.errorOnBuild = undefined;
+    this.blockProvider = undefined;
+  }
+}
+
+/**
+ * A fake CheckpointsBuilder (factory) for testing that implements the same interface
+ * as FullNodeCheckpointsBuilder. Returns MockCheckpointBuilder instances.
+ * Does NOT use jest mocks - this is a proper test double.
+ */
+export class MockCheckpointsBuilder implements FunctionsOf<FullNodeCheckpointsBuilder> {
+  private checkpointBuilder: MockCheckpointBuilder | undefined;
+
+  /** Track calls for assertions */
+  public startCheckpointCalls: Array<{
+    checkpointNumber: CheckpointNumber;
+    constants: CheckpointGlobalVariables;
+    l1ToL2Messages: Fr[];
+  }> = [];
+  public updateConfigCalls: Array<Partial<FullNodeBlockBuilderConfig>> = [];
+
+  /**
+   * Set the MockCheckpointBuilder to return from startCheckpoint.
+   * Must be called before startCheckpoint is invoked.
+   */
+  setCheckpointBuilder(builder: MockCheckpointBuilder): this {
+    this.checkpointBuilder = builder;
+    return this;
+  }
+
+  /**
+   * Creates a new MockCheckpointBuilder with the given constants.
+   * Convenience method that creates and sets the builder in one call.
+   */
+  createCheckpointBuilder(
+    constants: CheckpointGlobalVariables,
+    checkpointNumber: CheckpointNumber,
+  ): MockCheckpointBuilder {
+    this.checkpointBuilder = new MockCheckpointBuilder(constants, checkpointNumber);
+    return this.checkpointBuilder;
+  }
+
+  /** Get the current checkpoint builder (for assertions) */
+  getCheckpointBuilder(): MockCheckpointBuilder | undefined {
+    return this.checkpointBuilder;
+  }
+
+  updateConfig(config: Partial<FullNodeBlockBuilderConfig>): void {
+    this.updateConfigCalls.push(config);
+  }
+
+  startCheckpoint(
+    checkpointNumber: CheckpointNumber,
+    constants: CheckpointGlobalVariables,
+    l1ToL2Messages: Fr[],
+    _fork: unknown,
+  ): Promise<CheckpointBuilder> {
+    this.startCheckpointCalls.push({ checkpointNumber, constants, l1ToL2Messages });
+
+    if (!this.checkpointBuilder) {
+      // Auto-create a builder if none was set
+      this.checkpointBuilder = new MockCheckpointBuilder(constants, checkpointNumber);
+    }
+
+    return Promise.resolve(this.checkpointBuilder as unknown as CheckpointBuilder);
+  }
+
+  /** Reset for reuse in another test */
+  reset(): void {
+    this.checkpointBuilder = undefined;
+    this.startCheckpointCalls = [];
+    this.updateConfigCalls = [];
+  }
+}