@aztec/archiver 0.0.1-commit.0dc957cde → 0.0.1-commit.0ec55a70b

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,
@@ -56,7 +58,6 @@ import {
   ProposedCheckpointArchiveRootMismatchError,
   ProposedCheckpointNotSequentialError,
   ProposedCheckpointPromotionNotSequentialError,
-  ProposedCheckpointStaleError,
 } from '../errors.js';
 
 export { TxReceipt, type TxEffect, type TxHash } from '@aztec/stdlib/tx';
@@ -84,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). */
@@ -101,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. */
@@ -134,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) {
@@ -152,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');
   }
 
   /**
@@ -188,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();
@@ -207,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
@@ -322,15 +318,15 @@ 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;
@@ -374,6 +370,7 @@ export class BlockStore {
         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);
@@ -391,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) {
@@ -535,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 };
     });
@@ -588,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)),
     };
@@ -688,28 +686,34 @@ 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);
+    }
   }
 
   /**
-   * Promotes the proposed checkpoint singleton to a confirmed checkpoint entry.
-   * This persists the checkpoint to the store, clears the proposed singleton, and updates the L1 sync point.
-   * Should only be called after the checkpoint has been validated.
-   * @param expectedArchiveRoot - The archive root to match against the proposed checkpoint, to guard against races.
+   * 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.getProposedCheckpointOnly();
+      const proposed = await this.getProposedCheckpointByNumber(checkpointNumber);
       if (!proposed) {
         throw new NoProposedCheckpointToPromoteError();
       }
@@ -733,48 +737,76 @@ export class BlockStore {
         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);
 
-      // Clear the proposed checkpoint singleton
-      await this.#proposedCheckpoint.delete();
+      // 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);
     });
   }
 
-  /** 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();
+  /**
+   * 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;
     }
+    const stored = await this.#proposedCheckpoints.getAsync(key);
+    return stored ? this.convertToProposedCheckpointData(stored) : undefined;
   }
 
-  /** 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) {
-      return 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;
+  }
+
+  /**
+   * 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);
     }
-    return this.convertToProposedCheckpointData(stored);
   }
 
   /**
-   * 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(): 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 {
@@ -795,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();
     }
@@ -807,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();
     }
@@ -841,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);
@@ -885,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) {
@@ -907,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.
@@ -999,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) {
@@ -1188,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++) {
@@ -1216,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 () => {

package/src/store/contract_instance_store.ts

@@ -25,6 +25,49 @@ export class ContractInstanceStore {
     this.#contractInstanceUpdates = db.openMap('archiver_contract_instance_updates');
   }
 
+  /**
+   * Adds multiple contract instances to the store.
+   * @param data - Contract instances to add.
+   * @param blockNumber - L2 block number where the instances were deployed.
+   * @returns True if every insert succeeded.
+   */
+  async addContractInstances(data: ContractInstanceWithAddress[], blockNumber: number): Promise<boolean> {
+    return (await Promise.all(data.map(c => this.addContractInstance(c, blockNumber)))).every(Boolean);
+  }
+
+  /**
+   * Removes multiple contract instances from the store.
+   * @param data - Contract instances to delete.
+   * @returns True if every delete succeeded.
+   */
+  async deleteContractInstances(data: ContractInstanceWithAddress[]): Promise<boolean> {
+    return (await Promise.all(data.map(c => this.deleteContractInstance(c)))).every(Boolean);
+  }
+
+  /**
+   * Adds multiple contract instance updates to the store.
+   * @param data - Contract instance updates to add.
+   * @param timestamp - Timestamp at which the updates were scheduled.
+   * @returns True if every insert succeeded.
+   */
+  async addContractInstanceUpdates(data: ContractInstanceUpdateWithAddress[], timestamp: UInt64): Promise<boolean> {
+    return (
+      await Promise.all(data.map((update, logIndex) => this.addContractInstanceUpdate(update, timestamp, logIndex)))
+    ).every(Boolean);
+  }
+
+  /**
+   * Removes multiple contract instance updates from the store.
+   * @param data - Contract instance updates to delete.
+   * @param timestamp - Timestamp at which the updates were scheduled.
+   * @returns True if every delete succeeded.
+   */
+  async deleteContractInstanceUpdates(data: ContractInstanceUpdateWithAddress[], timestamp: UInt64): Promise<boolean> {
+    return (
+      await Promise.all(data.map((update, logIndex) => this.deleteContractInstanceUpdate(update, timestamp, logIndex)))
+    ).every(Boolean);
+  }
+
   addContractInstance(contractInstance: ContractInstanceWithAddress, blockNumber: number): Promise<void> {
     return this.db.transactionAsync(async () => {
       const key = contractInstance.address.toString();

package/src/store/data_stores.ts

@@ -0,0 +1,108 @@
+import type { L1BlockId } from '@aztec/ethereum/l1-types';
+import type { AztecAsyncKVStore } from '@aztec/kv-store';
+import type { ContractDataSource } from '@aztec/stdlib/contract';
+
+import { join } from 'path';
+
+import { ArchiverContractDataSourceAdapter } from '../modules/contract_data_source_adapter.js';
+import { BlockStore } from './block_store.js';
+import { ContractClassStore } from './contract_class_store.js';
+import { ContractInstanceStore } from './contract_instance_store.js';
+import { FunctionNamesCache } from './function_names_cache.js';
+import { LogStore } from './log_store.js';
+import { MessageStore } from './message_store.js';
+
+export const ARCHIVER_DB_VERSION = 6;
+
+/**
+ * Represents the latest L1 block processed by the archiver for various objects in L2.
+ */
+export type ArchiverL1SynchPoint = {
+  /** Number of the last L1 block that added a new L2 checkpoint metadata.  */
+  blocksSynchedTo?: bigint;
+  /** Last L1 block checked for L1 to L2 messages. */
+  messagesSynchedTo?: L1BlockId;
+};
+
+/**
+ * Bundle of archiver-owned LMDB substores plus the in-memory caches that span them.
+ *
+ * Replaces the former `KVArchiverDataStore` pass-through wrapper. Callers reach into
+ * the relevant substore directly (e.g. `stores.blocks.getBlock`) and use
+ * {@link createArchiverDataStores} to wire them up against a shared KV store.
+ */
+export type ArchiverDataStores = {
+  /** The underlying key-value store. Use {@link AztecAsyncKVStore.transactionAsync} to compose updates atomically. */
+  db: AztecAsyncKVStore;
+  /** Blocks, checkpoints, tx effects, proven/finalized state. */
+  blocks: BlockStore;
+  /** Public, private and contract class logs. */
+  logs: LogStore;
+  /** L1 to L2 messages and message sync state. */
+  messages: MessageStore;
+  /** Contract classes (with bytecode commitments). */
+  contractClasses: ContractClassStore;
+  /** Contract instances and contract instance updates. */
+  contractInstances: ContractInstanceStore;
+  /** In-memory cache of public function selectors -> names. */
+  functionNames: FunctionNamesCache;
+};
+
+/** Options used by {@link createArchiverDataStores}. */
+export type CreateArchiverDataStoresOptions = {
+  /** Maximum number of logs returned per page when paginating tagged log queries. */
+  logsMaxPageSize?: number;
+};
+
+/**
+ * Wires up the archiver substores against a shared KV store and returns the
+ * {@link ArchiverDataStores} bundle.
+ */
+export function createArchiverDataStores(
+  db: AztecAsyncKVStore,
+  opts: CreateArchiverDataStoresOptions = {},
+): ArchiverDataStores {
+  const blocks = new BlockStore(db);
+  return {
+    db,
+    blocks,
+    logs: new LogStore(db, blocks, opts.logsMaxPageSize ?? 1000),
+    messages: new MessageStore(db),
+    contractClasses: new ContractClassStore(db),
+    contractInstances: new ContractInstanceStore(db),
+    functionNames: new FunctionNamesCache(),
+  };
+}
+
+/**
+ * Returns the L1 sync point of the archiver, combining the block sync point from {@link BlockStore}
+ * and the message sync point from {@link MessageStore}.
+ */
+export async function getArchiverSynchPoint(stores: ArchiverDataStores): Promise<ArchiverL1SynchPoint> {
+  const [blocksSynchedTo, messagesSynchedTo] = await Promise.all([
+    stores.blocks.getSynchedL1BlockNumber(),
+    stores.messages.getSynchedL1Block(),
+  ]);
+  return { blocksSynchedTo, messagesSynchedTo };
+}
+
+/**
+ * Backs up the underlying KV store to the given folder. Returns the path to the resulting db file.
+ */
+export async function backupArchiverDataStores(
+  stores: ArchiverDataStores,
+  path: string,
+  compress = true,
+): Promise<string> {
+  await stores.db.backupTo(path, compress);
+  return join(path, 'data.mdb');
+}
+
+/**
+ * Returns a {@link ContractDataSource} adapter over {@link ArchiverDataStores}.
+ * Used by contexts (e.g. offline epoch re-prover tools) that need a ContractDataSource
+ * but do not need a full archiver instance.
+ */
+export function createContractDataSource(stores: ArchiverDataStores): ContractDataSource {
+  return new ArchiverContractDataSourceAdapter(stores);
+}