@aztec/world-state 0.0.1-commit.d3ec352c → 0.0.1-commit.d58ff9d0

package/src/synchronizer/server_world_state_synchronizer.ts

@@ -1,17 +1,17 @@
-import { BlockNumber } from '@aztec/foundation/branded-types';
-import type { Fr } from '@aztec/foundation/fields';
+import { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import { promiseWithResolvers } from '@aztec/foundation/promise';
 import { elapsed } from '@aztec/foundation/timer';
-import type {
-  L2BlockId,
-  L2BlockNew,
-  L2BlockSource,
-  L2BlockStream,
-  L2BlockStreamEvent,
-  L2BlockStreamEventHandler,
-  L2BlockStreamLocalDataProvider,
-  L2Tips,
+import {
+  type BlockHash,
+  EventDrivenL2BlockStream,
+  type L2Block,
+  type L2BlockSource,
+  type L2BlockStreamEvent,
+  type L2BlockStreamEventHandler,
+  type L2BlockStreamLocalDataProvider,
+  type LocalChainTips,
 } from '@aztec/stdlib/block';
 import {
   WorldStateRunningState,
@@ -23,14 +23,13 @@ import type { L1ToL2MessageSource } from '@aztec/stdlib/messaging';
 import type { SnapshotDataKeys } from '@aztec/stdlib/snapshots';
 import type { L2BlockHandledStats } from '@aztec/stdlib/stats';
 import { MerkleTreeId, type MerkleTreeReadOperations, type MerkleTreeWriteOperations } from '@aztec/stdlib/trees';
-import { TraceableL2BlockStream, getTelemetryClient } from '@aztec/telemetry-client';
+import { getTelemetryClient } from '@aztec/telemetry-client';
 
 import { WorldStateInstrumentation } from '../instrumentation/instrumentation.js';
 import type { WorldStateStatusFull } from '../native/message.js';
 import type { MerkleTreeAdminDatabase } from '../world-state-db/merkle_tree_db.js';
 import type { WorldStateConfig } from './config.js';
 import { WorldStateSynchronizerError } from './errors.js';
-import { findFirstBlocksInCheckpoints } from './utils.js';
 
 export type { SnapshotDataKeys };
 
@@ -47,10 +46,9 @@ export class ServerWorldStateSynchronizer
   private latestBlockNumberAtStart = BlockNumber.ZERO;
   private historyToKeep: number | undefined;
   private currentState: WorldStateRunningState = WorldStateRunningState.IDLE;
-  private latestBlockHashQuery: { blockNumber: BlockNumber; hash: string | undefined } | undefined = undefined;
 
   private syncPromise = promiseWithResolvers<void>();
-  protected blockStream: L2BlockStream | undefined;
+  protected blockStream: EventDrivenL2BlockStream | undefined;
 
   // WorldState doesn't track the proven block number, it only tracks the latest tips of the pending chain and the finalized chain
   // store the proven block number here, in the synchronizer, so that we don't end up spamming the logs with 'chain-proved' events
@@ -64,7 +62,7 @@ export class ServerWorldStateSynchronizer
     private readonly log: Logger = createLogger('world_state'),
   ) {
     this.merkleTreeCommitted = this.merkleTreeDb.getCommitted();
-    this.historyToKeep = config.worldStateBlockHistory < 1 ? undefined : config.worldStateBlockHistory;
+    this.historyToKeep = config.worldStateCheckpointHistory < 1 ? undefined : config.worldStateCheckpointHistory;
     this.log.info(
       `Created world state synchroniser with block history of ${
         this.historyToKeep === undefined ? 'infinity' : this.historyToKeep
@@ -80,8 +78,48 @@ export class ServerWorldStateSynchronizer
     return this.merkleTreeDb.getSnapshot(blockNumber);
   }
 
-  public fork(blockNumber?: BlockNumber): Promise<MerkleTreeWriteOperations> {
-    return this.merkleTreeDb.fork(blockNumber);
+  public async getVerifiedSnapshot(blockNumber: BlockNumber, blockHash: BlockHash): Promise<MerkleTreeReadOperations> {
+    const snapshot = this.merkleTreeDb.getSnapshot(blockNumber);
+    // Block 0's snapshot is the pre-genesis archive view (size 0), so archive leaf 0 is not visible from it;
+    // verify against the initial header hash instead. For later blocks, read archive leaf `blockNumber` from the
+    // snapshot's own view so the exact handle we return is validated against the requested fork.
+    const actualHash =
+      blockNumber === BlockNumber.ZERO
+        ? (await this.merkleTreeCommitted.getInitialHeader().hash()).toString()
+        : (await snapshot.getLeafValue(MerkleTreeId.ARCHIVE, BigInt(blockNumber)))?.toString();
+
+    if (actualHash === undefined) {
+      // A missing archive leaf means either the block's history has been pruned away (permanent: the block predates
+      // the oldest historical block kept by world state) or a reorg flipped the fork between the sync and this read
+      // (transient). Only the latter is worth retrying, so it alone surfaces as WorldStateSynchronizerError.
+      const { oldestHistoricalBlock } = await this.merkleTreeDb.getStatusSummary();
+      if (blockNumber < oldestHistoricalBlock) {
+        throw new Error(
+          `Unable to find leaf for block ${blockNumber} in the archive tree: world state history has been pruned to block ${oldestHistoricalBlock}`,
+        );
+      }
+      throw new WorldStateSynchronizerError(`Unable to read block hash at block ${blockNumber} to verify snapshot`, {
+        cause: { reason: 'block_not_available', targetBlockNumber: blockNumber },
+      });
+    }
+    if (actualHash !== blockHash.toString()) {
+      throw new WorldStateSynchronizerError(
+        `Block hash mismatch at block ${blockNumber} (expected ${blockHash} but got ${actualHash})`,
+        {
+          cause: {
+            reason: 'block_hash_mismatch',
+            targetBlockNumber: blockNumber,
+            expectedHash: blockHash.toString(),
+            actualHash,
+          },
+        },
+      );
+    }
+    return snapshot;
+  }
+
+  public fork(blockNumber?: BlockNumber, opts?: { closeDelayMs?: number }): Promise<MerkleTreeWriteOperations> {
+    return this.merkleTreeDb.fork(blockNumber, opts);
   }
 
   public backupTo(dstPath: string, compact?: boolean): Promise<Record<Exclude<SnapshotDataKeys, 'archiver'>, string>> {
@@ -101,11 +139,7 @@ export class ServerWorldStateSynchronizer
     }
 
     // Get the current latest block number
-    this.latestBlockNumberAtStart = BlockNumber(
-      await (this.config.worldStateProvenBlocksOnly
-        ? this.l2BlockSource.getProvenBlockNumber()
-        : this.l2BlockSource.getBlockNumber()),
-    );
+    this.latestBlockNumberAtStart = BlockNumber(await this.l2BlockSource.getBlockNumber());
 
     const blockToDownloadFrom = (await this.getLatestBlockNumber()) + 1;
 
@@ -126,13 +160,12 @@ export class ServerWorldStateSynchronizer
     return this.syncPromise.promise;
   }
 
-  protected createBlockStream(): L2BlockStream {
-    const tracer = this.instrumentation.telemetry.getTracer('WorldStateL2BlockStream');
+  protected createBlockStream(): EventDrivenL2BlockStream {
     const logger = createLogger('world-state:block_stream');
-    return new TraceableL2BlockStream(this.l2BlockSource, this, this, tracer, 'WorldStateL2BlockStream', logger, {
-      proven: this.config.worldStateProvenBlocksOnly,
+    return new EventDrivenL2BlockStream(this.l2BlockSource, this, this, logger, {
       pollIntervalMS: this.config.worldStateBlockCheckIntervalMS,
       batchSize: this.config.worldStateBlockRequestBatchSize,
+      ignoreCheckpoints: true,
     });
   }
 
@@ -161,7 +194,7 @@ export class ServerWorldStateSynchronizer
   }
 
   public async getLatestBlockNumber() {
-    return (await this.getL2Tips()).latest.number;
+    return (await this.getL2Tips()).proposed.number;
   }
 
   public async stopSync() {
@@ -182,13 +215,10 @@ export class ServerWorldStateSynchronizer
   /**
    * Forces an immediate sync.
    * @param targetBlockNumber - The target block number that we must sync to. Will download unproven blocks if needed to reach it.
-   * @param skipThrowIfTargetNotReached - Whether to skip throwing if the target block number is not reached.
+   * @param blockHash - If provided, verifies the block at targetBlockNumber matches this hash. On mismatch, triggers a resync (reorg detection).
    * @returns A promise that resolves with the block number the world state was synced to
    */
-  public async syncImmediate(
-    targetBlockNumber?: BlockNumber,
-    skipThrowIfTargetNotReached?: boolean,
-  ): Promise<BlockNumber> {
+  public async syncImmediate(targetBlockNumber?: BlockNumber, blockHash?: BlockHash): Promise<BlockNumber> {
     if (this.currentState !== WorldStateRunningState.RUNNING) {
       throw new Error(`World State is not running. Unable to perform sync.`);
     }
@@ -200,7 +230,19 @@ export class ServerWorldStateSynchronizer
     // If we have been given a block number to sync to and we have reached that number then return
     const currentBlockNumber = await this.getLatestBlockNumber();
     if (targetBlockNumber !== undefined && targetBlockNumber <= currentBlockNumber) {
-      return currentBlockNumber;
+      if (blockHash === undefined) {
+        return currentBlockNumber;
+      }
+
+      // If a block hash was provided, verify we're on the expected fork
+      const currentHash = await this.getL2BlockHash(targetBlockNumber);
+      if (currentHash === blockHash.toString()) {
+        return currentBlockNumber;
+      }
+      // Hash mismatch: a reorg may have occurred, fall through to trigger sync
+      this.log.debug(
+        `World state block hash mismatch at ${targetBlockNumber} (expected ${blockHash}, got ${currentHash}). Triggering resync.`,
+      );
     }
     this.log.debug(`World State at ${currentBlockNumber} told to sync to ${targetBlockNumber ?? 'latest'}`);
 
@@ -218,7 +260,7 @@ export class ServerWorldStateSynchronizer
 
     // If we have been given a block number to sync to and we have not reached that number then fail
     const updatedBlockNumber = await this.getLatestBlockNumber();
-    if (!skipThrowIfTargetNotReached && targetBlockNumber !== undefined && targetBlockNumber > updatedBlockNumber) {
+    if (targetBlockNumber !== undefined && targetBlockNumber > updatedBlockNumber) {
       throw new WorldStateSynchronizerError(
         `Unable to sync to block number ${targetBlockNumber} (last synced is ${updatedBlockNumber})`,
         {
@@ -232,6 +274,24 @@ export class ServerWorldStateSynchronizer
       );
     }
 
+    // If a block hash was provided, verify we're on the expected fork after syncing, throw otherwise
+    if (blockHash !== undefined && targetBlockNumber !== undefined) {
+      const updatedHash = await this.getL2BlockHash(targetBlockNumber);
+      if (updatedHash !== blockHash.toString()) {
+        throw new WorldStateSynchronizerError(
+          `Block hash mismatch at block ${targetBlockNumber} (expected ${blockHash} but got ${updatedHash})`,
+          {
+            cause: {
+              reason: 'block_hash_mismatch',
+              targetBlockNumber,
+              expectedHash: blockHash.toString(),
+              actualHash: updatedHash,
+            },
+          },
+        );
+      }
+    }
+
     return updatedBlockNumber;
   }
 
@@ -240,27 +300,36 @@ export class ServerWorldStateSynchronizer
     if (number === BlockNumber.ZERO) {
       return (await this.merkleTreeCommitted.getInitialHeader().hash()).toString();
     }
-    if (this.latestBlockHashQuery?.hash === undefined || number !== this.latestBlockHashQuery.blockNumber) {
-      this.latestBlockHashQuery = {
-        hash: await this.merkleTreeCommitted
-          .getLeafValue(MerkleTreeId.ARCHIVE, BigInt(number))
-          .then(leaf => leaf?.toString()),
-        blockNumber: number,
-      };
-    }
-    return this.latestBlockHashQuery.hash;
+    return this.merkleTreeCommitted.getLeafValue(MerkleTreeId.ARCHIVE, BigInt(number)).then(leaf => leaf?.toString());
   }
 
-  /** Returns the latest L2 block number for each tip of the chain (latest, proven, finalized). */
-  public async getL2Tips(): Promise<L2Tips> {
+  /**
+   * Returns the proposed, proven, and finalized block tips of the chain. World state drives its block stream with
+   * `ignoreCheckpoints`, so it does not track checkpointed blocks or checkpoints and omits `checkpointed` from the tips
+   * it reports.
+   */
+  public async getL2Tips(): Promise<LocalChainTips> {
     const status = await this.merkleTreeDb.getStatusSummary();
-    const unfinalizedBlockHash = await this.getL2BlockHash(status.unfinalizedBlockNumber);
-    const latestBlockId: L2BlockId = { number: status.unfinalizedBlockNumber, hash: unfinalizedBlockHash! };
-
+    const unfinalizedBlockHashPromise = this.getL2BlockHash(status.unfinalizedBlockNumber);
+    const finalizedBlockHashPromise = this.getL2BlockHash(status.finalizedBlockNumber);
+
+    const provenBlockNumber = this.provenBlockNumber ?? status.finalizedBlockNumber;
+    const provenBlockHashPromise =
+      this.provenBlockNumber === undefined ? finalizedBlockHashPromise : this.getL2BlockHash(this.provenBlockNumber);
+
+    const [unfinalizedBlockHash, finalizedBlockHash, provenBlockHash] = await Promise.all([
+      unfinalizedBlockHashPromise,
+      finalizedBlockHashPromise,
+      provenBlockHashPromise,
+    ]);
     return {
-      latest: latestBlockId,
-      finalized: { number: status.finalizedBlockNumber, hash: '' },
-      proven: { number: this.provenBlockNumber ?? status.finalizedBlockNumber, hash: '' }, // TODO(palla/reorg): Using finalized as proven for now
+      proposed: { number: status.unfinalizedBlockNumber, hash: unfinalizedBlockHash },
+      finalized: {
+        block: { number: status.finalizedBlockNumber, hash: finalizedBlockHash },
+      },
+      proven: {
+        block: { number: provenBlockNumber, hash: provenBlockHash },
+      },
     };
   }
 
@@ -268,17 +337,26 @@ export class ServerWorldStateSynchronizer
   public async handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void> {
     switch (event.type) {
       case 'blocks-added':
-        await this.handleL2Blocks(event.blocks.map(b => b.block.toL2Block()));
+        await this.handleL2Blocks(event.blocks);
         break;
       case 'chain-pruned':
-        await this.handleChainPruned(BlockNumber(event.block.number));
+        await this.handleChainPruned(event.block.number);
         break;
       case 'chain-proven':
-        await this.handleChainProven(BlockNumber(event.block.number));
+        await this.handleChainProven(event.block.number);
         break;
       case 'chain-finalized':
-        await this.handleChainFinalized(BlockNumber(event.block.number));
+        await this.handleChainFinalized(event.block.number);
+        break;
+      // World state runs in block mode with ignoreCheckpoints: it tracks tips via blocks-added/pruned/proven/finalized
+      // and ignores the thin tip events (it never anchors on them).
+      case 'chain-proposed':
+      case 'chain-checkpointed':
         break;
+      default: {
+        const _: never = event;
+        break;
+      }
     }
   }
 
@@ -287,16 +365,25 @@ export class ServerWorldStateSynchronizer
    * @param l2Blocks - The L2 blocks to handle.
    * @returns Whether the block handled was produced by this same node.
    */
-  private async handleL2Blocks(l2Blocks: L2BlockNew[]) {
-    this.log.trace(`Handling L2 blocks ${l2Blocks[0].number} to ${l2Blocks.at(-1)!.number}`);
-
-    const firstBlocksInCheckpoints = await findFirstBlocksInCheckpoints(l2Blocks, this.l2BlockSource);
+  private async handleL2Blocks(l2Blocks: L2Block[]) {
+    this.log.debug(`Handling L2 blocks ${l2Blocks[0].number} to ${l2Blocks.at(-1)!.number}`);
+
+    // Fetch the L1->L2 messages for the first block in a checkpoint.
+    const messagesForBlocks = new Map<BlockNumber, Fr[]>();
+    await Promise.all(
+      l2Blocks
+        .filter(b => b.indexWithinCheckpoint === 0)
+        .map(async block => {
+          const l1ToL2Messages = await this.l2BlockSource.getL1ToL2Messages(block.checkpointNumber);
+          messagesForBlocks.set(block.number, l1ToL2Messages);
+        }),
+    );
 
     let updateStatus: WorldStateStatusFull | undefined = undefined;
     for (const block of l2Blocks) {
-      const l1ToL2Messages = firstBlocksInCheckpoints.get(block.number) ?? [];
-      const isFirstBlock = firstBlocksInCheckpoints.has(block.number);
-      const [duration, result] = await elapsed(() => this.handleL2Block(block, l1ToL2Messages, isFirstBlock));
+      const [duration, result] = await elapsed(() =>
+        this.handleL2Block(block, messagesForBlocks.get(block.number) ?? []),
+      );
       this.log.info(`World state updated with L2 block ${block.number}`, {
         eventName: 'l2-block-handled',
         duration,
@@ -319,18 +406,15 @@ export class ServerWorldStateSynchronizer
    * @param l1ToL2Messages - The L1 to L2 messages for the block.
    * @returns Whether the block handled was produced by this same node.
    */
-  private async handleL2Block(
-    l2Block: L2BlockNew,
-    l1ToL2Messages: Fr[],
-    isFirstBlock: boolean,
-  ): Promise<WorldStateStatusFull> {
-    // If the above check succeeds, we can proceed to handle the block.
-    this.log.trace(`Pushing L2 block ${l2Block.number} to merkle tree db `, {
+  private async handleL2Block(l2Block: L2Block, l1ToL2Messages: Fr[]): Promise<WorldStateStatusFull> {
+    this.log.debug(`Pushing L2 block ${l2Block.number} to merkle tree db `, {
       blockNumber: l2Block.number,
       blockHash: await l2Block.hash().then(h => h.toString()),
       l1ToL2Messages: l1ToL2Messages.map(msg => msg.toString()),
+      blockHeader: l2Block.header.toInspect(),
+      blockStats: l2Block.getStats(),
     });
-    const result = await this.merkleTreeDb.handleL2BlockAndMessages(l2Block, l1ToL2Messages, isFirstBlock);
+    const result = await this.merkleTreeDb.handleL2BlockAndMessages(l2Block, l1ToL2Messages);
 
     if (this.currentState === WorldStateRunningState.SYNCHING && l2Block.number >= this.latestBlockNumberAtStart) {
       this.setCurrentState(WorldStateRunningState.RUNNING);
@@ -342,16 +426,56 @@ export class ServerWorldStateSynchronizer
 
   private async handleChainFinalized(blockNumber: BlockNumber) {
     this.log.verbose(`Finalized chain is now at block ${blockNumber}`);
+    // If the finalized block number is older than the oldest available block in world state,
+    // skip entirely. The finalized block number can jump backwards (e.g. when the finalization
+    // heuristic changes) and try to read block data that has already been pruned. When this
+    // happens, there is nothing useful to do — the native world state is already finalized
+    // past this point and pruning has already happened.
+    const currentSummary = await this.merkleTreeDb.getStatusSummary();
+    if (blockNumber < currentSummary.oldestHistoricalBlock || blockNumber < 1) {
+      this.log.trace(
+        `Finalized block ${blockNumber} is older than the oldest available block ${currentSummary.oldestHistoricalBlock}. Skipping.`,
+      );
+      return;
+    }
     const summary = await this.merkleTreeDb.setFinalized(blockNumber);
     if (this.historyToKeep === undefined) {
       return;
     }
-    const newHistoricBlock = BlockNumber(summary.finalizedBlockNumber - this.historyToKeep + 1);
-    if (newHistoricBlock <= BlockNumber(1)) {
+    const finalisedBlockData = await this.l2BlockSource.getBlockData({ number: summary.finalizedBlockNumber });
+    if (finalisedBlockData === undefined) {
+      this.log.warn(
+        `Failed to retrieve checkpointed block for finalized block number: ${summary.finalizedBlockNumber}`,
+      );
       return;
     }
-    this.log.verbose(`Pruning historic blocks to ${newHistoricBlock}`);
-    const status = await this.merkleTreeDb.removeHistoricalBlocks(newHistoricBlock);
+    // Compute the required historic checkpoint number
+    const newHistoricCheckpointNumber = finalisedBlockData.checkpointNumber - this.historyToKeep + 1;
+    if (newHistoricCheckpointNumber <= 1) {
+      return;
+    }
+    // Retrieve the historic checkpoint
+    const historicCheckpoint = await this.l2BlockSource.getCheckpoint({
+      number: CheckpointNumber(newHistoricCheckpointNumber),
+    });
+    if (!historicCheckpoint) {
+      this.log.warn(`Failed to retrieve checkpoint number ${newHistoricCheckpointNumber} from Archiver`);
+      return;
+    }
+    if (historicCheckpoint.checkpoint.blocks.length === 0 || historicCheckpoint.checkpoint.blocks[0] === undefined) {
+      this.log.warn(`Retrieved checkpoint number ${newHistoricCheckpointNumber} has no blocks!`);
+      return;
+    }
+    // Find the block at the start of the checkpoint and remove blocks up to this one
+    const newHistoricBlock = historicCheckpoint.checkpoint.blocks[0];
+    if (newHistoricBlock.number <= currentSummary.oldestHistoricalBlock) {
+      this.log.debug(
+        `Historic block ${newHistoricBlock.number} is not newer than oldest available ${currentSummary.oldestHistoricalBlock}. Skipping prune.`,
+      );
+      return;
+    }
+    this.log.verbose(`Pruning historic blocks to ${newHistoricBlock.number}`);
+    const status = await this.merkleTreeDb.removeHistoricalBlocks(BlockNumber(newHistoricBlock.number));
     this.log.debug(`World state summary `, status.summary);
   }
 
@@ -362,10 +486,11 @@ export class ServerWorldStateSynchronizer
   }
 
   private async handleChainPruned(blockNumber: BlockNumber) {
-    this.log.warn(`Chain pruned to block ${blockNumber}`);
+    this.log.info(`Chain pruned to block ${blockNumber}`);
     const status = await this.merkleTreeDb.unwindBlocks(blockNumber);
-    this.latestBlockHashQuery = undefined;
-    this.provenBlockNumber = undefined;
+    if (this.provenBlockNumber !== undefined && this.provenBlockNumber > blockNumber) {
+      this.provenBlockNumber = undefined;
+    }
     this.instrumentation.updateWorldStateMetrics(status);
   }