@aztec/sequencer-client 0.0.1-commit.f5d02921e → 0.0.1-commit.f7ea82942

package/src/publisher/sequencer-publisher.ts

@@ -3,17 +3,18 @@ import { Blob, getBlobsPerL1Block, getPrefixedEthBlobCommitments } from '@aztec/
 import type { EpochCache } from '@aztec/epoch-cache';
 import type { L1ContractsConfig } from '@aztec/ethereum/config';
 import {
-  type EmpireSlashingProposerContract,
   FeeAssetPriceOracle,
-  type FeeHeader,
   type GovernanceProposerContract,
   type IEmpireBase,
   MULTI_CALL_3_ADDRESS,
   Multicall3,
   RollupContract,
-  type TallySlashingProposerContract,
+  SimulationOverridesBuilder,
+  type SimulationOverridesPlan,
+  type SlashingProposerContract,
   type ViemCommitteeAttestations,
   type ViemHeader,
+  buildSimulationOverridesStateOverride,
 } from '@aztec/ethereum/contracts';
 import { type L1FeeAnalysisResult, L1FeeAnalyzer } from '@aztec/ethereum/l1-fee-analysis';
 import {
@@ -27,7 +28,6 @@ import {
 } from '@aztec/ethereum/l1-tx-utils';
 import { FormattedViemError, formatViemError, mergeAbis, tryExtractEvent } from '@aztec/ethereum/utils';
 import { sumBigint } from '@aztec/foundation/bigint';
-import { toHex as toPaddedHex } from '@aztec/foundation/bigint-buffer';
 import { CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
 import { trimmedBytesLength } from '@aztec/foundation/buffer';
 import { pick } from '@aztec/foundation/collection';
@@ -45,14 +45,12 @@ import { type ProposerSlashAction, encodeSlashConsensusVotes } from '@aztec/slas
 import { CommitteeAttestationsAndSigners, type ValidateCheckpointResult } from '@aztec/stdlib/block';
 import type { Checkpoint } from '@aztec/stdlib/checkpoint';
 import { getLastL1SlotTimestampForL2Slot, getNextL1SlotTimestamp } from '@aztec/stdlib/epoch-helpers';
-import { SlashFactoryContract } from '@aztec/stdlib/l1-contracts';
 import type { CheckpointHeader } from '@aztec/stdlib/rollup';
 import type { L1PublishCheckpointStats } from '@aztec/stdlib/stats';
 import { type TelemetryClient, type Tracer, getTelemetryClient, trackSpan } from '@aztec/telemetry-client';
 
 import {
   type Hex,
-  type StateOverride,
   type TransactionReceipt,
   type TypedDataDefinition,
   encodeFunctionData,
@@ -100,16 +98,13 @@ export const Actions = [
   'invalidate-by-insufficient-attestations',
   'propose',
   'governance-signal',
-  'empire-slashing-signal',
-  'create-empire-payload',
-  'execute-empire-payload',
   'vote-offenses',
   'execute-slash',
 ] as const;
 
 export type Action = (typeof Actions)[number];
 
-type GovernanceSignalAction = Extract<Action, 'governance-signal' | 'empire-slashing-signal'>;
+type GovernanceSignalAction = Extract<Action, 'governance-signal'>;
 
 // Sorting for actions such that invalidations go before proposals, and proposals go before votes
 export const compareActions = (a: Action, b: Action) => Actions.indexOf(a) - Actions.indexOf(b);
@@ -124,12 +119,19 @@ export type InvalidateCheckpointRequest = {
   lastArchive: Fr;
 };
 
+type EnqueueProposeCheckpointOpts = {
+  txTimeoutAt?: Date;
+  simulationOverridesPlan?: SimulationOverridesPlan;
+};
+
 interface RequestWithExpiry {
   action: Action;
   request: L1TxRequest;
   lastValidL2Slot: SlotNumber;
   gasConfig?: Pick<L1TxConfig, 'txTimeoutAt' | 'gasLimit'>;
   blobConfig?: L1BlobInputs;
+  /** Optional pre-send validation. If it rejects, the request is discarded. */
+  preCheck?: () => Promise<void>;
   checkSuccess: (
     request: L1TxRequest,
     result?: { receipt: TransactionReceipt; stats?: TransactionStats; errorMsg?: string },
@@ -183,8 +185,7 @@ export class SequencerPublisher {
   public l1TxUtils: L1TxUtils;
   public rollupContract: RollupContract;
   public govProposerContract: GovernanceProposerContract;
-  public slashingProposerContract: EmpireSlashingProposerContract | TallySlashingProposerContract | undefined;
-  public slashFactoryContract: SlashFactoryContract;
+  public slashingProposerContract: SlashingProposerContract | undefined;
 
   public readonly tracer: Tracer;
 
@@ -198,9 +199,8 @@ export class SequencerPublisher {
       blobClient: BlobClientInterface;
       l1TxUtils: L1TxUtils;
       rollupContract: RollupContract;
-      slashingProposerContract: EmpireSlashingProposerContract | TallySlashingProposerContract | undefined;
+      slashingProposerContract: SlashingProposerContract | undefined;
       governanceProposerContract: GovernanceProposerContract;
-      slashFactoryContract: SlashFactoryContract;
       epochCache: EpochCache;
       dateProvider: DateProvider;
       metrics: SequencerPublisherMetrics;
@@ -235,8 +235,6 @@ export class SequencerPublisher {
       const newSlashingProposer = await this.rollupContract.getSlashingProposer();
       this.slashingProposerContract = newSlashingProposer;
     });
-    this.slashFactoryContract = deps.slashFactoryContract;
-
     // Initialize L1 fee analyzer for fisherman mode
     if (config.fishermanMode) {
       this.l1FeeAnalyzer = new L1FeeAnalyzer(
@@ -569,6 +567,28 @@ export class SequencerPublisher {
     if (this.interrupted) {
       return undefined;
     }
+
+    // Re-validate enqueued requests after the sleep (state may have changed, e.g. prune or L1 reorg)
+    const validRequests: RequestWithExpiry[] = [];
+    for (const request of this.requests) {
+      if (!request.preCheck) {
+        validRequests.push(request);
+        continue;
+      }
+
+      try {
+        await request.preCheck();
+        validRequests.push(request);
+      } catch (err) {
+        this.log.warn(`Pre-send validation failed for ${request.action}, discarding request`, err);
+      }
+    }
+
+    this.requests = validRequests;
+    if (this.requests.length === 0) {
+      return undefined;
+    }
+
     return this.sendRequests();
   }
 
@@ -647,27 +667,21 @@ export class SequencerPublisher {
    * @param tipArchive - The archive to check
    * @returns The slot and block number if it is possible to propose, undefined otherwise
    */
-  public canProposeAt(
-    tipArchive: Fr,
-    msgSender: EthAddress,
-    opts: {
-      forcePendingCheckpointNumber?: CheckpointNumber;
-      forceArchive?: { checkpointNumber: CheckpointNumber; archive: Fr };
-      pipelined?: boolean;
-    } = {},
-  ) {
+  public async canProposeAt(tipArchive: Fr, msgSender: EthAddress, simulationOverridesPlan?: SimulationOverridesPlan) {
     // TODO: #14291 - should loop through multiple keys to check if any of them can propose
     const ignoredErrors = ['SlotAlreadyInChain', 'InvalidProposer', 'InvalidArchive'];
 
-    const pipelined = opts.pipelined ?? this.epochCache.isProposerPipeliningEnabled();
+    const pipelined = this.epochCache.isProposerPipeliningEnabled();
     const slotOffset = pipelined ? this.aztecSlotDuration : 0n;
     const nextL1SlotTs = this.getNextL1SlotTimestamp() + slotOffset;
 
     return this.rollupContract
-      .canProposeAt(tipArchive.toBuffer(), msgSender.toString(), nextL1SlotTs, {
-        forcePendingCheckpointNumber: opts.forcePendingCheckpointNumber,
-        forceArchive: opts.forceArchive,
-      })
+      .canProposeAt(
+        tipArchive.toBuffer(),
+        msgSender.toString(),
+        nextL1SlotTs,
+        await buildSimulationOverridesStateOverride(this.rollupContract, simulationOverridesPlan),
+      )
       .catch(err => {
         if (err instanceof FormattedViemError && ignoredErrors.find(e => err.message.includes(e))) {
           this.log.warn(`Failed canProposeAtTime check with ${ignoredErrors.find(e => err.message.includes(e))}`, {
@@ -689,7 +703,7 @@ export class SequencerPublisher {
   @trackSpan('SequencerPublisher.validateBlockHeader')
   public async validateBlockHeader(
     header: CheckpointHeader,
-    opts?: { forcePendingCheckpointNumber: CheckpointNumber | undefined },
+    simulationOverridesPlan?: SimulationOverridesPlan,
   ): Promise<void> {
     const flags = { ignoreDA: true, ignoreSignatures: true };
 
@@ -704,9 +718,7 @@ export class SequencerPublisher {
     ] as const;
 
     const ts = this.getSimulationTimestamp(header.slotNumber);
-    const stateOverrides = await this.rollupContract.makePendingCheckpointNumberOverride(
-      opts?.forcePendingCheckpointNumber,
-    );
+    const stateOverrides = await buildSimulationOverridesStateOverride(this.rollupContract, simulationOverridesPlan);
     let balance = 0n;
     if (this.config.fishermanMode) {
       // In fisherman mode, we can't know where the proposer is publishing from
@@ -867,10 +879,7 @@ export class SequencerPublisher {
     checkpoint: Checkpoint,
     attestationsAndSigners: CommitteeAttestationsAndSigners,
     attestationsAndSignersSignature: Signature,
-    options: {
-      forcePendingCheckpointNumber?: CheckpointNumber;
-      forceProposedFeeHeader?: { checkpointNumber: CheckpointNumber; feeHeader: FeeHeader };
-    },
+    simulationOverridesPlan?: SimulationOverridesPlan,
   ): Promise<void> {
     const blobFields = checkpoint.toBlobFields();
     const blobs = await getBlobsPerL1Block(blobFields);
@@ -890,7 +899,7 @@ export class SequencerPublisher {
       blobInput,
     ] as const;
 
-    await this.simulateProposeTx(args, options);
+    await this.simulateProposeTx(args, simulationOverridesPlan);
   }
 
   private async enqueueCastSignalHelper(
@@ -1078,55 +1087,6 @@ export class SequencerPublisher {
 
     for (const action of actions) {
       switch (action.type) {
-        case 'vote-empire-payload': {
-          if (this.slashingProposerContract?.type !== 'empire') {
-            this.log.error('Cannot vote for empire payload on non-empire slashing contract');
-            break;
-          }
-          this.log.debug(`Enqueuing slashing vote for payload ${action.payload} at slot ${slotNumber}`, {
-            signerAddress,
-          });
-          await this.enqueueCastSignalHelper(
-            slotNumber,
-            'empire-slashing-signal',
-            action.payload,
-            this.slashingProposerContract,
-            signerAddress,
-            signer,
-          );
-          break;
-        }
-
-        case 'create-empire-payload': {
-          this.log.debug(`Enqueuing slashing create payload at slot ${slotNumber}`, { slotNumber, signerAddress });
-          const request = this.slashFactoryContract.buildCreatePayloadRequest(action.data);
-          await this.simulateAndEnqueueRequest(
-            'create-empire-payload',
-            request,
-            (receipt: TransactionReceipt) =>
-              !!this.slashFactoryContract.tryExtractSlashPayloadCreatedEvent(receipt.logs),
-            slotNumber,
-          );
-          break;
-        }
-
-        case 'execute-empire-payload': {
-          this.log.debug(`Enqueuing slashing execute payload at slot ${slotNumber}`, { slotNumber, signerAddress });
-          if (this.slashingProposerContract?.type !== 'empire') {
-            this.log.error('Cannot execute slashing payload on non-empire slashing contract');
-            return false;
-          }
-          const empireSlashingProposer = this.slashingProposerContract as EmpireSlashingProposerContract;
-          const request = empireSlashingProposer.buildExecuteRoundRequest(action.round);
-          await this.simulateAndEnqueueRequest(
-            'execute-empire-payload',
-            request,
-            (receipt: TransactionReceipt) => !!empireSlashingProposer.tryExtractPayloadSubmittedEvent(receipt.logs),
-            slotNumber,
-          );
-          break;
-        }
-
         case 'vote-offenses': {
           this.log.debug(`Enqueuing slashing vote for ${action.votes.length} votes at slot ${slotNumber}`, {
             slotNumber,
@@ -1134,17 +1094,16 @@ export class SequencerPublisher {
             votesCount: action.votes.length,
             signerAddress,
           });
-          if (this.slashingProposerContract?.type !== 'tally') {
-            this.log.error('Cannot vote for slashing offenses on non-tally slashing contract');
+          if (!this.slashingProposerContract) {
+            this.log.error('No slashing proposer contract available');
             return false;
           }
-          const tallySlashingProposer = this.slashingProposerContract as TallySlashingProposerContract;
           const votes = bufferToHex(encodeSlashConsensusVotes(action.votes));
-          const request = await tallySlashingProposer.buildVoteRequestFromSigner(votes, slotNumber, signer);
+          const request = await this.slashingProposerContract.buildVoteRequestFromSigner(votes, slotNumber, signer);
           await this.simulateAndEnqueueRequest(
             'vote-offenses',
             request,
-            (receipt: TransactionReceipt) => !!tallySlashingProposer.tryExtractVoteCastEvent(receipt.logs),
+            (receipt: TransactionReceipt) => !!this.slashingProposerContract!.tryExtractVoteCastEvent(receipt.logs),
             slotNumber,
           );
           break;
@@ -1156,16 +1115,19 @@ export class SequencerPublisher {
             round: action.round,
             signerAddress,
           });
-          if (this.slashingProposerContract?.type !== 'tally') {
-            this.log.error('Cannot execute slashing offenses on non-tally slashing contract');
+          if (!this.slashingProposerContract) {
+            this.log.error('No slashing proposer contract available');
             return false;
           }
-          const tallySlashingProposer = this.slashingProposerContract as TallySlashingProposerContract;
-          const request = tallySlashingProposer.buildExecuteRoundRequest(action.round, action.committees);
+          const executeRequest = this.slashingProposerContract.buildExecuteRoundRequest(
+            action.round,
+            action.committees,
+          );
           await this.simulateAndEnqueueRequest(
             'execute-slash',
-            request,
-            (receipt: TransactionReceipt) => !!tallySlashingProposer.tryExtractRoundExecutedEvent(receipt.logs),
+            executeRequest,
+            (receipt: TransactionReceipt) =>
+              !!this.slashingProposerContract!.tryExtractRoundExecutedEvent(receipt.logs),
             slotNumber,
           );
           break;
@@ -1186,11 +1148,7 @@ export class SequencerPublisher {
     checkpoint: Checkpoint,
     attestationsAndSigners: CommitteeAttestationsAndSigners,
     attestationsAndSignersSignature: Signature,
-    opts: {
-      txTimeoutAt?: Date;
-      forcePendingCheckpointNumber?: CheckpointNumber;
-      forceProposedFeeHeader?: { checkpointNumber: CheckpointNumber; feeHeader: FeeHeader };
-    } = {},
+    opts: EnqueueProposeCheckpointOpts = {},
   ): Promise<void> {
     const checkpointHeader = checkpoint.header;
 
@@ -1206,6 +1164,10 @@ export class SequencerPublisher {
       feeAssetPriceModifier: checkpoint.feeAssetPriceModifier,
     };
 
+    const simulationOverridesPlan = SimulationOverridesBuilder.from(opts.simulationOverridesPlan)
+      .withoutBlobCheck()
+      .build();
+
     try {
       // @note  This will make sure that we are passing the checks for our header ASSUMING that the data is also made available
       //        This means that we can avoid the simulation issues in later checks.
@@ -1216,19 +1178,43 @@ export class SequencerPublisher {
         checkpoint,
         attestationsAndSigners,
         attestationsAndSignersSignature,
-        opts,
+        simulationOverridesPlan,
       );
     } catch (err: any) {
       this.log.error(`Checkpoint validation failed. ${err instanceof Error ? err.message : 'No error message'}`, err, {
         ...checkpoint.getStats(),
         slotNumber: checkpoint.header.slotNumber,
-        forcePendingCheckpointNumber: opts.forcePendingCheckpointNumber,
+        simulationOverridesPlan,
       });
       throw err;
     }
 
-    this.log.verbose(`Enqueuing checkpoint propose transaction`, { ...checkpoint.toCheckpointInfo(), ...opts });
-    await this.addProposeTx(checkpoint, proposeTxArgs, opts);
+    // Build a pre-check callback that re-validates the checkpoint before L1 submission.
+    // During pipelining this catches stale proposals due to prunes or L1 reorgs that occur during the pipeline sleep.
+    let preCheck = undefined;
+    if (this.epochCache.isProposerPipeliningEnabled()) {
+      preCheck = async () => {
+        this.log.debug(`Re-validating checkpoint ${checkpoint.number} before L1 submission`);
+        await this.validateCheckpointForSubmission(
+          checkpoint,
+          attestationsAndSigners,
+          attestationsAndSignersSignature,
+          simulationOverridesPlan,
+        );
+      };
+    }
+
+    this.log.verbose(`Enqueuing checkpoint propose transaction`, {
+      ...checkpoint.toCheckpointInfo(),
+      txTimeoutAt: opts.txTimeoutAt,
+      simulationOverridesPlan,
+    });
+    await this.addProposeTx(
+      checkpoint,
+      proposeTxArgs,
+      { txTimeoutAt: opts.txTimeoutAt, simulationOverridesPlan },
+      preCheck,
+    );
   }
 
   public enqueueInvalidateCheckpoint(
@@ -1358,10 +1344,7 @@ export class SequencerPublisher {
     this.l1TxUtils.restart();
   }
 
-  private async prepareProposeTx(
-    encodedData: L1ProcessArgs,
-    options: { forcePendingCheckpointNumber?: CheckpointNumber },
-  ) {
+  private async prepareProposeTx(encodedData: L1ProcessArgs, simulationOverridesPlan?: SimulationOverridesPlan) {
     const kzg = Blob.getViemKzgInstance();
     const blobInput = getPrefixedEthBlobCommitments(encodedData.blobs);
     this.log.debug('Validating blob input', { blobInput });
@@ -1432,7 +1415,7 @@ export class SequencerPublisher {
       blobInput,
     ] as const;
 
-    const { rollupData, simulationResult } = await this.simulateProposeTx(args, options);
+    const { rollupData, simulationResult } = await this.simulateProposeTx(args, simulationOverridesPlan);
 
     return { args, blobEvaluationGas, rollupData, simulationResult };
   }
@@ -1456,10 +1439,7 @@ export class SequencerPublisher {
       ViemSignature,
       `0x${string}`,
     ],
-    options: {
-      forcePendingCheckpointNumber?: CheckpointNumber;
-      forceProposedFeeHeader?: { checkpointNumber: CheckpointNumber; feeHeader: FeeHeader };
-    },
+    simulationOverridesPlan?: SimulationOverridesPlan,
   ) {
     const rollupData = encodeFunctionData({
       abi: RollupAbi,
@@ -1467,34 +1447,7 @@ export class SequencerPublisher {
       args,
     });
 
-    // override the proposed checkpoint number if requested
-    const forcePendingCheckpointNumberStateDiff = (
-      options.forcePendingCheckpointNumber !== undefined
-        ? await this.rollupContract.makePendingCheckpointNumberOverride(options.forcePendingCheckpointNumber)
-        : []
-    ).flatMap(override => override.stateDiff ?? []);
-
-    // override the fee header for a specific checkpoint number if requested (used when pipelining)
-    const forceProposedFeeHeaderStateDiff = (
-      options.forceProposedFeeHeader !== undefined
-        ? await this.rollupContract.makeFeeHeaderOverride(
-            options.forceProposedFeeHeader.checkpointNumber,
-            options.forceProposedFeeHeader.feeHeader,
-          )
-        : []
-    ).flatMap(override => override.stateDiff ?? []);
-
-    const stateOverrides: StateOverride = [
-      {
-        address: this.rollupContract.address,
-        // @note we override checkBlob to false since blobs are not part simulate()
-        stateDiff: [
-          { slot: toPaddedHex(RollupContract.checkBlobStorageSlot, true), value: toPaddedHex(0n, true) },
-          ...forcePendingCheckpointNumberStateDiff,
-          ...forceProposedFeeHeaderStateDiff,
-        ],
-      },
-    ];
+    const stateOverrides = await buildSimulationOverridesStateOverride(this.rollupContract, simulationOverridesPlan);
     // In fisherman mode, simulate as the proposer but with sufficient balance
     if (this.proposerAddressForSimulation) {
       stateOverrides.push({
@@ -1559,16 +1512,16 @@ export class SequencerPublisher {
   private async addProposeTx(
     checkpoint: Checkpoint,
     encodedData: L1ProcessArgs,
-    opts: {
-      txTimeoutAt?: Date;
-      forcePendingCheckpointNumber?: CheckpointNumber;
-      forceProposedFeeHeader?: { checkpointNumber: CheckpointNumber; feeHeader: FeeHeader };
-    } = {},
+    opts: EnqueueProposeCheckpointOpts = {},
+    preCheck?: () => Promise<void>,
   ): Promise<void> {
     const slot = checkpoint.header.slotNumber;
     const timer = new Timer();
     const kzg = Blob.getViemKzgInstance();
-    const { rollupData, simulationResult, blobEvaluationGas } = await this.prepareProposeTx(encodedData, opts);
+    const { rollupData, simulationResult, blobEvaluationGas } = await this.prepareProposeTx(
+      encodedData,
+      opts.simulationOverridesPlan,
+    );
     const startBlock = await this.l1TxUtils.getBlockNumber();
     const gasLimit = this.l1TxUtils.bumpGasLimit(
       BigInt(Math.ceil((Number(simulationResult.gasUsed) * 64) / 63)) +
@@ -1591,7 +1544,8 @@ export class SequencerPublisher {
         data: rollupData,
       },
       lastValidL2Slot: checkpoint.header.slotNumber,
-      gasConfig: { ...opts, gasLimit },
+      gasConfig: { txTimeoutAt: opts.txTimeoutAt, gasLimit },
+      preCheck,
       blobConfig: {
         blobs: encodedData.blobs.map(b => b.data),
         kzg,

package/src/sequencer/README.md

@@ -1,8 +1,8 @@
 # Sequencer Timing Model
 
-The Aztec sequencer divides each slot into **fixed-duration sub-slots**. Each sub-slot has a pre-defined start and end time based on an initialization offset (how much time we expect syncing the previous slot will take), a finalization time (how much time we need for closing a checkpoint and publishing it to L1), and the configured block duration.
+The Aztec sequencer divides each slot into **fixed-duration sub-slots**. Each sub-slot has a pre-defined start and end time based on an initialization offset (how much time we expect syncing the previous slot will take), the configured block duration, and whether checkpoint finalization is paid for in the current slot or deferred under proposer pipelining.
 
-**Example: 72-second slot with 8-second sub-slots**
+**Example: 72-second slot with 8-second sub-slots (non-pipelined)**
 
 ```
 0s:  Slot starts
@@ -31,7 +31,7 @@ Deadlines are fixed relative to slot start, not relative to when work actually c
 
 ## Overview
 
-The Aztec sequencer operates in fixed-duration **slots** (typically 72 seconds). During each slot, a designated proposer builds multiple **blocks** containing transactions over multiple **sub-slots**, then collects a single round of attestations for the entire **checkpoint** from validators, and finally publishes the resulting checkpoint to L1 Ethereum.
+The Aztec sequencer operates in fixed-duration **slots** (typically 72 seconds). During each slot, a designated proposer builds multiple **blocks** containing transactions over multiple **sub-slots**. In the default mode, the same slot also reserves time to collect attestations for the resulting **checkpoint**, finalize it, and publish it to L1 Ethereum. When proposer pipelining is enabled, the slot budget for block building is larger because checkpoint finalization is deferred to the next target slot.
 
 ## Key Concepts
 
@@ -42,12 +42,14 @@ The Aztec sequencer operates in fixed-duration **slots** (typically 72 seconds).
 - **Checkpoint**: The collection of all blocks built in a slot, attested by validators and published to L1
 - **Sub-slot**: A fixed-duration time window within a slot (e.g., 8 seconds) during which a block should be built
 
-In a typical configuration, a 72-second slot contains:
+In a typical configuration without pipelining, a 72-second slot contains:
 - 1 initialization period (2 seconds)
 - 5 block-building sub-slots (8 seconds each = 40 seconds)
 - 1 last validator re-execution sub-slot (8 seconds)
 - 1 attestation and publishing period (17 seconds)
 
+With proposer pipelining enabled, the last validator re-execution sub-slot is still reserved, but the checkpoint finalization and L1 publishing budget is no longer subtracted when deciding how many block-building sub-slots fit in the slot.
+
 ### The Fixed Sub-Slot Model
 
 Building multiple blocks per slot uses **fixed sub-slots** with predictable deadlines:
@@ -75,14 +77,19 @@ These values are configurable but must satisfy certain constraints (explained be
 
 ## Calculating Sub-Slots and Blocks
 
-Given a slot configuration, we calculate how many blocks fit using this formula:
+Given a slot configuration, we calculate how many blocks fit using these formulas:
 
 ```
-timeReservedAtEnd = blockDuration                              (last sub-slot for reexecution)
-                  + propagationTime                            (validators receive proposal)
-                  + propagationTime                            (attestations come back)
-                  + finalizationTime                           (checkpoint finalization)
-                  + l1PublishingTime                           (L1 transaction)
+checkpointFinalizationTime = propagationTime
+                           + propagationTime
+                           + finalizationTime
+                           + l1PublishingTime
+
+timeReservedAtEnd (normal mode) = blockDuration               (last sub-slot for reexecution)
+                                + checkpointFinalizationTime
+
+timeReservedAtEnd (pipelining) = assembleTime
+                               + propagationTime             (proposal must reach validators before the slot flips)
 
 timeAvailableForBlocks = slotDuration - initializationOffset - timeReservedAtEnd
 
@@ -101,6 +108,62 @@ This means:
 - Sub-slot 6: Reserved for validator re-execution of block 5
 - After sub-slot 6: Attestation collection, finalization, and L1 publishing
 
+**The same slot with proposer pipelining enabled:**
+```
+timeReservedAtEnd = 1s + 2s = 3s
+timeAvailableForBlocks = 72s - 2s - 3s = 67s
+numberOfBlocks = floor(67s / 8s) = 8 blocks
+```
+
+The extra two block opportunities come from not charging the current slot for checkpoint finalization and L1 publishing.
+
+### Pipelining Mode
+
+When proposer pipelining is enabled, the sequencer uses the current wall-clock slot to build the checkpoint for the **next target slot**.
+
+It helps to think in terms of two different slots:
+
+- **Wall-clock slot N-1**: The sequencer initializes checkpoint `N`, builds its blocks, and validators re-execute the last block
+- **Target slot N**: Checkpoint `N` is proposed, attestations are gathered, and the L1 transaction is submitted
+
+So the work is split like this:
+
+- **During slot N-1**: Initialization, block building, and last-block re-execution
+- **Near the end of slot N-1**: The checkpoint proposal is broadcast so validators can start the last re-execution as slot `N` begins.
+- **During slot N**: Validators finish re-executing, send attestations, the proposer collects them, and the checkpoint is submitted to L1 before slot `N` reaches its publish cutoff
+
+In other words, pipelining does not mean "do everything for slot N earlier". It specifically moves **block production and block re-execution** earlier, while **checkpoint proposal, attestation gathering, and L1 submission** remain aligned with slot `N`.
+
+**Example: building checkpoint 12 while wall-clock time is in slot 11**
+```
+Slot 11 (wall clock):
+- Build blocks that will make up checkpoint 12
+- Validators re-execute the last block of checkpoint 12
+- Broadcast checkpoint 12 proposal
+- Collect checkpoint 12 attestations
+
+Slot 12 (target/submission slot):
+- Collect attestations for checkpoint 12 until slot 12 reaches its L1 publish cutoff
+- Submit checkpoint 12 to L1
+```
+
+For timetable purposes, this changes two things:
+
+- `maxNumberOfBlocks` is computed by reserving only the final validator re-execution sub-slot
+- `initializeDeadline` no longer subtracts checkpoint finalization time; it only requires enough time for initialization, execution, and validator re-execution
+
+In code, that means:
+
+```
+initializeDeadline (normal mode) =
+  slotDuration - initializationOffset - 2 * minExecutionTime - checkpointFinalizationTime
+
+initializeDeadline (pipelining) =
+  slotDuration - initializationOffset - 2 * minExecutionTime
+```
+
+The fixed sub-slot deadlines themselves do not change. Pipelining only changes how much of the slot is considered available for block building.
+
 ## The Sequencer's Work
 
 When elected as proposer for a slot, the sequencer performs these tasks:
@@ -226,7 +289,9 @@ After the last block is built and validators have re-executed it:
 
 **Time reserved:** `2*propagationTime + finalizationTime + l1PublishingTime = 2s + 2s + 1s + 12s = 17s`
 
-This 17s comes after the last sub-slot, ensuring we have enough time to complete the checkpoint. If the sequencer receives the necessary attestations before the reserved time, the L1 tx is submitted earlier.
+In the non-pipelined path, this 17s comes after the last sub-slot, ensuring we have enough time to complete the checkpoint. If the sequencer receives the necessary attestations before the reserved time, the L1 tx is submitted earlier.
+
+With proposer pipelining enabled, this finalization budget is not charged against the current slot when calculating how many blocks fit. The checkpoint is instead queued for submission at the start of the target slot, so proposal broadcast, attestation gathering, and L1 submission happen in slot `N` while block building and block re-execution already happened in slot `N-1`.
 
 ## Handling Timing Variations
 
@@ -399,7 +464,7 @@ When configuring timing parameters, ensure these constraints are satisfied:
 
 ### Minimum Slot Duration
 
-For a valid configuration:
+For a valid multi-block configuration without pipelining:
 ```
 slotDuration >= initializationOffset
               + blockDuration * 2                          (at least 2 blocks)
@@ -414,6 +479,11 @@ Simplified:
 slotDuration >= initializationOffset + 3*blockDuration + 2*propagationTime + finalizationTime + l1PublishingTime
 ```
 
+With proposer pipelining enabled, the same "at least 2 buildable blocks plus the final validator re-execution sub-slot" requirement becomes:
+```
+slotDuration >= initializationOffset + 3*blockDuration
+```
+
 **Example:**
 ```
 slotDuration >= 2s + 3*8s + 2*2s + 1s + 12s = 2s + 24s + 4s + 1s + 12s = 43s
@@ -465,7 +535,7 @@ The sequencer transitions through these states during a slot:
 | **WAITING_UNTIL_NEXT_BLOCK** | Until next sub-slot start | Sleep between blocks to maintain intervals |
 | **ASSEMBLING_CHECKPOINT** | assembleTime (1s) | Assemble final checkpoint |
 | **COLLECTING_ATTESTATIONS** | Until L1 publish deadline | Wait for validator signatures |
-| **PUBLISHING_CHECKPOINT** | Until slot end | Submit to L1 |
+| **PUBLISHING_CHECKPOINT** | Until L1 publish deadline | Submit to L1 |
 
 ## Complete Example: 72-Second Slot with 8-Second Sub-Slots