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

package/src/modules/data_store_updater.ts

@@ -6,17 +6,23 @@ import {
   ContractInstancePublishedEvent,
   ContractInstanceUpdatedEvent,
 } from '@aztec/protocol-contracts/instance-registry';
-import type { L2Block, ValidateCheckpointResult } from '@aztec/stdlib/block';
-import { type ProposedCheckpointInput, type PublishedCheckpoint, validateCheckpoint } from '@aztec/stdlib/checkpoint';
+import type { CommitteeAttestation, L2Block, ValidateCheckpointResult } from '@aztec/stdlib/block';
+import {
+  type L1PublishedData,
+  type ProposedCheckpointInput,
+  type PublishedCheckpoint,
+  validateCheckpoint,
+} from '@aztec/stdlib/checkpoint';
 import {
   type ContractClassPublicWithCommitment,
   computeContractAddressFromInstance,
   computeContractClassId,
 } from '@aztec/stdlib/contract';
+import { MAX_CAPACITY_BLOCKS_PER_CHECKPOINT } from '@aztec/stdlib/deserialization';
 import type { ContractClassLog, PrivateLog, PublicLog } from '@aztec/stdlib/logs';
 import type { UInt64 } from '@aztec/stdlib/types';
 
-import type { KVArchiverDataStore } from '../store/kv_archiver_store.js';
+import type { ArchiverDataStores } from '../store/data_stores.js';
 import type { L2TipsCache } from '../store/l2_tips_cache.js';
 
 /** Operation type for contract data updates. */
@@ -38,7 +44,7 @@ export class ArchiverDataStoreUpdater {
   private readonly log = createLogger('archiver:store_updater');
 
   constructor(
-    private store: KVArchiverDataStore,
+    private stores: ArchiverDataStores,
     private l2TipsCache?: L2TipsCache,
     private opts: { rollupManaLimit?: number } = {},
   ) {}
@@ -56,21 +62,22 @@ export class ArchiverDataStoreUpdater {
     block: L2Block,
     pendingChainValidationStatus?: ValidateCheckpointResult,
   ): Promise<boolean> {
-    const result = await this.store.transactionAsync(async () => {
-      await this.store.addProposedBlock(block);
+    const result = await this.stores.db.transactionAsync(async () => {
+      await this.stores.blocks.addProposedBlock(block);
 
       const opResults = await Promise.all([
         // Update the pending chain validation status if provided
-        pendingChainValidationStatus && this.store.setPendingChainValidationStatus(pendingChainValidationStatus),
+        pendingChainValidationStatus &&
+          this.stores.blocks.setPendingChainValidationStatus(pendingChainValidationStatus),
         // Add any logs emitted during the retrieved block
-        this.store.addLogs([block]),
+        this.stores.logs.addLogs([block]),
         // Unroll all logs emitted during the retrieved block and extract any contract classes and instances from it
         this.addContractDataToDb(block),
       ]);
 
-      await this.l2TipsCache?.refresh();
       return opResults.every(Boolean);
     });
+    await this.l2TipsCache?.refresh();
     return result;
   }
 
@@ -79,64 +86,106 @@ export class ArchiverDataStoreUpdater {
    * Adds new checkpoints to the store with contract class/instance extraction from logs.
    * Prunes any local blocks that conflict with checkpoint data (by comparing archive roots).
    * Extracts ContractClassPublished, ContractInstancePublished, ContractInstanceUpdated events from the checkpoint block logs.
+   * If `promoteProposed` is supplied, the proposed-checkpoint promotion runs inside the same transaction
+   * as the added checkpoints so both updates are applied atomically.
    *
-   * @param checkpoints - The published checkpoints to add.
+   * @param checkpoints - The published checkpoints to add (excluding any being promoted from proposed).
    * @param pendingChainValidationStatus - Optional validation status to set.
+   * @param promoteProposed - Optional promotion of the current proposed checkpoint (fast path when blocks are already local).
    * @returns Result with information about any pruned blocks.
    */
   public async addCheckpoints(
     checkpoints: PublishedCheckpoint[],
     pendingChainValidationStatus?: ValidateCheckpointResult,
+    promoteProposed?: {
+      l1: L1PublishedData;
+      attestations: CommitteeAttestation[];
+      checkpoint: PublishedCheckpoint;
+    },
+    evictProposedFrom?: CheckpointNumber,
   ): Promise<ReconcileCheckpointsResult> {
+    // These checkpoints are already on L1, so ingest validates against the physical blob capacity rather than
+    // the conservative build/attest policy, and tolerates an empty non-first block. Both rules are enforced by
+    // proposers and attesters; rejecting an ingest would stall sync rather than undo the checkpoint.
+    const validateOpts = {
+      rollupManaLimit: this.opts?.rollupManaLimit,
+      maxBlocksPerCheckpoint: MAX_CAPACITY_BLOCKS_PER_CHECKPOINT,
+      allowEmptyNonFirstBlocks: true,
+    };
     for (const checkpoint of checkpoints) {
-      validateCheckpoint(checkpoint.checkpoint, { rollupManaLimit: this.opts?.rollupManaLimit });
+      validateCheckpoint(checkpoint.checkpoint, validateOpts);
+    }
+    if (promoteProposed) {
+      validateCheckpoint(promoteProposed.checkpoint.checkpoint, validateOpts);
     }
 
-    const result = await this.store.transactionAsync(async () => {
+    const result = await this.stores.db.transactionAsync(async () => {
       // Before adding checkpoints, check for conflicts with local blocks if any
       const { prunedBlocks, lastAlreadyInsertedBlockNumber } = await this.pruneMismatchingLocalBlocks(checkpoints);
 
-      await this.store.addCheckpoints(checkpoints);
+      const insertedCheckpoints = await this.stores.blocks.addCheckpoints(checkpoints);
 
-      // Filter out blocks that were already inserted via addProposedBlock() to avoid duplicating logs/contract data
-      const newBlocks = checkpoints
+      // Skip blocks already inserted via addProposedBlock() and blocks of already-stored checkpoints
+      // re-included by an L1 reorg: their logs/contract data were extracted when first inserted.
+      const newBlocks = insertedCheckpoints
         .flatMap((ch: PublishedCheckpoint) => ch.checkpoint.blocks)
         .filter(b => lastAlreadyInsertedBlockNumber === undefined || b.number > lastAlreadyInsertedBlockNumber);
 
       await Promise.all([
         // Update the pending chain validation status if provided
-        pendingChainValidationStatus && this.store.setPendingChainValidationStatus(pendingChainValidationStatus),
+        pendingChainValidationStatus &&
+          this.stores.blocks.setPendingChainValidationStatus(pendingChainValidationStatus),
         // Add any logs emitted during the retrieved blocks
-        this.store.addLogs(newBlocks),
+        this.stores.logs.addLogs(newBlocks),
         // Unroll all logs emitted during the retrieved blocks and extract any contract classes and instances from them
         ...newBlocks.map(block => this.addContractDataToDb(block)),
+        // Promote the proposed checkpoint if requested (uses explicit checkpoint number)
+        promoteProposed
+          ? this.stores.blocks.promoteProposedToCheckpointed(
+              promoteProposed.checkpoint.checkpoint.number,
+              promoteProposed.l1,
+              promoteProposed.attestations,
+              promoteProposed.checkpoint.checkpoint.archive.root,
+            )
+          : undefined,
+        // Evict pending checkpoints that diverged from what L1 mined
+        evictProposedFrom !== undefined
+          ? this.stores.blocks.evictProposedCheckpointsFrom(evictProposedFrom)
+          : undefined,
       ]);
 
-      await this.l2TipsCache?.refresh();
       return { prunedBlocks, lastAlreadyInsertedBlockNumber };
     });
+    await this.l2TipsCache?.refresh();
     return result;
   }
 
-  public async setProposedCheckpoint(proposedCheckpoint: ProposedCheckpointInput) {
-    const result = await this.store.transactionAsync(async () => {
-      await this.store.setProposedCheckpoint(proposedCheckpoint);
-      await this.l2TipsCache?.refresh();
+  public async addProposedCheckpoint(proposedCheckpoint: ProposedCheckpointInput) {
+    const result = await this.stores.db.transactionAsync(async () => {
+      await this.stores.blocks.addProposedCheckpoint(proposedCheckpoint);
     });
-
+    await this.l2TipsCache?.refresh();
     return result;
   }
 
   /**
    * Checks for local proposed blocks that do not match the ones to be checkpointed and prunes them.
-   * This method handles multiple checkpoints but returns after pruning the first conflict found.
-   * This is correct because pruning from the first conflict point removes all subsequent blocks,
-   * and when checkpoints are added afterward, they include all the correct blocks.
+   * Conflict detection is keyed on `blockNumber`: when a local proposed block and an L1
+   * checkpointed block share a block number but live at different slots (e.g. a different proposer
+   * mined the same block number one slot earlier), we still treat them as a conflict and prune.
+   * The trailing per-checkpoint prune that handles "local has extra trailing blocks within the
+   * same slot as the published checkpoint" remains scoped by slot to preserve pipelining: local
+   * blocks that live at a later slot than the checkpoint being processed represent speculation
+   * atop the just-confirmed tip (and may be referenced by a pending proposed checkpoint), so we
+   * leave them in place. This method handles multiple checkpoints but returns after pruning the
+   * first conflict found. This is correct because pruning from the first conflict point removes
+   * all subsequent blocks, and when checkpoints are added afterward, they include all the correct
+   * blocks.
    */
   private async pruneMismatchingLocalBlocks(checkpoints: PublishedCheckpoint[]): Promise<ReconcileCheckpointsResult> {
     const [lastCheckpointedBlockNumber, lastBlockNumber] = await Promise.all([
-      this.store.getCheckpointedL2BlockNumber(),
-      this.store.getLatestBlockNumber(),
+      this.stores.blocks.getCheckpointedL2BlockNumber(),
+      this.stores.blocks.getLatestL2BlockNumber(),
     ]);
 
     // Exit early if there are no local uncheckpointed blocks
@@ -145,29 +194,29 @@ export class ArchiverDataStoreUpdater {
     }
 
     // Get all uncheckpointed local blocks
-    const uncheckpointedLocalBlocks = await this.store.getBlocks(
-      BlockNumber.add(lastCheckpointedBlockNumber, 1),
-      lastBlockNumber - lastCheckpointedBlockNumber,
-    );
+    const uncheckpointedLocalBlocks = await this.stores.blocks.getBlocksData({
+      from: BlockNumber.add(lastCheckpointedBlockNumber, 1),
+      limit: lastBlockNumber - lastCheckpointedBlockNumber,
+    });
 
     let lastAlreadyInsertedBlockNumber: BlockNumber | undefined;
 
     for (const publishedCheckpoint of checkpoints) {
       const checkpointBlocks = publishedCheckpoint.checkpoint.blocks;
       const slot = publishedCheckpoint.checkpoint.slot;
-      const localBlocksInSlot = uncheckpointedLocalBlocks.filter(b => b.slot === slot);
 
       if (checkpointBlocks.length === 0) {
         this.log.warn(`Checkpoint ${publishedCheckpoint.checkpoint.number} for slot ${slot} has no blocks`);
         continue;
       }
 
-      // Find the first checkpoint block that conflicts with an existing local block and prune local afterwards
+      // Find the first checkpoint block that conflicts with an existing local block and prune local afterwards.
+      // Conflict detection joins on block number only — same block number at a different slot is still a conflict.
       for (const checkpointBlock of checkpointBlocks) {
         const blockNumber = checkpointBlock.number;
-        const existingBlock = localBlocksInSlot.find(b => b.number === blockNumber);
+        const existingBlock = uncheckpointedLocalBlocks.find(b => b.header.getBlockNumber() === blockNumber);
         const blockInfos = {
-          existingBlock: existingBlock?.toBlockInfo(),
+          existingBlock: existingBlock?.header.toInspect(),
           checkpointBlock: checkpointBlock.toBlockInfo(),
         };
 
@@ -179,20 +228,24 @@ export class ArchiverDataStoreUpdater {
         } else {
           this.log.info(`Conflict detected at block ${blockNumber} between checkpointed and local block`, blockInfos);
           const prunedBlocks = await this.removeBlocksAfter(BlockNumber(blockNumber - 1));
+          await this.evictProposedCheckpointsForPrunedBlocks(prunedBlocks);
           return { prunedBlocks, lastAlreadyInsertedBlockNumber };
         }
       }
 
-      // If local has more blocks than the checkpoint (e.g., local has [2,3,4] but checkpoint has [2,3]),
-      // we need to prune the extra local blocks so they match what was checkpointed
+      // If the sequencer locally proposed extra blocks within this checkpoint's slot (e.g. local has
+      // [N, N+1] but L1 confirmed just [N]), prune the extras. Scoped to the checkpoint's slot so we
+      // do not throw away speculative blocks at later slots that belong to a pending proposed checkpoint.
       const lastCheckpointBlockNumber = checkpointBlocks.at(-1)!.number;
-      const lastLocalBlockNumber = localBlocksInSlot.at(-1)?.number;
+      const localBlocksInSlot = uncheckpointedLocalBlocks.filter(b => b.header.getSlot() === slot);
+      const lastLocalBlockNumber = localBlocksInSlot.at(-1)?.header.getBlockNumber();
 
       if (lastLocalBlockNumber !== undefined && lastLocalBlockNumber > lastCheckpointBlockNumber) {
         this.log.warn(
           `Local chain for slot ${slot} ends at block ${lastLocalBlockNumber} but checkpoint ends at ${lastCheckpointBlockNumber}. Pruning blocks after block ${lastCheckpointBlockNumber}.`,
         );
         const prunedBlocks = await this.removeBlocksAfter(lastCheckpointBlockNumber);
+        await this.evictProposedCheckpointsForPrunedBlocks(prunedBlocks);
         return { prunedBlocks, lastAlreadyInsertedBlockNumber };
       }
     }
@@ -210,37 +263,74 @@ export class ArchiverDataStoreUpdater {
    * @throws Error if any block to be removed is checkpointed.
    */
   public async removeUncheckpointedBlocksAfter(blockNumber: BlockNumber): Promise<L2Block[]> {
-    const result = await this.store.transactionAsync(async () => {
+    const result = await this.stores.db.transactionAsync(async () => {
       // Verify we're only removing uncheckpointed blocks
-      const lastCheckpointedBlockNumber = await this.store.getCheckpointedL2BlockNumber();
+      const lastCheckpointedBlockNumber = await this.stores.blocks.getCheckpointedL2BlockNumber();
       if (blockNumber < lastCheckpointedBlockNumber) {
         throw new Error(
           `Cannot remove blocks after ${blockNumber} because checkpointed blocks exist up to ${lastCheckpointedBlockNumber}`,
         );
       }
 
-      const result = await this.removeBlocksAfter(blockNumber);
+      const prunedBlocks = await this.removeBlocksAfter(blockNumber);
+      await this.evictProposedCheckpointsForPrunedBlocks(prunedBlocks);
 
-      // Clear the proposed checkpoint if it exists, since its blocks have been pruned
-      await this.store.deleteProposedCheckpoint();
+      return prunedBlocks;
+    });
+    await this.l2TipsCache?.refresh();
+    return result;
+  }
+
+  /**
+   * Removes all blocks without a proposed checkpoint strictly after the specified block number and cleans up associated contract data.
+   * This handles removal of provisionally added blocks along with their contract classes/instances.
+   * Verifies that each block being removed is not part of a stored checkpoint (proposed or not).
+   * This differs from `removeUncheckpointedBlocksAfter` in that it also checks proposed checkpoints.
+   *
+   * @param blockNumber - Remove all blocks with number greater than this.
+   * @returns The removed blocks.
+   * @throws Error if any block to be removed is checkpointed.
+   */
+  public async removeBlocksWithoutProposedCheckpointAfter(blockNumber: BlockNumber): Promise<L2Block[]> {
+    const result = await this.stores.db.transactionAsync(async () => {
+      // Verify we're only removing uncheckpointed blocks
+      const lastCheckpointedBlockNumber = await this.stores.blocks.getProposedCheckpointL2BlockNumber();
+      if (blockNumber < lastCheckpointedBlockNumber) {
+        throw new Error(
+          `Cannot remove blocks after ${blockNumber} because proposed checkpointed blocks exist up to ${lastCheckpointedBlockNumber}`,
+        );
+      }
 
-      await this.l2TipsCache?.refresh();
-      return result;
+      return await this.removeBlocksAfter(blockNumber);
     });
+    await this.l2TipsCache?.refresh();
     return result;
   }
 
+  /**
+   * Evicts pending proposed checkpoints that referenced any of the just-pruned blocks. Pruned
+   * blocks invalidate all proposed checkpoints from the lowest pruned block's checkpoint number
+   * onwards: those checkpoints either reference the pruned blocks directly or chain off them.
+   */
+  private async evictProposedCheckpointsForPrunedBlocks(prunedBlocks: L2Block[]): Promise<void> {
+    if (prunedBlocks.length === 0) {
+      return;
+    }
+    const fromCheckpointNumber = prunedBlocks[0].checkpointNumber;
+    await this.stores.blocks.evictProposedCheckpointsFrom(fromCheckpointNumber);
+  }
+
   /**
    * Removes all blocks strictly after the given block number along with any logs and contract data.
    * Does not remove their checkpoints.
    */
   private async removeBlocksAfter(blockNumber: BlockNumber): Promise<L2Block[]> {
     // First get the blocks to be removed so we can clean up contract data
-    const removedBlocks = await this.store.removeBlocksAfter(blockNumber);
+    const removedBlocks = await this.stores.blocks.removeBlocksAfter(blockNumber);
 
     // Clean up contract data and logs for the removed blocks
     await Promise.all([
-      this.store.deleteLogs(removedBlocks),
+      this.stores.logs.deleteLogs(removedBlocks),
       ...removedBlocks.map(block => this.removeContractDataFromDb(block)),
     ]);
 
@@ -257,20 +347,21 @@ export class ArchiverDataStoreUpdater {
    * @returns True if the operation is successful.
    */
   public async removeCheckpointsAfter(checkpointNumber: CheckpointNumber): Promise<boolean> {
-    return await this.store.transactionAsync(async () => {
-      const { blocksRemoved = [] } = await this.store.removeCheckpointsAfter(checkpointNumber);
+    const result = await this.stores.db.transactionAsync(async () => {
+      const { blocksRemoved = [] } = await this.stores.blocks.removeCheckpointsAfter(checkpointNumber);
 
       const opResults = await Promise.all([
         // Prune rolls back to the last proven block, which is by definition valid
-        this.store.setPendingChainValidationStatus({ valid: true }),
+        this.stores.blocks.setPendingChainValidationStatus({ valid: true }),
         // Remove contract data for all blocks being removed
         ...blocksRemoved.map(block => this.removeContractDataFromDb(block)),
-        this.store.deleteLogs(blocksRemoved),
+        this.stores.logs.deleteLogs(blocksRemoved),
       ]);
 
-      await this.l2TipsCache?.refresh();
       return opResults.every(Boolean);
     });
+    await this.l2TipsCache?.refresh();
+    return result;
   }
 
   /**
@@ -278,10 +369,10 @@ export class ArchiverDataStoreUpdater {
    * @param checkpointNumber - The checkpoint number to set as proven.
    */
   public async setProvenCheckpointNumber(checkpointNumber: CheckpointNumber): Promise<void> {
-    await this.store.transactionAsync(async () => {
-      await this.store.setProvenCheckpointNumber(checkpointNumber);
-      await this.l2TipsCache?.refresh();
+    await this.stores.db.transactionAsync(async () => {
+      await this.stores.blocks.setProvenCheckpointNumber(checkpointNumber);
     });
+    await this.l2TipsCache?.refresh();
   }
 
   /**
@@ -289,10 +380,10 @@ export class ArchiverDataStoreUpdater {
    * @param checkpointNumber - The checkpoint number to set as finalized.
    */
   public async setFinalizedCheckpointNumber(checkpointNumber: CheckpointNumber): Promise<void> {
-    await this.store.transactionAsync(async () => {
-      await this.store.setFinalizedCheckpointNumber(checkpointNumber);
-      await this.l2TipsCache?.refresh();
+    await this.stores.db.transactionAsync(async () => {
+      await this.stores.blocks.setFinalizedCheckpointNumber(checkpointNumber);
     });
+    await this.l2TipsCache?.refresh();
   }
 
   /** Extracts and stores contract data from a single block. */
@@ -336,7 +427,7 @@ export class ArchiverDataStoreUpdater {
       const contractClasses = contractClassPublishedEvents.map(e => e.toContractClassPublic());
       if (contractClasses.length > 0) {
         contractClasses.forEach(c => this.log.verbose(`${Operation[operation]} contract class ${c.id.toString()}`));
-        return await this.store.deleteContractClasses(contractClasses, blockNum);
+        return await this.stores.contractClasses.deleteContractClasses(contractClasses, blockNum);
       }
       return true;
     }
@@ -362,7 +453,7 @@ export class ArchiverDataStoreUpdater {
 
     if (contractClasses.length > 0) {
       contractClasses.forEach(c => this.log.verbose(`${Operation[operation]} contract class ${c.id.toString()}`));
-      return await this.store.addContractClasses(contractClasses, blockNum);
+      return await this.stores.contractClasses.addContractClasses(contractClasses, blockNum);
     }
     return true;
   }
@@ -401,9 +492,9 @@ export class ArchiverDataStoreUpdater {
         this.log.verbose(`${Operation[operation]} contract instance at ${c.address.toString()}`),
       );
       if (operation == Operation.Store) {
-        return await this.store.addContractInstances(contractInstances, blockNum);
+        return await this.stores.contractInstances.addContractInstances(contractInstances, blockNum);
       } else if (operation == Operation.Delete) {
-        return await this.store.deleteContractInstances(contractInstances, blockNum);
+        return await this.stores.contractInstances.deleteContractInstances(contractInstances);
       }
     }
     return true;
@@ -427,9 +518,9 @@ export class ArchiverDataStoreUpdater {
         this.log.verbose(`${Operation[operation]} contract instance update at ${c.address.toString()}`),
       );
       if (operation == Operation.Store) {
-        return await this.store.addContractInstanceUpdates(contractUpdates, timestamp);
+        return await this.stores.contractInstances.addContractInstanceUpdates(contractUpdates, timestamp);
       } else if (operation == Operation.Delete) {
-        return await this.store.deleteContractInstanceUpdates(contractUpdates, timestamp);
+        return await this.stores.contractInstances.deleteContractInstanceUpdates(contractUpdates, timestamp);
       }
     }
     return true;

package/src/modules/instrumentation.ts

@@ -32,6 +32,7 @@ export class ArchiverInstrumentation {
   private pruneCount: UpDownCounter;
 
   private syncDurationPerBlock: Histogram;
+  private syncDurationPerCheckpoint: Histogram;
   private syncBlockCount: UpDownCounter;
   private manaPerBlock: Histogram;
   private txsPerBlock: Histogram;
@@ -42,6 +43,7 @@ export class ArchiverInstrumentation {
   private blockProposalTxTargetCount: UpDownCounter;
 
   private checkpointL1InclusionDelay: Histogram;
+  private checkpointPromotedCount: UpDownCounter;
 
   private log = createLogger('archiver:instrumentation');
 
@@ -68,6 +70,8 @@ export class ArchiverInstrumentation {
 
     this.syncDurationPerBlock = meter.createHistogram(Metrics.ARCHIVER_SYNC_PER_BLOCK);
 
+    this.syncDurationPerCheckpoint = meter.createHistogram(Metrics.ARCHIVER_SYNC_PER_CHECKPOINT);
+
     this.syncBlockCount = createUpDownCounterWithDefault(meter, Metrics.ARCHIVER_SYNC_BLOCK_COUNT);
 
     this.manaPerBlock = meter.createHistogram(Metrics.ARCHIVER_MANA_PER_BLOCK);
@@ -80,7 +84,9 @@ export class ArchiverInstrumentation {
 
     this.pruneDuration = meter.createHistogram(Metrics.ARCHIVER_PRUNE_DURATION);
 
-    this.pruneCount = createUpDownCounterWithDefault(meter, Metrics.ARCHIVER_PRUNE_COUNT);
+    this.pruneCount = createUpDownCounterWithDefault(meter, Metrics.ARCHIVER_PRUNE_COUNT, {
+      [Attributes.PRUNE_TYPE]: ['unproven', 'uncheckpointed', 'l1_conflict', 'orphan', 'l1_mismatch'],
+    });
 
     this.blockProposalTxTargetCount = createUpDownCounterWithDefault(
       meter,
@@ -92,6 +98,8 @@ export class ArchiverInstrumentation {
 
     this.checkpointL1InclusionDelay = meter.createHistogram(Metrics.ARCHIVER_CHECKPOINT_L1_INCLUSION_DELAY);
 
+    this.checkpointPromotedCount = createUpDownCounterWithDefault(meter, Metrics.ARCHIVER_CHECKPOINT_PROMOTED_COUNT);
+
     this.dbMetrics = new LmdbMetrics(
       meter,
       {
@@ -113,17 +121,26 @@ export class ArchiverInstrumentation {
     return this.telemetry.isEnabled();
   }
 
-  public processNewBlocks(syncTimePerBlock: number, blocks: L2Block[]) {
+  public processNewProposedBlock(syncTimePerBlock: number, block: L2Block) {
+    const attrs = { [Attributes.STATUS]: 'proposed' };
+    this.blockHeight.record(block.number, attrs);
     this.syncDurationPerBlock.record(Math.ceil(syncTimePerBlock));
-    this.blockHeight.record(Math.max(...blocks.map(b => b.number)));
-    this.checkpointHeight.record(Math.max(...blocks.map(b => b.checkpointNumber)));
-    this.syncBlockCount.add(blocks.length);
 
-    for (const block of blocks) {
-      this.txCount.add(block.body.txEffects.length);
-      this.txsPerBlock.record(block.body.txEffects.length);
-      this.manaPerBlock.record(block.header.totalManaUsed.toNumber() / 1e6);
+    // Per block metrics
+    this.txCount.add(block.body.txEffects.length);
+    this.txsPerBlock.record(block.body.txEffects.length);
+    this.manaPerBlock.record(block.header.totalManaUsed.toNumber() / 1e6);
+  }
+
+  public processNewCheckpointedBlocks(syncTimePerCheckpoint: number, blocks: L2Block[]) {
+    if (blocks.length === 0) {
+      return;
     }
+
+    this.syncDurationPerCheckpoint.record(Math.ceil(syncTimePerCheckpoint));
+    this.blockHeight.record(Math.max(...blocks.map(b => b.number)), { [Attributes.STATUS]: 'checkpointed' });
+    this.checkpointHeight.record(Math.max(...blocks.map(b => b.checkpointNumber)));
+    this.syncBlockCount.add(blocks.length);
   }
 
   public processNewMessages(count: number, syncPerMessageMs: number) {
@@ -135,10 +152,21 @@ export class ArchiverInstrumentation {
   }
 
   public processPrune(duration: number) {
-    this.pruneCount.add(1);
+    this.pruneCount.add(1, { [Attributes.PRUNE_TYPE]: 'unproven' });
     this.pruneDuration.record(Math.ceil(duration));
   }
 
+  /**
+   * Records a pending-chain reorg, where the archiver dropped proposed blocks (and world-state follows by pruning). The
+   * type distinguishes the cause: 'uncheckpointed' (slot ended without a checkpoint), 'l1_conflict' (proposed blocks
+   * conflicting with an L1 checkpoint), 'orphan' (no matching proposed checkpoint arrived before the deadline), or
+   * 'l1_mismatch' (the local checkpointed tip diverged from L1 — an L1 reorg or a pruned/missed-proof checkpoint — so
+   * already-checkpointed blocks were rewound).
+   */
+  public recordPrune(pruneType: 'uncheckpointed' | 'l1_conflict' | 'orphan' | 'l1_mismatch') {
+    this.pruneCount.add(1, { [Attributes.PRUNE_TYPE]: pruneType });
+  }
+
   public updateLastProvenCheckpoint(checkpoint: CheckpointData) {
     const lastBlockNumberInCheckpoint = checkpoint.startBlock + checkpoint.blockCount - 1;
     this.blockHeight.record(lastBlockNumberInCheckpoint, { [Attributes.STATUS]: 'proven' });
@@ -169,6 +197,11 @@ export class ArchiverInstrumentation {
     });
   }
 
+  /** Records a checkpoint promoted from proposed (blob fetch skipped). */
+  public processCheckpointPromoted() {
+    this.checkpointPromotedCount.add(1);
+  }
+
   /**
    * Records L1 inclusion timing for a checkpoint observed on L1 (seconds into the L2 slot).
    */