@aztec/archiver 0.0.1-commit.42ee6df9b → 0.0.1-commit.431c48d

package/dest/store/block_store.js

@@ -1,25 +1,24 @@
 import { INITIAL_CHECKPOINT_NUMBER, INITIAL_L2_BLOCK_NUM } from '@aztec/constants';
-import { BlockNumber, CheckpointNumber, IndexWithinCheckpoint } from '@aztec/foundation/branded-types';
+import { BlockNumber, CheckpointNumber, IndexWithinCheckpoint, SlotNumber } from '@aztec/foundation/branded-types';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { toArray } from '@aztec/foundation/iterable';
 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 { BlockHash, Body, CommitteeAttestation, GENESIS_CHECKPOINT_HEADER_HASH, 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 { BlockAlreadyCheckpointedError, BlockArchiveNotConsistentError, BlockIndexNotSequentialError, BlockNotFoundError, BlockNumberNotSequentialError, CannotOverwriteCheckpointedBlockError, CheckpointNotFoundError, CheckpointNumberNotSequentialError, InitialCheckpointNumberNotSequentialError, ProposedCheckpointNotSequentialError, ProposedCheckpointStaleError } from '../errors.js';
-export { TxReceipt } from '@aztec/stdlib/tx';
+import { BlockHeader, TxHash, deserializeIndexedTxEffect, serializeIndexedTxEffect } from '@aztec/stdlib/tx';
+import { BlockAlreadyCheckpointedError, BlockArchiveNotConsistentError, BlockCheckpointNumberNotSequentialError, BlockIndexNotSequentialError, BlockNotFoundError, BlockNumberNotSequentialError, CannotOverwriteCheckpointedBlockError, CheckpointNotFoundError, CheckpointNumberNotSequentialError, InitialCheckpointNumberNotSequentialError, NoProposedCheckpointToPromoteError, ProposedCheckpointArchiveRootMismatchError, ProposedCheckpointNotSequentialError, ProposedCheckpointPromotionNotSequentialError } from '../errors.js';
 /**
  * LMDB-based block storage for the archiver.
  */ export class BlockStore {
     db;
     /** Map block number to block data */ #blocks;
-    /** Map checkpoint number to checkpoint data */ #checkpoints;
+    /** Map keyed by checkpoint number holding proposed (locally-validated, not yet L1-confirmed) checkpoints. */ #proposedCheckpoints;
+    /** Map checkpoint number to checkpoint data for mined checkpoints only */ #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;
@@ -30,7 +29,8 @@ export { TxReceipt } from '@aztec/stdlib/tx';
     /** 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;
+    /** Map rejected checkpoints (due to invalid attestations) by archive root */ #rejectedCheckpoints;
+    /** Index mapping a rejected checkpoint's number to its archive root, so the latest can be read in reverse order */ #rejectedCheckpointsByNumber;
     #log;
     constructor(db){
         this.db = db;
@@ -47,7 +47,9 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         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');
+        this.#proposedCheckpoints = db.openMap('archiver_proposed_checkpoints');
+        this.#rejectedCheckpoints = db.openMap('archiver_rejected_checkpoints');
+        this.#rejectedCheckpointsByNumber = db.openMap('archiver_rejected_checkpoints_by_number');
     }
     /**
    * Returns the finalized L2 block number. An L2 block is finalized when it was proven
@@ -78,13 +80,14 @@ export { TxReceipt } from '@aztec/stdlib/tx';
             const blockLastArchive = block.header.lastArchive.root;
             // Extract the latest block and checkpoint numbers
             const previousBlockNumber = await this.getLatestL2BlockNumber();
-            const proposedCheckpointNumber = await this.getProposedCheckpointNumber();
-            const previousCheckpointNumber = await this.getLatestCheckpointNumber();
+            const latestCheckpointNumber = await this.getLatestCheckpointNumber();
             // Verify we're not overwriting checkpointed blocks
             const lastCheckpointedBlockNumber = await this.getCheckpointedL2BlockNumber();
             if (!opts.force && blockNumber <= lastCheckpointedBlockNumber) {
                 // Check if the proposed block matches the already-checkpointed one
-                const existingBlock = await this.getBlock(BlockNumber(blockNumber));
+                const existingBlock = await this.getBlockData({
+                    number: BlockNumber(blockNumber)
+                });
                 if (existingBlock && existingBlock.archive.root.equals(block.archive.root)) {
                     throw new BlockAlreadyCheckpointedError(blockNumber);
                 }
@@ -94,21 +97,22 @@ export { TxReceipt } from '@aztec/stdlib/tx';
             if (!opts.force && previousBlockNumber !== blockNumber - 1) {
                 throw new BlockNumberNotSequentialError(blockNumber, previousBlockNumber);
             }
-            // 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.
+            // Accept the block if either the confirmed checkpoint or a pending checkpoint matches
+            // the expected predecessor. We look for a pending entry at exactly blockCheckpointNumber - 1.
             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);
+            const hasPendingAtExpected = await this.#proposedCheckpoints.hasAsync(expectedCheckpointNumber);
+            if (!opts.force && latestCheckpointNumber !== expectedCheckpointNumber && !hasPendingAtExpected) {
+                const [latestPendingKey] = await toArray(this.#proposedCheckpoints.keysAsync({
+                    reverse: true,
+                    limit: 1
+                }));
+                const previous = CheckpointNumber(Math.max(latestCheckpointNumber, latestPendingKey ?? 0));
+                throw new BlockCheckpointNumberNotSequentialError(BlockNumber(blockNumber), blockCheckpointNumber, previous);
             }
             // 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);
+            const previousBlockResult = await this.getBlockData({
+                number: previousBlockNumber
+            });
             let expectedBlockIndex = 0;
             let previousBlockIndex = undefined;
             if (previousBlockResult !== undefined) {
@@ -118,7 +122,7 @@ export { TxReceipt } from '@aztec/stdlib/tx';
                     expectedBlockIndex = previousBlockIndex + 1;
                 }
                 if (!previousBlockResult.archive.root.equals(blockLastArchive)) {
-                    throw new BlockArchiveNotConsistentError(blockNumber, previousBlockResult.number, blockLastArchive, previousBlockResult.archive.root);
+                    throw new BlockArchiveNotConsistentError(blockNumber, previousBlockResult.header.globalVariables.blockNumber, blockLastArchive, previousBlockResult.archive.root);
                 }
             }
             // Now check that the block has the expected index value
@@ -131,21 +135,36 @@ export { TxReceipt } from '@aztec/stdlib/tx';
     }
     /**
    * Append new checkpoints to the store's list.
+   * Checkpoints at the start of the batch that are already stored (e.g. re-included by an L1 reorg)
+   * are accepted if their archive root matches: their L1 metadata is updated but they are not
+   * re-inserted, and they are excluded from the returned array.
    * @param checkpoints - The L2 checkpoints to be added to the store.
-   * @returns True if the operation is successful.
+   * @returns The checkpoints that were actually inserted (excluding already-stored ones).
    */ async addCheckpoints(checkpoints, opts = {}) {
         if (checkpoints.length === 0) {
-            return true;
+            return [];
         }
         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 [];
+                }
+                // 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(firstCheckpointNumber);
+            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,19 +188,55 @@ export { TxReceipt } from '@aztec/stdlib/tx';
                     attestations: checkpoint.attestations.map((attestation)=>attestation.toBuffer()),
                     checkpointNumber: checkpoint.checkpoint.number,
                     startBlock: checkpoint.checkpoint.blocks[0].number,
-                    blockCount: checkpoint.checkpoint.blocks.length
+                    blockCount: checkpoint.checkpoint.blocks.length,
+                    feeAssetPriceModifier: checkpoint.checkpoint.feeAssetPriceModifier.toString()
                 });
                 // Update slot-to-checkpoint index
                 await this.#slotToCheckpoint.set(checkpoint.checkpoint.header.slotNumber, checkpoint.checkpoint.number);
+                // Remove proposed checkpoint if it exists, since L1 is authoritative
+                await this.#proposedCheckpoints.delete(checkpoint.checkpoint.number);
+                // Drop any rejected entry for this archive root: a checkpoint that was previously rejected
+                // (e.g. invalid attestations) is now being ingested as valid, so its descendants are allowed.
+                await this.removeRejectedCheckpointByArchiveRoot(checkpoint.checkpoint.archive.root);
             }
-            // 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;
+            await this.advanceSynchedL1BlockNumber(checkpoints[checkpoints.length - 1].l1.blockNumber);
+            return checkpoints;
         });
     }
     /**
+   * 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,
+                feeAssetPriceModifier: incoming.checkpoint.feeAssetPriceModifier.toString()
+            });
+            // Update the sync point to reflect the new L1 block
+            await this.advanceSynchedL1BlockNumber(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) {
@@ -189,12 +244,15 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         if (previousCheckpointNumber === INITIAL_CHECKPOINT_NUMBER - 1) {
             return undefined;
         }
-        const previousCheckpointData = await this.getCheckpointData(previousCheckpointNumber);
-        if (previousCheckpointData === undefined) {
+        // Check across both proposed and mined checkpoints
+        const predecessor = await this.getProposedCheckpointByNumber(previousCheckpointNumber) ?? await this.getCheckpointData(previousCheckpointNumber);
+        if (!predecessor) {
             throw new CheckpointNotFoundError(previousCheckpointNumber);
         }
-        const previousBlockNumber = BlockNumber(previousCheckpointData.startBlock + previousCheckpointData.blockCount - 1);
-        const previousBlock = await this.getBlock(previousBlockNumber);
+        const previousBlockNumber = BlockNumber(predecessor.startBlock + predecessor.blockCount - 1);
+        const previousBlock = await this.getBlock({
+            number: previousBlockNumber
+        });
         if (previousBlock === undefined) {
             throw new BlockNotFoundError(previousBlockNumber);
         }
@@ -203,7 +261,7 @@ export { TxReceipt } from '@aztec/stdlib/tx';
     /**
    * 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).
+   * proposed checkpoints (addProposedCheckpoint).
    */ validateCheckpointBlocks(blocks, previousBlock) {
         for (const block of blocks){
             if (previousBlock) {
@@ -245,7 +303,8 @@ export { TxReceipt } from '@aztec/stdlib/tx';
                 data: block.body.txEffects[i],
                 l2BlockNumber: block.number,
                 l2BlockHash: blockHash,
-                txIndexInBlock: i
+                txIndexInBlock: i,
+                slotNumber: block.header.globalVariables.slotNumber
             };
             await this.#txEffects.set(txEffect.data.txHash.toString(), serializeIndexedTxEffect(txEffect));
         }
@@ -254,17 +313,51 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         await this.#blockHashIndex.set(blockHash.toString(), block.number);
         await this.#blockArchiveIndex.set(block.archive.root.toString(), block.number);
     }
-    /** Deletes a block and all associated data (tx effects, indices). */ async deleteBlock(block) {
+    /** Deletes a block and all associated data (tx effects, indices). */ async deleteBlock(blockNumber, blockStorage) {
         // Delete the block from the main blocks map
-        await this.#blocks.delete(block.number);
-        // Delete all tx effects for this block
-        await Promise.all(block.body.txEffects.map((tx)=>this.#txEffects.delete(tx.txHash.toString())));
+        await this.#blocks.delete(blockNumber);
+        const blockHash = bufferToHex(blockStorage.blockHash);
+        // Delete the tx effects of the block's txs, skipping entries that no longer point at this block: if
+        // another stored block also contains the tx, the entry points at that block, and deleting it here would
+        // orphan that block's index. Honest chains never store the same tx twice (duplicate nullifiers are
+        // rejected at build, re-execution, and world-state sync), so the store must not turn such a state into
+        // corruption of the surviving block if it ever appears.
+        const blockTxsBuffer = await this.#blockTxs.getAsync(blockHash);
+        if (blockTxsBuffer !== undefined) {
+            const reader = BufferReader.asReader(blockTxsBuffer);
+            const txHashes = [];
+            while(!reader.isEmpty()){
+                txHashes.push(reader.readObject(TxHash).toString());
+            }
+            await Promise.all(txHashes.map((txHash)=>this.deleteTxEffect(txHash, blockStorage.blockHash)));
+        }
         // Delete block txs mapping
-        const blockHash = (await block.hash()).toString();
         await this.#blockTxs.delete(blockHash);
         // Clean up indices
         await this.#blockHashIndex.delete(blockHash);
-        await this.#blockArchiveIndex.delete(block.archive.root.toString());
+        await this.#blockArchiveIndex.delete(AppendOnlyTreeSnapshot.fromBuffer(blockStorage.archive).root.toString());
+    }
+    /** Deletes a tx effect only if it is still owned by (points at) the given block. */ async deleteTxEffect(txHash, blockHash) {
+        const stored = await this.#txEffects.getAsync(txHash);
+        if (stored === undefined) {
+            this.#log.warn(`Missing tx effect for tx ${txHash} while removing its block`, {
+                txHash,
+                blockHash: bufferToHex(blockHash)
+            });
+            return;
+        }
+        // An IndexedTxEffect starts with the owning block hash (32 bytes) — see getTxLocation.
+        if (!Buffer.from(stored.buffer, stored.byteOffset, 32).equals(blockHash)) {
+            // Fires only when two stored blocks listed the same tx — a state upstream validation should make
+            // unreachable. Keep the entry (it belongs to the surviving block) but flag the duplication loudly.
+            this.#log.warn(`Tx effect for tx ${txHash} is owned by a block other than the one being removed`, {
+                txHash,
+                removedBlockHash: bufferToHex(blockHash),
+                owningBlockHash: bufferToHex(Buffer.from(stored.buffer, stored.byteOffset, 32))
+            });
+            return;
+        }
+        await this.#txEffects.delete(txHash);
     }
     /**
    * Removes all checkpoints with checkpoint number > checkpointNumber.
@@ -308,11 +401,8 @@ export { TxReceipt } from '@aztec/stdlib/tx';
                 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();
-            }
+            // Evict all pending checkpoints > checkpointNumber (their base chain no longer exists)
+            await this.evictProposedCheckpointsFrom(CheckpointNumber(checkpointNumber + 1));
             return {
                 blocksRemoved
             };
@@ -336,6 +426,31 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         }
         return checkpoints;
     }
+    /**
+   * Returns up to `limit` checkpoints anchored at `fromSlot`, ordered nearest-first, walking the slot index.
+   * With `reverse`, takes the checkpoints at or before `fromSlot` (descending by slot); otherwise the
+   * checkpoints at or after it (ascending). `limit: 1, reverse: true` yields the latest checkpoint at or
+   * before the slot in a single range scan.
+   */ async getCheckpointsBySlot(fromSlot, limit, reverse) {
+        // The KV range bounds are direction-dependent: forward is [start, end), reverse is (start, end], so a
+        // reverse scan uses `end: fromSlot` (inclusive) with no +1 to include the checkpoint at fromSlot itself.
+        const range = reverse ? {
+            end: fromSlot,
+            reverse: true,
+            limit
+        } : {
+            start: fromSlot,
+            limit
+        };
+        const result = [];
+        for await (const [, checkpointNumber] of this.#slotToCheckpoint.entriesAsync(range)){
+            const checkpointStorage = await this.#checkpoints.getAsync(checkpointNumber);
+            if (checkpointStorage) {
+                result.push(this.checkpointDataFromCheckpointStorage(checkpointStorage));
+            }
+        }
+        return result;
+    }
     /** 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({
@@ -349,6 +464,20 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         }
         return result;
     }
+    /**
+   * Returns the checkpoint numbers for all checkpoints whose slot falls within the given range (inclusive).
+   * Lighter than {@link getCheckpointDataForSlotRange} when callers only need to identify which
+   * checkpoints fall in the range and will fetch full data for at most a few of them.
+   */ async getCheckpointNumbersForSlotRange(startSlot, endSlot) {
+        const result = [];
+        for await (const [, checkpointNumber] of this.#slotToCheckpoint.entriesAsync({
+            start: startSlot,
+            end: endSlot + 1
+        })){
+            result.push(CheckpointNumber(checkpointNumber));
+        }
+        return result;
+    }
     checkpointDataFromCheckpointStorage(checkpointStorage) {
         return {
             header: CheckpointHeader.fromBuffer(checkpointStorage.header),
@@ -357,6 +486,7 @@ export { TxReceipt } from '@aztec/stdlib/tx';
             checkpointNumber: CheckpointNumber(checkpointStorage.checkpointNumber),
             startBlock: BlockNumber(checkpointStorage.startBlock),
             blockCount: checkpointStorage.blockCount,
+            feeAssetPriceModifier: BigInt(checkpointStorage.feeAssetPriceModifier),
             l1: L1PublishedData.fromBuffer(checkpointStorage.l1),
             attestations: checkpointStorage.attestations.map((buf)=>CommitteeAttestation.fromBuffer(buf))
         };
@@ -408,14 +538,22 @@ export { TxReceipt } from '@aztec/stdlib/tx';
             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));
-                if (block === undefined) {
+                const blockStorage = await this.#blocks.getAsync(bn);
+                if (blockStorage === undefined) {
                     this.#log.warn(`Cannot remove block ${bn} from the store since we don't have it`);
                     continue;
                 }
-                removedBlocks.push(block);
-                await this.deleteBlock(block);
-                this.#log.debug(`Removed block ${bn} ${(await block.hash()).toString()}`);
+                // Load the full block for the returned list when possible, but clean up from the raw row regardless:
+                // a block whose body can no longer be fully loaded must still release its row, tx effects, and indices,
+                // or later inserts at this number leave stale tx-effect entries pointing into the new chain.
+                const block = await this.getBlockFromBlockStorage(bn, blockStorage);
+                if (block !== undefined) {
+                    removedBlocks.push(block);
+                } else {
+                    this.#log.warn(`Removing block ${bn} whose body could not be fully loaded`);
+                }
+                await this.deleteBlock(bn, blockStorage);
+                this.#log.debug(`Removed block ${bn} ${bufferToHex(blockStorage.blockHash)}`);
             }
             return removedBlocks;
         });
@@ -443,36 +581,117 @@ 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();
+        const [key] = await toArray(this.#proposedCheckpoints.keysAsync({
+            limit: 1
+        }));
+        return key !== undefined;
     }
-    /** 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();
+    /** Deletes all pending proposed checkpoints from storage. */ async deleteProposedCheckpoints() {
+        for await (const key of this.#proposedCheckpoints.keysAsync()){
+            await this.#proposedCheckpoints.delete(key);
         }
     }
-    /** 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) {
+    /**
+   * Promotes a specific pending checkpoint to a confirmed checkpoint entry.
+   * This persists the checkpoint to the store, removes only that pending entry, and updates the L1 sync point.
+   * Remaining pending entries (e.g. N+1, N+2) are left intact — they chain off the just-promoted one.
+   * @param checkpointNumber - The checkpoint number to promote.
+   * @param l1 - L1 published data for the checkpoint.
+   * @param attestations - Committee attestations.
+   * @param expectedArchiveRoot - Archive root guard against races.
+   */ async promoteProposedToCheckpointed(checkpointNumber, l1, attestations, expectedArchiveRoot) {
+        return await this.db.transactionAsync(async ()=>{
+            const proposed = await this.getProposedCheckpointByNumber(checkpointNumber);
+            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,
+                feeAssetPriceModifier: proposed.feeAssetPriceModifier.toString()
+            });
+            // Update the slot-to-checkpoint index
+            await this.#slotToCheckpoint.set(proposed.header.slotNumber, proposed.checkpointNumber);
+            // Remove only this pending entry — remaining entries N+1, N+2, ... stay valid
+            await this.#proposedCheckpoints.delete(proposed.checkpointNumber);
+            // Drop any rejected entry for this archive root: a checkpoint that was previously rejected
+            // (e.g. invalid attestations) is now being promoted as valid, so its descendants are allowed.
+            await this.removeRejectedCheckpointByArchiveRoot(proposed.archive.root);
+            // Update the last synced L1 block
+            await this.advanceSynchedL1BlockNumber(l1.blockNumber);
+        });
+    }
+    /**
+   * Returns the latest pending checkpoint (highest-numbered entry), or undefined if none.
+   * No fallback to confirmed.
+   */ async getLastProposedCheckpoint() {
+        const [key] = await toArray(this.#proposedCheckpoints.keysAsync({
+            reverse: true,
+            limit: 1
+        }));
+        if (key === undefined) {
             return undefined;
         }
-        return this.convertToProposedCheckpointData(stored);
+        const stored = await this.#proposedCheckpoints.getAsync(key);
+        return stored ? this.convertToProposedCheckpointData(stored) : undefined;
+    }
+    /** Returns the pending checkpoint for a specific checkpoint number, or undefined if not found. */ async getProposedCheckpointByNumber(n) {
+        const stored = await this.#proposedCheckpoints.getAsync(n);
+        return stored ? this.convertToProposedCheckpointData(stored) : undefined;
+    }
+    /**
+   * Returns the pending checkpoint whose header slot matches the given slot, or undefined if not found.
+   * Iterates `#proposedCheckpoints` rather than reading an index because the map carries 0–1 entries
+   * in normal operation (bounded by the proposer pipelining window). Returns the first match.
+   */ async getProposedCheckpointBySlot(slot) {
+        for await (const [, stored] of this.#proposedCheckpoints.entriesAsync()){
+            const header = CheckpointHeader.fromBuffer(stored.header);
+            if (header.slotNumber === slot) {
+                return this.convertToProposedCheckpointData(stored);
+            }
+        }
+        return undefined;
+    }
+    /**
+   * Evicts all pending checkpoints with checkpoint number >= fromNumber.
+   * Used for divergent-mined-checkpoint cleanup: when L1 mines checkpoint N with a different archive,
+   * all pending >= N must be evicted since they chain off the now-invalid pending N.
+   */ async evictProposedCheckpointsFrom(fromNumber) {
+        const keysToDelete = [];
+        for await (const key of this.#proposedCheckpoints.keysAsync()){
+            if (key >= fromNumber) {
+                keysToDelete.push(key);
+            }
+        }
+        for (const key of keysToDelete){
+            await this.#proposedCheckpoints.delete(key);
+        }
     }
     /**
-   * Gets the checkpoint at the proposed tip
-   * - pending checkpoint if it exists
+   * Gets the checkpoint at the proposed tip:
+   * - latest pending checkpoint if any exist
    * - fallsback to latest confirmed checkpoint otherwise
-   * @returns CommonCheckpointData
-   */ async getProposedCheckpoint() {
-        const stored = await this.#proposedCheckpoint.getAsync();
-        if (!stored) {
+   */ async getLastCheckpoint() {
+        const latest = await this.getLastProposedCheckpoint();
+        if (!latest) {
             return this.getCheckpointData(await this.getLatestCheckpointNumber());
         }
-        return this.convertToProposedCheckpointData(stored);
+        return latest;
     }
     convertToProposedCheckpointData(stored) {
         return {
@@ -490,7 +709,7 @@ export { TxReceipt } from '@aztec/stdlib/tx';
    * 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();
+        const proposed = await this.getLastCheckpoint();
         if (!proposed) {
             return await this.getLatestCheckpointNumber();
         }
@@ -500,134 +719,32 @@ export { TxReceipt } from '@aztec/stdlib/tx';
    * 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();
+        const proposed = await this.getLastCheckpoint();
         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) {
-            return undefined;
-        }
-        const checkpoint = await this.#checkpoints.getAsync(blockStorage.checkpointNumber);
-        if (!checkpoint) {
-            return undefined;
-        }
-        const block = await this.getBlockFromBlockStorage(number, blockStorage);
-        if (!block) {
-            return undefined;
-        }
-        return new CheckpointedL2Block(CheckpointNumber(checkpoint.checkpointNumber), block, L1PublishedData.fromBuffer(checkpoint.l1), checkpoint.attestations.map((buf)=>CommitteeAttestation.fromBuffer(buf)));
-    }
-    /**
-   * Gets up to `limit` amount of Checkpointed L2 blocks starting from `from`.
-   * @param start - Number of the first block to return (inclusive).
-   * @param limit - The number of blocks to return.
-   * @returns The requested L2 blocks
-   */ async *getCheckpointedBlocks(start, limit) {
-        const checkpointCache = new Map();
-        for await (const [blockNumber, blockStorage] of this.getBlockStorages(start, limit)){
-            const block = await this.getBlockFromBlockStorage(blockNumber, blockStorage);
-            if (block) {
-                const checkpoint = checkpointCache.get(CheckpointNumber(blockStorage.checkpointNumber)) ?? await this.#checkpoints.getAsync(blockStorage.checkpointNumber);
-                if (checkpoint) {
-                    checkpointCache.set(CheckpointNumber(blockStorage.checkpointNumber), checkpoint);
-                    const checkpointedBlock = new CheckpointedL2Block(CheckpointNumber(checkpoint.checkpointNumber), block, L1PublishedData.fromBuffer(checkpoint.l1), checkpoint.attestations.map((buf)=>CommitteeAttestation.fromBuffer(buf)));
-                    yield checkpointedBlock;
-                }
-            }
-        }
+    /** Returns the checkpoint number that contains the given slot (or undefined if not found). */ async getCheckpointNumberBySlot(slot) {
+        const checkpointNumber = await this.#slotToCheckpoint.getAsync(slot);
+        return checkpointNumber === undefined ? undefined : CheckpointNumber(checkpointNumber);
     }
-    async getCheckpointedBlockByHash(blockHash) {
-        const blockNumber = await this.#blockHashIndex.getAsync(blockHash.toString());
+    /** Gets a single L2 block matching the given resolved query. */ async getBlock(query) {
+        const blockNumber = await this.getBlockNumber(query);
         if (blockNumber === undefined) {
             return undefined;
         }
-        return this.getCheckpointedBlock(BlockNumber(blockNumber));
-    }
-    async getCheckpointedBlockByArchive(archive) {
-        const blockNumber = await this.#blockArchiveIndex.getAsync(archive.toString());
-        if (blockNumber === undefined) {
-            return undefined;
-        }
-        return this.getCheckpointedBlock(BlockNumber(blockNumber));
-    }
-    /**
-   * Gets up to `limit` amount of L2 blocks starting from `from`.
-   * @param start - Number of the first block to return (inclusive).
-   * @param limit - The number of blocks to return.
-   * @returns The requested L2 blocks
-   */ async *getBlocks(start, limit) {
-        for await (const [blockNumber, blockStorage] of this.getBlockStorages(start, limit)){
-            const block = await this.getBlockFromBlockStorage(blockNumber, blockStorage);
-            if (block) {
-                yield block;
-            }
-        }
-    }
-    /**
-   * 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) {
+        if (!blockStorage) {
             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.
-   */ async getBlock(blockNumber) {
-        const blockStorage = await this.#blocks.getAsync(blockNumber);
-        if (!blockStorage || !blockStorage.header) {
-            return Promise.resolve(undefined);
-        }
         return this.getBlockFromBlockStorage(blockNumber, blockStorage);
     }
-    /**
-   * Gets an L2 block by its hash.
-   * @param blockHash - The hash of the block to return.
-   * @returns The requested L2 block.
-   */ async getBlockByHash(blockHash) {
-        const blockNumber = await this.#blockHashIndex.getAsync(blockHash.toString());
-        if (blockNumber === undefined) {
-            return undefined;
-        }
-        return this.getBlock(BlockNumber(blockNumber));
-    }
-    /**
-   * Gets an L2 block by its archive root.
-   * @param archive - The archive root of the block to return.
-   * @returns The requested L2 block.
-   */ async getBlockByArchive(archive) {
-        const blockNumber = await this.#blockArchiveIndex.getAsync(archive.toString());
-        if (blockNumber === undefined) {
-            return undefined;
-        }
-        return this.getBlock(BlockNumber(blockNumber));
+    /** Gets a collection of L2 blocks for a resolved range. */ getBlocks(query) {
+        return toArray(this.iterateBlocks(query));
     }
-    /**
-   * Gets a block header by its hash.
-   * @param blockHash - The hash of the block to return.
-   * @returns The requested block header.
-   */ async getBlockHeaderByHash(blockHash) {
-        const blockNumber = await this.#blockHashIndex.getAsync(blockHash.toString());
+    /** Gets single block metadata matching the given resolved query. */ async getBlockData(query) {
+        const blockNumber = await this.getBlockNumber(query);
         if (blockNumber === undefined) {
             return undefined;
         }
@@ -635,35 +752,30 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         if (!blockStorage || !blockStorage.header) {
             return undefined;
         }
-        return BlockHeader.fromBuffer(blockStorage.header);
+        return this.getBlockDataFromBlockStorage(blockStorage);
     }
-    /**
-   * Gets a block header by its archive root.
-   * @param archive - The archive root of the block to return.
-   * @returns The requested block header.
-   */ async getBlockHeaderByArchive(archive) {
-        const blockNumber = await this.#blockArchiveIndex.getAsync(archive.toString());
-        if (blockNumber === undefined) {
-            return undefined;
-        }
-        const blockStorage = await this.#blocks.getAsync(blockNumber);
-        if (!blockStorage || !blockStorage.header) {
-            return undefined;
+    /** Gets a collection of block metadata entries for a resolved range. */ getBlocksData(query) {
+        return toArray(this.iterateBlocksData(query));
+    }
+    /** Async iterator over L2 blocks for a resolved range. */ async *iterateBlocks(query) {
+        const cap = query.onlyCheckpointed ? await this.getCheckpointedL2BlockNumber() : undefined;
+        for await (const [blockNumber, blockStorage] of this.getBlockStorages(query.from, query.limit)){
+            if (cap !== undefined && blockNumber > cap) {
+                break;
+            }
+            const block = await this.getBlockFromBlockStorage(blockNumber, blockStorage);
+            if (block) {
+                yield block;
+            }
         }
-        return BlockHeader.fromBuffer(blockStorage.header);
     }
-    /**
-   * Gets the headers for a sequence of L2 blocks.
-   * @param start - Number of the first block to return (inclusive).
-   * @param limit - The number of blocks to return.
-   * @returns The requested L2 block headers
-   */ async *getBlockHeaders(start, limit) {
-        for await (const [blockNumber, blockStorage] of this.getBlockStorages(start, limit)){
-            const header = BlockHeader.fromBuffer(blockStorage.header);
-            if (header.getBlockNumber() !== blockNumber) {
-                throw new Error(`Block number mismatch when retrieving block header from archive (expected ${blockNumber} but got ${header.getBlockNumber()})`);
+    /** Async iterator over block metadata for a resolved range. */ async *iterateBlocksData(query) {
+        const cap = query.onlyCheckpointed ? await this.getCheckpointedL2BlockNumber() : undefined;
+        for await (const [blockNumber, blockStorage] of this.getBlockStorages(query.from, query.limit)){
+            if (cap !== undefined && blockNumber > cap) {
+                break;
             }
-            yield header;
+            yield this.getBlockDataFromBlockStorage(blockStorage);
         }
     }
     async *getBlockStorages(start, limit) {
@@ -679,11 +791,27 @@ export { TxReceipt } from '@aztec/stdlib/tx';
             ];
         }
     }
+    /** Resolves a ResolvedBlockQuery discriminant to a block number, or undefined if not found. */ async getBlockNumber(query) {
+        let blockNumber;
+        if ('number' in query) {
+            blockNumber = query.number;
+        } else if ('hash' in query) {
+            const n = await this.#blockHashIndex.getAsync(query.hash.toString());
+            blockNumber = n !== undefined ? BlockNumber(n) : undefined;
+        } else {
+            const n = await this.#blockArchiveIndex.getAsync(query.archive.toString());
+            blockNumber = n !== undefined ? BlockNumber(n) : undefined;
+        }
+        if (blockNumber === undefined) {
+            return undefined;
+        }
+        return blockNumber;
+    }
     getBlockDataFromBlockStorage(blockStorage) {
         return {
             header: BlockHeader.fromBuffer(blockStorage.header),
             archive: AppendOnlyTreeSnapshot.fromBuffer(blockStorage.archive),
-            blockHash: Fr.fromBuffer(blockStorage.blockHash),
+            blockHash: BlockHash.fromBuffer(blockStorage.blockHash),
             checkpointNumber: CheckpointNumber(blockStorage.checkpointNumber),
             indexWithinCheckpoint: IndexWithinCheckpoint(blockStorage.indexWithinCheckpoint)
         };
@@ -727,36 +855,6 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         return deserializeIndexedTxEffect(buffer);
     }
     /**
-   * 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, 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, blockData] = await Promise.all([
-            this.getProvenBlockNumber(),
-            this.getCheckpointedL2BlockNumber(),
-            this.getFinalizedL2BlockNumber(),
-            this.getBlockData(blockNumber)
-        ]);
-        let status;
-        if (blockNumber <= finalizedBlockNumber) {
-            status = TxStatus.FINALIZED;
-        } else if (blockNumber <= provenBlockNumber) {
-            status = TxStatus.PROVEN;
-        } else if (blockNumber <= checkpointedBlockNumber) {
-            status = TxStatus.CHECKPOINTED;
-        } else {
-            status = TxStatus.PROPOSED;
-        }
-        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.
    * @param txHash - The txHash of the tx.
    * @returns The block number and index of the tx.
@@ -765,13 +863,50 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         if (!txEffect) {
             return undefined;
         }
-        const { l2BlockNumber, txIndexInBlock } = deserializeIndexedTxEffect(txEffect);
+        // Read only the IndexedTxEffect header (`blockHash(32) + l2BlockNumber(4) + txIndexInBlock(4)`); the
+        // large tail (the full TxEffect with logs etc.) is irrelevant here.
+        const view = Buffer.from(txEffect.buffer, txEffect.byteOffset, txEffect.byteLength);
+        const l2BlockNumber = view.readUInt32BE(32);
+        const txIndexInBlock = view.readUInt32BE(36);
         return [
             l2BlockNumber,
             txIndexInBlock
         ];
     }
     /**
+   * Batched, partial deserializer that fetches `noteHashes` and `nullifiers` (all of them) for the given
+   * txs. For each input txHash, returns a `[noteHashes, nullifiers]` tuple. Returns `[[], []]` for any
+   * unknown txHash. Preserves input order. Used by the log read path when `includeEffects` is set to
+   * attach effect data on demand without paying for a full {@link TxEffect} deserialization.
+   *
+   * The on-disk `IndexedTxEffect` layout starts with a fixed-length header
+   * (`blockHash(32) + l2BlockNumber(4) + txIndexInBlock(4) + slotNumber(4) + revertCode(1) + txHash(32) +
+   * transactionFee(32)` = 109 bytes), followed by `noteHashes` and `nullifiers` (both u8-length-prefixed `Fr`
+   * vectors). We
+   * skip the header, then read the two vectors, and stop — the large tail (`l2ToL1Msgs`,
+   * `publicDataWrites`, `privateLogs`, `publicLogs`, `contractClassLogs`) is never touched.
+   */ getNoteHashesAndNullifiers(txHashes) {
+        return Promise.all(txHashes.map(async (txHash)=>{
+            const buffer = await this.#txEffects.getAsync(txHash.toString());
+            if (!buffer) {
+                return [
+                    [],
+                    []
+                ];
+            }
+            const reader = BufferReader.asReader(buffer);
+            // Skip the fixed-length header: blockHash + l2BlockNumber + txIndexInBlock + slotNumber + revertCode +
+            // txHash + transactionFee.
+            reader.readBytes(32 + 4 + 4 + 4 + 1 + 32 + 32);
+            const noteHashes = reader.readVectorUint8Prefix(Fr);
+            const nullifiers = reader.readVectorUint8Prefix(Fr);
+            return [
+                noteHashes,
+                nullifiers
+            ];
+        }));
+    }
+    /**
    * Looks up which block deployed a particular contract.
    * @param contractAddress - The address of the contract to look up.
    * @returns The block number and index of the contract.
@@ -797,6 +932,142 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         return typeof lastBlockNumber === 'number' ? BlockNumber(lastBlockNumber) : BlockNumber(INITIAL_L2_BLOCK_NUM - 1);
     }
     /**
+   * Resolves all four L2 chain tips (proposed, checkpointed, proven, finalized) in a single
+   * read-only transaction so the snapshot is internally consistent. Each underlying record is
+   * read at most once: latest block and latest confirmed checkpoint are loaded directly (no
+   * separate "find the number, then look up data" hop), the proven/finalized checkpoint
+   * singletons are read once and their storage entries are reused if they coincide with the
+   * latest checkpoint, and per-tip block hashes are deduped when two tips land on the same block
+   * (e.g. finalized == proven).
+   *
+   * The result is guaranteed to satisfy `finalized <= proven <= checkpointed <= proposed` (by
+   * block number). Genesis is represented by `(INITIAL_L2_BLOCK_NUM - 1)` and the supplied
+   * `genesisBlockHash`, paired with the synthetic genesis checkpoint id.
+   *
+   * @param genesisBlockHash - Block hash to report for the synthetic pre-initial block (used when
+   *   a tip is still at genesis).
+   */ async getL2TipsData(genesisBlockHash) {
+        return await this.db.transactionAsync(async ()=>{
+            // Define genesis tips
+            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 = {
+                block: genesisBlockId,
+                checkpoint: genesisCheckpointId
+            };
+            // Load latest block and checkpoint entries
+            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;
+            // Load proven and finalized checkpoint number pointers
+            const [provenRaw, finalizedRaw] = await Promise.all([
+                this.#lastProvenCheckpoint.getAsync(),
+                this.#lastFinalizedCheckpoint.getAsync()
+            ]);
+            // Clamp to enforce finalized <= proven <= checkpointed.
+            const provenCheckpointNumber = CheckpointNumber(Math.min(provenRaw ?? 0, latestCheckpointNumber));
+            const finalizedCheckpointNumber = CheckpointNumber(Math.min(finalizedRaw ?? 0, provenCheckpointNumber));
+            // Avoid loading the same checkpoint more than once
+            const checkpointStorageCache = new Map();
+            if (latestCheckpointEntry) {
+                checkpointStorageCache.set(CheckpointNumber(latestCheckpointEntry[0]), latestCheckpointEntry[1]);
+            }
+            const loadCheckpointStorage = async (n)=>{
+                if (n === 0) {
+                    return undefined;
+                }
+                if (!checkpointStorageCache.has(n)) {
+                    const checkpointStorage = await this.#checkpoints.getAsync(n);
+                    if (!checkpointStorage) {
+                        throw new CheckpointNotFoundError(n);
+                    }
+                    checkpointStorageCache.set(n, checkpointStorage);
+                }
+                return checkpointStorageCache.get(n);
+            };
+            // Load proven and finalized checkpoint storage entries
+            const provenCheckpoint = await loadCheckpointStorage(provenCheckpointNumber);
+            const finalizedCheckpoint = await loadCheckpointStorage(finalizedCheckpointNumber);
+            // Avoid loading the same block hash multiple times when tips land on the same block
+            const blockHashCache = new Map();
+            blockHashCache.set(genesisBlockNumber, genesisBlockHash.toString());
+            if (latestBlockEntry) {
+                blockHashCache.set(latestBlockEntry[0], BlockHash.fromBuffer(latestBlockEntry[1].blockHash).toString());
+            }
+            const loadBlockHash = async (n)=>{
+                if (!blockHashCache.has(n)) {
+                    const blockStorage = await this.#blocks.getAsync(n);
+                    if (!blockStorage) {
+                        throw new BlockNotFoundError(n);
+                    }
+                    const blockHash = BlockHash.fromBuffer(blockStorage.blockHash).toString();
+                    blockHashCache.set(n, blockHash);
+                }
+                return blockHashCache.get(n);
+            };
+            // Build proposed chain tip (this one has block only, no checkpoint)
+            const proposedBlockId = latestBlockEntry === undefined ? genesisBlockId : {
+                number: BlockNumber(latestBlockEntry[0]),
+                hash: BlockHash.fromBuffer(latestBlockEntry[1].blockHash).toString()
+            };
+            // Build other tips from checkpoint data, reading corresponding block data from the cache
+            const buildTipFromCheckpoint = async (stored)=>{
+                if (!stored) {
+                    return genesisTip;
+                }
+                const blockNumber = BlockNumber(stored.startBlock + stored.blockCount - 1);
+                const blockHash = await loadBlockHash(blockNumber);
+                const header = CheckpointHeader.fromBuffer(stored.header);
+                return {
+                    block: {
+                        number: blockNumber,
+                        hash: blockHash
+                    },
+                    checkpoint: {
+                        number: CheckpointNumber(stored.checkpointNumber),
+                        hash: header.hash().toString()
+                    }
+                };
+            };
+            const checkpointedTip = await buildTipFromCheckpoint(latestCheckpointEntry?.[1]);
+            const provenTip = await buildTipFromCheckpoint(provenCheckpoint);
+            const finalizedTip = await buildTipFromCheckpoint(finalizedCheckpoint);
+            // A checkpointed block past the latest stored block would mean a checkpoint
+            // references blocks that aren't in blocks.
+            if (proposedBlockId.number < checkpointedTip.block.number) {
+                throw new Error(`Inconsistent block store: latest block ${proposedBlockId.number} is behind checkpointed block ${checkpointedTip.block.number}`);
+            }
+            // Assert that checkpoint numbers are increasing
+            if (finalizedTip.checkpoint.number > provenTip.checkpoint.number || provenTip.checkpoint.number > checkpointedTip.checkpoint.number) {
+                throw new Error(`Inconsistent checkpoint numbers in chain tips: finalized=${finalizedTip.checkpoint.number} proven=${provenTip.checkpoint.number} checkpointed=${checkpointedTip.checkpoint.number}`);
+            }
+            // Assert block numbers are increasing
+            if (finalizedTip.block.number > provenTip.block.number || provenTip.block.number > checkpointedTip.block.number || checkpointedTip.block.number > proposedBlockId.number) {
+                throw new Error(`Inconsistent block numbers in chain tips: finalized=${finalizedTip.block.number} proven=${provenTip.block.number} checkpointed=${checkpointedTip.block.number} proposed=${proposedBlockId.number}`);
+            }
+            return {
+                proposed: proposedBlockId,
+                checkpointed: checkpointedTip,
+                proven: provenTip,
+                finalized: finalizedTip
+            };
+        });
+    }
+    /**
    * Gets the most recent L1 block processed.
    * @returns The L1 block that published the latest L2 block
    */ getSynchedL1BlockNumber() {
@@ -805,22 +1076,29 @@ 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) {
+    /**
+   * Adds a proposed checkpoint to the pending queue.
+   * Accepts proposed.checkpointNumber === latestTip + 1, where latestTip is the highest of
+   * confirmed and the highest pending checkpoint number.
+   * Computes archive and checkpointOutHash from the stored blocks.
+   */ async addProposedCheckpoint(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);
+            const [latestPendingKey] = await toArray(this.#proposedCheckpoints.keysAsync({
+                reverse: true,
+                limit: 1
+            }));
+            const latestTip = CheckpointNumber(latestPendingKey !== undefined ? Math.max(latestPendingKey, confirmed) : confirmed);
+            if (proposed.checkpointNumber !== latestTip + 1) {
+                throw new ProposedCheckpointNotSequentialError(proposed.checkpointNumber, latestTip);
             }
-            // Ensure the previous checkpoint + blocks exist
+            // Ensure the predecessor block (from pending or confirmed chain) exists
             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));
+                const block = await this.getBlock({
+                    number: BlockNumber(proposed.startBlock + i)
+                });
                 if (!block) {
                     throw new BlockNotFoundError(proposed.startBlock + i);
                 }
@@ -829,7 +1107,7 @@ export { TxReceipt } from '@aztec/stdlib/tx';
             this.validateCheckpointBlocks(blocks, previousBlock);
             const archive = blocks[blocks.length - 1].archive;
             const checkpointOutHash = Checkpoint.getCheckpointOutHash(blocks);
-            await this.#proposedCheckpoint.set({
+            await this.#proposedCheckpoints.set(proposed.checkpointNumber, {
                 header: proposed.header.toBuffer(),
                 archive: archive.toBuffer(),
                 checkpointOutHash: checkpointOutHash.toBuffer(),
@@ -842,22 +1120,26 @@ export { TxReceipt } from '@aztec/stdlib/tx';
         });
     }
     async getProvenCheckpointNumber() {
-        const [latestCheckpointNumber, provenCheckpointNumber] = await Promise.all([
-            this.getLatestCheckpointNumber(),
-            this.#lastProvenCheckpoint.getAsync()
-        ]);
-        return (provenCheckpointNumber ?? 0) > latestCheckpointNumber ? latestCheckpointNumber : CheckpointNumber(provenCheckpointNumber ?? 0);
+        return await this.db.transactionAsync(async ()=>{
+            const [latestCheckpointNumber, provenCheckpointNumber] = await Promise.all([
+                this.getLatestCheckpointNumber(),
+                this.#lastProvenCheckpoint.getAsync()
+            ]);
+            return (provenCheckpointNumber ?? 0) > latestCheckpointNumber ? latestCheckpointNumber : CheckpointNumber(provenCheckpointNumber ?? 0);
+        });
     }
     async setProvenCheckpointNumber(checkpointNumber) {
         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);
+        return await this.db.transactionAsync(async ()=>{
+            const [provenCheckpointNumber, finalizedCheckpointNumber] = await Promise.all([
+                this.getProvenCheckpointNumber(),
+                this.#lastFinalizedCheckpoint.getAsync()
+            ]);
+            return (finalizedCheckpointNumber ?? 0) > provenCheckpointNumber ? provenCheckpointNumber : CheckpointNumber(finalizedCheckpointNumber ?? 0);
+        });
     }
     setFinalizedCheckpointNumber(checkpointNumber) {
         return this.#lastFinalizedCheckpoint.set(checkpointNumber);
@@ -895,4 +1177,70 @@ export { TxReceipt } from '@aztec/stdlib/tx';
             await this.#pendingChainValidationStatus.delete();
         }
     }
+    /** Records a rejected-checkpoint entry, keyed by its own archive root. */ async addRejectedCheckpoint(entry) {
+        const archiveRootHex = entry.archiveRoot.toString();
+        await this.#rejectedCheckpoints.set(archiveRootHex, {
+            checkpointNumber: entry.checkpointNumber,
+            archiveRoot: entry.archiveRoot.toBuffer(),
+            parentArchiveRoot: entry.parentArchiveRoot.toBuffer(),
+            slotNumber: entry.slotNumber,
+            l1: entry.l1.toBuffer(),
+            reason: entry.reason
+        });
+        await this.#rejectedCheckpointsByNumber.set(entry.checkpointNumber, archiveRootHex);
+        await this.advanceSynchedL1BlockNumber(entry.l1.blockNumber);
+    }
+    /** Returns the rejected-checkpoint entry with the given archive root, or undefined if not present. */ async getRejectedCheckpointByArchiveRoot(archiveRoot) {
+        const stored = await this.#rejectedCheckpoints.getAsync(archiveRoot.toString());
+        return stored ? this.rejectedCheckpointFromStorage(stored) : undefined;
+    }
+    /** Returns the rejected-checkpoint entry recorded for the given checkpoint number, or undefined if none. */ async getRejectedCheckpointByNumber(checkpointNumber) {
+        const archiveRootHex = await this.#rejectedCheckpointsByNumber.getAsync(checkpointNumber);
+        if (archiveRootHex === undefined) {
+            return undefined;
+        }
+        const stored = await this.#rejectedCheckpoints.getAsync(archiveRootHex);
+        return stored ? this.rejectedCheckpointFromStorage(stored) : undefined;
+    }
+    /** Returns the highest checkpoint number recorded across all rejected entries, or `INITIAL_CHECKPOINT_NUMBER - 1` if none. */ async getLatestRejectedCheckpointNumber() {
+        const [latest] = await toArray(this.#rejectedCheckpointsByNumber.keysAsync({
+            reverse: true,
+            limit: 1
+        }));
+        return CheckpointNumber(latest ?? INITIAL_CHECKPOINT_NUMBER - 1);
+    }
+    /** Removes a rejected-checkpoint entry by its archive root (used when an entry no longer matches L1). */ async removeRejectedCheckpointByArchiveRoot(archiveRoot) {
+        const archiveRootHex = archiveRoot.toString();
+        const stored = await this.#rejectedCheckpoints.getAsync(archiveRootHex);
+        await this.#rejectedCheckpoints.delete(archiveRootHex);
+        if (stored) {
+            // Only clear the by-number index if it still points at this archive root, so a distinct
+            // entry that shares the checkpoint number (e.g. an L1 reorg replacement) is not dropped.
+            const indexed = await this.#rejectedCheckpointsByNumber.getAsync(stored.checkpointNumber);
+            if (indexed === archiveRootHex) {
+                await this.#rejectedCheckpointsByNumber.delete(stored.checkpointNumber);
+            }
+        }
+    }
+    /**
+   * Advances the stored last-synched L1 block number to `l1BlockNumber` only if it is strictly
+   * greater than the current value. Use this whenever ingesting checkpoint-shaped data so the
+   * sync pointer never walks backwards on out-of-order writes (e.g. an invalid checkpoint
+   * advance followed by a valid-checkpoint commit landing at an earlier L1 block).
+   */ async advanceSynchedL1BlockNumber(l1BlockNumber) {
+        const current = await this.#lastSynchedL1Block.getAsync();
+        if (current === undefined || l1BlockNumber > current) {
+            await this.#lastSynchedL1Block.set(l1BlockNumber);
+        }
+    }
+    rejectedCheckpointFromStorage(stored) {
+        return {
+            checkpointNumber: CheckpointNumber(stored.checkpointNumber),
+            archiveRoot: Fr.fromBuffer(stored.archiveRoot),
+            parentArchiveRoot: Fr.fromBuffer(stored.parentArchiveRoot),
+            slotNumber: SlotNumber(stored.slotNumber),
+            l1: L1PublishedData.fromBuffer(stored.l1),
+            reason: stored.reason
+        };
+    }
 }