@aztec/archiver 0.0.1-commit.9d2bcf6d → 0.0.1-commit.9d619b6c6

package/dest/store/block_store.js

@@ -6,32 +6,34 @@ import { createLogger } from '@aztec/foundation/log';
 import { BufferReader } from '@aztec/foundation/serialize';
 import { bufferToHex } from '@aztec/foundation/string';
 import { isDefined } from '@aztec/foundation/types';
-import { Body, CheckpointedL2Block, CommitteeAttestation, L2Block, deserializeValidateCheckpointResult, serializeValidateCheckpointResult } from '@aztec/stdlib/block';
-import { L1PublishedData } from '@aztec/stdlib/checkpoint';
+import { BlockHash, Body, CheckpointedL2Block, CommitteeAttestation, L2Block, deserializeValidateCheckpointResult, serializeValidateCheckpointResult } from '@aztec/stdlib/block';
+import { Checkpoint, L1PublishedData } from '@aztec/stdlib/checkpoint';
+import { getEpochAtSlot } from '@aztec/stdlib/epoch-helpers';
 import { CheckpointHeader } from '@aztec/stdlib/rollup';
 import { AppendOnlyTreeSnapshot } from '@aztec/stdlib/trees';
 import { BlockHeader, TxHash, TxReceipt, TxStatus, deserializeIndexedTxEffect, serializeIndexedTxEffect } from '@aztec/stdlib/tx';
-import { BlockArchiveNotConsistentError, BlockIndexNotSequentialError, BlockNotFoundError, BlockNumberNotSequentialError, CannotOverwriteCheckpointedBlockError, CheckpointNotFoundError, CheckpointNumberNotConsistentError, CheckpointNumberNotSequentialError, InitialBlockNumberNotSequentialError, InitialCheckpointNumberNotSequentialError } from '../errors.js';
+import { BlockAlreadyCheckpointedError, BlockArchiveNotConsistentError, BlockIndexNotSequentialError, BlockNotFoundError, BlockNumberNotSequentialError, CannotOverwriteCheckpointedBlockError, CheckpointNotFoundError, CheckpointNumberNotSequentialError, InitialCheckpointNumberNotSequentialError, NoProposedCheckpointToPromoteError, ProposedCheckpointArchiveRootMismatchError, ProposedCheckpointNotSequentialError, ProposedCheckpointPromotionNotSequentialError, ProposedCheckpointStaleError } from '../errors.js';
 export { TxReceipt } from '@aztec/stdlib/tx';
 /**
  * LMDB-based block storage for the archiver.
  */ export class BlockStore {
     db;
-    l1Constants;
     /** Map block number to block data */ #blocks;
     /** Map checkpoint number to checkpoint data */ #checkpoints;
+    /** Map slot number to checkpoint number, for looking up checkpoints by slot range. */ #slotToCheckpoint;
     /** Map block hash to list of tx hashes */ #blockTxs;
     /** Tx hash to serialized IndexedTxEffect */ #txEffects;
     /** Stores L1 block number in which the last processed L2 block was included */ #lastSynchedL1Block;
     /** Stores last proven checkpoint */ #lastProvenCheckpoint;
+    /** Stores last finalized checkpoint (proven at or before the finalized L1 block) */ #lastFinalizedCheckpoint;
     /** Stores the pending chain validation status */ #pendingChainValidationStatus;
     /** Index mapping a contract's address (as a string) to its location in a block */ #contractIndex;
     /** Index mapping block hash to block number */ #blockHashIndex;
     /** Index mapping block archive to block number */ #blockArchiveIndex;
+    /** Singleton: assumes max 1-deep pipeline. For deeper pipelining, replace with a map keyed by checkpoint number. */ #proposedCheckpoint;
     #log;
-    constructor(db, l1Constants){
+    constructor(db){
         this.db = db;
-        this.l1Constants = l1Constants;
         this.#log = createLogger('archiver:block_store');
         this.#blocks = db.openMap('archiver_blocks');
         this.#blockTxs = db.openMap('archiver_block_txs');
@@ -41,94 +43,94 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         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');
+        this.#proposedCheckpoint = db.openSingleton('proposed_checkpoint_data');
     }
     /**
-   * 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() {
-        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, opts = {}) {
-        if (blocks.length === 0) {
-            return true;
-        }
+   */ async addProposedBlock(block, opts = {}) {
         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();
+            const previousBlockNumber = await this.getLatestL2BlockNumber();
+            const proposedCheckpointNumber = await this.getProposedCheckpointNumber();
             const previousCheckpointNumber = await this.getLatestCheckpointNumber();
             // 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);
+            // The same check as above but for checkpoints. Accept the block if either the confirmed
+            // checkpoint or the pending (locally validated but not yet confirmed) checkpoint matches.
+            const expectedCheckpointNumber = blockCheckpointNumber - 1;
+            if (!opts.force && previousCheckpointNumber !== expectedCheckpointNumber && proposedCheckpointNumber !== expectedCheckpointNumber) {
+                const [reported, source] = proposedCheckpointNumber > previousCheckpointNumber ? [
+                    proposedCheckpointNumber,
+                    'proposed'
+                ] : [
+                    previousCheckpointNumber,
+                    'confirmed'
+                ];
+                throw new CheckpointNumberNotSequentialError(blockCheckpointNumber, reported, source);
             }
             // 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 = 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)) {
-                    throw new BlockArchiveNotConsistentError(firstBlockNumber, previousBlockResult.number, firstBlockLastArchive, previousBlockResult.archive.root);
+                if (!previousBlockResult.archive.root.equals(blockLastArchive)) {
+                    throw new BlockArchiveNotConsistentError(blockNumber, previousBlockResult.number, 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);
-            }
-            // 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 = 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);
+            // Now check that the block has the expected index value
+            if (!opts.force && expectedBlockIndex !== blockIndex) {
+                throw new BlockIndexNotSequentialError(blockIndex, previousBlockIndex);
             }
+            await this.addBlockToDatabase(block, block.checkpointNumber, block.indexWithinCheckpoint);
             return true;
         });
     }
     /**
-   * Append new cheskpoints to the store's list.
+   * Append new checkpoints to the store's list.
    * @param checkpoints - The L2 checkpoints to be added to the store.
    * @returns True if the operation is successful.
    */ async addCheckpoints(checkpoints, opts = {}) {
@@ -136,32 +138,26 @@ export { TxReceipt } from '@aztec/stdlib/tx';
             return true;
         }
         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) {
-                throw new InitialCheckpointNumberNotSequentialError(firstCheckpointNumber, previousCheckpointNumber);
-            }
-            // Extract the previous checkpoint if there is one
-            let previousCheckpointData = undefined;
-            if (previousCheckpointNumber !== INITIAL_CHECKPOINT_NUMBER - 1) {
-                // There should be a previous checkpoint
-                previousCheckpointData = await this.getCheckpointData(previousCheckpointNumber);
-                if (previousCheckpointData === undefined) {
-                    throw new CheckpointNotFoundError(previousCheckpointNumber);
+            // 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;
                 }
-            }
-            let previousBlockNumber = undefined;
-            let previousBlock = undefined;
-            // 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);
-                previousBlock = await this.getBlock(previousBlockNumber);
-                if (previousBlock === undefined) {
-                    // We should be able to get the required previous block
-                    throw new BlockNotFoundError(previousBlockNumber);
+                // 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);
             }
+            // Get the last block of the previous checkpoint for archive chaining
+            let previousBlock = await this.getPreviousCheckpointBlock(checkpoints[0].checkpoint.number);
             // Iterate over checkpoints array and insert them, checking that the block numbers are sequential.
             let previousCheckpoint = undefined;
             for (const checkpoint of checkpoints){
@@ -169,48 +165,116 @@ export { TxReceipt } from '@aztec/stdlib/tx';
                     throw new CheckpointNumberNotSequentialError(checkpoint.checkpoint.number, previousCheckpoint.checkpoint.number);
                 }
                 previousCheckpoint = checkpoint;
-                // Store every block in the database. the block may already exist, but this has come from chain and is assumed to be correct.
+                // Validate block sequencing, indexes, and archive chaining
+                this.validateCheckpointBlocks(checkpoint.checkpoint.blocks, previousBlock);
+                // Store every block in the database (may already exist, but L1 data is authoritative)
                 for(let i = 0; i < checkpoint.checkpoint.blocks.length; i++){
-                    const block = checkpoint.checkpoint.blocks[i];
-                    if (previousBlock) {
-                        // The blocks should have a sequential block number
-                        if (previousBlock.number !== block.number - 1) {
-                            throw new BlockNumberNotSequentialError(block.number, previousBlock.number);
-                        }
-                        // If the blocks are for the same checkpoint then they should have sequential indexes
-                        if (previousBlock.checkpointNumber === block.checkpointNumber && previousBlock.indexWithinCheckpoint !== block.indexWithinCheckpoint - 1) {
-                            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);
-                        }
-                    } else {
-                        // No previous block, must be block 1 at checkpoint index 0
-                        if (block.indexWithinCheckpoint !== 0) {
-                            throw new BlockIndexNotSequentialError(block.indexWithinCheckpoint, undefined);
-                        }
-                        if (block.number !== INITIAL_L2_BLOCK_NUM) {
-                            throw new BlockNumberNotSequentialError(block.number, undefined);
-                        }
-                    }
-                    previousBlock = block;
-                    await this.addBlockToDatabase(block, checkpoint.checkpoint.number, i);
+                    await this.addBlockToDatabase(checkpoint.checkpoint.blocks[i], checkpoint.checkpoint.number, i);
                 }
+                previousBlock = checkpoint.checkpoint.blocks.at(-1);
                 // Store the checkpoint in the database
                 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);
             }
+            // Clear the proposed checkpoint if any of the confirmed checkpoints match or supersede it
+            const lastConfirmedCheckpointNumber = checkpoints[checkpoints.length - 1].checkpoint.number;
+            await this.clearProposedCheckpointIfSuperseded(lastConfirmedCheckpointNumber);
             await this.#lastSynchedL1Block.set(checkpoints[checkpoints.length - 1].l1.blockNumber);
             return true;
         });
     }
+    /**
+   * 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.
+   */ async skipOrUpdateAlreadyStoredCheckpoints(checkpoints, latestStored) {
+        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) {
+                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);
+    }
+    /**
+   * Gets the last block of the checkpoint before the given one.
+   * Returns undefined if there is no previous checkpoint (i.e. genesis).
+   */ async getPreviousCheckpointBlock(checkpointNumber) {
+        const previousCheckpointNumber = CheckpointNumber(checkpointNumber - 1);
+        if (previousCheckpointNumber === INITIAL_CHECKPOINT_NUMBER - 1) {
+            return undefined;
+        }
+        const previousCheckpointData = await this.getCheckpointData(previousCheckpointNumber);
+        if (previousCheckpointData === undefined) {
+            throw new CheckpointNotFoundError(previousCheckpointNumber);
+        }
+        const previousBlockNumber = BlockNumber(previousCheckpointData.startBlock + previousCheckpointData.blockCount - 1);
+        const previousBlock = await this.getBlock(previousBlockNumber);
+        if (previousBlock === undefined) {
+            throw new BlockNotFoundError(previousBlockNumber);
+        }
+        return previousBlock;
+    }
+    /**
+   * Validates that blocks are sequential, have correct indexes, and chain via archive roots.
+   * This is the same validation used for both confirmed checkpoints (addCheckpoints) and
+   * proposed checkpoints (setProposedCheckpoint).
+   */ validateCheckpointBlocks(blocks, previousBlock) {
+        for (const block of blocks){
+            if (previousBlock) {
+                if (previousBlock.number !== block.number - 1) {
+                    throw new BlockNumberNotSequentialError(block.number, previousBlock.number);
+                }
+                if (previousBlock.checkpointNumber === block.checkpointNumber) {
+                    if (previousBlock.indexWithinCheckpoint !== block.indexWithinCheckpoint - 1) {
+                        throw new BlockIndexNotSequentialError(block.indexWithinCheckpoint, previousBlock.indexWithinCheckpoint);
+                    }
+                } else if (block.indexWithinCheckpoint !== 0) {
+                    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);
+                }
+            } else {
+                if (block.indexWithinCheckpoint !== 0) {
+                    throw new BlockIndexNotSequentialError(block.indexWithinCheckpoint, undefined);
+                }
+                if (block.number !== INITIAL_L2_BLOCK_NUM) {
+                    throw new BlockNumberNotSequentialError(block.number, undefined);
+                }
+            }
+            previousBlock = block;
+        }
+    }
     async addBlockToDatabase(block, checkpointNumber, indexWithinCheckpoint) {
         const blockHash = await block.hash();
         await this.#blocks.set(block.number, {
@@ -274,15 +338,25 @@ export { TxReceipt } from '@aztec/stdlib/tx';
                 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)
             const blocksRemoved = await this.removeBlocksAfter(lastBlockToKeep);
             // 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}`);
             }
+            // Clear any proposed checkpoint that was orphaned by the removal (its base chain no longer exists)
+            const proposedCheckpointNumber = await this.getProposedCheckpointNumber();
+            if (proposedCheckpointNumber > checkpointNumber) {
+                await this.#proposedCheckpoint.delete();
+            }
             return {
                 blocksRemoved
             };
@@ -306,17 +380,30 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         }
         return checkpoints;
     }
+    /** Returns checkpoint data for all checkpoints whose slot falls within the given range (inclusive). */ async getCheckpointDataForSlotRange(startSlot, endSlot) {
+        const result = [];
+        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;
+    }
     checkpointDataFromCheckpointStorage(checkpointStorage) {
-        const data = {
+        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) {
         const checkpoint = await this.#checkpoints.getAsync(checkpointNumber);
@@ -325,7 +412,7 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         }
         const blocksForCheckpoint = await toArray(this.#blocks.entriesAsync({
             start: checkpoint.startBlock,
-            end: checkpoint.startBlock + checkpoint.numBlocks
+            end: checkpoint.startBlock + checkpoint.blockCount
         }));
         const converted = await Promise.all(blocksForCheckpoint.map((x)=>this.getBlockFromBlockStorage(x[0], x[1])));
         return converted.filter(isDefined);
@@ -362,7 +449,7 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         return await this.db.transactionAsync(async ()=>{
             const removedBlocks = [];
             // Get the latest block number to determine the range
-            const latestBlockNumber = await this.getLatestBlockNumber();
+            const latestBlockNumber = await this.getLatestL2BlockNumber();
             // Iterate from blockNumber + 1 to latestBlockNumber
             for(let bn = blockNumber + 1; bn <= latestBlockNumber; bn++){
                 const block = await this.getBlock(BlockNumber(bn));
@@ -386,16 +473,9 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         if (!checkpointStorage) {
             throw new CheckpointNotFoundError(provenCheckpointNumber);
         } else {
-            return BlockNumber(checkpointStorage.startBlock + checkpointStorage.numBlocks - 1);
+            return BlockNumber(checkpointStorage.startBlock + checkpointStorage.blockCount - 1);
         }
     }
-    async getLatestBlockNumber() {
-        const [latestBlocknumber] = await toArray(this.#blocks.keysAsync({
-            reverse: true,
-            limit: 1
-        }));
-        return typeof latestBlocknumber === 'number' ? BlockNumber(latestBlocknumber) : BlockNumber(INITIAL_L2_BLOCK_NUM - 1);
-    }
     async getLatestCheckpointNumber() {
         const [latestCheckpointNumber] = await toArray(this.#checkpoints.keysAsync({
             reverse: true,
@@ -406,6 +486,108 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         }
         return CheckpointNumber(latestCheckpointNumber);
     }
+    async hasProposedCheckpoint() {
+        const proposed = await this.#proposedCheckpoint.getAsync();
+        return proposed !== undefined;
+    }
+    /** Deletes the proposed checkpoint from storage. */ async deleteProposedCheckpoint() {
+        await this.#proposedCheckpoint.delete();
+    }
+    /**
+   * Promotes the proposed checkpoint singleton to a confirmed checkpoint entry.
+   * This persists the checkpoint to the store, clears the proposed singleton, and updates the L1 sync point.
+   * Should only be called after the checkpoint has been validated.
+   * @param expectedArchiveRoot - The archive root to match against the proposed checkpoint, to guard against races.
+   */ async promoteProposedToCheckpointed(l1, attestations, expectedArchiveRoot) {
+        return await this.db.transactionAsync(async ()=>{
+            const proposed = await this.getProposedCheckpointOnly();
+            if (!proposed) {
+                throw new NoProposedCheckpointToPromoteError();
+            }
+            if (!proposed.archive.root.equals(expectedArchiveRoot)) {
+                throw new ProposedCheckpointArchiveRootMismatchError(expectedArchiveRoot, proposed.archive.root);
+            }
+            // Verify sequentiality: promoted checkpoint must follow the latest confirmed one
+            const latestCheckpointNumber = await this.getLatestCheckpointNumber();
+            if (latestCheckpointNumber !== proposed.checkpointNumber - 1) {
+                throw new ProposedCheckpointPromotionNotSequentialError(proposed.checkpointNumber, latestCheckpointNumber);
+            }
+            // Write the checkpoint entry
+            await this.#checkpoints.set(proposed.checkpointNumber, {
+                header: proposed.header.toBuffer(),
+                archive: proposed.archive.toBuffer(),
+                checkpointOutHash: proposed.checkpointOutHash.toBuffer(),
+                l1: l1.toBuffer(),
+                attestations: attestations.map((attestation)=>attestation.toBuffer()),
+                checkpointNumber: proposed.checkpointNumber,
+                startBlock: proposed.startBlock,
+                blockCount: proposed.blockCount
+            });
+            // Update the slot-to-checkpoint index
+            await this.#slotToCheckpoint.set(proposed.header.slotNumber, proposed.checkpointNumber);
+            // Clear the proposed checkpoint singleton
+            await this.#proposedCheckpoint.delete();
+            // Update the last synced L1 block
+            await this.#lastSynchedL1Block.set(l1.blockNumber);
+        });
+    }
+    /** Clears the proposed checkpoint if the given confirmed checkpoint number supersedes it. */ async clearProposedCheckpointIfSuperseded(confirmedCheckpointNumber) {
+        const proposedCheckpointNumber = await this.getProposedCheckpointNumber();
+        if (proposedCheckpointNumber <= confirmedCheckpointNumber) {
+            await this.#proposedCheckpoint.delete();
+        }
+    }
+    /** Returns the proposed checkpoint data, or undefined if no proposed checkpoint exists. No fallback to confirmed. */ async getProposedCheckpointOnly() {
+        const stored = await this.#proposedCheckpoint.getAsync();
+        if (!stored) {
+            return undefined;
+        }
+        return this.convertToProposedCheckpointData(stored);
+    }
+    /**
+   * Gets the checkpoint at the proposed tip
+   * - pending checkpoint if it exists
+   * - fallsback to latest confirmed checkpoint otherwise
+   * @returns CommonCheckpointData
+   */ async getProposedCheckpoint() {
+        const stored = await this.#proposedCheckpoint.getAsync();
+        if (!stored) {
+            return this.getCheckpointData(await this.getLatestCheckpointNumber());
+        }
+        return this.convertToProposedCheckpointData(stored);
+    }
+    convertToProposedCheckpointData(stored) {
+        return {
+            checkpointNumber: CheckpointNumber(stored.checkpointNumber),
+            header: CheckpointHeader.fromBuffer(stored.header),
+            archive: AppendOnlyTreeSnapshot.fromBuffer(stored.archive),
+            checkpointOutHash: Fr.fromBuffer(stored.checkpointOutHash),
+            startBlock: BlockNumber(stored.startBlock),
+            blockCount: stored.blockCount,
+            totalManaUsed: BigInt(stored.totalManaUsed),
+            feeAssetPriceModifier: BigInt(stored.feeAssetPriceModifier)
+        };
+    }
+    /**
+   * Attempts to get the proposedCheckpoint's number, if there is not one, then fallback to the latest confirmed checkpoint number.
+   * @returns CheckpointNumber
+   */ async getProposedCheckpointNumber() {
+        const proposed = await this.getProposedCheckpoint();
+        if (!proposed) {
+            return await this.getLatestCheckpointNumber();
+        }
+        return CheckpointNumber(proposed.checkpointNumber);
+    }
+    /**
+   * Attempts to get the proposedCheckpoint's block number, if there is not one, then fallback to the checkpointed block number
+   * @returns BlockNumber
+   */ async getProposedCheckpointL2BlockNumber() {
+        const proposed = await this.getProposedCheckpoint();
+        if (!proposed) {
+            return await this.getCheckpointedL2BlockNumber();
+        }
+        return BlockNumber(proposed.startBlock + proposed.blockCount - 1);
+    }
     async getCheckpointedBlock(number) {
         const blockStorage = await this.#blocks.getAsync(number);
         if (!blockStorage) {
@@ -468,6 +650,28 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         }
     }
     /**
+   * 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) {
+        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) {
+        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.
    * @returns The requested L2 block.
@@ -557,12 +761,19 @@ export { TxReceipt } from '@aztec/stdlib/tx';
             ];
         }
     }
+    getBlockDataFromBlockStorage(blockStorage) {
+        return {
+            header: BlockHeader.fromBuffer(blockStorage.header),
+            archive: AppendOnlyTreeSnapshot.fromBuffer(blockStorage.archive),
+            blockHash: BlockHash.fromBuffer(blockStorage.blockHash),
+            checkpointNumber: CheckpointNumber(blockStorage.checkpointNumber),
+            indexWithinCheckpoint: IndexWithinCheckpoint(blockStorage.indexWithinCheckpoint)
+        };
+    }
     async getBlockFromBlockStorage(blockNumber, blockStorage) {
-        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}`);
@@ -580,7 +791,7 @@ export { TxReceipt } from '@aztec/stdlib/tx';
             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(`Block number mismatch when retrieving block from archive (expected ${blockNumber} but got ${block.number} with hash ${blockHashString})`);
         }
@@ -601,17 +812,18 @@ export { TxReceipt } from '@aztec/stdlib/tx';
    * Gets a receipt of a settled tx.
    * @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) {
+   */ async getSettledTxReceipt(txHash, l1Constants) {
         const txEffect = await this.getTxEffect(txHash);
         if (!txEffect) {
             return undefined;
         }
         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.getFinalizedL2BlockNumber(),
+            this.getBlockData(blockNumber)
         ]);
         let status;
         if (blockNumber <= finalizedBlockNumber) {
@@ -623,7 +835,8 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         } else {
             status = TxStatus.PROPOSED;
         }
-        return new TxReceipt(txHash, status, TxReceipt.executionResultFromRevertCode(txEffect.data.revertCode), undefined, txEffect.data.transactionFee.toBigInt(), txEffect.l2BlockHash, blockNumber);
+        const epochNumber = blockData && l1Constants ? getEpochAtSlot(blockData.header.globalVariables.slotNumber, l1Constants) : undefined;
+        return new TxReceipt(txHash, status, TxReceipt.executionResultFromRevertCode(txEffect.data.revertCode), undefined, txEffect.data.transactionFee.toBigInt(), txEffect.l2BlockHash, blockNumber, epochNumber);
     }
     /**
    * Looks up which block included the requested tx effect.
@@ -656,7 +869,7 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         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() {
         const [lastBlockNumber] = await toArray(this.#blocks.keysAsync({
@@ -674,6 +887,42 @@ export { TxReceipt } from '@aztec/stdlib/tx';
     setSynchedL1BlockNumber(l1BlockNumber) {
         return this.#lastSynchedL1Block.set(l1BlockNumber);
     }
+    /** Sets the proposed checkpoint (not yet L1-confirmed). Only accepts confirmed + 1.
+   *  Computes archive and checkpointOutHash from the stored blocks. */ async setProposedCheckpoint(proposed) {
+        return await this.db.transactionAsync(async ()=>{
+            const current = await this.getProposedCheckpointNumber();
+            if (proposed.checkpointNumber <= current) {
+                throw new ProposedCheckpointStaleError(proposed.checkpointNumber, current);
+            }
+            const confirmed = await this.getLatestCheckpointNumber();
+            if (proposed.checkpointNumber !== confirmed + 1) {
+                throw new ProposedCheckpointNotSequentialError(proposed.checkpointNumber, confirmed);
+            }
+            // Ensure the previous checkpoint + blocks exist
+            const previousBlock = await this.getPreviousCheckpointBlock(proposed.checkpointNumber);
+            const blocks = [];
+            for(let i = 0; i < proposed.blockCount; i++){
+                const block = await this.getBlock(BlockNumber(proposed.startBlock + i));
+                if (!block) {
+                    throw new BlockNotFoundError(proposed.startBlock + i);
+                }
+                blocks.push(block);
+            }
+            this.validateCheckpointBlocks(blocks, previousBlock);
+            const archive = blocks[blocks.length - 1].archive;
+            const checkpointOutHash = Checkpoint.getCheckpointOutHash(blocks);
+            await this.#proposedCheckpoint.set({
+                header: proposed.header.toBuffer(),
+                archive: archive.toBuffer(),
+                checkpointOutHash: checkpointOutHash.toBuffer(),
+                checkpointNumber: proposed.checkpointNumber,
+                startBlock: proposed.startBlock,
+                blockCount: proposed.blockCount,
+                totalManaUsed: proposed.totalManaUsed.toString(),
+                feeAssetPriceModifier: proposed.feeAssetPriceModifier.toString()
+            });
+        });
+    }
     async getProvenCheckpointNumber() {
         const [latestCheckpointNumber, provenCheckpointNumber] = await Promise.all([
             this.getLatestCheckpointNumber(),
@@ -685,6 +934,16 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         const result = await this.#lastProvenCheckpoint.set(checkpointNumber);
         return result;
     }
+    async getFinalizedCheckpointNumber() {
+        const [latestCheckpointNumber, finalizedCheckpointNumber] = await Promise.all([
+            this.getLatestCheckpointNumber(),
+            this.#lastFinalizedCheckpoint.getAsync()
+        ]);
+        return (finalizedCheckpointNumber ?? 0) > latestCheckpointNumber ? latestCheckpointNumber : CheckpointNumber(finalizedCheckpointNumber ?? 0);
+    }
+    setFinalizedCheckpointNumber(checkpointNumber) {
+        return this.#lastFinalizedCheckpoint.set(checkpointNumber);
+    }
     #computeBlockRange(start, limit) {
         if (limit < 1) {
             throw new Error(`Invalid limit: ${limit}`);