@aztec/archiver 0.0.1-commit.e588bc7e5 → 0.0.1-commit.e5a3663dd

package/src/modules/validation.ts

@@ -10,7 +10,7 @@ import {
 } from '@aztec/stdlib/block';
 import type { PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
 import { type L1RollupConstants, computeQuorum, getEpochAtSlot } from '@aztec/stdlib/epoch-helpers';
-import { ConsensusPayload } from '@aztec/stdlib/p2p';
+import { ConsensusPayload, type CoordinationSignatureContext } from '@aztec/stdlib/p2p';
 
 export type { ValidateCheckpointResult };
 
@@ -18,11 +18,11 @@ export type { ValidateCheckpointResult };
  * Extracts attestation information from a published checkpoint.
  * Returns info for each attestation, preserving array indices.
  */
-export function getAttestationInfoFromPublishedCheckpoint({
-  checkpoint,
-  attestations,
-}: PublishedCheckpoint): AttestationInfo[] {
-  const payload = ConsensusPayload.fromCheckpoint(checkpoint);
+export function getAttestationInfoFromPublishedCheckpoint(
+  { checkpoint, attestations }: PublishedCheckpoint,
+  signatureContext: CoordinationSignatureContext,
+): AttestationInfo[] {
+  const payload = ConsensusPayload.fromCheckpoint(checkpoint, signatureContext);
   return getAttestationInfoFromPayload(payload, attestations);
 }
 
@@ -34,9 +34,10 @@ export async function validateCheckpointAttestations(
   publishedCheckpoint: PublishedCheckpoint,
   epochCache: EpochCache,
   constants: Pick<L1RollupConstants, 'epochDuration'>,
+  signatureContext: CoordinationSignatureContext,
   logger?: Logger,
 ): Promise<ValidateCheckpointResult> {
-  const attestorInfos = getAttestationInfoFromPublishedCheckpoint(publishedCheckpoint);
+  const attestorInfos = getAttestationInfoFromPublishedCheckpoint(publishedCheckpoint, signatureContext);
   const attestors = compactArray(attestorInfos.map(info => ('address' in info ? info.address : undefined)));
   const { checkpoint, attestations } = publishedCheckpoint;
   const headerHash = checkpoint.header.hash();

package/src/store/block_store.ts

@@ -10,6 +10,7 @@ import type { AztecAsyncKVStore, AztecAsyncMap, AztecAsyncSingleton, Range } fro
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 import {
   type BlockData,
+  type BlockDataWithCheckpointContext,
   BlockHash,
   Body,
   CheckpointedL2Block,
@@ -45,6 +46,7 @@ import {
 import {
   BlockAlreadyCheckpointedError,
   BlockArchiveNotConsistentError,
+  BlockCheckpointNumberNotSequentialError,
   BlockIndexNotSequentialError,
   BlockNotFoundError,
   BlockNumberNotSequentialError,
@@ -52,8 +54,10 @@ import {
   CheckpointNotFoundError,
   CheckpointNumberNotSequentialError,
   InitialCheckpointNumberNotSequentialError,
+  NoProposedCheckpointToPromoteError,
+  ProposedCheckpointArchiveRootMismatchError,
   ProposedCheckpointNotSequentialError,
-  ProposedCheckpointStaleError,
+  ProposedCheckpointPromotionNotSequentialError,
 } from '../errors.js';
 
 export { TxReceipt, type TxEffect, type TxHash } from '@aztec/stdlib/tx';
@@ -81,6 +85,7 @@ type CommonCheckpointStorage = {
 type CheckpointStorage = CommonCheckpointStorage & {
   l1: Buffer;
   attestations: Buffer[];
+  feeAssetPriceModifier: string;
 };
 
 /** Storage format for a proposed checkpoint (attested but not yet L1-confirmed). */
@@ -98,7 +103,10 @@ export class BlockStore {
   /** Map block number to block data */
   #blocks: AztecAsyncMap<number, BlockStorage>;
 
-  /** Map checkpoint number to checkpoint data */
+  /** Map keyed by checkpoint number holding proposed (locally-validated, not yet L1-confirmed) checkpoints. */
+  #proposedCheckpoints: AztecAsyncMap<number, ProposedCheckpointStorage>;
+
+  /** Map checkpoint number to checkpoint data for mined checkpoints only */
   #checkpoints: AztecAsyncMap<number, CheckpointStorage>;
 
   /** Map slot number to checkpoint number, for looking up checkpoints by slot range. */
@@ -131,9 +139,6 @@ export class BlockStore {
   /** Index mapping block archive to block number */
   #blockArchiveIndex: AztecAsyncMap<string, number>;
 
-  /** Singleton: assumes max 1-deep pipeline. For deeper pipelining, replace with a map keyed by checkpoint number. */
-  #proposedCheckpoint: AztecAsyncSingleton<ProposedCheckpointStorage>;
-
   #log = createLogger('archiver:block_store');
 
   constructor(private db: AztecAsyncKVStore) {
@@ -149,7 +154,7 @@ export class BlockStore {
     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');
   }
 
   /**
@@ -185,8 +190,7 @@ export class BlockStore {
 
       // 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();
@@ -204,19 +208,14 @@ export class BlockStore {
         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]: [CheckpointNumber, 'confirmed' | 'proposed'] =
-          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, blockCheckpointNumber, previous);
       }
 
       // Extract the previous block if there is one and see if it is for the same checkpoint or not
@@ -262,16 +261,28 @@ export class BlockStore {
     }
 
     return await this.db.transactionAsync(async () => {
-      // Check that the checkpoint immediately before the first block to be added is present in the store.
       const firstCheckpointNumber = checkpoints[0].checkpoint.number;
       const previousCheckpointNumber = await this.getLatestCheckpointNumber();
 
-      if (previousCheckpointNumber !== firstCheckpointNumber - 1 && !opts.force) {
+      // Handle already-stored checkpoints at the start of the batch.
+      // This can happen after an L1 reorg re-includes a checkpoint in a different L1 block.
+      // We accept them if archives match (same content) and update their L1 metadata.
+      if (!opts.force && firstCheckpointNumber <= previousCheckpointNumber) {
+        checkpoints = await this.skipOrUpdateAlreadyStoredCheckpoints(checkpoints, previousCheckpointNumber);
+        if (checkpoints.length === 0) {
+          return true;
+        }
+        // Re-check sequentiality after skipping
+        const newFirstNumber = checkpoints[0].checkpoint.number;
+        if (previousCheckpointNumber !== newFirstNumber - 1) {
+          throw new InitialCheckpointNumberNotSequentialError(newFirstNumber, previousCheckpointNumber);
+        }
+      } else if (previousCheckpointNumber !== firstCheckpointNumber - 1 && !opts.force) {
         throw new InitialCheckpointNumberNotSequentialError(firstCheckpointNumber, previousCheckpointNumber);
       }
 
       // 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: PublishedCheckpoint | undefined = undefined;
@@ -307,21 +318,66 @@ export class BlockStore {
           checkpointNumber: checkpoint.checkpoint.number,
           startBlock: checkpoint.checkpoint.blocks[0].number,
           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);
-      }
 
-      // 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);
+        // Remove proposed checkpoint if it exists, since L1 is authoritative
+        await this.#proposedCheckpoints.delete(checkpoint.checkpoint.number);
+      }
 
       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.
+   */
+  private async skipOrUpdateAlreadyStoredCheckpoints(
+    checkpoints: PublishedCheckpoint[],
+    latestStored: CheckpointNumber,
+  ): Promise<PublishedCheckpoint[]> {
+    let i = 0;
+    for (; i < checkpoints.length && checkpoints[i].checkpoint.number <= latestStored; i++) {
+      const incoming = checkpoints[i];
+      const stored = await this.getCheckpointData(incoming.checkpoint.number);
+      if (!stored) {
+        // Should not happen if latestStored is correct, but be safe
+        break;
+      }
+      // Verify the checkpoint content matches (archive root)
+      if (!stored.archive.root.equals(incoming.checkpoint.archive.root)) {
+        throw new Error(
+          `Checkpoint ${incoming.checkpoint.number} already exists in store but with a different archive root. ` +
+            `Stored: ${stored.archive.root}, incoming: ${incoming.checkpoint.archive.root}`,
+        );
+      }
+      // Update L1 metadata and attestations for the already-stored checkpoint
+      this.#log.warn(
+        `Checkpoint ${incoming.checkpoint.number} already stored, updating L1 info ` +
+          `(L1 block ${stored.l1.blockNumber} -> ${incoming.l1.blockNumber})`,
+      );
+      await this.#checkpoints.set(incoming.checkpoint.number, {
+        header: incoming.checkpoint.header.toBuffer(),
+        archive: incoming.checkpoint.archive.toBuffer(),
+        checkpointOutHash: incoming.checkpoint.getCheckpointOutHash().toBuffer(),
+        l1: incoming.l1.toBuffer(),
+        attestations: incoming.attestations.map(a => a.toBuffer()),
+        checkpointNumber: incoming.checkpoint.number,
+        startBlock: incoming.checkpoint.blocks[0].number,
+        blockCount: incoming.checkpoint.blocks.length,
+        feeAssetPriceModifier: incoming.checkpoint.feeAssetPriceModifier.toString(),
+      });
+      // 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).
@@ -332,24 +388,27 @@ export class BlockStore {
       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 previousBlockNumber = BlockNumber(predecessor.startBlock + predecessor.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).
+   * proposed checkpoints (addProposedCheckpoint).
    */
   private validateCheckpointBlocks(blocks: L2Block[], previousBlock: L2Block | undefined): void {
     for (const block of blocks) {
@@ -476,11 +535,8 @@ export class BlockStore {
         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 };
     });
@@ -529,6 +585,7 @@ export class BlockStore {
       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)),
     };
@@ -629,44 +686,127 @@ export class BlockStore {
   }
 
   async hasProposedCheckpoint(): Promise<boolean> {
-    const proposed = await this.#proposedCheckpoint.getAsync();
-    return proposed !== undefined;
+    const [key] = await toArray(this.#proposedCheckpoints.keysAsync({ limit: 1 }));
+    return key !== undefined;
   }
 
-  /** Deletes the proposed checkpoint from storage. */
-  async deleteProposedCheckpoint(): Promise<void> {
-    await this.#proposedCheckpoint.delete();
+  /** Deletes all pending proposed checkpoints from storage. */
+  async deleteProposedCheckpoints(): Promise<void> {
+    for await (const key of this.#proposedCheckpoints.keysAsync()) {
+      await this.#proposedCheckpoints.delete(key);
+    }
   }
 
-  /** Clears the proposed checkpoint if the given confirmed checkpoint number supersedes it. */
-  async clearProposedCheckpointIfSuperseded(confirmedCheckpointNumber: CheckpointNumber): Promise<void> {
-    const proposedCheckpointNumber = await this.getProposedCheckpointNumber();
-    if (proposedCheckpointNumber <= confirmedCheckpointNumber) {
-      await this.#proposedCheckpoint.delete();
-    }
+  /**
+   * 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: CheckpointNumber,
+    l1: L1PublishedData,
+    attestations: CommitteeAttestation[],
+    expectedArchiveRoot: Fr,
+  ): Promise<void> {
+    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);
+
+      // Update the last synced L1 block
+      await this.#lastSynchedL1Block.set(l1.blockNumber);
+    });
   }
 
-  /** Returns the proposed checkpoint data, or undefined if no proposed checkpoint exists. No fallback to confirmed. */
-  async getProposedCheckpointOnly(): Promise<ProposedCheckpointData | undefined> {
-    const stored = await this.#proposedCheckpoint.getAsync();
-    if (!stored) {
+  /**
+   * Returns the latest pending checkpoint (highest-numbered entry), or undefined if none.
+   * No fallback to confirmed.
+   */
+  async getLastProposedCheckpoint(): Promise<ProposedCheckpointData | undefined> {
+    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: CheckpointNumber): Promise<ProposedCheckpointData | undefined> {
+    const stored = await this.#proposedCheckpoints.getAsync(n);
+    return stored ? this.convertToProposedCheckpointData(stored) : undefined;
+  }
+
+  /** Returns all pending checkpoints in ascending checkpoint-number order. */
+  async getProposedCheckpoints(): Promise<ProposedCheckpointData[]> {
+    const results: ProposedCheckpointData[] = [];
+    for await (const [, stored] of this.#proposedCheckpoints.entriesAsync()) {
+      results.push(this.convertToProposedCheckpointData(stored));
+    }
+    return results;
   }
 
   /**
-   * Gets the checkpoint at the proposed tip
-   * - pending checkpoint if it exists
+   * 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: CheckpointNumber): Promise<void> {
+    const keysToDelete: number[] = [];
+    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:
+   * - latest pending checkpoint if any exist
    * - fallsback to latest confirmed checkpoint otherwise
-   * @returns CommonCheckpointData
    */
-  async getProposedCheckpoint(): Promise<CommonCheckpointData | undefined> {
-    const stored = await this.#proposedCheckpoint.getAsync();
-    if (!stored) {
+  async getLastCheckpoint(): Promise<CommonCheckpointData | undefined> {
+    const latest = await this.getLastProposedCheckpoint();
+    if (!latest) {
       return this.getCheckpointData(await this.getLatestCheckpointNumber());
     }
-    return this.convertToProposedCheckpointData(stored);
+    return latest;
   }
 
   private convertToProposedCheckpointData(stored: ProposedCheckpointStorage): ProposedCheckpointData {
@@ -687,7 +827,7 @@ export class BlockStore {
    * @returns CheckpointNumber
    */
   async getProposedCheckpointNumber(): Promise<CheckpointNumber> {
-    const proposed = await this.getProposedCheckpoint();
+    const proposed = await this.getLastCheckpoint();
     if (!proposed) {
       return await this.getLatestCheckpointNumber();
     }
@@ -699,7 +839,7 @@ export class BlockStore {
    * @returns BlockNumber
    */
   async getProposedCheckpointL2BlockNumber(): Promise<BlockNumber> {
-    const proposed = await this.getProposedCheckpoint();
+    const proposed = await this.getLastCheckpoint();
     if (!proposed) {
       return await this.getCheckpointedL2BlockNumber();
     }
@@ -733,7 +873,12 @@ export class BlockStore {
    * @param limit - The number of blocks to return.
    * @returns The requested L2 blocks
    */
-  async *getCheckpointedBlocks(start: BlockNumber, limit: number): AsyncIterableIterator<CheckpointedL2Block> {
+  getCheckpointedBlocks(start: BlockNumber, limit: number): Promise<CheckpointedL2Block[]> {
+    return toArray(this.iterateCheckpointedBlocks(start, limit));
+  }
+
+  /** Async iterator variant of {@link getCheckpointedBlocks}. */
+  async *iterateCheckpointedBlocks(start: BlockNumber, limit: number): AsyncIterableIterator<CheckpointedL2Block> {
     const checkpointCache = new Map<CheckpointNumber, CheckpointStorage>();
     for await (const [blockNumber, blockStorage] of this.getBlockStorages(start, limit)) {
       const block = await this.getBlockFromBlockStorage(blockNumber, blockStorage);
@@ -777,7 +922,12 @@ export class BlockStore {
    * @param limit - The number of blocks to return.
    * @returns The requested L2 blocks
    */
-  async *getBlocks(start: BlockNumber, limit: number): AsyncIterableIterator<L2Block> {
+  getBlocks(start: BlockNumber, limit: number): Promise<L2Block[]> {
+    return toArray(this.iterateBlocks(start, limit));
+  }
+
+  /** Async iterator variant of {@link getBlocks}. */
+  async *iterateBlocks(start: BlockNumber, limit: number): AsyncIterableIterator<L2Block> {
     for await (const [blockNumber, blockStorage] of this.getBlockStorages(start, limit)) {
       const block = await this.getBlockFromBlockStorage(blockNumber, blockStorage);
       if (block) {
@@ -799,6 +949,33 @@ export class BlockStore {
     return this.getBlockDataFromBlockStorage(blockStorage);
   }
 
+  /**
+   * Gets block metadata plus checkpoint-derived context (L1 publish info, attestations) without
+   * deserializing tx bodies. When the block's containing checkpoint has not yet been L1-confirmed,
+   * `checkpoint` and `l1` are `undefined` and `attestations` is empty.
+   */
+  async getBlockDataWithCheckpointContext(
+    blockNumber: BlockNumber,
+  ): Promise<BlockDataWithCheckpointContext | undefined> {
+    const blockStorage = await this.#blocks.getAsync(blockNumber);
+    if (!blockStorage || !blockStorage.header) {
+      return undefined;
+    }
+    const data = this.getBlockDataFromBlockStorage(blockStorage);
+    const checkpointStorage = await this.#checkpoints.getAsync(blockStorage.checkpointNumber);
+    if (!checkpointStorage) {
+      return { data, checkpoint: undefined, l1: undefined, attestations: [] };
+    }
+    const checkpoint = this.checkpointDataFromCheckpointStorage(checkpointStorage);
+    return { data, checkpoint, l1: checkpoint.l1, attestations: checkpoint.attestations };
+  }
+
+  /** Returns the checkpoint number that contains the given slot (or undefined if not found). */
+  async getCheckpointNumberBySlot(slot: SlotNumber): Promise<CheckpointNumber | undefined> {
+    const checkpointNumber = await this.#slotToCheckpoint.getAsync(slot);
+    return checkpointNumber === undefined ? undefined : CheckpointNumber(checkpointNumber);
+  }
+
   /**
    * Gets block metadata (without tx data) by archive root.
    * @param archive - The archive root of the block to return.
@@ -891,7 +1068,12 @@ export class BlockStore {
    * @param limit - The number of blocks to return.
    * @returns The requested L2 block headers
    */
-  async *getBlockHeaders(start: BlockNumber, limit: number): AsyncIterableIterator<BlockHeader> {
+  getBlockHeaders(start: BlockNumber, limit: number): Promise<BlockHeader[]> {
+    return toArray(this.iterateBlockHeaders(start, limit));
+  }
+
+  /** Async iterator variant of {@link getBlockHeaders}. */
+  async *iterateBlockHeaders(start: BlockNumber, limit: number): AsyncIterableIterator<BlockHeader> {
     for await (const [blockNumber, blockStorage] of this.getBlockStorages(start, limit)) {
       const header = BlockHeader.fromBuffer(blockStorage.header);
       if (header.getBlockNumber() !== blockNumber) {
@@ -920,7 +1102,7 @@ export class BlockStore {
     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),
     };
@@ -1080,20 +1262,25 @@ export class BlockStore {
     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: ProposedCheckpointInput) {
+  /**
+   * 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: ProposedCheckpointInput) {
     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: L2Block[] = [];
       for (let i = 0; i < proposed.blockCount; i++) {
@@ -1108,7 +1295,7 @@ export class BlockStore {
       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(),

package/src/store/contract_class_store.ts

@@ -2,7 +2,11 @@ import { Fr } from '@aztec/foundation/curves/bn254';
 import { toArray } from '@aztec/foundation/iterable';
 import { BufferReader, numToUInt8, serializeToBuffer } from '@aztec/foundation/serialize';
 import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
-import type { ContractClassPublic, ContractClassPublicWithBlockNumber } from '@aztec/stdlib/contract';
+import type {
+  ContractClassPublic,
+  ContractClassPublicWithBlockNumber,
+  ContractClassPublicWithCommitment,
+} from '@aztec/stdlib/contract';
 
 /**
  * LMDB-based contract class storage for the archiver.
@@ -16,6 +20,28 @@ export class ContractClassStore {
     this.#bytecodeCommitments = db.openMap('archiver_bytecode_commitments');
   }
 
+  /**
+   * Adds multiple contract classes to the store.
+   * @param data - Contract classes (with bytecode commitments) to add.
+   * @param blockNumber - L2 block number where the classes were registered.
+   * @returns True if every insert succeeded.
+   */
+  async addContractClasses(data: ContractClassPublicWithCommitment[], blockNumber: number): Promise<boolean> {
+    return (await Promise.all(data.map(c => this.addContractClass(c, c.publicBytecodeCommitment, blockNumber)))).every(
+      Boolean,
+    );
+  }
+
+  /**
+   * Removes multiple contract classes from the store, but only if they were registered at or after the given block.
+   * @param data - Contract classes to delete.
+   * @param blockNumber - Lower bound on the block number at which the classes were registered.
+   * @returns True if every delete succeeded.
+   */
+  async deleteContractClasses(data: ContractClassPublic[], blockNumber: number): Promise<boolean> {
+    return (await Promise.all(data.map(c => this.deleteContractClass(c, blockNumber)))).every(Boolean);
+  }
+
   async addContractClass(
     contractClass: ContractClassPublic,
     bytecodeCommitment: Fr,
@@ -34,7 +60,7 @@ export class ContractClassStore {
     });
   }
 
-  async deleteContractClasses(contractClass: ContractClassPublic, blockNumber: number): Promise<void> {
+  async deleteContractClass(contractClass: ContractClassPublic, blockNumber: number): Promise<void> {
     const restoredContractClass = await this.#contractClasses.getAsync(contractClass.id.toString());
     if (restoredContractClass && deserializeContractClassPublic(restoredContractClass).l2BlockNumber >= blockNumber) {
       await this.db.transactionAsync(async () => {