@aztec/archiver 0.0.1-commit.fffb133c → 0.0.1-dev

package/src/store/block_store.ts

@@ -9,17 +9,21 @@ import { isDefined } from '@aztec/foundation/types';
 import type { AztecAsyncKVStore, AztecAsyncMap, AztecAsyncSingleton, Range } from '@aztec/kv-store';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 import {
+  type BlockData,
+  BlockHash,
   Body,
   CheckpointedL2Block,
   CommitteeAttestation,
+  GENESIS_CHECKPOINT_HEADER_HASH,
   L2Block,
-  L2BlockHash,
+  type L2TipId,
+  type L2Tips,
   type ValidateCheckpointResult,
   deserializeValidateCheckpointResult,
   serializeValidateCheckpointResult,
 } from '@aztec/stdlib/block';
-import { L1PublishedData, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
-import type { L1RollupConstants } from '@aztec/stdlib/epoch-helpers';
+import { type CheckpointData, L1PublishedData, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
+import { type L1RollupConstants, getEpochAtSlot } from '@aztec/stdlib/epoch-helpers';
 import { CheckpointHeader } from '@aztec/stdlib/rollup';
 import { AppendOnlyTreeSnapshot } from '@aztec/stdlib/trees';
 import {
@@ -34,15 +38,14 @@ import {
 } from '@aztec/stdlib/tx';
 
 import {
+  BlockAlreadyCheckpointedError,
   BlockArchiveNotConsistentError,
   BlockIndexNotSequentialError,
   BlockNotFoundError,
   BlockNumberNotSequentialError,
   CannotOverwriteCheckpointedBlockError,
   CheckpointNotFoundError,
-  CheckpointNumberNotConsistentError,
   CheckpointNumberNotSequentialError,
-  InitialBlockNumberNotSequentialError,
   InitialCheckpointNumberNotSequentialError,
 } from '../errors.js';
 
@@ -61,23 +64,14 @@ type BlockStorage = {
 type CheckpointStorage = {
   header: Buffer;
   archive: Buffer;
+  checkpointOutHash: Buffer;
   checkpointNumber: number;
   startBlock: number;
-  numBlocks: number;
+  blockCount: number;
   l1: Buffer;
   attestations: Buffer[];
 };
 
-export type CheckpointData = {
-  checkpointNumber: CheckpointNumber;
-  header: CheckpointHeader;
-  archive: AppendOnlyTreeSnapshot;
-  startBlock: number;
-  numBlocks: number;
-  l1: L1PublishedData;
-  attestations: Buffer[];
-};
-
 export type RemoveCheckpointsResult = { blocksRemoved: L2Block[] | undefined };
 
 /**
@@ -90,6 +84,9 @@ export class BlockStore {
   /** Map checkpoint number to checkpoint data */
   #checkpoints: AztecAsyncMap<number, CheckpointStorage>;
 
+  /** Map slot number to checkpoint number, for looking up checkpoints by slot range. */
+  #slotToCheckpoint: AztecAsyncMap<number, number>;
+
   /** Map block hash to list of tx hashes */
   #blockTxs: AztecAsyncMap<string, Buffer>;
 
@@ -102,6 +99,9 @@ export class BlockStore {
   /** Stores last proven checkpoint */
   #lastProvenCheckpoint: AztecAsyncSingleton<number>;
 
+  /** Stores last finalized checkpoint (proven at or before the finalized L1 block) */
+  #lastFinalizedCheckpoint: AztecAsyncSingleton<number>;
+
   /** Stores the pending chain validation status */
   #pendingChainValidationStatus: AztecAsyncSingleton<Buffer>;
 
@@ -116,10 +116,7 @@ export class BlockStore {
 
   #log = createLogger('archiver:block_store');
 
-  constructor(
-    private db: AztecAsyncKVStore,
-    private l1Constants: Pick<L1RollupConstants, 'epochDuration'>,
-  ) {
+  constructor(private db: AztecAsyncKVStore) {
     this.#blocks = db.openMap('archiver_blocks');
     this.#blockTxs = db.openMap('archiver_block_txs');
     this.#txEffects = db.openMap('archiver_tx_effects');
@@ -128,40 +125,42 @@ export class BlockStore {
     this.#blockArchiveIndex = db.openMap('archiver_block_archive_index');
     this.#lastSynchedL1Block = db.openSingleton('archiver_last_synched_l1_block');
     this.#lastProvenCheckpoint = db.openSingleton('archiver_last_proven_l2_checkpoint');
+    this.#lastFinalizedCheckpoint = db.openSingleton('archiver_last_finalized_l2_checkpoint');
     this.#pendingChainValidationStatus = db.openSingleton('archiver_pending_chain_validation_status');
     this.#checkpoints = db.openMap('archiver_checkpoints');
+    this.#slotToCheckpoint = db.openMap('archiver_slot_to_checkpoint');
   }
 
   /**
-   * Computes the finalized block number based on the proven block number.
-   * A block is considered finalized when it's 2 epochs behind the proven block.
-   * TODO(#13569): Compute proper finalized block number based on L1 finalized block.
-   * TODO(palla/mbps): Even the provisional computation is wrong, since it should subtract checkpoints, not blocks
+   * Returns the finalized L2 block number. An L2 block is finalized when it was proven
+   * in an L1 block that has itself been finalized on Ethereum.
    * @returns The finalized block number.
    */
   async getFinalizedL2BlockNumber(): Promise<BlockNumber> {
-    const provenBlockNumber = await this.getProvenBlockNumber();
-    return BlockNumber(Math.max(provenBlockNumber - this.l1Constants.epochDuration * 2, 0));
+    const finalizedCheckpointNumber = await this.getFinalizedCheckpointNumber();
+    if (finalizedCheckpointNumber === INITIAL_CHECKPOINT_NUMBER - 1) {
+      return BlockNumber(INITIAL_L2_BLOCK_NUM - 1);
+    }
+    const checkpointStorage = await this.#checkpoints.getAsync(finalizedCheckpointNumber);
+    if (!checkpointStorage) {
+      throw new CheckpointNotFoundError(finalizedCheckpointNumber);
+    }
+    return BlockNumber(checkpointStorage.startBlock + checkpointStorage.blockCount - 1);
   }
 
   /**
-   * Append new proposed blocks to the store's list. All blocks must be for the 'current' checkpoint.
-   * These are uncheckpointed blocks that have been proposed by the sequencer but not yet included in a checkpoint on L1.
+   * Append a new proposed block to the store.
+   * This is an uncheckpointed block that has been proposed by the sequencer but not yet included in a checkpoint on L1.
    * For checkpointed blocks (already published to L1), use addCheckpoints() instead.
-   * @param blocks - The proposed L2 blocks to be added to the store.
+   * @param block - The proposed L2 block to be added to the store.
    * @returns True if the operation is successful.
    */
-  async addProposedBlocks(blocks: L2Block[], opts: { force?: boolean } = {}): Promise<boolean> {
-    if (blocks.length === 0) {
-      return true;
-    }
-
+  async addProposedBlock(block: L2Block, opts: { force?: boolean } = {}): Promise<boolean> {
     return await this.db.transactionAsync(async () => {
-      // Check that the block immediately before the first block to be added is present in the store.
-      const firstBlockNumber = blocks[0].number;
-      const firstBlockCheckpointNumber = blocks[0].checkpointNumber;
-      const firstBlockIndex = blocks[0].indexWithinCheckpoint;
-      const firstBlockLastArchive = blocks[0].header.lastArchive.root;
+      const blockNumber = block.number;
+      const blockCheckpointNumber = block.checkpointNumber;
+      const blockIndex = block.indexWithinCheckpoint;
+      const blockLastArchive = block.header.lastArchive.root;
 
       // Extract the latest block and checkpoint numbers
       const previousBlockNumber = await this.getLatestBlockNumber();
@@ -169,71 +168,52 @@ export class BlockStore {
 
       // Verify we're not overwriting checkpointed blocks
       const lastCheckpointedBlockNumber = await this.getCheckpointedL2BlockNumber();
-      if (!opts.force && firstBlockNumber <= lastCheckpointedBlockNumber) {
-        throw new CannotOverwriteCheckpointedBlockError(firstBlockNumber, lastCheckpointedBlockNumber);
+      if (!opts.force && blockNumber <= lastCheckpointedBlockNumber) {
+        // Check if the proposed block matches the already-checkpointed one
+        const existingBlock = await this.getBlock(BlockNumber(blockNumber));
+        if (existingBlock && existingBlock.archive.root.equals(block.archive.root)) {
+          throw new BlockAlreadyCheckpointedError(blockNumber);
+        }
+        throw new CannotOverwriteCheckpointedBlockError(blockNumber, lastCheckpointedBlockNumber);
       }
 
-      // Check that the first block number is the expected one
-      if (!opts.force && previousBlockNumber !== firstBlockNumber - 1) {
-        throw new InitialBlockNumberNotSequentialError(firstBlockNumber, previousBlockNumber);
+      // Check that the block number is the expected one
+      if (!opts.force && previousBlockNumber !== blockNumber - 1) {
+        throw new BlockNumberNotSequentialError(blockNumber, previousBlockNumber);
       }
 
       // The same check as above but for checkpoints
-      if (!opts.force && previousCheckpointNumber !== firstBlockCheckpointNumber - 1) {
-        throw new InitialCheckpointNumberNotSequentialError(firstBlockCheckpointNumber, previousCheckpointNumber);
+      if (!opts.force && previousCheckpointNumber !== blockCheckpointNumber - 1) {
+        throw new CheckpointNumberNotSequentialError(blockCheckpointNumber, previousCheckpointNumber);
       }
 
       // Extract the previous block if there is one and see if it is for the same checkpoint or not
       const previousBlockResult = await this.getBlock(previousBlockNumber);
 
-      let expectedFirstblockIndex = 0;
+      let expectedBlockIndex = 0;
       let previousBlockIndex: number | undefined = undefined;
       if (previousBlockResult !== undefined) {
-        if (previousBlockResult.checkpointNumber === firstBlockCheckpointNumber) {
+        if (previousBlockResult.checkpointNumber === blockCheckpointNumber) {
           // The previous block is for the same checkpoint, therefore our index should follow it
           previousBlockIndex = previousBlockResult.indexWithinCheckpoint;
-          expectedFirstblockIndex = previousBlockIndex + 1;
+          expectedBlockIndex = previousBlockIndex + 1;
         }
-        if (!previousBlockResult.archive.root.equals(firstBlockLastArchive)) {
+        if (!previousBlockResult.archive.root.equals(blockLastArchive)) {
           throw new BlockArchiveNotConsistentError(
-            firstBlockNumber,
+            blockNumber,
             previousBlockResult.number,
-            firstBlockLastArchive,
+            blockLastArchive,
             previousBlockResult.archive.root,
           );
         }
       }
 
-      // Now check that the first block has the expected index value
-      if (!opts.force && expectedFirstblockIndex !== firstBlockIndex) {
-        throw new BlockIndexNotSequentialError(firstBlockIndex, previousBlockIndex);
+      // Now check that the block has the expected index value
+      if (!opts.force && expectedBlockIndex !== blockIndex) {
+        throw new BlockIndexNotSequentialError(blockIndex, previousBlockIndex);
       }
 
-      // Iterate over blocks array and insert them, checking that the block numbers and indexes are sequential. Also check they are for the correct checkpoint.
-      let previousBlock: L2Block | undefined = undefined;
-      for (const block of blocks) {
-        if (!opts.force && previousBlock) {
-          if (previousBlock.number + 1 !== block.number) {
-            throw new BlockNumberNotSequentialError(block.number, previousBlock.number);
-          }
-          if (previousBlock.indexWithinCheckpoint + 1 !== block.indexWithinCheckpoint) {
-            throw new BlockIndexNotSequentialError(block.indexWithinCheckpoint, previousBlock.indexWithinCheckpoint);
-          }
-          if (!previousBlock.archive.root.equals(block.header.lastArchive.root)) {
-            throw new BlockArchiveNotConsistentError(
-              block.number,
-              previousBlock.number,
-              block.header.lastArchive.root,
-              previousBlock.archive.root,
-            );
-          }
-        }
-        if (!opts.force && firstBlockCheckpointNumber !== block.checkpointNumber) {
-          throw new CheckpointNumberNotConsistentError(block.checkpointNumber, firstBlockCheckpointNumber);
-        }
-        previousBlock = block;
-        await this.addBlockToDatabase(block, block.checkpointNumber, block.indexWithinCheckpoint);
-      }
+      await this.addBlockToDatabase(block, block.checkpointNumber, block.indexWithinCheckpoint);
 
       return true;
     });
@@ -250,21 +230,34 @@ export class BlockStore {
     }
 
     return await this.db.transactionAsync(async () => {
-      // Check that the checkpoint immediately before the first block to be added is present in the store.
       const firstCheckpointNumber = checkpoints[0].checkpoint.number;
       const previousCheckpointNumber = await this.getLatestCheckpointNumber();
 
-      if (previousCheckpointNumber !== firstCheckpointNumber - 1 && !opts.force) {
+      // Handle already-stored checkpoints at the start of the batch.
+      // This can happen after an L1 reorg re-includes a checkpoint in a different L1 block.
+      // We accept them if archives match (same content) and update their L1 metadata.
+      if (!opts.force && firstCheckpointNumber <= previousCheckpointNumber) {
+        checkpoints = await this.skipOrUpdateAlreadyStoredCheckpoints(checkpoints, previousCheckpointNumber);
+        if (checkpoints.length === 0) {
+          return true;
+        }
+        // Re-check sequentiality after skipping
+        const newFirstNumber = checkpoints[0].checkpoint.number;
+        if (previousCheckpointNumber !== newFirstNumber - 1) {
+          throw new InitialCheckpointNumberNotSequentialError(newFirstNumber, previousCheckpointNumber);
+        }
+      } else if (previousCheckpointNumber !== firstCheckpointNumber - 1 && !opts.force) {
         throw new InitialCheckpointNumberNotSequentialError(firstCheckpointNumber, previousCheckpointNumber);
       }
 
       // Extract the previous checkpoint if there is one
+      const currentFirstCheckpointNumber = checkpoints[0].checkpoint.number;
       let previousCheckpointData: CheckpointData | undefined = undefined;
-      if (previousCheckpointNumber !== INITIAL_CHECKPOINT_NUMBER - 1) {
+      if (currentFirstCheckpointNumber - 1 !== INITIAL_CHECKPOINT_NUMBER - 1) {
         // There should be a previous checkpoint
-        previousCheckpointData = await this.getCheckpointData(previousCheckpointNumber);
+        previousCheckpointData = await this.getCheckpointData(CheckpointNumber(currentFirstCheckpointNumber - 1));
         if (previousCheckpointData === undefined) {
-          throw new CheckpointNotFoundError(previousCheckpointNumber);
+          throw new CheckpointNotFoundError(CheckpointNumber(currentFirstCheckpointNumber - 1));
         }
       }
 
@@ -273,7 +266,7 @@ export class BlockStore {
 
       // If we have a previous checkpoint then we need to get the previous block number
       if (previousCheckpointData !== undefined) {
-        previousBlockNumber = BlockNumber(previousCheckpointData.startBlock + previousCheckpointData.numBlocks - 1);
+        previousBlockNumber = BlockNumber(previousCheckpointData.startBlock + previousCheckpointData.blockCount - 1);
         previousBlock = await this.getBlock(previousBlockNumber);
         if (previousBlock === undefined) {
           // We should be able to get the required previous block
@@ -337,12 +330,16 @@ export class BlockStore {
         await this.#checkpoints.set(checkpoint.checkpoint.number, {
           header: checkpoint.checkpoint.header.toBuffer(),
           archive: checkpoint.checkpoint.archive.toBuffer(),
+          checkpointOutHash: checkpoint.checkpoint.getCheckpointOutHash().toBuffer(),
           l1: checkpoint.l1.toBuffer(),
           attestations: checkpoint.attestations.map(attestation => attestation.toBuffer()),
           checkpointNumber: checkpoint.checkpoint.number,
           startBlock: checkpoint.checkpoint.blocks[0].number,
-          numBlocks: checkpoint.checkpoint.blocks.length,
+          blockCount: checkpoint.checkpoint.blocks.length,
         });
+
+        // Update slot-to-checkpoint index
+        await this.#slotToCheckpoint.set(checkpoint.checkpoint.header.slotNumber, checkpoint.checkpoint.number);
       }
 
       await this.#lastSynchedL1Block.set(checkpoints[checkpoints.length - 1].l1.blockNumber);
@@ -350,8 +347,52 @@ export class BlockStore {
     });
   }
 
+  /**
+   * Handles checkpoints at the start of a batch that are already stored (e.g. due to L1 reorg).
+   * Verifies the archive root matches, updates L1 metadata, and returns only the new checkpoints.
+   */
+  private async skipOrUpdateAlreadyStoredCheckpoints(
+    checkpoints: PublishedCheckpoint[],
+    latestStored: CheckpointNumber,
+  ): Promise<PublishedCheckpoint[]> {
+    let i = 0;
+    for (; i < checkpoints.length && checkpoints[i].checkpoint.number <= latestStored; i++) {
+      const incoming = checkpoints[i];
+      const stored = await this.getCheckpointData(incoming.checkpoint.number);
+      if (!stored) {
+        // Should not happen if latestStored is correct, but be safe
+        break;
+      }
+      // Verify the checkpoint content matches (archive root)
+      if (!stored.archive.root.equals(incoming.checkpoint.archive.root)) {
+        throw new Error(
+          `Checkpoint ${incoming.checkpoint.number} already exists in store but with a different archive root. ` +
+            `Stored: ${stored.archive.root}, incoming: ${incoming.checkpoint.archive.root}`,
+        );
+      }
+      // Update L1 metadata and attestations for the already-stored checkpoint
+      this.#log.warn(
+        `Checkpoint ${incoming.checkpoint.number} already stored, updating L1 info ` +
+          `(L1 block ${stored.l1.blockNumber} -> ${incoming.l1.blockNumber})`,
+      );
+      await this.#checkpoints.set(incoming.checkpoint.number, {
+        header: incoming.checkpoint.header.toBuffer(),
+        archive: incoming.checkpoint.archive.toBuffer(),
+        checkpointOutHash: incoming.checkpoint.getCheckpointOutHash().toBuffer(),
+        l1: incoming.l1.toBuffer(),
+        attestations: incoming.attestations.map(a => a.toBuffer()),
+        checkpointNumber: incoming.checkpoint.number,
+        startBlock: incoming.checkpoint.blocks[0].number,
+        blockCount: incoming.checkpoint.blocks.length,
+      });
+      // Update the sync point to reflect the new L1 block
+      await this.#lastSynchedL1Block.set(incoming.l1.blockNumber);
+    }
+    return checkpoints.slice(i);
+  }
+
   private async addBlockToDatabase(block: L2Block, checkpointNumber: number, indexWithinCheckpoint: number) {
-    const blockHash = L2BlockHash.fromField(await block.hash());
+    const blockHash = await block.hash();
 
     await this.#blocks.set(block.number, {
       header: block.header.toBuffer(),
@@ -425,7 +466,7 @@ export class BlockStore {
         if (!targetCheckpoint) {
           throw new Error(`Target checkpoint ${checkpointNumber} not found in store`);
         }
-        lastBlockToKeep = BlockNumber(targetCheckpoint.startBlock + targetCheckpoint.numBlocks - 1);
+        lastBlockToKeep = BlockNumber(targetCheckpoint.startBlock + targetCheckpoint.blockCount - 1);
       }
 
       // Remove all blocks after lastBlockToKeep (both checkpointed and uncheckpointed)
@@ -433,6 +474,11 @@ export class BlockStore {
 
       // Remove all checkpoints after the target
       for (let c = latestCheckpointNumber; c > checkpointNumber; c = CheckpointNumber(c - 1)) {
+        const checkpointStorage = await this.#checkpoints.getAsync(c);
+        if (checkpointStorage) {
+          const slotNumber = CheckpointHeader.fromBuffer(checkpointStorage.header).slotNumber;
+          await this.#slotToCheckpoint.delete(slotNumber);
+        }
         await this.#checkpoints.delete(c);
         this.#log.debug(`Removed checkpoint ${c}`);
       }
@@ -461,17 +507,32 @@ export class BlockStore {
     return checkpoints;
   }
 
-  private checkpointDataFromCheckpointStorage(checkpointStorage: CheckpointStorage) {
-    const data: CheckpointData = {
+  /** Returns checkpoint data for all checkpoints whose slot falls within the given range (inclusive). */
+  async getCheckpointDataForSlotRange(startSlot: SlotNumber, endSlot: SlotNumber): Promise<CheckpointData[]> {
+    const result: CheckpointData[] = [];
+    for await (const [, checkpointNumber] of this.#slotToCheckpoint.entriesAsync({
+      start: startSlot,
+      end: endSlot + 1,
+    })) {
+      const checkpointStorage = await this.#checkpoints.getAsync(checkpointNumber);
+      if (checkpointStorage) {
+        result.push(this.checkpointDataFromCheckpointStorage(checkpointStorage));
+      }
+    }
+    return result;
+  }
+
+  private checkpointDataFromCheckpointStorage(checkpointStorage: CheckpointStorage): CheckpointData {
+    return {
       header: CheckpointHeader.fromBuffer(checkpointStorage.header),
       archive: AppendOnlyTreeSnapshot.fromBuffer(checkpointStorage.archive),
+      checkpointOutHash: Fr.fromBuffer(checkpointStorage.checkpointOutHash),
       checkpointNumber: CheckpointNumber(checkpointStorage.checkpointNumber),
-      startBlock: checkpointStorage.startBlock,
-      numBlocks: checkpointStorage.numBlocks,
+      startBlock: BlockNumber(checkpointStorage.startBlock),
+      blockCount: checkpointStorage.blockCount,
       l1: L1PublishedData.fromBuffer(checkpointStorage.l1),
-      attestations: checkpointStorage.attestations,
+      attestations: checkpointStorage.attestations.map(buf => CommitteeAttestation.fromBuffer(buf)),
     };
-    return data;
   }
 
   async getBlocksForCheckpoint(checkpointNumber: CheckpointNumber): Promise<L2Block[] | undefined> {
@@ -483,7 +544,7 @@ export class BlockStore {
     const blocksForCheckpoint = await toArray(
       this.#blocks.entriesAsync({
         start: checkpoint.startBlock,
-        end: checkpoint.startBlock + checkpoint.numBlocks,
+        end: checkpoint.startBlock + checkpoint.blockCount,
       }),
     );
 
@@ -556,7 +617,7 @@ export class BlockStore {
     if (!checkpointStorage) {
       throw new CheckpointNotFoundError(provenCheckpointNumber);
     } else {
-      return BlockNumber(checkpointStorage.startBlock + checkpointStorage.numBlocks - 1);
+      return BlockNumber(checkpointStorage.startBlock + checkpointStorage.blockCount - 1);
     }
   }
 
@@ -567,6 +628,138 @@ export class BlockStore {
       : BlockNumber(INITIAL_L2_BLOCK_NUM - 1);
   }
 
+  /**
+   * Resolves all L2 chain tips in a single read transaction so the snapshot is internally consistent.
+   * The result is guaranteed to satisfy finalized <= proven <= checkpointed <= proposed by block number.
+   */
+  async getL2TipsData(genesisBlockHash: Fr): Promise<L2Tips> {
+    return await this.db.transactionAsync(async () => {
+      const genesisBlockNumber = BlockNumber(INITIAL_L2_BLOCK_NUM - 1);
+      const genesisCheckpointNumber = CheckpointNumber(INITIAL_CHECKPOINT_NUMBER - 1);
+      const genesisBlockId = { number: genesisBlockNumber, hash: genesisBlockHash.toString() };
+      const genesisCheckpointId = {
+        number: genesisCheckpointNumber,
+        hash: GENESIS_CHECKPOINT_HEADER_HASH.toString(),
+      };
+      const genesisTip: L2TipId = { block: genesisBlockId, checkpoint: genesisCheckpointId };
+
+      const [latestBlockEntry] = await toArray(this.#blocks.entriesAsync({ reverse: true, limit: 1 }));
+      const [latestCheckpointEntry] = await toArray(this.#checkpoints.entriesAsync({ reverse: true, limit: 1 }));
+      const latestCheckpointNumber = latestCheckpointEntry
+        ? CheckpointNumber(latestCheckpointEntry[0])
+        : genesisCheckpointNumber;
+
+      const [provenRaw, finalizedRaw] = await Promise.all([
+        this.#lastProvenCheckpoint.getAsync(),
+        this.#lastFinalizedCheckpoint.getAsync(),
+      ]);
+
+      const provenCheckpointNumber = CheckpointNumber(Math.min(provenRaw ?? 0, latestCheckpointNumber));
+      const finalizedCheckpointNumber = CheckpointNumber(Math.min(finalizedRaw ?? 0, provenCheckpointNumber));
+
+      const checkpointStorageCache = new Map<CheckpointNumber, CheckpointStorage>();
+      if (latestCheckpointEntry) {
+        checkpointStorageCache.set(CheckpointNumber(latestCheckpointEntry[0]), latestCheckpointEntry[1]);
+      }
+
+      const loadCheckpointStorage = async (
+        checkpointNumber: CheckpointNumber,
+      ): Promise<CheckpointStorage | undefined> => {
+        if (checkpointNumber === genesisCheckpointNumber) {
+          return undefined;
+        }
+        if (!checkpointStorageCache.has(checkpointNumber)) {
+          const checkpointStorage = await this.#checkpoints.getAsync(checkpointNumber);
+          if (!checkpointStorage) {
+            throw new CheckpointNotFoundError(checkpointNumber);
+          }
+          checkpointStorageCache.set(checkpointNumber, checkpointStorage);
+        }
+        return checkpointStorageCache.get(checkpointNumber)!;
+      };
+
+      const [provenCheckpoint, finalizedCheckpoint] = await Promise.all([
+        loadCheckpointStorage(provenCheckpointNumber),
+        loadCheckpointStorage(finalizedCheckpointNumber),
+      ]);
+
+      const blockHashCache = new Map<BlockNumber, string>();
+      blockHashCache.set(genesisBlockNumber, genesisBlockHash.toString());
+      if (latestBlockEntry) {
+        blockHashCache.set(
+          BlockNumber(latestBlockEntry[0]),
+          BlockHash.fromBuffer(latestBlockEntry[1].blockHash).toString(),
+        );
+      }
+
+      const loadBlockHash = async (blockNumber: BlockNumber): Promise<string> => {
+        if (!blockHashCache.has(blockNumber)) {
+          const blockStorage = await this.#blocks.getAsync(blockNumber);
+          if (!blockStorage) {
+            throw new BlockNotFoundError(blockNumber);
+          }
+          blockHashCache.set(blockNumber, BlockHash.fromBuffer(blockStorage.blockHash).toString());
+        }
+        return blockHashCache.get(blockNumber)!;
+      };
+
+      const proposed =
+        latestBlockEntry === undefined
+          ? genesisBlockId
+          : {
+              number: BlockNumber(latestBlockEntry[0]),
+              hash: BlockHash.fromBuffer(latestBlockEntry[1].blockHash).toString(),
+            };
+
+      const buildTipFromCheckpoint = async (stored: CheckpointStorage | undefined): Promise<L2TipId> => {
+        if (!stored) {
+          return genesisTip;
+        }
+        const blockNumber = BlockNumber(stored.startBlock + stored.blockCount - 1);
+        return {
+          block: { number: blockNumber, hash: await loadBlockHash(blockNumber) },
+          checkpoint: {
+            number: CheckpointNumber(stored.checkpointNumber),
+            hash: CheckpointHeader.fromBuffer(stored.header).hash().toString(),
+          },
+        };
+      };
+
+      const [checkpointed, proven, finalized] = await Promise.all([
+        buildTipFromCheckpoint(latestCheckpointEntry?.[1]),
+        buildTipFromCheckpoint(provenCheckpoint),
+        buildTipFromCheckpoint(finalizedCheckpoint),
+      ]);
+
+      if (proposed.number < checkpointed.block.number) {
+        throw new Error(
+          `Inconsistent block store: latest block ${proposed.number} is behind checkpointed block ${checkpointed.block.number}`,
+        );
+      }
+
+      if (
+        finalized.checkpoint.number > proven.checkpoint.number ||
+        proven.checkpoint.number > checkpointed.checkpoint.number
+      ) {
+        throw new Error(
+          `Inconsistent checkpoint numbers in chain tips: finalized=${finalized.checkpoint.number} proven=${proven.checkpoint.number} checkpointed=${checkpointed.checkpoint.number}`,
+        );
+      }
+
+      if (
+        finalized.block.number > proven.block.number ||
+        proven.block.number > checkpointed.block.number ||
+        checkpointed.block.number > proposed.number
+      ) {
+        throw new Error(
+          `Inconsistent block numbers in chain tips: finalized=${finalized.block.number} proven=${proven.block.number} checkpointed=${checkpointed.block.number} proposed=${proposed.number}`,
+        );
+      }
+
+      return { proposed, checkpointed, proven, finalized };
+    });
+  }
+
   async getLatestCheckpointNumber(): Promise<CheckpointNumber> {
     const [latestCheckpointNumber] = await toArray(this.#checkpoints.keysAsync({ reverse: true, limit: 1 }));
     if (latestCheckpointNumber === undefined) {
@@ -624,7 +817,7 @@ export class BlockStore {
     }
   }
 
-  async getCheckpointedBlockByHash(blockHash: Fr): Promise<CheckpointedL2Block | undefined> {
+  async getCheckpointedBlockByHash(blockHash: BlockHash): Promise<CheckpointedL2Block | undefined> {
     const blockNumber = await this.#blockHashIndex.getAsync(blockHash.toString());
     if (blockNumber === undefined) {
       return undefined;
@@ -655,6 +848,32 @@ export class BlockStore {
     }
   }
 
+  /**
+   * Gets block metadata (without tx data) by block number.
+   * @param blockNumber - The number of the block to return.
+   * @returns The requested block data.
+   */
+  async getBlockData(blockNumber: BlockNumber): Promise<BlockData | undefined> {
+    const blockStorage = await this.#blocks.getAsync(blockNumber);
+    if (!blockStorage || !blockStorage.header) {
+      return undefined;
+    }
+    return this.getBlockDataFromBlockStorage(blockStorage);
+  }
+
+  /**
+   * Gets block metadata (without tx data) by archive root.
+   * @param archive - The archive root of the block to return.
+   * @returns The requested block data.
+   */
+  async getBlockDataByArchive(archive: Fr): Promise<BlockData | undefined> {
+    const blockNumber = await this.#blockArchiveIndex.getAsync(archive.toString());
+    if (blockNumber === undefined) {
+      return undefined;
+    }
+    return this.getBlockData(BlockNumber(blockNumber));
+  }
+
   /**
    * Gets an L2 block.
    * @param blockNumber - The number of the block to return.
@@ -673,7 +892,7 @@ export class BlockStore {
    * @param blockHash - The hash of the block to return.
    * @returns The requested L2 block.
    */
-  async getBlockByHash(blockHash: L2BlockHash): Promise<L2Block | undefined> {
+  async getBlockByHash(blockHash: BlockHash): Promise<L2Block | undefined> {
     const blockNumber = await this.#blockHashIndex.getAsync(blockHash.toString());
     if (blockNumber === undefined) {
       return undefined;
@@ -699,7 +918,7 @@ export class BlockStore {
    * @param blockHash - The hash of the block to return.
    * @returns The requested block header.
    */
-  async getBlockHeaderByHash(blockHash: L2BlockHash): Promise<BlockHeader | undefined> {
+  async getBlockHeaderByHash(blockHash: BlockHash): Promise<BlockHeader | undefined> {
     const blockNumber = await this.#blockHashIndex.getAsync(blockHash.toString());
     if (blockNumber === undefined) {
       return undefined;
@@ -759,15 +978,24 @@ export class BlockStore {
     }
   }
 
+  private getBlockDataFromBlockStorage(blockStorage: BlockStorage): BlockData {
+    return {
+      header: BlockHeader.fromBuffer(blockStorage.header),
+      archive: AppendOnlyTreeSnapshot.fromBuffer(blockStorage.archive),
+      blockHash: Fr.fromBuffer(blockStorage.blockHash),
+      checkpointNumber: CheckpointNumber(blockStorage.checkpointNumber),
+      indexWithinCheckpoint: IndexWithinCheckpoint(blockStorage.indexWithinCheckpoint),
+    };
+  }
+
   private async getBlockFromBlockStorage(
     blockNumber: number,
     blockStorage: BlockStorage,
   ): Promise<L2Block | undefined> {
-    const header = BlockHeader.fromBuffer(blockStorage.header);
-    const archive = AppendOnlyTreeSnapshot.fromBuffer(blockStorage.archive);
-    const blockHash = blockStorage.blockHash;
-    header.setHash(Fr.fromBuffer(blockHash));
-    const blockHashString = bufferToHex(blockHash);
+    const { header, archive, blockHash, checkpointNumber, indexWithinCheckpoint } =
+      this.getBlockDataFromBlockStorage(blockStorage);
+    header.setHash(blockHash);
+    const blockHashString = bufferToHex(blockStorage.blockHash);
     const blockTxsBuffer = await this.#blockTxs.getAsync(blockHashString);
     if (blockTxsBuffer === undefined) {
       this.#log.warn(`Could not find body for block ${header.globalVariables.blockNumber} ${blockHash}`);
@@ -786,13 +1014,7 @@ export class BlockStore {
       txEffects.push(deserializeIndexedTxEffect(txEffect).data);
     }
     const body = new Body(txEffects);
-    const block = new L2Block(
-      archive,
-      header,
-      body,
-      CheckpointNumber(blockStorage.checkpointNumber!),
-      IndexWithinCheckpoint(blockStorage.indexWithinCheckpoint),
-    );
+    const block = new L2Block(archive, header, body, checkpointNumber, indexWithinCheckpoint);
 
     if (block.number !== blockNumber) {
       throw new Error(
@@ -822,7 +1044,10 @@ export class BlockStore {
    * @param txHash - The hash of a tx we try to get the receipt for.
    * @returns The requested tx receipt (or undefined if not found).
    */
-  async getSettledTxReceipt(txHash: TxHash): Promise<TxReceipt | undefined> {
+  async getSettledTxReceipt(
+    txHash: TxHash,
+    l1Constants?: Pick<L1RollupConstants, 'epochDuration'>,
+  ): Promise<TxReceipt | undefined> {
     const txEffect = await this.getTxEffect(txHash);
     if (!txEffect) {
       return undefined;
@@ -831,10 +1056,11 @@ export class BlockStore {
     const blockNumber = BlockNumber(txEffect.l2BlockNumber);
 
     // Use existing archiver methods to determine finalization level
-    const [provenBlockNumber, checkpointedBlockNumber, finalizedBlockNumber] = await Promise.all([
+    const [provenBlockNumber, checkpointedBlockNumber, finalizedBlockNumber, blockData] = await Promise.all([
       this.getProvenBlockNumber(),
       this.getCheckpointedL2BlockNumber(),
       this.getFinalizedL2BlockNumber(),
+      this.getBlockData(blockNumber),
     ]);
 
     let status: TxStatus;
@@ -848,6 +1074,9 @@ export class BlockStore {
       status = TxStatus.PROPOSED;
     }
 
+    const epochNumber =
+      blockData && l1Constants ? getEpochAtSlot(blockData.header.globalVariables.slotNumber, l1Constants) : undefined;
+
     return new TxReceipt(
       txHash,
       status,
@@ -856,6 +1085,7 @@ export class BlockStore {
       txEffect.data.transactionFee.toBigInt(),
       txEffect.l2BlockHash,
       blockNumber,
+      epochNumber,
     );
   }
 
@@ -892,7 +1122,7 @@ export class BlockStore {
     if (!checkpoint) {
       return BlockNumber(INITIAL_L2_BLOCK_NUM - 1);
     }
-    return BlockNumber(checkpoint.startBlock + checkpoint.numBlocks - 1);
+    return BlockNumber(checkpoint.startBlock + checkpoint.blockCount - 1);
   }
 
   async getLatestL2BlockNumber(): Promise<BlockNumber> {
@@ -927,6 +1157,20 @@ export class BlockStore {
     return result;
   }
 
+  async getFinalizedCheckpointNumber(): Promise<CheckpointNumber> {
+    const [latestCheckpointNumber, finalizedCheckpointNumber] = await Promise.all([
+      this.getLatestCheckpointNumber(),
+      this.#lastFinalizedCheckpoint.getAsync(),
+    ]);
+    return (finalizedCheckpointNumber ?? 0) > latestCheckpointNumber
+      ? latestCheckpointNumber
+      : CheckpointNumber(finalizedCheckpointNumber ?? 0);
+  }
+
+  setFinalizedCheckpointNumber(checkpointNumber: CheckpointNumber) {
+    return this.#lastFinalizedCheckpoint.set(checkpointNumber);
+  }
+
   #computeBlockRange(start: BlockNumber, limit: number): Required<Pick<Range<number>, 'start' | 'limit'>> {
     if (limit < 1) {
       throw new Error(`Invalid limit: ${limit}`);