@aztec/validator-client 4.0.0-devnet.2-patch.3 → 4.0.0-devnet.3-patch.0

package/src/{block_proposal_handler.ts → proposal_handler.ts}

@@ -1,21 +1,34 @@
+import type { BlobClientInterface } from '@aztec/blob-client/client';
+import { type Blob, encodeCheckpointBlobDataFromBlocks, getBlobsPerL1Block } from '@aztec/blob-lib';
 import { INITIAL_L2_BLOCK_NUM } from '@aztec/constants';
 import type { EpochCache } from '@aztec/epoch-cache';
+import { validateFeeAssetPriceModifier } from '@aztec/ethereum/contracts';
 import { BlockNumber, CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import { pick } from '@aztec/foundation/collection';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { TimeoutError } from '@aztec/foundation/error';
+import type { LogData } from '@aztec/foundation/log';
 import { createLogger } from '@aztec/foundation/log';
 import { retryUntil } from '@aztec/foundation/retry';
 import { DateProvider, Timer } from '@aztec/foundation/timer';
 import type { P2P, PeerId } from '@aztec/p2p';
 import { BlockProposalValidator } from '@aztec/p2p/msg_validators';
 import type { BlockData, L2Block, L2BlockSink, L2BlockSource } from '@aztec/stdlib/block';
+import { validateCheckpoint } from '@aztec/stdlib/checkpoint';
 import { getEpochAtSlot, getTimestampForSlot } from '@aztec/stdlib/epoch-helpers';
+import { Gas } from '@aztec/stdlib/gas';
 import type { ITxProvider, ValidatorClientFullConfig, WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
-import { type L1ToL2MessageSource, computeInHashFromL1ToL2Messages } from '@aztec/stdlib/messaging';
-import type { BlockProposal } from '@aztec/stdlib/p2p';
+import {
+  type L1ToL2MessageSource,
+  accumulateCheckpointOutHashes,
+  computeInHashFromL1ToL2Messages,
+} from '@aztec/stdlib/messaging';
+import type { BlockProposal, CheckpointProposalCore } from '@aztec/stdlib/p2p';
+import { MerkleTreeId } from '@aztec/stdlib/trees';
 import type { CheckpointGlobalVariables, FailedTx, Tx } from '@aztec/stdlib/tx';
 import {
   ReExFailedTxsError,
+  ReExInitialStateMismatchError,
   ReExStateMismatchError,
   ReExTimeoutError,
   TransactionsNotAvailableError,
@@ -28,6 +41,7 @@ import type { ValidatorMetrics } from './metrics.js';
 export type BlockProposalValidationFailureReason =
   | 'invalid_proposal'
   | 'parent_block_not_found'
+  | 'block_source_not_synced'
   | 'parent_block_wrong_slot'
   | 'in_hash_mismatch'
   | 'global_variables_mismatch'
@@ -35,6 +49,7 @@ export type BlockProposalValidationFailureReason =
   | 'txs_not_available'
   | 'state_mismatch'
   | 'failed_txs'
+  | 'initial_state_mismatch'
   | 'timeout'
   | 'unknown_error';
 
@@ -60,11 +75,14 @@ export type BlockProposalValidationFailureResult = {
 
 export type BlockProposalValidationResult = BlockProposalValidationSuccessResult | BlockProposalValidationFailureResult;
 
+export type CheckpointProposalValidationResult = { isValid: true } | { isValid: false; reason: string };
+
 type CheckpointComputationResult =
   | { checkpointNumber: CheckpointNumber; reason?: undefined }
   | { checkpointNumber?: undefined; reason: 'invalid_proposal' | 'global_variables_mismatch' };
 
-export class BlockProposalHandler {
+/** Handles block and checkpoint proposals for both validator and non-validator nodes. */
+export class ProposalHandler {
   public readonly tracer: Tracer;
 
   constructor(
@@ -76,36 +94,44 @@ export class BlockProposalHandler {
     private blockProposalValidator: BlockProposalValidator,
     private epochCache: EpochCache,
     private config: ValidatorClientFullConfig,
+    private blobClient: BlobClientInterface,
     private metrics?: ValidatorMetrics,
     private dateProvider: DateProvider = new DateProvider(),
     telemetry: TelemetryClient = getTelemetryClient(),
-    private log = createLogger('validator:block-proposal-handler'),
+    private log = createLogger('validator:proposal-handler'),
   ) {
     if (config.fishermanMode) {
       this.log = this.log.createChild('[FISHERMAN]');
     }
-    this.tracer = telemetry.getTracer('BlockProposalHandler');
+    this.tracer = telemetry.getTracer('ProposalHandler');
   }
 
-  registerForReexecution(p2pClient: P2P): BlockProposalHandler {
-    // Non-validator handler that re-executes for monitoring but does not attest.
+  /**
+   * Registers non-validator handlers for block and checkpoint proposals on the p2p client.
+   * Block proposals are always registered. Checkpoint proposals are registered if the blob client can upload.
+   */
+  register(p2pClient: P2P, shouldReexecute: boolean): ProposalHandler {
+    // Non-validator handler that processes or re-executes for monitoring but does not attest.
     // Returns boolean indicating whether the proposal was valid.
-    const handler = async (proposal: BlockProposal, proposalSender: PeerId): Promise<boolean> => {
+    const blockHandler = async (proposal: BlockProposal, proposalSender: PeerId): Promise<boolean> => {
       try {
-        const result = await this.handleBlockProposal(proposal, proposalSender, true);
+        const { slotNumber, blockNumber } = proposal;
+        const result = await this.handleBlockProposal(proposal, proposalSender, shouldReexecute);
         if (result.isValid) {
-          this.log.info(`Non-validator reexecution completed for slot ${proposal.slotNumber}`, {
+          this.log.info(`Non-validator block proposal ${blockNumber} at slot ${slotNumber} handled`, {
             blockNumber: result.blockNumber,
+            slotNumber,
             reexecutionTimeMs: result.reexecutionResult?.reexecutionTimeMs,
             totalManaUsed: result.reexecutionResult?.totalManaUsed,
             numTxs: result.reexecutionResult?.block?.body?.txEffects?.length ?? 0,
+            reexecuted: shouldReexecute,
           });
           return true;
         } else {
-          this.log.warn(`Non-validator reexecution failed for slot ${proposal.slotNumber}`, {
-            blockNumber: result.blockNumber,
-            reason: result.reason,
-          });
+          this.log.warn(
+            `Non-validator block proposal ${blockNumber} at slot ${slotNumber} failed processing with ${result.reason}`,
+            { blockNumber: result.blockNumber, slotNumber, reason: result.reason },
+          );
           return false;
         }
       } catch (error) {
@@ -114,7 +140,35 @@ export class BlockProposalHandler {
       }
     };
 
-    p2pClient.registerBlockProposalHandler(handler);
+    p2pClient.registerBlockProposalHandler(blockHandler);
+
+    // Register checkpoint proposal handler if blob uploads are enabled and we are reexecuting
+    if (this.blobClient.canUpload() && shouldReexecute) {
+      const checkpointHandler = async (checkpoint: CheckpointProposalCore, _sender: PeerId) => {
+        try {
+          const proposalInfo = {
+            proposalSlotNumber: checkpoint.slotNumber,
+            archive: checkpoint.archive.toString(),
+            proposer: checkpoint.getSender()?.toString(),
+          };
+          const result = await this.handleCheckpointProposal(checkpoint, proposalInfo);
+          if (result.isValid) {
+            this.log.info(`Non-validator checkpoint proposal at slot ${checkpoint.slotNumber} handled`, proposalInfo);
+          } else {
+            this.log.warn(
+              `Non-validator checkpoint proposal at slot ${checkpoint.slotNumber} failed: ${result.reason}`,
+              proposalInfo,
+            );
+          }
+        } catch (error) {
+          this.log.error('Error processing checkpoint proposal in non-validator handler', error);
+        }
+        // Non-validators don't attest
+        return undefined;
+      };
+      p2pClient.registerCheckpointProposalHandler(checkpointHandler);
+    }
+
     return this;
   }
 
@@ -133,7 +187,13 @@ export class BlockProposalHandler {
       return { isValid: false, reason: 'invalid_proposal' };
     }
 
-    const proposalInfo = { ...proposal.toBlockInfo(), proposer: proposer.toString() };
+    const proposalInfo = {
+      ...proposal.toBlockInfo(),
+      proposer: proposer.toString(),
+      blockNumber: undefined as BlockNumber | undefined,
+      checkpointNumber: undefined as CheckpointNumber | undefined,
+    };
+
     this.log.info(`Processing proposal for slot ${slotNumber}`, {
       ...proposalInfo,
       txHashes: proposal.txHashes.map(t => t.toString()),
@@ -147,7 +207,20 @@ export class BlockProposalHandler {
       return { isValid: false, reason: 'invalid_proposal' };
     }
 
-    // Check that the parent proposal is a block we know, otherwise reexecution would fail
+    // Ensure the block source is synced before checking for existing blocks,
+    // since a pending checkpoint prune may remove blocks we'd otherwise find.
+    // This affects mostly the block_number_already_exists check, since a pending
+    // checkpoint prune could remove a block that would conflict with this proposal.
+    // TODO(@Maddiaa0): This may break staggered slots.
+    const blockSourceSync = await this.waitForBlockSourceSync(slotNumber);
+    if (!blockSourceSync) {
+      this.log.warn(`Block source is not synced, skipping processing`, proposalInfo);
+      return { isValid: false, reason: 'block_source_not_synced' };
+    }
+
+    // Check that the parent proposal is a block we know, otherwise reexecution would fail.
+    // If we don't find it immediately, we keep retrying for a while; it may be we still
+    // need to process other block proposals to get to it.
     const parentBlock = await this.getParentBlock(proposal);
     if (parentBlock === undefined) {
       this.log.warn(`Parent block for proposal not found, skipping processing`, proposalInfo);
@@ -169,6 +242,7 @@ export class BlockProposalHandler {
       parentBlock === 'genesis'
         ? BlockNumber(INITIAL_L2_BLOCK_NUM)
         : BlockNumber(parentBlock.header.getBlockNumber() + 1);
+    proposalInfo.blockNumber = blockNumber;
 
     // Check that this block number does not exist already
     const existingBlock = await this.blockSource.getBlockHeader(blockNumber);
@@ -184,12 +258,22 @@ export class BlockProposalHandler {
       deadline: this.getReexecutionDeadline(slotNumber, config),
     });
 
+    // If reexecution is disabled, bail. We were just interested in triggering tx collection.
+    if (!shouldReexecute) {
+      this.log.info(
+        `Received valid block ${blockNumber} proposal at index ${proposal.indexWithinCheckpoint} on slot ${slotNumber}`,
+        proposalInfo,
+      );
+      return { isValid: true, blockNumber };
+    }
+
     // Compute the checkpoint number for this block and validate checkpoint consistency
     const checkpointResult = this.computeCheckpointNumber(proposal, parentBlock, proposalInfo);
     if (checkpointResult.reason) {
       return { isValid: false, blockNumber, reason: checkpointResult.reason };
     }
     const checkpointNumber = checkpointResult.checkpointNumber;
+    proposalInfo.checkpointNumber = checkpointNumber;
 
     // Check that I have the same set of l1ToL2Messages as the proposal
     const l1ToL2Messages = await this.l1ToL2MessageSource.getL1ToL2Messages(checkpointNumber);
@@ -210,30 +294,28 @@ export class BlockProposalHandler {
       return { isValid: false, blockNumber, reason: 'txs_not_available' };
     }
 
+    // Collect the out hashes of all the checkpoints before this one in the same epoch
+    const epoch = getEpochAtSlot(slotNumber, this.epochCache.getL1Constants());
+    const previousCheckpointOutHashes = (await this.blockSource.getCheckpointsDataForEpoch(epoch))
+      .filter(c => c.checkpointNumber < checkpointNumber)
+      .map(c => c.checkpointOutHash);
+
     // Try re-executing the transactions in the proposal if needed
     let reexecutionResult;
-    if (shouldReexecute) {
-      // Collect the out hashes of all the checkpoints before this one in the same epoch
-      const epoch = getEpochAtSlot(slotNumber, this.epochCache.getL1Constants());
-      const previousCheckpointOutHashes = (await this.blockSource.getCheckpointsDataForEpoch(epoch))
-        .filter(c => c.checkpointNumber < checkpointNumber)
-        .map(c => c.checkpointOutHash);
-
-      try {
-        this.log.verbose(`Re-executing transactions in the proposal`, proposalInfo);
-        reexecutionResult = await this.reexecuteTransactions(
-          proposal,
-          blockNumber,
-          checkpointNumber,
-          txs,
-          l1ToL2Messages,
-          previousCheckpointOutHashes,
-        );
-      } catch (error) {
-        this.log.error(`Error reexecuting txs while processing block proposal`, error, proposalInfo);
-        const reason = this.getReexecuteFailureReason(error);
-        return { isValid: false, blockNumber, reason, reexecutionResult };
-      }
+    try {
+      this.log.verbose(`Re-executing transactions in the proposal`, proposalInfo);
+      reexecutionResult = await this.reexecuteTransactions(
+        proposal,
+        blockNumber,
+        checkpointNumber,
+        txs,
+        l1ToL2Messages,
+        previousCheckpointOutHashes,
+      );
+    } catch (error) {
+      this.log.error(`Error reexecuting txs while processing block proposal`, error, proposalInfo);
+      const reason = this.getReexecuteFailureReason(error);
+      return { isValid: false, blockNumber, reason, reexecutionResult };
     }
 
     // If we succeeded, push this block into the archiver (unless disabled)
@@ -242,8 +324,8 @@ export class BlockProposalHandler {
     }
 
     this.log.info(
-      `Successfully processed block ${blockNumber} proposal at index ${proposal.indexWithinCheckpoint} on slot ${slotNumber}`,
-      proposalInfo,
+      `Successfully re-executed block ${blockNumber} proposal at index ${proposal.indexWithinCheckpoint} on slot ${slotNumber}`,
+      { ...proposalInfo, ...pick(reexecutionResult, 'reexecutionTimeMs', 'totalManaUsed') },
     );
 
     return { isValid: true, blockNumber, reexecutionResult };
@@ -413,8 +495,48 @@ export class BlockProposalHandler {
     return new Date(nextSlotTimestampSeconds * 1000);
   }
 
-  private getReexecuteFailureReason(err: any) {
-    if (err instanceof ReExStateMismatchError) {
+  /** Waits for the block source to sync L1 data up to at least the slot before the given one. */
+  private async waitForBlockSourceSync(slot: SlotNumber): Promise<boolean> {
+    const deadline = this.getReexecutionDeadline(slot, this.checkpointsBuilder.getConfig());
+    const timeoutMs = deadline.getTime() - this.dateProvider.now();
+    if (slot === 0) {
+      return true;
+    }
+
+    // Make a quick check before triggering an archiver sync
+    const syncedSlot = await this.blockSource.getSyncedL2SlotNumber();
+    if (syncedSlot !== undefined && syncedSlot + 1 >= slot) {
+      return true;
+    }
+
+    try {
+      // Trigger an immediate sync of the block source, and wait until it reports being synced to the required slot
+      return await retryUntil(
+        async () => {
+          await this.blockSource.syncImmediate();
+          const syncedSlot = await this.blockSource.getSyncedL2SlotNumber();
+          return syncedSlot !== undefined && syncedSlot + 1 >= slot;
+        },
+        'wait for block source sync',
+        timeoutMs / 1000,
+        0.5,
+      );
+    } catch (err) {
+      if (err instanceof TimeoutError) {
+        this.log.warn(`Timed out waiting for block source to sync to slot ${slot}`);
+        return false;
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  private getReexecuteFailureReason(err: any): BlockProposalValidationFailureReason {
+    if (err instanceof TransactionsNotAvailableError) {
+      return 'txs_not_available';
+    } else if (err instanceof ReExInitialStateMismatchError) {
+      return 'initial_state_mismatch';
+    } else if (err instanceof ReExStateMismatchError) {
       return 'state_mismatch';
     } else if (err instanceof ReExFailedTxsError) {
       return 'failed_txs';
@@ -455,6 +577,13 @@ export class BlockProposalHandler {
     await this.worldState.syncImmediate(parentBlockNumber);
     await using fork = await this.worldState.fork(parentBlockNumber);
 
+    // Verify the fork's archive root matches the proposal's expected last archive.
+    // If they don't match, our world state synced to a different chain and reexecution would fail.
+    const forkArchiveRoot = new Fr((await fork.getTreeInfo(MerkleTreeId.ARCHIVE)).root);
+    if (!forkArchiveRoot.equals(proposal.blockHeader.lastArchive.root)) {
+      throw new ReExInitialStateMismatchError(proposal.blockHeader.lastArchive.root, forkArchiveRoot);
+    }
+
     // Build checkpoint constants from proposal (excludes blockNumber which is per-block)
     const constants: CheckpointGlobalVariables = {
       chainId: new Fr(config.l1ChainId),
@@ -480,18 +609,27 @@ export class BlockProposalHandler {
 
     // Build the new block
     const deadline = this.getReexecutionDeadline(slot, config);
+    const maxBlockGas =
+      this.config.validateMaxL2BlockGas !== undefined || this.config.validateMaxDABlockGas !== undefined
+        ? new Gas(this.config.validateMaxDABlockGas ?? Infinity, this.config.validateMaxL2BlockGas ?? Infinity)
+        : undefined;
     const result = await checkpointBuilder.buildBlock(txs, blockNumber, blockHeader.globalVariables.timestamp, {
+      isBuildingProposal: false,
+      minValidTxs: 0,
       deadline,
       expectedEndState: blockHeader.state,
+      maxTransactions: this.config.validateMaxTxsPerBlock,
+      maxBlockGas,
     });
 
     const { block, failedTxs } = result;
     const numFailedTxs = failedTxs.length;
 
-    this.log.verbose(`Transaction re-execution complete for slot ${slot}`, {
+    this.log.verbose(`Block proposal ${blockNumber} at slot ${slot} transaction re-execution complete`, {
       numFailedTxs,
       numProposalTxs: txHashes.length,
       numProcessedTxs: block.body.txEffects.length,
+      blockNumber,
       slot,
     });
 
@@ -532,4 +670,234 @@ export class BlockProposalHandler {
       totalManaUsed,
     };
   }
+
+  /**
+   * Validates a checkpoint proposal and uploads blobs if configured.
+   * Used by both non-validator nodes (via register) and the validator client (via delegation).
+   */
+  async handleCheckpointProposal(
+    proposal: CheckpointProposalCore,
+    proposalInfo: LogData,
+  ): Promise<CheckpointProposalValidationResult> {
+    const proposer = proposal.getSender();
+    if (!proposer) {
+      this.log.warn(`Received checkpoint proposal with invalid signature for slot ${proposal.slotNumber}`);
+      return { isValid: false, reason: 'invalid_signature' };
+    }
+
+    if (!validateFeeAssetPriceModifier(proposal.feeAssetPriceModifier)) {
+      this.log.warn(
+        `Received checkpoint proposal with invalid feeAssetPriceModifier ${proposal.feeAssetPriceModifier} for slot ${proposal.slotNumber}`,
+      );
+      return { isValid: false, reason: 'invalid_fee_asset_price_modifier' };
+    }
+
+    const result = await this.validateCheckpointProposal(proposal, proposalInfo);
+
+    // Upload blobs to filestore if validation passed (fire and forget)
+    if (result.isValid) {
+      this.tryUploadBlobsForCheckpoint(proposal, proposalInfo);
+    }
+
+    return result;
+  }
+
+  /**
+   * Validates a checkpoint proposal by building the full checkpoint and comparing it with the proposal.
+   * @returns Validation result with isValid flag and reason if invalid.
+   */
+  async validateCheckpointProposal(
+    proposal: CheckpointProposalCore,
+    proposalInfo: LogData,
+  ): Promise<CheckpointProposalValidationResult> {
+    const slot = proposal.slotNumber;
+
+    // Timeout block syncing at the start of the next slot
+    const config = this.checkpointsBuilder.getConfig();
+    const nextSlotTimestampSeconds = Number(getTimestampForSlot(SlotNumber(slot + 1), config));
+    const timeoutSeconds = Math.max(1, nextSlotTimestampSeconds - Math.floor(this.dateProvider.now() / 1000));
+
+    // Wait for last block to sync by archive
+    let lastBlockHeader;
+    try {
+      lastBlockHeader = await retryUntil(
+        async () => {
+          await this.blockSource.syncImmediate();
+          return this.blockSource.getBlockHeaderByArchive(proposal.archive);
+        },
+        `waiting for block with archive ${proposal.archive.toString()} for slot ${slot}`,
+        timeoutSeconds,
+        0.5,
+      );
+    } catch (err) {
+      if (err instanceof TimeoutError) {
+        this.log.warn(`Timed out waiting for block with archive matching checkpoint proposal`, proposalInfo);
+        return { isValid: false, reason: 'last_block_not_found' };
+      }
+      this.log.error(`Error fetching last block for checkpoint proposal`, err, proposalInfo);
+      return { isValid: false, reason: 'block_fetch_error' };
+    }
+
+    if (!lastBlockHeader) {
+      this.log.warn(`Last block not found for checkpoint proposal`, proposalInfo);
+      return { isValid: false, reason: 'last_block_not_found' };
+    }
+
+    // Get all full blocks for the slot and checkpoint
+    const blocks = await this.blockSource.getBlocksForSlot(slot);
+    if (blocks.length === 0) {
+      this.log.warn(`No blocks found for slot ${slot}`, proposalInfo);
+      return { isValid: false, reason: 'no_blocks_for_slot' };
+    }
+
+    // Ensure the last block for this slot matches the archive in the checkpoint proposal
+    if (!blocks.at(-1)?.archive.root.equals(proposal.archive)) {
+      this.log.warn(`Last block archive mismatch for checkpoint proposal`, proposalInfo);
+      return { isValid: false, reason: 'last_block_archive_mismatch' };
+    }
+
+    this.log.debug(`Found ${blocks.length} blocks for slot ${slot}`, {
+      ...proposalInfo,
+      blockNumbers: blocks.map(b => b.number),
+    });
+
+    // Get checkpoint constants from first block
+    const firstBlock = blocks[0];
+    const constants = this.extractCheckpointConstants(firstBlock);
+    const checkpointNumber = firstBlock.checkpointNumber;
+
+    // Get L1-to-L2 messages for this checkpoint
+    const l1ToL2Messages = await this.l1ToL2MessageSource.getL1ToL2Messages(checkpointNumber);
+
+    // Collect the out hashes of all the checkpoints before this one in the same epoch
+    const epoch = getEpochAtSlot(slot, this.epochCache.getL1Constants());
+    const previousCheckpointOutHashes = (await this.blockSource.getCheckpointsDataForEpoch(epoch))
+      .filter(c => c.checkpointNumber < checkpointNumber)
+      .map(c => c.checkpointOutHash);
+
+    // Fork world state at the block before the first block
+    const parentBlockNumber = BlockNumber(firstBlock.number - 1);
+    const fork = await this.worldState.fork(parentBlockNumber);
+
+    try {
+      // Create checkpoint builder with all existing blocks
+      const checkpointBuilder = await this.checkpointsBuilder.openCheckpoint(
+        checkpointNumber,
+        constants,
+        proposal.feeAssetPriceModifier,
+        l1ToL2Messages,
+        previousCheckpointOutHashes,
+        fork,
+        blocks,
+        this.log.getBindings(),
+      );
+
+      // Complete the checkpoint to get computed values
+      const computedCheckpoint = await checkpointBuilder.completeCheckpoint();
+
+      // Compare checkpoint header with proposal
+      if (!computedCheckpoint.header.equals(proposal.checkpointHeader)) {
+        this.log.warn(`Checkpoint header mismatch`, {
+          ...proposalInfo,
+          computed: computedCheckpoint.header.toInspect(),
+          proposal: proposal.checkpointHeader.toInspect(),
+        });
+        return { isValid: false, reason: 'checkpoint_header_mismatch' };
+      }
+
+      // Compare archive root with proposal
+      if (!computedCheckpoint.archive.root.equals(proposal.archive)) {
+        this.log.warn(`Archive root mismatch`, {
+          ...proposalInfo,
+          computed: computedCheckpoint.archive.root.toString(),
+          proposal: proposal.archive.toString(),
+        });
+        return { isValid: false, reason: 'archive_mismatch' };
+      }
+
+      // Check that the accumulated epoch out hash matches the value in the proposal.
+      // The epoch out hash is the accumulated hash of all checkpoint out hashes in the epoch.
+      const checkpointOutHash = computedCheckpoint.getCheckpointOutHash();
+      const computedEpochOutHash = accumulateCheckpointOutHashes([...previousCheckpointOutHashes, checkpointOutHash]);
+      const proposalEpochOutHash = proposal.checkpointHeader.epochOutHash;
+      if (!computedEpochOutHash.equals(proposalEpochOutHash)) {
+        this.log.warn(`Epoch out hash mismatch`, {
+          proposalEpochOutHash: proposalEpochOutHash.toString(),
+          computedEpochOutHash: computedEpochOutHash.toString(),
+          checkpointOutHash: checkpointOutHash.toString(),
+          previousCheckpointOutHashes: previousCheckpointOutHashes.map(h => h.toString()),
+          ...proposalInfo,
+        });
+        return { isValid: false, reason: 'out_hash_mismatch' };
+      }
+
+      // Final round of validations on the checkpoint, just in case.
+      try {
+        validateCheckpoint(computedCheckpoint, {
+          rollupManaLimit: this.checkpointsBuilder.getConfig().rollupManaLimit,
+          maxDABlockGas: this.config.validateMaxDABlockGas,
+          maxL2BlockGas: this.config.validateMaxL2BlockGas,
+          maxTxsPerBlock: this.config.validateMaxTxsPerBlock,
+          maxTxsPerCheckpoint: this.config.validateMaxTxsPerCheckpoint,
+        });
+      } catch (err) {
+        this.log.warn(`Checkpoint validation failed: ${err}`, proposalInfo);
+        return { isValid: false, reason: 'checkpoint_validation_failed' };
+      }
+
+      this.log.verbose(`Checkpoint proposal validation successful for slot ${slot}`, proposalInfo);
+      return { isValid: true };
+    } finally {
+      await fork.close();
+    }
+  }
+
+  /** Extracts checkpoint global variables from a block. */
+  private extractCheckpointConstants(block: L2Block): CheckpointGlobalVariables {
+    const gv = block.header.globalVariables;
+    return {
+      chainId: gv.chainId,
+      version: gv.version,
+      slotNumber: gv.slotNumber,
+      timestamp: gv.timestamp,
+      coinbase: gv.coinbase,
+      feeRecipient: gv.feeRecipient,
+      gasFees: gv.gasFees,
+    };
+  }
+
+  /** Triggers blob upload for a checkpoint if the blob client can upload (fire and forget). */
+  protected tryUploadBlobsForCheckpoint(proposal: CheckpointProposalCore, proposalInfo: LogData): void {
+    if (this.blobClient.canUpload()) {
+      void this.uploadBlobsForCheckpoint(proposal, proposalInfo);
+    }
+  }
+
+  /** Uploads blobs for a checkpoint to the filestore. */
+  protected async uploadBlobsForCheckpoint(proposal: CheckpointProposalCore, proposalInfo: LogData): Promise<void> {
+    try {
+      const lastBlockHeader = await this.blockSource.getBlockHeaderByArchive(proposal.archive);
+      if (!lastBlockHeader) {
+        this.log.warn(`Failed to get last block header for blob upload`, proposalInfo);
+        return;
+      }
+
+      const blocks = await this.blockSource.getBlocksForSlot(proposal.slotNumber);
+      if (blocks.length === 0) {
+        this.log.warn(`No blocks found for blob upload`, proposalInfo);
+        return;
+      }
+
+      const blockBlobData = blocks.map(b => b.toBlockBlobData());
+      const blobFields = encodeCheckpointBlobDataFromBlocks(blockBlobData);
+      const blobs: Blob[] = await getBlobsPerL1Block(blobFields);
+      await this.blobClient.sendBlobsToFilestore(blobs);
+      this.log.debug(`Uploaded ${blobs.length} blobs to filestore for checkpoint at slot ${proposal.slotNumber}`, {
+        ...proposalInfo,
+        numBlobs: blobs.length,
+      });
+    } catch (err) {
+      this.log.warn(`Failed to upload blobs for checkpoint: ${err}`, proposalInfo);
+    }
+  }
 }