@aztec/stdlib 0.0.0-test.1 → 0.0.1-commit.5476d83

package/src/block/l2_block_new.ts

@@ -0,0 +1,171 @@
+import { type BlockBlobData, encodeBlockBlobData } from '@aztec/blob-lib/encoding';
+import { Fr } from '@aztec/foundation/fields';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+
+import { z } from 'zod';
+
+import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+import { BlockHeader } from '../tx/block_header.js';
+import { Body } from './body.js';
+import type { L2BlockInfo } from './l2_block_info.js';
+
+/**
+ * An L2 block with a header and a body.
+ * TODO: Delete the existing `L2Block` class and rename this to `L2Block`.
+ */
+export class L2BlockNew {
+  constructor(
+    /** Snapshot of archive tree after the block is applied. */
+    public archive: AppendOnlyTreeSnapshot,
+    /** Header of the block. */
+    public header: BlockHeader,
+    /** L2 block body. */
+    public body: Body,
+    private blockHash: Fr | undefined = undefined,
+  ) {}
+
+  get number(): number {
+    return this.header.globalVariables.blockNumber;
+  }
+
+  get timestamp(): bigint {
+    return this.header.globalVariables.timestamp;
+  }
+
+  static get schema() {
+    return z
+      .object({
+        archive: AppendOnlyTreeSnapshot.schema,
+        header: BlockHeader.schema,
+        body: Body.schema,
+      })
+      .transform(({ archive, header, body }) => new L2BlockNew(archive, header, body));
+  }
+
+  /**
+   * Deserializes a block from a buffer
+   * @returns A deserialized L2 block.
+   */
+  static fromBuffer(buf: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buf);
+    const header = reader.readObject(BlockHeader);
+    const archive = reader.readObject(AppendOnlyTreeSnapshot);
+    const body = reader.readObject(Body);
+
+    return new L2BlockNew(archive, header, body);
+  }
+
+  /**
+   * Serializes a block
+   * @returns A serialized L2 block as a Buffer.
+   */
+  toBuffer() {
+    return serializeToBuffer(this.header, this.archive, this.body);
+  }
+
+  /**
+   * Returns the block's hash (hash of block header).
+   * @returns The block's hash.
+   */
+  public async hash(): Promise<Fr> {
+    if (this.blockHash === undefined) {
+      this.blockHash = await this.header.hash();
+    }
+    return this.blockHash;
+  }
+
+  public toBlobFields(isFirstBlock: boolean): Fr[] {
+    const blockBlobData = this.toBlockBlobData(isFirstBlock);
+    return encodeBlockBlobData(blockBlobData);
+  }
+
+  public toBlockBlobData(isFirstBlock: boolean): BlockBlobData {
+    return {
+      blockEndMarker: {
+        numTxs: this.body.txEffects.length,
+        timestamp: this.header.globalVariables.timestamp,
+        blockNumber: this.number,
+      },
+      blockEndStateField: {
+        l1ToL2MessageNextAvailableLeafIndex: this.header.state.l1ToL2MessageTree.nextAvailableLeafIndex,
+        noteHashNextAvailableLeafIndex: this.header.state.partial.noteHashTree.nextAvailableLeafIndex,
+        nullifierNextAvailableLeafIndex: this.header.state.partial.nullifierTree.nextAvailableLeafIndex,
+        publicDataNextAvailableLeafIndex: this.header.state.partial.publicDataTree.nextAvailableLeafIndex,
+        totalManaUsed: this.header.totalManaUsed.toBigInt(),
+      },
+      lastArchiveRoot: this.header.lastArchive.root,
+      noteHashRoot: this.header.state.partial.noteHashTree.root,
+      nullifierRoot: this.header.state.partial.nullifierTree.root,
+      publicDataRoot: this.header.state.partial.publicDataTree.root,
+      l1ToL2MessageRoot: isFirstBlock ? this.header.state.l1ToL2MessageTree.root : undefined,
+      txs: this.body.toTxBlobData(),
+    };
+  }
+
+  /**
+   * Creates an L2 block containing random data.
+   * @param l2BlockNum - The number of the L2 block.
+   * @param txsPerBlock - The number of transactions to include in the block.
+   * @param numPublicCallsPerTx - The number of public function calls to include in each transaction.
+   * @param numPublicLogsPerCall - The number of public logs per 1 public function invocation.
+   * @param inHash - The hash of the L1 to L2 messages subtree which got inserted in this block.
+   * @returns The L2 block.
+   */
+  static async random(
+    blockNumber: number,
+    {
+      txsPerBlock = 1,
+      txOptions = {},
+      makeTxOptions,
+      ...blockHeaderOverrides
+    }: {
+      txsPerBlock?: number;
+      txOptions?: Partial<Parameters<typeof Body.random>[0]>;
+      makeTxOptions?: (txIndex: number) => Partial<Parameters<typeof Body.random>[0]>;
+    } & Partial<Parameters<typeof BlockHeader.random>[0]> = {},
+  ): Promise<L2BlockNew> {
+    const archive = new AppendOnlyTreeSnapshot(Fr.random(), blockNumber + 1);
+    const header = BlockHeader.random({ blockNumber, ...blockHeaderOverrides });
+    const body = await Body.random({ txsPerBlock, makeTxOptions, ...txOptions });
+    return new L2BlockNew(archive, header, body);
+  }
+
+  /**
+   * Returns stats used for logging.
+   * @returns Stats on tx count, number, and log size and count.
+   */
+  getStats() {
+    const logsStats = {
+      privateLogCount: this.body.txEffects.reduce((logCount, txEffect) => logCount + txEffect.privateLogs.length, 0),
+      publicLogCount: this.body.txEffects.reduce((logCount, txEffect) => logCount + txEffect.publicLogs.length, 0),
+      contractClassLogCount: this.body.txEffects.reduce(
+        (logCount, txEffect) => logCount + txEffect.contractClassLogs.length,
+        0,
+      ),
+      contractClassLogSize: this.body.txEffects.reduce(
+        (totalLogSize, txEffect) =>
+          totalLogSize + txEffect.contractClassLogs.reduce((acc, log) => acc + log.emittedLength, 0),
+        0,
+      ),
+    };
+
+    return {
+      txCount: this.body.txEffects.length,
+      blockNumber: this.number,
+      blockTimestamp: Number(this.header.globalVariables.timestamp),
+      ...logsStats,
+    };
+  }
+
+  toBlockInfo(): L2BlockInfo {
+    return {
+      blockHash: this.blockHash,
+      archive: this.archive.root,
+      lastArchive: this.header.lastArchive.root,
+      blockNumber: this.number,
+      slotNumber: Number(this.header.getSlot()),
+      txCount: this.body.txEffects.length,
+      timestamp: this.header.globalVariables.timestamp,
+    };
+  }
+}

package/src/block/l2_block_source.ts

@@ -1,15 +1,18 @@
+import type { EpochNumber, SlotNumber } from '@aztec/foundation/branded-types';
 import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { Fr } from '@aztec/foundation/fields';
+import type { TypedEventEmitter } from '@aztec/foundation/types';
 
-import type { EventEmitter } from 'events';
 import { z } from 'zod';
 
 import type { L1RollupConstants } from '../epoch-helpers/index.js';
 import type { BlockHeader } from '../tx/block_header.js';
-import type { TxEffect } from '../tx/tx_effect.js';
+import type { IndexedTxEffect } from '../tx/indexed_tx_effect.js';
 import type { TxHash } from '../tx/tx_hash.js';
 import type { TxReceipt } from '../tx/tx_receipt.js';
-import type { InBlock } from './in_block.js';
 import type { L2Block } from './l2_block.js';
+import { PublishedL2Block } from './published_l2_block.js';
+import type { ValidateBlockNegativeResult, ValidateBlockResult } from './validate_block_result.js';
 
 /**
  * Interface of classes allowing for the retrieval of L2 blocks.
@@ -62,12 +65,43 @@ export interface L2BlockSource {
    */
   getBlocks(from: number, limit: number, proven?: boolean): Promise<L2Block[]>;
 
+  /** Equivalent to getBlocks but includes publish data. */
+  getPublishedBlocks(from: number, limit: number, proven?: boolean): Promise<PublishedL2Block[]>;
+
+  /**
+   * Gets a published block by its hash.
+   * @param blockHash - The block hash to retrieve.
+   * @returns The requested published block (or undefined if not found).
+   */
+  getPublishedBlockByHash(blockHash: Fr): Promise<PublishedL2Block | undefined>;
+
+  /**
+   * Gets a published block by its archive root.
+   * @param archive - The archive root to retrieve.
+   * @returns The requested published block (or undefined if not found).
+   */
+  getPublishedBlockByArchive(archive: Fr): Promise<PublishedL2Block | undefined>;
+
+  /**
+   * Gets a block header by its hash.
+   * @param blockHash - The block hash to retrieve.
+   * @returns The requested block header (or undefined if not found).
+   */
+  getBlockHeaderByHash(blockHash: Fr): Promise<BlockHeader | undefined>;
+
+  /**
+   * Gets a block header by its archive root.
+   * @param archive - The archive root to retrieve.
+   * @returns The requested block header (or undefined if not found).
+   */
+  getBlockHeaderByArchive(archive: Fr): Promise<BlockHeader | undefined>;
+
   /**
    * Gets a tx effect.
-   * @param txHash - The hash of a transaction which resulted in the returned tx effect.
-   * @returns The requested tx effect.
+   * @param txHash - The hash of the tx corresponding to the tx effect.
+   * @returns The requested tx effect with block info (or undefined if not found).
    */
-  getTxEffect(txHash: TxHash): Promise<InBlock<TxEffect> | undefined>;
+  getTxEffect(txHash: TxHash): Promise<IndexedTxEffect | undefined>;
 
   /**
    * Gets a receipt of a settled tx.
@@ -77,27 +111,34 @@ export interface L2BlockSource {
   getSettledTxReceipt(txHash: TxHash): Promise<TxReceipt | undefined>;
 
   /**
-   * Returns the current L2 slot number based on the current L1 timestamp.
+   * Returns the current L2 slot number based on the currently synced L1 timestamp.
    */
-  getL2SlotNumber(): Promise<bigint>;
+  getL2SlotNumber(): Promise<SlotNumber | undefined>;
 
   /**
-   * Returns the current L2 epoch number based on the current L1 timestamp.
+   * Returns the current L2 epoch number based on the currently synced L1 timestamp.
    */
-  getL2EpochNumber(): Promise<bigint>;
+  getL2EpochNumber(): Promise<EpochNumber | undefined>;
 
   /**
    * Returns all blocks for a given epoch.
    * @dev Use this method only with recent epochs, since it walks the block list backwards.
    * @param epochNumber - The epoch number to return blocks for.
    */
-  getBlocksForEpoch(epochNumber: bigint): Promise<L2Block[]>;
+  getBlocksForEpoch(epochNumber: EpochNumber): Promise<L2Block[]>;
+
+  /**
+   * Returns all block headers for a given epoch.
+   * @dev Use this method only with recent epochs, since it walks the block list backwards.
+   * @param epochNumber - The epoch number to return headers for.
+   */
+  getBlockHeadersForEpoch(epochNumber: EpochNumber): Promise<BlockHeader[]>;
 
   /**
    * Returns whether the given epoch is completed on L1, based on the current L1 and L2 block numbers.
    * @param epochNumber - The epoch number to check.
    */
-  isEpochComplete(epochNumber: bigint): Promise<boolean>;
+  isEpochComplete(epochNumber: EpochNumber): Promise<boolean>;
 
   /**
    * Returns the tips of the L2 chain.
@@ -108,13 +149,39 @@ export interface L2BlockSource {
    * Returns the rollup constants for the current chain.
    */
   getL1Constants(): Promise<L1RollupConstants>;
+
+  /** Returns values for the genesis block */
+  getGenesisValues(): Promise<{ genesisArchiveRoot: Fr }>;
+
+  /** Latest synced L1 timestamp. */
+  getL1Timestamp(): Promise<bigint | undefined>;
+
+  /**
+   * Returns whether the latest block in the pending chain on L1 is invalid (ie its attestations are incorrect).
+   * Note that invalid blocks do not get synced, so the latest block returned by the block source is always a valid one.
+   */
+  isPendingChainInvalid(): Promise<boolean>;
+
+  /**
+   * Returns the status of the pending chain validation. If the chain is invalid, reports the earliest consecutive block
+   * that is invalid, along with the reason for being invalid, which can be used to trigger an invalidation.
+   */
+  getPendingChainValidationStatus(): Promise<ValidateBlockResult>;
+
+  /** Force a sync. */
+  syncImmediate(): Promise<void>;
 }
 
 /**
  * L2BlockSource that emits events upon pending / proven chain changes.
  * see L2BlockSourceEvents for the events emitted.
  */
-export interface L2BlockSourceEventEmitter extends L2BlockSource, EventEmitter {}
+export type ArchiverEmitter = TypedEventEmitter<{
+  [L2BlockSourceEvents.L2PruneDetected]: (args: L2BlockPruneEvent) => void;
+  [L2BlockSourceEvents.L2BlockProven]: (args: L2BlockProvenEvent) => void;
+  [L2BlockSourceEvents.InvalidAttestationsBlockDetected]: (args: InvalidBlockDetectedEvent) => void;
+}>;
+export interface L2BlockSourceEventEmitter extends L2BlockSource, ArchiverEmitter {}
 
 /**
  * Identifier for L2 block tags.
@@ -130,6 +197,14 @@ export type L2Tips = Record<L2BlockTag, L2BlockId>;
 /** Identifies a block by number and hash. */
 export type L2BlockId = z.infer<typeof L2BlockIdSchema>;
 
+/** Creates an L2 block id */
+export function makeL2BlockId(number: number, hash?: string): L2BlockId {
+  if (number !== 0 && !hash) {
+    throw new Error(`Hash is required for non-genesis blocks (got block number ${number})`);
+  }
+  return { number, hash: hash! };
+}
+
 // TODO(palla/schemas): This package should know what is the block hash of the genesis block 0.
 const L2BlockIdSchema = z.union([
   z.object({
@@ -150,11 +225,24 @@ export const L2TipsSchema = z.object({
 
 export enum L2BlockSourceEvents {
   L2PruneDetected = 'l2PruneDetected',
+  L2BlockProven = 'l2BlockProven',
+  InvalidAttestationsBlockDetected = 'invalidBlockDetected',
 }
 
-export type L2BlockSourceEvent = {
-  type: 'l2PruneDetected';
+export type L2BlockProvenEvent = {
+  type: 'l2BlockProven';
   blockNumber: bigint;
-  slotNumber: bigint;
-  epochNumber: bigint;
+  slotNumber: SlotNumber;
+  epochNumber: EpochNumber;
+};
+
+export type L2BlockPruneEvent = {
+  type: 'l2PruneDetected';
+  epochNumber: EpochNumber;
+  blocks: L2Block[];
+};
+
+export type InvalidBlockDetectedEvent = {
+  type: 'invalidBlockDetected';
+  validationResult: ValidateBlockNegativeResult;
 };

package/src/block/l2_block_stream/index.ts

@@ -0,0 +1,3 @@
+export * from './interfaces.js';
+export * from './l2_block_stream.js';
+export * from './l2_tips_memory_store.js';

package/src/block/l2_block_stream/interfaces.ts

@@ -0,0 +1,33 @@
+import type { L2BlockId, L2Tips } from '../l2_block_source.js';
+import type { PublishedL2Block } from '../published_l2_block.js';
+
+/** Interface to the local view of the chain. Implemented by world-state and l2-tips-store. */
+export interface L2BlockStreamLocalDataProvider {
+  getL2BlockHash(number: number): Promise<string | undefined>;
+  getL2Tips(): Promise<L2Tips>;
+}
+
+/** Interface to a handler of events emitted. */
+export interface L2BlockStreamEventHandler {
+  handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void>;
+}
+
+export type L2BlockStreamEvent =
+  | /** Emits blocks added to the chain. */ {
+      type: 'blocks-added';
+      blocks: PublishedL2Block[];
+    }
+  | /** Reports last correct block (new tip of the unproven chain). */ {
+      type: 'chain-pruned';
+      block: L2BlockId;
+    }
+  | /** Reports new proven block. */ {
+      type: 'chain-proven';
+      block: L2BlockId;
+    }
+  | /** Reports new finalized block (proven and finalized on L1). */ {
+      type: 'chain-finalized';
+      block: L2BlockId;
+    };
+
+export type L2TipsStore = L2BlockStreamEventHandler & L2BlockStreamLocalDataProvider;

package/src/block/{l2_block_downloader → l2_block_stream}/l2_block_stream.ts

@@ -2,16 +2,17 @@ import { AbortError } from '@aztec/foundation/error';
 import { createLogger } from '@aztec/foundation/log';
 import { RunningPromise } from '@aztec/foundation/running-promise';
 
-import type { L2Block } from '../l2_block.js';
-import type { L2BlockId, L2BlockSource, L2Tips } from '../l2_block_source.js';
+import { type L2BlockId, type L2BlockSource, makeL2BlockId } from '../l2_block_source.js';
+import type { L2BlockStreamEvent, L2BlockStreamEventHandler, L2BlockStreamLocalDataProvider } from './interfaces.js';
 
 /** Creates a stream of events for new blocks, chain tips updates, and reorgs, out of polling an archiver or a node. */
 export class L2BlockStream {
   private readonly runningPromise: RunningPromise;
   private isSyncing = false;
+  private hasStarted = false;
 
   constructor(
-    private l2BlockSource: Pick<L2BlockSource, 'getBlocks' | 'getBlockHeader' | 'getL2Tips'>,
+    private l2BlockSource: Pick<L2BlockSource, 'getPublishedBlocks' | 'getBlockHeader' | 'getL2Tips'>,
     private localData: L2BlockStreamLocalDataProvider,
     private handler: L2BlockStreamEventHandler,
     private readonly log = createLogger('types:block_stream'),
@@ -20,6 +21,8 @@ export class L2BlockStream {
       pollIntervalMS?: number;
       batchSize?: number;
       startingBlock?: number;
+      /** Instead of downloading all blocks, only fetch the smallest subset that results in reliable reorg detection. */
+      skipFinalized?: boolean;
     } = {},
   ) {
     this.runningPromise = new RunningPromise(() => this.work(), log, this.opts.pollIntervalMS ?? 1000);
@@ -65,41 +68,63 @@ export class L2BlockStream {
 
       // Check if there was a reorg and emit a chain-pruned event if so.
       let latestBlockNumber = localTips.latest.number;
-      while (!(await this.areBlockHashesEqualAt(latestBlockNumber, { sourceCache: [sourceTips.latest] }))) {
+      const sourceCache = new BlockHashCache([sourceTips.latest]);
+      while (!(await this.areBlockHashesEqualAt(latestBlockNumber, { sourceCache }))) {
         latestBlockNumber--;
       }
+
       if (latestBlockNumber < localTips.latest.number) {
+        latestBlockNumber = Math.min(latestBlockNumber, sourceTips.latest.number); // see #13471
+        const hash = sourceCache.get(latestBlockNumber) ?? (await this.getBlockHashFromSource(latestBlockNumber));
+        if (latestBlockNumber !== 0 && !hash) {
+          throw new Error(`Block hash not found in block source for block number ${latestBlockNumber}`);
+        }
         this.log.verbose(`Reorg detected. Pruning blocks from ${latestBlockNumber + 1} to ${localTips.latest.number}.`);
-        await this.emitEvent({ type: 'chain-pruned', blockNumber: latestBlockNumber });
+        await this.emitEvent({ type: 'chain-pruned', block: makeL2BlockId(latestBlockNumber, hash) });
       }
 
       // If we are just starting, use the starting block number from the options.
       if (latestBlockNumber === 0 && this.opts.startingBlock !== undefined) {
         latestBlockNumber = Math.max(this.opts.startingBlock - 1, 0);
+      }
+
+      // Only log this entry once (for sanity)
+      if (!this.hasStarted) {
         this.log.verbose(`Starting sync from block number ${latestBlockNumber}`);
+        this.hasStarted = true;
+      }
+
+      let nextBlockNumber = latestBlockNumber + 1;
+      if (this.opts.skipFinalized) {
+        // When skipping finalized blocks we need to provide reliable reorg detection while fetching as few blocks as
+        // possible. Finalized blocks cannot be reorged by definition, so we can skip most of them. We do need the very
+        // last finalized block however in order to guarantee that we will eventually find a block in which our local
+        // store matches the source.
+        // If the last finalized block is behind our local tip, there is nothing to skip.
+        nextBlockNumber = Math.max(sourceTips.finalized.number, nextBlockNumber);
       }
 
       // Request new blocks from the source.
-      while (latestBlockNumber < sourceTips.latest.number) {
-        const from = latestBlockNumber + 1;
-        const limit = Math.min(this.opts.batchSize ?? 20, sourceTips.latest.number - from + 1);
-        this.log.trace(`Requesting blocks from ${from} limit ${limit} proven=${this.opts.proven}`);
-        const blocks = await this.l2BlockSource.getBlocks(from, limit, this.opts.proven);
+      while (nextBlockNumber <= sourceTips.latest.number) {
+        const limit = Math.min(this.opts.batchSize ?? 50, sourceTips.latest.number - nextBlockNumber + 1);
+        this.log.trace(`Requesting blocks from ${nextBlockNumber} limit ${limit} proven=${this.opts.proven}`);
+        const blocks = await this.l2BlockSource.getPublishedBlocks(nextBlockNumber, limit, this.opts.proven);
         if (blocks.length === 0) {
           break;
         }
         await this.emitEvent({ type: 'blocks-added', blocks });
-        latestBlockNumber = blocks.at(-1)!.number;
+        nextBlockNumber = blocks.at(-1)!.block.number + 1;
       }
 
       // Update the proven and finalized tips.
-      // TODO(palla/reorg): Should we emit this before passing the new blocks? This would allow world-state to skip
-      // building the data structures for the pending chain if it's unneeded.
       if (localTips.proven !== undefined && sourceTips.proven.number !== localTips.proven.number) {
-        await this.emitEvent({ type: 'chain-proven', blockNumber: sourceTips.proven.number });
+        await this.emitEvent({
+          type: 'chain-proven',
+          block: sourceTips.proven,
+        });
       }
       if (localTips.finalized !== undefined && sourceTips.finalized.number !== localTips.finalized.number) {
-        await this.emitEvent({ type: 'chain-finalized', blockNumber: sourceTips.finalized.number });
+        await this.emitEvent({ type: 'chain-finalized', block: sourceTips.finalized });
       }
     } catch (err: any) {
       if (err.name === 'AbortError') {
@@ -114,29 +139,40 @@ export class L2BlockStream {
    * @param blockNumber - The block number to test.
    * @param args - A cache of data already requested from source, to avoid re-requesting it.
    */
-  private async areBlockHashesEqualAt(blockNumber: number, args: { sourceCache: L2BlockId[] }) {
+  private async areBlockHashesEqualAt(blockNumber: number, args: { sourceCache: BlockHashCache }) {
     if (blockNumber === 0) {
       return true;
     }
     const localBlockHash = await this.localData.getL2BlockHash(blockNumber);
-    const sourceBlockHash =
-      args.sourceCache.find(id => id.number === blockNumber && id.hash)?.hash ??
-      (await this.l2BlockSource
-        .getBlockHeader(blockNumber)
-        .then(h => h?.hash())
-        .then(hash => hash?.toString()));
-    this.log.trace(`Comparing block hashes for block ${blockNumber}`, {
-      localBlockHash,
-      sourceBlockHash,
-      sourceCacheNumber: args.sourceCache[0]?.number,
-      sourceCacheHash: args.sourceCache[0]?.hash,
-    });
+    if (!localBlockHash && this.opts.skipFinalized) {
+      // Failing to find a block hash when skipping finalized blocks can be highly problematic as we'd potentially need
+      // to go all the way back to the genesis block to find a block in which we agree with the source (since we've
+      // potentially skipped all history). This means that stores that prune old blocks must be careful to leave no gaps
+      // when going back from latest block to the last finalized one.
+      this.log.error(`No local block hash for block number ${blockNumber}`);
+      throw new AbortError();
+    }
+
+    const sourceBlockHashFromCache = args.sourceCache.get(blockNumber);
+    const sourceBlockHash = args.sourceCache.get(blockNumber) ?? (await this.getBlockHashFromSource(blockNumber));
+    if (!sourceBlockHashFromCache && sourceBlockHash) {
+      args.sourceCache.add({ number: blockNumber, hash: sourceBlockHash });
+    }
+
+    this.log.trace(`Comparing block hashes for block ${blockNumber}`, { localBlockHash, sourceBlockHash });
     return localBlockHash === sourceBlockHash;
   }
 
+  private getBlockHashFromSource(blockNumber: number) {
+    return this.l2BlockSource
+      .getBlockHeader(blockNumber)
+      .then(h => h?.hash())
+      .then(hash => hash?.toString());
+  }
+
   private async emitEvent(event: L2BlockStreamEvent) {
     this.log.debug(
-      `Emitting ${event.type} (${event.type === 'blocks-added' ? event.blocks.length : event.blockNumber})`,
+      `Emitting ${event.type} (${event.type === 'blocks-added' ? event.blocks.length : event.block.number})`,
     );
     await this.handler.handleBlockStreamEvent(event);
     if (!this.isRunning() && !this.isSyncing) {
@@ -145,35 +181,22 @@ export class L2BlockStream {
   }
 }
 
-/** Interface to the local view of the chain. Implemented by world-state and l2-tips-store. */
-export interface L2BlockStreamLocalDataProvider {
-  getL2BlockHash(number: number): Promise<string | undefined>;
-  getL2Tips(): Promise<L2Tips>;
-}
-
-/** Interface to a handler of events emitted. */
-export interface L2BlockStreamEventHandler {
-  handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void>;
-}
+class BlockHashCache {
+  private readonly cache: Map<number, string> = new Map();
 
-export type L2BlockStreamEvent =
-  | {
-      type: 'blocks-added';
-      /** New blocks added to the chain. */
-      blocks: L2Block[];
-    }
-  | {
-      type: 'chain-pruned';
-      /** Last correct block number (new tip of the unproven chain). */
-      blockNumber: number;
+  constructor(initial: L2BlockId[] = []) {
+    for (const block of initial) {
+      this.add(block);
     }
-  | {
-      type: 'chain-proven';
-      /** New proven block number */
-      blockNumber: number;
+  }
+
+  public add(block: L2BlockId) {
+    if (block.hash) {
+      this.cache.set(block.number, block.hash);
     }
-  | {
-      type: 'chain-finalized';
-      /** New finalized block number */
-      blockNumber: number;
-    };
+  }
+
+  public get(blockNumber: number) {
+    return this.cache.get(blockNumber);
+  }
+}