@aztec/archiver 5.0.0-rc.2 → 5.0.0

package/src/modules/l1_synchronizer.ts

@@ -16,7 +16,12 @@ import { retryTimes } from '@aztec/foundation/retry';
 import { count } from '@aztec/foundation/string';
 import { DateProvider, Timer, elapsed } from '@aztec/foundation/timer';
 import { isDefined, isErrorClass } from '@aztec/foundation/types';
-import { type ArchiverEmitter, L2BlockSourceEvents, type ValidateCheckpointResult } from '@aztec/stdlib/block';
+import {
+  type ArchiverEmitter,
+  type L2Block,
+  L2BlockSourceEvents,
+  type ValidateCheckpointResult,
+} from '@aztec/stdlib/block';
 import {
   Checkpoint,
   type CheckpointData,
@@ -57,6 +62,8 @@ type RollupStatus = {
   lastRetrievedCheckpoint?: PublishedCheckpoint;
   /** Last checkpoint observed on L1 across both valid and rejected entries on this iteration */
   lastSeenCheckpoint?: { checkpointNumber: CheckpointNumber; l1: L1PublishedData };
+  /** Blocks added while handling checkpoints this iteration, for the aggregate block source update event. */
+  blocksAdded: L2Block[];
 };
 
 /**
@@ -145,7 +152,9 @@ export class ArchiverL1Synchronizer implements Traceable {
   }
 
   @trackSpan('Archiver.syncFromL1')
-  public async syncFromL1(initialSyncComplete: boolean): Promise<void> {
+  public async syncFromL1(initialSyncComplete: boolean): Promise<L2Block[]> {
+    const blocksAdded: L2Block[] = [];
+
     // In between the various calls to L1, the block number can move meaning some of the following
     // calls will return data for blocks that were not present during earlier calls. To combat this
     // we ensure that all data retrieval methods only retrieve data up to the currentBlockNumber
@@ -158,7 +167,7 @@ export class ArchiverL1Synchronizer implements Traceable {
 
     if (this.l1BlockHash && currentL1BlockHash.equals(this.l1BlockHash)) {
       this.log.trace(`No new L1 blocks since last sync at L1 block ${this.l1BlockNumber}`);
-      return;
+      return blocksAdded;
     }
 
     // Log at error if the latest L1 block timestamp is too old
@@ -196,6 +205,7 @@ export class ArchiverL1Synchronizer implements Traceable {
       // First we retrieve new checkpoints and L2 blocks and store them in the DB. This will also update the
       // pending chain validation status, proven checkpoint number, and synched L1 block number.
       const rollupStatus = await this.handleCheckpoints(blocksSynchedTo, currentL1BlockNumber, initialSyncComplete);
+      blocksAdded.push(...rollupStatus.blocksAdded);
 
       // Then we try pruning uncheckpointed blocks if a new slot was mined without checkpoints
       await this.pruneUncheckpointedBlocks(currentL1Timestamp);
@@ -237,6 +247,8 @@ export class ArchiverL1Synchronizer implements Traceable {
       l1TimestampAtStart: currentL1Timestamp,
       l1BlockNumberAtEnd,
     });
+
+    return blocksAdded;
   }
 
   /** Updates the finalized checkpoint using the pre-fetched finalized L1 block from the current sync iteration. */
@@ -267,7 +279,7 @@ export class ArchiverL1Synchronizer implements Traceable {
   }
 
   /** Prune all proposed local blocks that should have been checkpointed by now. */
-  private async pruneUncheckpointedBlocks(currentL1Timestamp: bigint) {
+  private async pruneUncheckpointedBlocks(currentL1Timestamp: bigint): Promise<void> {
     const [lastCheckpointedBlockNumber, lastProposedBlockNumber] = await Promise.all([
       this.stores.blocks.getCheckpointedL2BlockNumber(),
       this.stores.blocks.getLatestL2BlockNumber(),
@@ -302,6 +314,7 @@ export class ArchiverL1Synchronizer implements Traceable {
 
     const prunedBlocks = await this.updater.removeUncheckpointedBlocksAfter(lastCheckpointedBlockNumber);
     if (prunedBlocks.length > 0) {
+      this.instrumentation.recordPrune('uncheckpointed');
       this.events.emit(L2BlockSourceEvents.L2PruneUncheckpointed, {
         type: L2BlockSourceEvents.L2PruneUncheckpointed,
         slotNumber: firstUncheckpointedBlockSlot,
@@ -622,6 +635,7 @@ export class ArchiverL1Synchronizer implements Traceable {
     currentL1BlockNumber: bigint,
     initialSyncComplete: boolean,
   ): Promise<RollupStatus> {
+    const blocksAdded: L2Block[] = [];
     const localPendingCheckpointNumber = await this.stores.blocks.getLatestCheckpointNumber();
     const initialValidationResult: ValidateCheckpointResult | undefined =
       await this.stores.blocks.getPendingChainValidationStatus();
@@ -640,6 +654,7 @@ export class ArchiverL1Synchronizer implements Traceable {
       pendingCheckpointNumber,
       pendingArchive: pendingArchive.toString(),
       validationResult: initialValidationResult,
+      blocksAdded,
     };
     this.log.trace(`Retrieved rollup status at current L1 block ${currentL1BlockNumber}.`, {
       localPendingCheckpointNumber,
@@ -782,6 +797,9 @@ export class ArchiverL1Synchronizer implements Traceable {
 
         const checkpointsToRemove = localPendingCheckpointNumber - tipAfterUnwind;
         await this.updater.removeCheckpointsAfter(CheckpointNumber(tipAfterUnwind));
+        if (checkpointsToRemove > 0) {
+          this.instrumentation.recordPrune('l1_mismatch');
+        }
 
         this.log.warn(
           `Removed ${count(checkpointsToRemove, 'checkpoint')} after checkpoint ${tipAfterUnwind} ` +
@@ -1067,6 +1085,11 @@ export class ArchiverL1Synchronizer implements Traceable {
           );
         }
 
+        // Record blocks newly fetched from L1 checkpoint payloads as added. The promoted checkpoint (if any) is
+        // excluded: its blocks were already in local archiver storage (added via the proposed-block path) so the
+        // block stream does not need them re-downloaded.
+        blocksAdded.push(...checkpointsToAdd.flatMap(c => c.checkpoint.blocks));
+
         // If blocks were pruned due to conflict with L1 checkpoints, emit event
         if (result.prunedBlocks && result.prunedBlocks.length > 0) {
           const prunedCheckpointNumber = result.prunedBlocks[0].checkpointNumber;
@@ -1077,6 +1100,8 @@ export class ArchiverL1Synchronizer implements Traceable {
             { prunedBlocks: result.prunedBlocks.map(b => b.toBlockInfo()), prunedSlotNumber, prunedCheckpointNumber },
           );
 
+          this.instrumentation.recordPrune('l1_conflict');
+
           // Emit event for listening services to react to the prune.
           // Note: slotNumber comes from the first pruned block. If pruned blocks theoretically spanned multiple slots,
           // only one slot number would be reported (though in practice all blocks in a checkpoint span a single slot).

package/src/modules/validation.ts

@@ -1,4 +1,5 @@
 import type { EpochCache } from '@aztec/epoch-cache';
+import type { ViemCommitteeAttestations } from '@aztec/ethereum/contracts';
 import { type CheckpointNumber, EpochNumber } from '@aztec/foundation/branded-types';
 import { compactArray } from '@aztec/foundation/collection';
 import type { Fr } from '@aztec/foundation/curves/bn254';
@@ -29,22 +30,6 @@ export function getAttestationInfoFromPublishedCheckpoint(
   return getAttestationInfoFromPayload(payload, attestations);
 }
 
-/**
- * Validates the attestations of a checkpoint already retrieved (with its blocks) from blobs.
- * Returns true if the attestations are valid and sufficient, false otherwise.
- */
-export function validateCheckpointAttestations(
-  publishedCheckpoint: PublishedCheckpoint,
-  epochCache: EpochCache,
-  constants: Pick<L1RollupConstants, 'epochDuration'>,
-  signatureContext: CoordinationSignatureContext,
-  logger?: Logger,
-): Promise<ValidateCheckpointResult> {
-  const { checkpoint, attestations } = publishedCheckpoint;
-  const payload = ConsensusPayload.fromCheckpoint(checkpoint, signatureContext);
-  return validateAttestations(payload, attestations, checkpoint.toCheckpointInfo(), epochCache, constants, logger);
-}
-
 /** The subset of a calldata-only checkpoint needed to validate its committee attestations. */
 export type CalldataCheckpointForAttestations = {
   checkpointNumber: CheckpointNumber;
@@ -52,6 +37,8 @@ export type CalldataCheckpointForAttestations = {
   feeAssetPriceModifier: bigint;
   header: CheckpointHeader;
   attestations: CommitteeAttestation[];
+  /** The exact packed attestations tuple from L1 calldata, carried verbatim for byte-faithful invalidation. */
+  verbatimAttestations: ViemCommitteeAttestations;
 };
 
 /**
@@ -80,7 +67,15 @@ export function validateCheckpointAttestationsFromCalldata(
     checkpointNumber: checkpoint.checkpointNumber,
     timestamp: checkpoint.header.timestamp,
   };
-  return validateAttestations(payload, checkpoint.attestations, checkpointInfo, epochCache, constants, logger);
+  return validateAttestations(
+    payload,
+    checkpoint.attestations,
+    checkpoint.verbatimAttestations,
+    checkpointInfo,
+    epochCache,
+    constants,
+    logger,
+  );
 }
 
 /**
@@ -88,9 +83,10 @@ export function validateCheckpointAttestationsFromCalldata(
  * independent of whether the checkpoint's blocks have been decoded from blobs. Returns true if the
  * attestations are valid and sufficient, false otherwise.
  */
-async function validateAttestations(
+export async function validateAttestations(
   payload: ConsensusPayload,
   attestations: CommitteeAttestation[],
+  verbatimAttestations: ViemCommitteeAttestations,
   checkpointInfo: CheckpointInfo,
   epochCache: EpochCache,
   constants: Pick<L1RollupConstants, 'epochDuration'>,
@@ -137,6 +133,7 @@ async function validateAttestations(
     epoch,
     attestors,
     attestations,
+    verbatimAttestations,
   });
 
   for (let i = 0; i < attestorInfos.length; i++) {

package/src/store/block_store.ts

@@ -306,12 +306,18 @@ export class BlockStore {
 
   /**
    * 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: PublishedCheckpoint[], opts: { force?: boolean } = {}): Promise<boolean> {
+  async addCheckpoints(
+    checkpoints: PublishedCheckpoint[],
+    opts: { force?: boolean } = {},
+  ): Promise<PublishedCheckpoint[]> {
     if (checkpoints.length === 0) {
-      return true;
+      return [];
     }
 
     return await this.db.transactionAsync(async () => {
@@ -324,7 +330,7 @@ export class BlockStore {
       if (!opts.force && firstCheckpointNumber <= previousCheckpointNumber) {
         checkpoints = await this.skipOrUpdateAlreadyStoredCheckpoints(checkpoints, previousCheckpointNumber);
         if (checkpoints.length === 0) {
-          return true;
+          return [];
         }
         // Re-check sequentiality after skipping
         const newFirstNumber = checkpoints[0].checkpoint.number;
@@ -387,7 +393,7 @@ export class BlockStore {
       }
 
       await this.advanceSynchedL1BlockNumber(checkpoints[checkpoints.length - 1].l1.blockNumber);
-      return true;
+      return checkpoints;
     });
   }
 
@@ -621,6 +627,26 @@ export class BlockStore {
     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: SlotNumber, limit: number, reverse: boolean): Promise<CheckpointData[]> {
+    // 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: CheckpointData[] = [];
+    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: SlotNumber, endSlot: SlotNumber): Promise<CheckpointData[]> {
     const result: CheckpointData[] = [];

package/src/store/contract_class_store.ts

@@ -50,13 +50,19 @@ export class ContractClassStore {
   ): Promise<void> {
     await this.db.transactionAsync(async () => {
       const key = contractClass.id.toString();
-      if (await this.#contractClasses.hasAsync(key)) {
+      const existing = await this.#contractClasses.getAsync(key);
+      if (existing !== undefined) {
         // Protocol contracts are preloaded at block 0, so a later on-chain (re-)publish of a bundled
         // protocol class id is valid and must be a no-op. Keep the existing block-0 entry untouched
         // (do not bump its block number) so it survives reorgs of the publishing block.
         if (isProtocolContractClass(contractClass.id)) {
           return;
         }
+        // An L1 reorg can re-present an already-stored checkpoint, replaying this class at the same
+        // block; treat that as a no-op. A duplicate at a different block still signals double-processing.
+        if (deserializeContractClassPublic(existing).l2BlockNumber === blockNumber) {
+          return;
+        }
         throw new Error(`Contract class ${key} already exists, cannot add again at block ${blockNumber}`);
       }
       await this.#contractClasses.set(

package/src/store/contract_instance_store.ts

@@ -78,8 +78,14 @@ export class ContractInstanceStore {
         if (isProtocolContract(contractInstance.address)) {
           return;
         }
+        const existingBlockNumber = await this.#contractInstancePublishedAt.getAsync(key);
+        // An L1 reorg can re-present an already-stored checkpoint, replaying this instance at the same
+        // block; treat that as a no-op. A duplicate at a different block still signals double-processing.
+        if (existingBlockNumber === blockNumber) {
+          return;
+        }
         throw new Error(
-          `Contract instance at ${key} already exists (deployed at block ${await this.#contractInstancePublishedAt.getAsync(key)}), cannot add again at block ${blockNumber}`,
+          `Contract instance at ${key} already exists (deployed at block ${existingBlockNumber}), cannot add again at block ${blockNumber}`,
         );
       }
       await this.#contractInstances.set(key, new SerializableContractInstance(contractInstance).toBuffer());

package/src/test/fake_l1_state.ts

@@ -682,7 +682,7 @@ export class FakeL1State {
       getHashedSignaturePayloadTypedData(attestationsAndSigners),
     );
 
-    const packedAttestations = attestationsAndSigners.getPackedAttestations();
+    const verbatimAttestations = attestationsAndSigners.getPackedAttestations();
 
     const rollupInput = encodeFunctionData({
       abi: RollupAbi,
@@ -693,7 +693,7 @@ export class FakeL1State {
           archive,
           oracleInput: { feeAssetPriceModifier: 0n },
         },
-        packedAttestations,
+        verbatimAttestations,
         attestationsAndSigners.getSigners().map(signer => signer.toString()),
         attestationsAndSignersSignature.toViemSignature(),
         blobInput,
@@ -716,7 +716,7 @@ export class FakeL1State {
 
     // Compute attestationsHash (same logic as CalldataRetriever)
     const attestationsHash = Buffer32.fromString(
-      keccak256(encodeAbiParameters([this.getCommitteeAttestationsStructDef()], [packedAttestations])),
+      keccak256(encodeAbiParameters([this.getCommitteeAttestationsStructDef()], [verbatimAttestations])),
     );
 
     // Compute payloadDigest (same logic as CalldataRetriever)

package/src/test/mock_l2_block_source.ts

@@ -323,6 +323,13 @@ export class MockL2BlockSource implements L2BlockSource, ContractDataSource {
     if ('from' in query) {
       return this.checkpointList.slice(query.from - 1, query.from - 1 + query.limit);
     }
+    if ('fromSlot' in query) {
+      const matching = this.checkpointList.filter(c =>
+        query.reverse ? c.header.slotNumber <= query.fromSlot : c.header.slotNumber >= query.fromSlot,
+      );
+      const nearestFirst = query.reverse ? matching.reverse() : matching;
+      return nearestFirst.slice(0, query.limit);
+    }
     return this.getCheckpointsInEpoch(query.epoch);
   }
 

package/src/test/noop_l1_archiver.ts

@@ -7,7 +7,7 @@ import { Fr } from '@aztec/foundation/curves/bn254';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { DateProvider } from '@aztec/foundation/timer';
 import type { FunctionsOf } from '@aztec/foundation/types';
-import type { ArchiverEmitter, BlockHash } from '@aztec/stdlib/block';
+import type { ArchiverEmitter, BlockHash, L2Block } from '@aztec/stdlib/block';
 import type { L1RollupConstants } from '@aztec/stdlib/epoch-helpers';
 import type { BlockHeader } from '@aztec/stdlib/tx';
 import { type TelemetryClient, type Tracer, getTelemetryClient } from '@aztec/telemetry-client';
@@ -43,8 +43,8 @@ class NoopL1Synchronizer implements FunctionsOf<ArchiverL1Synchronizer> {
   testEthereumNodeSynced(): Promise<void> {
     return Promise.resolve();
   }
-  syncFromL1(_initialSyncComplete: boolean): Promise<void> {
-    return Promise.resolve();
+  syncFromL1(_initialSyncComplete: boolean): Promise<L2Block[]> {
+    return Promise.resolve([]);
   }
 }