@aztec/world-state 0.0.0-test.0

package/src/native/world_state_ops_queue.ts

@@ -0,0 +1,190 @@
+import { promiseWithResolvers } from '@aztec/foundation/promise';
+
+import { WorldStateMessageType } from './message.js';
+
+/**
+ * This is the implementation for queueing requests to the world state.
+ * Requests need to be queued for the world state to ensure that writes are correctly ordered
+ * and reads return the correct data.
+ * Due to the nature of the NAPI we can't really do this there.
+ *
+ * The rules for queueing are as follows:
+ *
+ * 1. Reads of committed state never need to be queued. LMDB uses MVCC to ensure readers see a consistent view of the DB.
+ * 2. Reads of uncommitted state can happen concurrently with other reads of uncommitted state on the same fork (or reads of committed state)
+ * 3. All writes require exclusive access to their respective fork
+ *
+ */
+
+type WorldStateOp = {
+  requestId: number;
+  mutating: boolean;
+  request: () => Promise<any>;
+  promise: PromiseWithResolvers<any>;
+};
+
+// These are the set of message types that implement mutating operations
+// Messages of these types require exclusive access to their given forks
+export const MUTATING_MSG_TYPES = new Set([
+  WorldStateMessageType.APPEND_LEAVES,
+  WorldStateMessageType.BATCH_INSERT,
+  WorldStateMessageType.SEQUENTIAL_INSERT,
+  WorldStateMessageType.UPDATE_ARCHIVE,
+  WorldStateMessageType.COMMIT,
+  WorldStateMessageType.ROLLBACK,
+  WorldStateMessageType.SYNC_BLOCK,
+  WorldStateMessageType.CREATE_FORK,
+  WorldStateMessageType.DELETE_FORK,
+  WorldStateMessageType.FINALISE_BLOCKS,
+  WorldStateMessageType.UNWIND_BLOCKS,
+  WorldStateMessageType.REMOVE_HISTORICAL_BLOCKS,
+  WorldStateMessageType.CREATE_CHECKPOINT,
+  WorldStateMessageType.COMMIT_CHECKPOINT,
+  WorldStateMessageType.REVERT_CHECKPOINT,
+]);
+
+// This class implements the per-fork operation queue
+export class WorldStateOpsQueue {
+  private requests: WorldStateOp[] = [];
+  private inFlightMutatingCount = 0;
+  private inFlightCount = 0;
+  private stopPromise?: Promise<void>;
+  private stopResolve?: () => void;
+  private requestId = 0;
+  private ops: Map<number, WorldStateOp> = new Map();
+
+  // The primary public api, this is where an operation is queued
+  // We return a promise that will ultimately be resolved/rejected with the response/error generated by the 'request' argument
+  public execute(request: () => Promise<any>, messageType: WorldStateMessageType, committedOnly: boolean) {
+    if (this.stopResolve !== undefined) {
+      throw new Error('Unable to send request to world state, queue already stopped');
+    }
+
+    const op: WorldStateOp = {
+      requestId: this.requestId++,
+      mutating: MUTATING_MSG_TYPES.has(messageType),
+      request,
+      promise: promiseWithResolvers(),
+    };
+    this.ops.set(op.requestId, op);
+
+    // Perform the appropriate action based upon the queueing rules
+    if (op.mutating) {
+      this.executeMutating(op);
+    } else if (committedOnly === false) {
+      this.executeNonMutatingUncommitted(op);
+    } else {
+      this.executeNonMutatingCommitted(op);
+    }
+    return op.promise.promise;
+  }
+
+  // Mutating requests need exclusive access
+  private executeMutating(op: WorldStateOp) {
+    // If nothing is in flight then we send the request immediately
+    // Otherwise add to the queue
+    if (this.inFlightCount === 0) {
+      this.sendEnqueuedRequest(op);
+    } else {
+      this.requests.push(op);
+    }
+  }
+
+  // Non mutating requests including uncommitted state
+  private executeNonMutatingUncommitted(op: WorldStateOp) {
+    // If there are no mutating requests in flight and there is nothing queued
+    // then send the request immediately
+    // If a mutating request is in flight then we must wait
+    // If a mutating request is not in flight but something is queued then it must be a mutating request
+    if (this.inFlightMutatingCount == 0 && this.requests.length == 0) {
+      this.sendEnqueuedRequest(op);
+    } else {
+      this.requests.push(op);
+    }
+  }
+
+  private executeNonMutatingCommitted(op: WorldStateOp) {
+    // This is a non-mutating request for committed data
+    // It can always be sent
+    op.request()
+      .then(op.promise.resolve, op.promise.reject)
+      .finally(() => {
+        this.ops.delete(op.requestId);
+      });
+  }
+
+  private checkAndEnqueue(completedOp: WorldStateOp) {
+    // As request has completed
+    // First we decrements the relevant in flight counters
+    if (completedOp.mutating) {
+      --this.inFlightMutatingCount;
+    }
+    --this.inFlightCount;
+
+    // If there are still requests in flight then do nothing further
+    if (this.inFlightCount != 0) {
+      return;
+    }
+
+    // No requests in flight, send next queued requests
+    // We loop and send:
+    // 1 mutating request if it is next in the queue
+    // As many non-mutating requests as we encounter until
+    // we exhaust the queue or we reach a mutating request
+    while (this.requests.length > 0) {
+      const next = this.requests[0];
+      if (next.mutating) {
+        if (this.inFlightCount == 0) {
+          // send the mutating request
+          this.requests.shift();
+          this.sendEnqueuedRequest(next);
+        }
+        // this request is mutating, we need to stop here
+        break;
+      } else {
+        // not mutating, send and go round again
+        this.requests.shift();
+        this.sendEnqueuedRequest(next);
+      }
+    }
+
+    // If the queue is empty, there is nothing in flight and we have been told to stop, then resolve the stop promise
+    if (this.inFlightCount == 0 && this.stopResolve !== undefined) {
+      this.stopResolve();
+    }
+  }
+
+  private sendEnqueuedRequest(op: WorldStateOp) {
+    // Here we increment the in flight counts before sending
+    ++this.inFlightCount;
+    if (op.mutating) {
+      ++this.inFlightMutatingCount;
+    }
+
+    // Make the request and pass the response/error through to the stored promise
+    op.request()
+      .then(op.promise.resolve, op.promise.reject)
+      .finally(() => {
+        this.checkAndEnqueue(op);
+        this.ops.delete(op.requestId);
+      });
+  }
+
+  public stop() {
+    // If there is already a stop promise then return it
+    if (this.stopPromise) {
+      return this.stopPromise;
+    }
+
+    // Otherwise create a new one and capture the resolve method
+    this.stopPromise = new Promise(resolve => {
+      this.stopResolve = resolve;
+    });
+
+    // If no outstanding requests then immediately resolve the promise
+    if (this.requests.length == 0 && this.inFlightCount == 0 && this.stopResolve !== undefined) {
+      this.stopResolve();
+    }
+    return this.stopPromise;
+  }
+}

package/src/synchronizer/config.ts

@@ -0,0 +1,68 @@
+import {
+  type ConfigMappingsType,
+  booleanConfigHelper,
+  getConfigFromMappings,
+  numberConfigHelper,
+} from '@aztec/foundation/config';
+
+/** World State synchronizer configuration values. */
+export interface WorldStateConfig {
+  /** The frequency in which to check. */
+  worldStateBlockCheckIntervalMS: number;
+
+  /** Whether to follow only the proven chain. */
+  worldStateProvenBlocksOnly: boolean;
+
+  /** Size of the batch for each get-blocks request from the synchronizer to the archiver. */
+  worldStateBlockRequestBatchSize?: number;
+
+  /** The map size to be provided to LMDB for each world state tree DB, optional, will inherit from the general dataStoreMapSizeKB if not specified*/
+  worldStateDbMapSizeKb?: number;
+
+  /** Optional directory for the world state DB, if unspecified will default to the general data directory */
+  worldStateDataDirectory?: string;
+
+  /** The number of historic blocks to maintain */
+  worldStateBlockHistory: number;
+}
+
+export const worldStateConfigMappings: ConfigMappingsType<WorldStateConfig> = {
+  worldStateBlockCheckIntervalMS: {
+    env: 'WS_BLOCK_CHECK_INTERVAL_MS',
+    parseEnv: (val: string) => +val,
+    defaultValue: 100,
+    description: 'The frequency in which to check.',
+  },
+  worldStateProvenBlocksOnly: {
+    env: 'WS_PROVEN_BLOCKS_ONLY',
+    description: 'Whether to follow only the proven chain.',
+    ...booleanConfigHelper(),
+  },
+  worldStateBlockRequestBatchSize: {
+    env: 'WS_BLOCK_REQUEST_BATCH_SIZE',
+    parseEnv: (val: string | undefined) => (val ? +val : undefined),
+    description: 'Size of the batch for each get-blocks request from the synchronizer to the archiver.',
+  },
+  worldStateDbMapSizeKb: {
+    env: 'WS_DB_MAP_SIZE_KB',
+    parseEnv: (val: string | undefined) => (val ? +val : undefined),
+    description: 'The maximum possible size of the world state DB',
+  },
+  worldStateDataDirectory: {
+    env: 'WS_DATA_DIRECTORY',
+    description: 'Optional directory for the world state database',
+  },
+  worldStateBlockHistory: {
+    env: 'WS_NUM_HISTORIC_BLOCKS',
+    description: 'The number of historic blocks to maintain. Values less than 1 mean all history is maintained',
+    ...numberConfigHelper(64),
+  },
+};
+
+/**
+ * Returns the configuration values for the world state synchronizer.
+ * @returns The configuration values for the world state synchronizer.
+ */
+export function getWorldStateConfigFromEnv(): WorldStateConfig {
+  return getConfigFromMappings<WorldStateConfig>(worldStateConfigMappings);
+}

package/src/synchronizer/factory.ts

@@ -0,0 +1,53 @@
+import type { DataStoreConfig } from '@aztec/kv-store/config';
+import type { L2BlockSource } from '@aztec/stdlib/block';
+import type { L1ToL2MessageSource } from '@aztec/stdlib/messaging';
+import type { PublicDataTreeLeaf } from '@aztec/stdlib/trees';
+import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-client';
+
+import { WorldStateInstrumentation } from '../instrumentation/instrumentation.js';
+import { NativeWorldStateService } from '../native/native_world_state.js';
+import type { WorldStateConfig } from './config.js';
+import { ServerWorldStateSynchronizer } from './server_world_state_synchronizer.js';
+
+export async function createWorldStateSynchronizer(
+  config: WorldStateConfig & DataStoreConfig,
+  l2BlockSource: L2BlockSource & L1ToL2MessageSource,
+  prefilledPublicData: PublicDataTreeLeaf[] = [],
+  client: TelemetryClient = getTelemetryClient(),
+) {
+  const instrumentation = new WorldStateInstrumentation(client);
+  const merkleTrees = await createWorldState(config, prefilledPublicData, instrumentation);
+  return new ServerWorldStateSynchronizer(merkleTrees, l2BlockSource, config, instrumentation);
+}
+
+export async function createWorldState(
+  config: WorldStateConfig & DataStoreConfig,
+  prefilledPublicData: PublicDataTreeLeaf[] = [],
+  instrumentation: WorldStateInstrumentation = new WorldStateInstrumentation(getTelemetryClient()),
+) {
+  const newConfig = {
+    dataDirectory: config.worldStateDataDirectory ?? config.dataDirectory,
+    dataStoreMapSizeKB: config.worldStateDbMapSizeKb ?? config.dataStoreMapSizeKB,
+  } as DataStoreConfig;
+
+  if (!config.l1Contracts?.rollupAddress) {
+    throw new Error('Rollup address is required to create a world state synchronizer.');
+  }
+
+  // If a data directory is provided in config, then create a persistent store.
+  const merkleTrees = newConfig.dataDirectory
+    ? await NativeWorldStateService.new(
+        config.l1Contracts.rollupAddress,
+        newConfig.dataDirectory,
+        newConfig.dataStoreMapSizeKB,
+        prefilledPublicData,
+        instrumentation,
+      )
+    : await NativeWorldStateService.tmp(
+        config.l1Contracts.rollupAddress,
+        !['true', '1'].includes(process.env.DEBUG_WORLD_STATE!),
+        prefilledPublicData,
+      );
+
+  return merkleTrees;
+}

package/src/synchronizer/index.ts

@@ -0,0 +1,2 @@
+export * from './server_world_state_synchronizer.js';
+export * from './factory.js';

package/src/synchronizer/server_world_state_synchronizer.ts

@@ -0,0 +1,344 @@
+import { L1_TO_L2_MSG_SUBTREE_HEIGHT } from '@aztec/constants';
+import type { Fr } from '@aztec/foundation/fields';
+import { createLogger } from '@aztec/foundation/log';
+import { promiseWithResolvers } from '@aztec/foundation/promise';
+import { elapsed } from '@aztec/foundation/timer';
+import { MerkleTreeCalculator } from '@aztec/foundation/trees';
+import { SHA256Trunc } from '@aztec/merkle-tree';
+import type {
+  L2Block,
+  L2BlockId,
+  L2BlockSource,
+  L2BlockStream,
+  L2BlockStreamEvent,
+  L2BlockStreamEventHandler,
+  L2BlockStreamLocalDataProvider,
+  L2Tips,
+} from '@aztec/stdlib/block';
+import {
+  WorldStateRunningState,
+  type WorldStateSyncStatus,
+  type WorldStateSynchronizer,
+  type WorldStateSynchronizerStatus,
+} from '@aztec/stdlib/interfaces/server';
+import type { L1ToL2MessageSource } from '@aztec/stdlib/messaging';
+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 { 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';
+
+/**
+ * Synchronizes the world state with the L2 blocks from a L2BlockSource via a block stream.
+ * The synchronizer will download the L2 blocks from the L2BlockSource and update the merkle trees.
+ * Handles chain reorgs via the L2BlockStream.
+ */
+export class ServerWorldStateSynchronizer
+  implements WorldStateSynchronizer, L2BlockStreamLocalDataProvider, L2BlockStreamEventHandler
+{
+  private readonly merkleTreeCommitted: MerkleTreeReadOperations;
+
+  private latestBlockNumberAtStart = 0;
+  private historyToKeep: number | undefined;
+  private currentState: WorldStateRunningState = WorldStateRunningState.IDLE;
+  private latestBlockHashQuery: { blockNumber: number; hash: string | undefined } | undefined = undefined;
+
+  private syncPromise = promiseWithResolvers<void>();
+  protected blockStream: L2BlockStream | undefined;
+
+  constructor(
+    private readonly merkleTreeDb: MerkleTreeAdminDatabase,
+    private readonly l2BlockSource: L2BlockSource & L1ToL2MessageSource,
+    private readonly config: WorldStateConfig,
+    private instrumentation = new WorldStateInstrumentation(getTelemetryClient()),
+    private readonly log = createLogger('world_state'),
+  ) {
+    this.merkleTreeCommitted = this.merkleTreeDb.getCommitted();
+    this.historyToKeep = config.worldStateBlockHistory < 1 ? undefined : config.worldStateBlockHistory;
+    this.log.info(
+      `Created world state synchroniser with block history of ${
+        this.historyToKeep === undefined ? 'infinity' : this.historyToKeep
+      }`,
+    );
+  }
+
+  public getCommitted(): MerkleTreeReadOperations {
+    return this.merkleTreeDb.getCommitted();
+  }
+
+  public getSnapshot(blockNumber: number): MerkleTreeReadOperations {
+    return this.merkleTreeDb.getSnapshot(blockNumber);
+  }
+
+  public fork(blockNumber?: number): Promise<MerkleTreeWriteOperations> {
+    return this.merkleTreeDb.fork(blockNumber);
+  }
+
+  public async start() {
+    if (this.currentState === WorldStateRunningState.STOPPED) {
+      throw new Error('Synchronizer already stopped');
+    }
+    if (this.currentState !== WorldStateRunningState.IDLE) {
+      return this.syncPromise;
+    }
+
+    // Get the current latest block number
+    this.latestBlockNumberAtStart = await (this.config.worldStateProvenBlocksOnly
+      ? this.l2BlockSource.getProvenBlockNumber()
+      : this.l2BlockSource.getBlockNumber());
+
+    const blockToDownloadFrom = (await this.getLatestBlockNumber()) + 1;
+
+    if (blockToDownloadFrom <= this.latestBlockNumberAtStart) {
+      // If there are blocks to be retrieved, go to a synching state
+      this.setCurrentState(WorldStateRunningState.SYNCHING);
+      this.log.verbose(`Starting sync from ${blockToDownloadFrom} to latest block ${this.latestBlockNumberAtStart}`);
+    } else {
+      // If no blocks to be retrieved, go straight to running
+      this.setCurrentState(WorldStateRunningState.RUNNING);
+      this.syncPromise.resolve();
+      this.log.debug(`Next block ${blockToDownloadFrom} already beyond latest block ${this.latestBlockNumberAtStart}`);
+    }
+
+    this.blockStream = this.createBlockStream();
+    this.blockStream.start();
+    this.log.info(`Started world state synchronizer from block ${blockToDownloadFrom}`);
+    return this.syncPromise.promise;
+  }
+
+  protected createBlockStream(): L2BlockStream {
+    const tracer = this.instrumentation.telemetry.getTracer('WorldStateL2BlockStream');
+    const logger = createLogger('world-state:block_stream');
+    return new TraceableL2BlockStream(this.l2BlockSource, this, this, tracer, 'WorldStateL2BlockStream', logger, {
+      proven: this.config.worldStateProvenBlocksOnly,
+      pollIntervalMS: this.config.worldStateBlockCheckIntervalMS,
+      batchSize: this.config.worldStateBlockRequestBatchSize,
+    });
+  }
+
+  public async stop() {
+    this.log.debug('Stopping block stream...');
+    await this.blockStream?.stop();
+    this.log.debug('Stopping merkle trees...');
+    await this.merkleTreeDb.close();
+    this.setCurrentState(WorldStateRunningState.STOPPED);
+    this.log.info(`Stopped world state synchronizer`);
+  }
+
+  public async status(): Promise<WorldStateSynchronizerStatus> {
+    const summary = await this.merkleTreeDb.getStatusSummary();
+    const status: WorldStateSyncStatus = {
+      latestBlockNumber: Number(summary.unfinalisedBlockNumber),
+      latestBlockHash: (await this.getL2BlockHash(Number(summary.unfinalisedBlockNumber))) ?? '',
+      finalisedBlockNumber: Number(summary.finalisedBlockNumber),
+      oldestHistoricBlockNumber: Number(summary.oldestHistoricalBlock),
+      treesAreSynched: summary.treesAreSynched,
+    };
+    return {
+      syncSummary: status,
+      state: this.currentState,
+    };
+  }
+
+  public async getLatestBlockNumber() {
+    return (await this.getL2Tips()).latest.number;
+  }
+
+  /**
+   * Forces an immediate sync.
+   * @param targetBlockNumber - The target block number that we must sync to. Will download unproven blocks if needed to reach it. Throws if cannot be reached.
+   * @returns A promise that resolves with the block number the world state was synced to
+   */
+  public async syncImmediate(targetBlockNumber?: number): Promise<number> {
+    if (this.currentState !== WorldStateRunningState.RUNNING || this.blockStream === undefined) {
+      throw new Error(`World State is not running. Unable to perform sync.`);
+    }
+
+    // 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;
+    }
+    this.log.debug(`World State at ${currentBlockNumber} told to sync to ${targetBlockNumber ?? 'latest'}`);
+
+    // Force the block stream to sync against the archiver now
+    await this.blockStream.sync();
+
+    // 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 (targetBlockNumber !== undefined && targetBlockNumber > updatedBlockNumber) {
+      throw new Error(`Unable to sync to block number ${targetBlockNumber} (last synced is ${updatedBlockNumber})`);
+    }
+
+    return updatedBlockNumber;
+  }
+
+  /** Returns the L2 block hash for a given number. Used by the L2BlockStream for detecting reorgs. */
+  public async getL2BlockHash(number: number): Promise<string | undefined> {
+    if (number === 0) {
+      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;
+  }
+
+  /** Returns the latest L2 block number for each tip of the chain (latest, proven, finalized). */
+  public async getL2Tips(): Promise<L2Tips> {
+    const status = await this.merkleTreeDb.getStatusSummary();
+    const unfinalisedBlockHash = await this.getL2BlockHash(Number(status.unfinalisedBlockNumber));
+    const latestBlockId: L2BlockId = { number: Number(status.unfinalisedBlockNumber), hash: unfinalisedBlockHash! };
+
+    return {
+      latest: latestBlockId,
+      finalized: { number: Number(status.finalisedBlockNumber), hash: '' },
+      proven: { number: Number(status.finalisedBlockNumber), hash: '' }, // TODO(palla/reorg): Using finalised as proven for now
+    };
+  }
+
+  /** Handles an event emitted by the block stream. */
+  public async handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void> {
+    try {
+      switch (event.type) {
+        case 'blocks-added':
+          await this.handleL2Blocks(event.blocks);
+          break;
+        case 'chain-pruned':
+          await this.handleChainPruned(event.blockNumber);
+          break;
+        case 'chain-proven':
+          await this.handleChainProven(event.blockNumber);
+          break;
+        case 'chain-finalized':
+          await this.handleChainFinalized(event.blockNumber);
+          break;
+      }
+    } catch (err) {
+      this.log.error('Error processing block stream', err);
+    }
+  }
+
+  /**
+   * Handles a list of L2 blocks (i.e. Inserts the new note hashes into the merkle tree).
+   * @param l2Blocks - The L2 blocks to handle.
+   * @returns Whether the block handled was produced by this same node.
+   */
+  private async handleL2Blocks(l2Blocks: L2Block[]) {
+    this.log.trace(`Handling L2 blocks ${l2Blocks[0].number} to ${l2Blocks.at(-1)!.number}`);
+
+    const messagePromises = l2Blocks.map(block => this.l2BlockSource.getL1ToL2Messages(BigInt(block.number)));
+    const l1ToL2Messages: Fr[][] = await Promise.all(messagePromises);
+    let updateStatus: WorldStateStatusFull | undefined = undefined;
+
+    for (let i = 0; i < l2Blocks.length; i++) {
+      const [duration, result] = await elapsed(() => this.handleL2Block(l2Blocks[i], l1ToL2Messages[i]));
+      this.log.verbose(`World state updated with L2 block ${l2Blocks[i].number}`, {
+        eventName: 'l2-block-handled',
+        duration,
+        unfinalisedBlockNumber: result.summary.unfinalisedBlockNumber,
+        finalisedBlockNumber: result.summary.finalisedBlockNumber,
+        oldestHistoricBlock: result.summary.oldestHistoricalBlock,
+        ...l2Blocks[i].getStats(),
+      } satisfies L2BlockHandledStats);
+      updateStatus = result;
+    }
+    if (!updateStatus) {
+      return;
+    }
+    this.instrumentation.updateWorldStateMetrics(updateStatus);
+  }
+
+  /**
+   * Handles a single L2 block (i.e. Inserts the new note hashes into the merkle tree).
+   * @param l2Block - The L2 block to handle.
+   * @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: L2Block, l1ToL2Messages: Fr[]): Promise<WorldStateStatusFull> {
+    // First we check that the L1 to L2 messages hash to the block inHash.
+    // Note that we cannot optimize this check by checking the root of the subtree after inserting the messages
+    // to the real L1_TO_L2_MESSAGE_TREE (like we do in merkleTreeDb.handleL2BlockAndMessages(...)) because that
+    // tree uses pedersen and we don't have access to the converted root.
+    await this.verifyMessagesHashToInHash(l1ToL2Messages, l2Block.header.contentCommitment.inHash);
+
+    // If the above check succeeds, we can proceed to handle the block.
+    this.log.trace(`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()),
+    });
+    const result = await this.merkleTreeDb.handleL2BlockAndMessages(l2Block, l1ToL2Messages);
+
+    if (this.currentState === WorldStateRunningState.SYNCHING && l2Block.number >= this.latestBlockNumberAtStart) {
+      this.setCurrentState(WorldStateRunningState.RUNNING);
+      this.syncPromise.resolve();
+    }
+
+    return result;
+  }
+
+  private async handleChainFinalized(blockNumber: number) {
+    this.log.verbose(`Finalized chain is now at block ${blockNumber}`);
+    const summary = await this.merkleTreeDb.setFinalised(BigInt(blockNumber));
+    if (this.historyToKeep === undefined) {
+      return;
+    }
+    const newHistoricBlock = summary.finalisedBlockNumber - BigInt(this.historyToKeep) + 1n;
+    if (newHistoricBlock <= 1) {
+      return;
+    }
+    this.log.verbose(`Pruning historic blocks to ${newHistoricBlock}`);
+    const status = await this.merkleTreeDb.removeHistoricalBlocks(newHistoricBlock);
+    this.log.debug(`World state summary `, status.summary);
+  }
+
+  private handleChainProven(blockNumber: number) {
+    this.log.debug(`Proven chain is now at block ${blockNumber}`);
+    return Promise.resolve();
+  }
+
+  private async handleChainPruned(blockNumber: number) {
+    this.log.warn(`Chain pruned to block ${blockNumber}`);
+    const status = await this.merkleTreeDb.unwindBlocks(BigInt(blockNumber));
+    this.latestBlockHashQuery = undefined;
+    this.instrumentation.updateWorldStateMetrics(status);
+  }
+
+  /**
+   * Method to set the value of the current state.
+   * @param newState - New state value.
+   */
+  private setCurrentState(newState: WorldStateRunningState) {
+    this.currentState = newState;
+    this.log.debug(`Moved to state ${WorldStateRunningState[this.currentState]}`);
+  }
+
+  /**
+   * Verifies that the L1 to L2 messages hash to the block inHash.
+   * @param l1ToL2Messages - The L1 to L2 messages for the block.
+   * @param inHash - The inHash of the block.
+   * @throws If the L1 to L2 messages do not hash to the block inHash.
+   */
+  protected async verifyMessagesHashToInHash(l1ToL2Messages: Fr[], inHash: Buffer) {
+    const treeCalculator = await MerkleTreeCalculator.create(
+      L1_TO_L2_MSG_SUBTREE_HEIGHT,
+      Buffer.alloc(32),
+      (lhs, rhs) => Promise.resolve(new SHA256Trunc().hash(lhs, rhs)),
+    );
+
+    const root = await treeCalculator.computeTreeRoot(l1ToL2Messages.map(msg => msg.toBuffer()));
+
+    if (!root.equals(inHash)) {
+      throw new Error('Obtained L1 to L2 messages failed to be hashed to the block inHash');
+    }
+  }
+}

package/src/test/index.ts

@@ -0,0 +1 @@
+export * from './utils.js';