@aztec/stdlib 0.0.0-test.0 → 0.0.1-commit.03f7ef2

package/src/block/l2_block_source.ts

@@ -1,15 +1,27 @@
+import {
+  BlockNumber,
+  BlockNumberSchema,
+  CheckpointNumber,
+  type EpochNumber,
+  type SlotNumber,
+} from '@aztec/foundation/branded-types';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { TypedEventEmitter } from '@aztec/foundation/types';
 
-import type { EventEmitter } from 'events';
 import { z } from 'zod';
 
+import type { Checkpoint } from '../checkpoint/checkpoint.js';
+import type { PublishedCheckpoint } from '../checkpoint/published_checkpoint.js';
 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 CheckpointedL2Block, PublishedL2Block } from './checkpointed_l2_block.js';
 import type { L2Block } from './l2_block.js';
+import type { L2BlockNew } from './l2_block_new.js';
+import type { ValidateBlockNegativeResult, ValidateBlockResult } from './validate_block_result.js';
 
 /**
  * Interface of classes allowing for the retrieval of L2 blocks.
@@ -31,43 +43,70 @@ export interface L2BlockSource {
    * Gets the number of the latest L2 block processed by the block source implementation.
    * @returns The number of the latest L2 block processed by the block source implementation.
    */
-  getBlockNumber(): Promise<number>;
+  getBlockNumber(): Promise<BlockNumber>;
 
   /**
    * Gets the number of the latest L2 block proven seen by the block source implementation.
    * @returns The number of the latest L2 block proven seen by the block source implementation.
    */
-  getProvenBlockNumber(): Promise<number>;
-
-  /**
-   * Gets an l2 block. If a negative number is passed, the block returned is the most recent.
-   * @param number - The block number to return (inclusive).
-   * @returns The requested L2 block.
-   */
-  getBlock(number: number): Promise<L2Block | undefined>;
+  getProvenBlockNumber(): Promise<BlockNumber>;
 
   /**
    * Gets an l2 block header.
    * @param number - The block number to return or 'latest' for the most recent one.
    * @returns The requested L2 block header.
    */
-  getBlockHeader(number: number | 'latest'): Promise<BlockHeader | undefined>;
+  getBlockHeader(number: BlockNumber | 'latest'): Promise<BlockHeader | undefined>;
 
   /**
-   * Gets up to `limit` amount of L2 blocks starting from `from`.
-   * @param from - Number of the first block to return (inclusive).
-   * @param limit - The maximum number of blocks to return.
-   * @param proven - If true, only return blocks that have been proven.
-   * @returns The requested L2 blocks.
+   * Gets a checkpointed L2 block by block number.
+   * Returns undefined if the block doesn't exist or hasn't been checkpointed yet.
+   * @param number - The block number to retrieve.
+   * @returns The requested checkpointed L2 block (or undefined if not found or not checkpointed).
+   */
+  getCheckpointedBlock(number: BlockNumber): Promise<CheckpointedL2Block | undefined>;
+
+  /**
+   * Retrieves a collection of published checkpoints
+   * @param checkpointNumber The first checkpoint to be retrieved
+   * @param limit The number of checkpoints to be retrieved
+   * @returns The collection of complete checkpoints
+   */
+  getPublishedCheckpoints(checkpointNumber: CheckpointNumber, limit: number): Promise<PublishedCheckpoint[]>;
+
+  /**
+   * Gets the checkpoints for a given epoch
+   * @param epochNumber - Epoch for which we want checkpoint data
+   */
+  getCheckpointsForEpoch(epochNumber: EpochNumber): Promise<Checkpoint[]>;
+
+  /**
+   * Gets a block header by its hash.
+   * @param blockHash - The block hash to retrieve.
+   * @returns The requested block header (or undefined if not found).
    */
-  getBlocks(from: number, limit: number, proven?: boolean): Promise<L2Block[]>;
+  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 an L2 block by block number.
+   * @param number - The block number to return.
+   * @returns The requested L2 block (or undefined if not found).
+   */
+  getL2BlockNew(number: BlockNumber): Promise<L2BlockNew | 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 +116,27 @@ 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.
+   * 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 blocks for.
+   * @param epochNumber - The epoch number to return headers for.
    */
-  getBlocksForEpoch(epochNumber: bigint): Promise<L2Block[]>;
+  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 +147,94 @@ 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>;
+
+  /* Legacy APIS */
+
+  /**
+   * Gets an l2 block. If a negative number is passed, the block returned is the most recent.
+   * @param number - The block number to return (inclusive).
+   * @returns The requested L2 block.
+   * @deprecated Use getL2BlockNew instead.
+   */
+  getBlock(number: BlockNumber): Promise<L2Block | 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: EpochNumber): Promise<L2Block[]>;
+
+  /**
+   * Gets a published block by its block hash.
+   * @param blockHash - The block hash to retrieve.
+   * @returns The requested 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 block (or undefined if not found).
+   */
+  getPublishedBlockByArchive(archive: Fr): Promise<PublishedL2Block | undefined>;
+
+  /**
+   * Gets up to `limit` amount of L2 blocks starting from `from`.
+   * @param from - Number of the first block to return (inclusive).
+   * @param limit - The maximum number of blocks to return.
+   * @param proven - If true, only return blocks that have been proven.
+   * @returns The requested L2 blocks.
+   */
+  getBlocks(from: BlockNumber, limit: number, proven?: boolean): Promise<L2Block[]>;
+
+  /** Equivalent to getBlocks but includes publish data. */
+  getPublishedBlocks(from: BlockNumber, limit: number, proven?: boolean): Promise<PublishedL2Block[]>;
+}
+
+/**
+ * Interface for classes that can receive and store L2 blocks.
+ */
+export interface L2BlockSink {
+  /**
+   * Adds a block to the store.
+   * @param block - The L2 block to add.
+   * @throws If block number is not incremental (i.e., not exactly one more than the last stored block).
+   */
+  addBlock(block: L2BlockNew): 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.
@@ -128,33 +248,47 @@ export type L2BlockTag = 'latest' | 'proven' | 'finalized';
 export type L2Tips = Record<L2BlockTag, L2BlockId>;
 
 /** Identifies a block by number and hash. */
-export type L2BlockId = z.infer<typeof L2BlockIdSchema>;
-
-// TODO(palla/schemas): This package should know what is the block hash of the genesis block 0.
-const L2BlockIdSchema = z.union([
-  z.object({
-    number: z.literal(0),
-    hash: z.undefined(),
-  }),
-  z.object({
-    number: z.number(),
-    hash: z.string(),
-  }),
-]);
+export type L2BlockId = { number: BlockNumber; hash: string };
+
+/** Creates an L2 block id */
+export function makeL2BlockId(number: BlockNumber, 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! };
+}
+
+const L2BlockIdSchema = z.object({
+  number: BlockNumberSchema,
+  hash: z.string(),
+});
 
 export const L2TipsSchema = z.object({
   latest: L2BlockIdSchema,
   proven: L2BlockIdSchema,
   finalized: L2BlockIdSchema,
-}) satisfies z.ZodType<L2Tips>;
+});
 
 export enum L2BlockSourceEvents {
   L2PruneDetected = 'l2PruneDetected',
+  L2BlockProven = 'l2BlockProven',
+  InvalidAttestationsBlockDetected = 'invalidBlockDetected',
 }
 
-export type L2BlockSourceEvent = {
+export type L2BlockProvenEvent = {
+  type: 'l2BlockProven';
+  blockNumber: BlockNumber;
+  slotNumber: SlotNumber;
+  epochNumber: EpochNumber;
+};
+
+export type L2BlockPruneEvent = {
   type: 'l2PruneDetected';
-  blockNumber: bigint;
-  slotNumber: bigint;
-  epochNumber: bigint;
+  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 { PublishedL2Block } from '../checkpointed_l2_block.js';
+import type { L2BlockId, L2Tips } from '../l2_block_source.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_stream/l2_block_stream.ts

@@ -0,0 +1,216 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { AbortError } from '@aztec/foundation/error';
+import { createLogger } from '@aztec/foundation/log';
+import { RunningPromise } from '@aztec/foundation/running-promise';
+
+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, 'getPublishedBlocks' | 'getBlockHeader' | 'getL2Tips'>,
+    private localData: L2BlockStreamLocalDataProvider,
+    private handler: L2BlockStreamEventHandler,
+    private readonly log = createLogger('types:block_stream'),
+    private opts: {
+      proven?: boolean;
+      pollIntervalMS?: number;
+      batchSize?: number;
+      startingBlock?: number;
+      /** Instead of downloading all blocks, only fetch the smallest subset that results in reliable reorg detection. */
+      skipFinalized?: boolean;
+    } = {},
+  ) {
+    // Note that RunningPromise is in stopped state by default. This promise won't run until someone invokes `start`,
+    // which makes it run periodically, or `sync`, which triggers it once.
+    // Users of L2BlockStream decide what mode to run it in (_periodically_ vs _manually triggered_).
+    // The default is _manually triggered_.
+    this.runningPromise = new RunningPromise(() => this.work(), log, this.opts.pollIntervalMS ?? 1000);
+  }
+
+  public start() {
+    this.log.verbose(`Starting L2 block stream`, this.opts);
+    this.runningPromise.start();
+  }
+
+  public async stop() {
+    await this.runningPromise.stop();
+  }
+
+  public isRunning() {
+    return this.runningPromise.isRunning();
+  }
+
+  /**
+   * Runs the synchronization process once.
+   *
+   * If you want to run this process continuously use `start` and `stop` instead.
+   */
+  public async sync() {
+    this.isSyncing = true;
+    await this.runningPromise.trigger();
+    this.isSyncing = false;
+  }
+
+  protected async work() {
+    try {
+      const sourceTips = await this.l2BlockSource.getL2Tips();
+      const localTips = await this.localData.getL2Tips();
+      this.log.trace(`Running L2 block stream`, {
+        sourceLatest: sourceTips.latest.number,
+        localLatest: localTips.latest.number,
+        sourceFinalized: sourceTips.finalized.number,
+        localFinalized: localTips.finalized.number,
+        sourceProven: sourceTips.proven.number,
+        localProven: localTips.proven.number,
+        sourceLatestHash: sourceTips.latest.hash,
+        localLatestHash: localTips.latest.hash,
+        sourceProvenHash: sourceTips.proven.hash,
+        localProvenHash: localTips.proven.hash,
+        sourceFinalizedHash: sourceTips.finalized.hash,
+        localFinalizedHash: localTips.finalized.hash,
+      });
+
+      // Check if there was a reorg and emit a chain-pruned event if so.
+      let latestBlockNumber = localTips.latest.number;
+      const sourceCache = new BlockHashCache([sourceTips.latest]);
+      while (!(await this.areBlockHashesEqualAt(latestBlockNumber, { sourceCache }))) {
+        latestBlockNumber--;
+      }
+
+      if (latestBlockNumber < localTips.latest.number) {
+        latestBlockNumber = BlockNumber(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', 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 = BlockNumber(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 (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(
+          BlockNumber(nextBlockNumber),
+          limit,
+          this.opts.proven,
+        );
+        if (blocks.length === 0) {
+          break;
+        }
+        await this.emitEvent({ type: 'blocks-added', blocks });
+        nextBlockNumber = blocks.at(-1)!.block.number + 1;
+      }
+
+      // Update the proven and finalized tips.
+      if (localTips.proven !== undefined && sourceTips.proven.number !== localTips.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', block: sourceTips.finalized });
+      }
+    } catch (err: any) {
+      if (err.name === 'AbortError') {
+        return;
+      }
+      this.log.error(`Error processing block stream`, err);
+    }
+  }
+
+  /**
+   * Returns whether the source and local agree on the block hash at a given height.
+   * @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: BlockNumber, args: { sourceCache: BlockHashCache }) {
+    if (blockNumber === 0) {
+      return true;
+    }
+    const localBlockHash = await this.localData.getL2BlockHash(blockNumber);
+    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: BlockNumber) {
+    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.block.number})`,
+    );
+    await this.handler.handleBlockStreamEvent(event);
+    if (!this.isRunning() && !this.isSyncing) {
+      throw new AbortError();
+    }
+  }
+}
+
+class BlockHashCache {
+  private readonly cache: Map<number, string> = new Map();
+
+  constructor(initial: L2BlockId[] = []) {
+    for (const block of initial) {
+      this.add(block);
+    }
+  }
+
+  public add(block: L2BlockId) {
+    if (block.hash) {
+      this.cache.set(block.number, block.hash);
+    }
+  }
+
+  public get(blockNumber: number) {
+    return this.cache.get(blockNumber);
+  }
+}

package/src/block/l2_block_stream/l2_tips_memory_store.ts

@@ -0,0 +1,78 @@
+import { GENESIS_BLOCK_HEADER_HASH } from '@aztec/constants';
+import { BlockNumber } from '@aztec/foundation/branded-types';
+
+import type { L2Block } from '../l2_block.js';
+import type { L2BlockId, L2BlockTag, L2Tips } from '../l2_block_source.js';
+import type { L2BlockStreamEvent, L2BlockStreamEventHandler, L2BlockStreamLocalDataProvider } from './interfaces.js';
+
+/**
+ * Stores currently synced L2 tips and unfinalized block hashes.
+ * @dev tests in kv-store/src/stores/l2_tips_memory_store.test.ts
+ */
+export class L2TipsMemoryStore implements L2BlockStreamEventHandler, L2BlockStreamLocalDataProvider {
+  protected readonly l2TipsStore: Map<L2BlockTag, BlockNumber> = new Map();
+  protected readonly l2BlockHashesStore: Map<number, string> = new Map();
+
+  public getL2BlockHash(number: number): Promise<string | undefined> {
+    return Promise.resolve(this.l2BlockHashesStore.get(number));
+  }
+
+  public getL2Tips(): Promise<L2Tips> {
+    return Promise.resolve({
+      latest: this.getL2Tip('latest'),
+      finalized: this.getL2Tip('finalized'),
+      proven: this.getL2Tip('proven'),
+    });
+  }
+
+  private getL2Tip(tag: L2BlockTag): L2BlockId {
+    const blockNumber = this.l2TipsStore.get(tag);
+    if (blockNumber === undefined || blockNumber === 0) {
+      return { number: BlockNumber.ZERO, hash: GENESIS_BLOCK_HEADER_HASH.toString() };
+    }
+    const blockHash = this.l2BlockHashesStore.get(blockNumber);
+    if (!blockHash) {
+      throw new Error(`Block hash not found for block number ${blockNumber}`);
+    }
+
+    return { number: blockNumber, hash: blockHash };
+  }
+
+  public async handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void> {
+    switch (event.type) {
+      case 'blocks-added': {
+        const blocks = event.blocks.map(b => b.block);
+        for (const block of blocks) {
+          this.l2BlockHashesStore.set(block.number, await this.computeBlockHash(block));
+        }
+        this.l2TipsStore.set('latest', blocks.at(-1)!.number);
+        break;
+      }
+      case 'chain-pruned':
+        this.saveTag('latest', event.block);
+        break;
+      case 'chain-proven':
+        this.saveTag('proven', event.block);
+        break;
+      case 'chain-finalized':
+        this.saveTag('finalized', event.block);
+        for (const key of this.l2BlockHashesStore.keys()) {
+          if (key < event.block.number) {
+            this.l2BlockHashesStore.delete(key);
+          }
+        }
+        break;
+    }
+  }
+
+  protected saveTag(name: L2BlockTag, block: L2BlockId) {
+    this.l2TipsStore.set(name, block.number);
+    if (block.hash) {
+      this.l2BlockHashesStore.set(block.number, block.hash);
+    }
+  }
+
+  protected computeBlockHash(block: L2Block) {
+    return block.hash().then(hash => hash.toString());
+  }
+}