@aztec/world-state 0.0.1-commit.2f68f620 → 0.0.1-commit.3100065

package/src/native/native_world_state_instance.ts

@@ -1,107 +1,318 @@
-import type { BlockNumber } from '@aztec/foundation/branded-types';
-import type { Fr } from '@aztec/foundation/curves/bn254';
-import type { IndexedTreeId, TreeInfo } from '@aztec/stdlib/interfaces/server';
-import type { MerkleTreeId } from '@aztec/stdlib/trees';
-import type { WorldStateRevision } from '@aztec/stdlib/world-state';
-
-import type {
-  BlockStateReference,
-  SerializedBatchInsertionResult,
-  SerializedIndexedLeaf,
-  SerializedLeafValue,
-  SerializedSequentialInsertionResult,
-  SerializedSiblingPathAndIndex,
-  TreeStateReference,
-  WorldStateStatusFull,
-  WorldStateStatusSummary,
+import {
+  ARCHIVE_HEIGHT,
+  DomainSeparator,
+  L1_TO_L2_MSG_TREE_HEIGHT,
+  MAX_NULLIFIERS_PER_TX,
+  MAX_TOTAL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX,
+  NOTE_HASH_TREE_HEIGHT,
+  NULLIFIER_TREE_HEIGHT,
+  PUBLIC_DATA_TREE_HEIGHT,
+} from '@aztec/constants';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
+import { NativeWorldState as BaseNativeWorldState, MsgpackChannel } from '@aztec/native';
+import { MerkleTreeId } from '@aztec/stdlib/trees';
+import { EMPTY_GENESIS_DATA, type GenesisData } from '@aztec/stdlib/world-state';
+
+import assert from 'assert';
+import { cpus } from 'os';
+
+import type { WorldStateInstrumentation } from '../instrumentation/instrumentation.js';
+import type { WorldStateTreeMapSizes } from '../synchronizer/factory.js';
+import {
+  WorldStateMessageType,
+  type WorldStateRequest,
+  type WorldStateRequestCategories,
+  type WorldStateResponse,
+  isWithCanonical,
+  isWithForkId,
+  isWithRevision,
 } from './message.js';
+import { WorldStateOpsQueue } from './world_state_ops_queue.js';
+
+const MAX_WORLD_STATE_THREADS = +(process.env.HARDWARE_CONCURRENCY || '16');
+
+export interface NativeWorldStateInstance {
+  call<T extends WorldStateMessageType>(
+    messageType: T,
+    body: WorldStateRequest[T] & WorldStateRequestCategories,
+  ): Promise<WorldStateResponse[T]>;
+  // TODO(dbanks12): this returns any type, but we should strongly type it
+  getHandle(): any;
+}
 
 /**
- * Backend-agnostic handle to a running aztec-wsdb world state, accessed by the TS layer.
- *
- * The legacy in-process NAPI implementation has been removed; the C++ AVM (NAPI) now connects to
- * the same aztec-wsdb process using the IPC path returned by {@link getIpcPath}.
+ * Strongly-typed interface to access the WorldState class in the native world_state_napi module.
  */
-export interface NativeWorldStateInstance {
-  getTreeInfo(treeId: MerkleTreeId, revision: WorldStateRevision): Promise<TreeInfo>;
-  getStateReference(revision: WorldStateRevision): Promise<Record<number, TreeStateReference>>;
-  getInitialStateReference(): Promise<Record<number, TreeStateReference>>;
-  getLeafValue(
-    treeId: MerkleTreeId,
-    revision: WorldStateRevision,
-    leafIndex: bigint,
-  ): Promise<SerializedLeafValue | undefined>;
-  getLeafPreimage(
-    treeId: IndexedTreeId,
-    revision: WorldStateRevision,
-    leafIndex: bigint,
-  ): Promise<SerializedIndexedLeaf | undefined>;
-  getSiblingPath(treeId: MerkleTreeId, revision: WorldStateRevision, leafIndex: bigint): Promise<Buffer[]>;
-  getBlockNumbersForLeafIndices(
-    treeId: MerkleTreeId,
-    revision: WorldStateRevision,
-    leafIndices: bigint[],
-  ): Promise<(bigint | undefined)[]>;
-  findLeafIndices(
-    treeId: MerkleTreeId,
-    revision: WorldStateRevision,
-    leaves: SerializedLeafValue[],
-    startIndex: bigint,
-  ): Promise<(bigint | undefined)[]>;
-  findLowLeaf(
-    treeId: IndexedTreeId,
-    revision: WorldStateRevision,
-    key: Fr,
-  ): Promise<{ index: bigint; alreadyPresent: boolean }>;
-  findSiblingPaths(
-    treeId: MerkleTreeId,
-    revision: WorldStateRevision,
-    leaves: SerializedLeafValue[],
-  ): Promise<(SerializedSiblingPathAndIndex | undefined)[]>;
-  updateArchive(forkId: number, blockStateRef: BlockStateReference, blockHeaderHash: Buffer): Promise<void>;
-  appendLeaves(treeId: MerkleTreeId, forkId: number, leaves: SerializedLeafValue[]): Promise<void>;
-  batchInsert(
-    treeId: IndexedTreeId,
-    forkId: number,
-    leaves: SerializedLeafValue[],
-    subtreeDepth: number,
-  ): Promise<SerializedBatchInsertionResult>;
-  sequentialInsert(
-    treeId: IndexedTreeId,
-    forkId: number,
-    leaves: SerializedLeafValue[],
-  ): Promise<SerializedSequentialInsertionResult>;
-  syncBlock(input: {
-    blockNumber: BlockNumber;
-    blockStateRef: BlockStateReference;
-    blockHeaderHash: Buffer;
-    paddedNoteHashes: readonly SerializedLeafValue[];
-    paddedL1ToL2Messages: readonly SerializedLeafValue[];
-    paddedNullifiers: readonly SerializedLeafValue[];
-    publicDataWrites: readonly SerializedLeafValue[];
-  }): Promise<WorldStateStatusFull>;
-  createFork(input: { latest: boolean; blockNumber: BlockNumber }): Promise<number>;
-  deleteFork(forkId: number): Promise<void>;
-  finalizeBlocks(toBlockNumber: BlockNumber): Promise<WorldStateStatusSummary>;
-  unwindBlocks(toBlockNumber: BlockNumber): Promise<WorldStateStatusFull>;
-  removeHistoricalBlocks(toBlockNumber: BlockNumber): Promise<WorldStateStatusFull>;
-  getStatus(): Promise<WorldStateStatusSummary>;
-  createCheckpoint(forkId: number): Promise<number>;
-  commitCheckpoint(forkId: number): Promise<void>;
-  revertCheckpoint(forkId: number): Promise<void>;
-  commitAllCheckpoints(forkId: number, depth: number): Promise<void>;
-  revertAllCheckpoints(forkId: number, depth: number): Promise<void>;
-  copyStores(dstPath: string, compact: boolean): Promise<void>;
+export class NativeWorldState implements NativeWorldStateInstance {
+  private open = true;
+
+  // We maintain a map of queue to fork
+  private queues = new Map<number, WorldStateOpsQueue>();
+
+  private instance: MsgpackChannel<WorldStateMessageType, WorldStateRequest, WorldStateResponse>;
+
+  /** Creates a new native WorldState instance */
+  constructor(
+    private readonly dataDir: string,
+    private readonly wsTreeMapSizes: WorldStateTreeMapSizes,
+    private readonly genesis: GenesisData = EMPTY_GENESIS_DATA,
+    private readonly instrumentation: WorldStateInstrumentation,
+    bindings?: LoggerBindings,
+    private readonly log: Logger = createLogger('world-state:database', bindings),
+    private readonly ephemeral: boolean = false,
+  ) {
+    const threads = Math.min(cpus().length, MAX_WORLD_STATE_THREADS);
+    log.info(
+      `Creating world state data store at directory ${dataDir} with map sizes ${JSON.stringify(
+        wsTreeMapSizes,
+      )} and ${threads} threads (ephemeral=${ephemeral}).`,
+    );
+    const prefilledPublicDataBufferArray = genesis.prefilledPublicData.map(d => [
+      d.slot.toBuffer(),
+      d.value.toBuffer(),
+    ]);
+    // Nullifiers to pre-insert into the genesis nullifier tree (empty by default, so production genesis roots are
+    // unchanged). The native indexed nullifier tree requires its prefilled leaves to be unique and strictly
+    // increasing, so we enforce that here before handing them over rather than failing deep inside the C++ tree
+    // construction.
+    const prefilledNullifiers = genesis.prefilledNullifiers ?? [];
+    for (let i = 1; i < prefilledNullifiers.length; i++) {
+      assert(
+        prefilledNullifiers[i].toBigInt() > prefilledNullifiers[i - 1].toBigInt(),
+        'Prefilled genesis nullifiers must be unique and strictly increasing',
+      );
+    }
+    const prefilledNullifiersBufferArray = prefilledNullifiers.map(n => n.toBuffer());
+    const ws = new BaseNativeWorldState(
+      dataDir,
+      {
+        [MerkleTreeId.NULLIFIER_TREE]: NULLIFIER_TREE_HEIGHT,
+        [MerkleTreeId.NOTE_HASH_TREE]: NOTE_HASH_TREE_HEIGHT,
+        [MerkleTreeId.PUBLIC_DATA_TREE]: PUBLIC_DATA_TREE_HEIGHT,
+        [MerkleTreeId.L1_TO_L2_MESSAGE_TREE]: L1_TO_L2_MSG_TREE_HEIGHT,
+        [MerkleTreeId.ARCHIVE]: ARCHIVE_HEIGHT,
+      },
+      {
+        [MerkleTreeId.NULLIFIER_TREE]: 2 * MAX_NULLIFIERS_PER_TX,
+        [MerkleTreeId.PUBLIC_DATA_TREE]: 2 * MAX_TOTAL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX,
+      },
+      prefilledPublicDataBufferArray,
+      prefilledNullifiersBufferArray,
+      DomainSeparator.BLOCK_HEADER_HASH,
+      Number(genesis.genesisTimestamp),
+      {
+        [MerkleTreeId.NULLIFIER_TREE]: wsTreeMapSizes.nullifierTreeMapSizeKb,
+        [MerkleTreeId.NOTE_HASH_TREE]: wsTreeMapSizes.noteHashTreeMapSizeKb,
+        [MerkleTreeId.PUBLIC_DATA_TREE]: wsTreeMapSizes.publicDataTreeMapSizeKb,
+        [MerkleTreeId.L1_TO_L2_MESSAGE_TREE]: wsTreeMapSizes.messageTreeMapSizeKb,
+        [MerkleTreeId.ARCHIVE]: wsTreeMapSizes.archiveTreeMapSizeKb,
+      },
+      threads,
+      ephemeral,
+    );
+    this.instance = new MsgpackChannel(ws);
+    // Manually create the queue for the canonical fork
+    this.queues.set(0, new WorldStateOpsQueue());
+  }
+
+  public getDataDir() {
+    return this.dataDir;
+  }
+
+  public clone() {
+    return new NativeWorldState(
+      this.dataDir,
+      this.wsTreeMapSizes,
+      this.genesis,
+      this.instrumentation,
+      this.log.getBindings(),
+      this.log,
+      this.ephemeral,
+    );
+  }
+
+  /**
+   * Gets the native WorldState handle from the underlying native instance.
+   * We call the getHandle() method on the native WorldState to get a NAPI External
+   * that wraps the underlying C++ WorldState pointer.
+   * @returns The NAPI External handle to the native WorldState instance,since
+   * the NAPI external type is opaque, we return any (we could also use an opaque symbol type)
+   */
+  public getHandle(): any {
+    const worldStateWrapper = (this.instance as any).dest;
+
+    if (!worldStateWrapper) {
+      throw new Error('No WorldStateWrapper found');
+    }
+
+    if (typeof worldStateWrapper.getHandle !== 'function') {
+      throw new Error('WorldStateWrapper does not have getHandle method');
+    }
+
+    // Call getHandle() to get the NAPI External
+    try {
+      return worldStateWrapper.getHandle();
+    } catch (error) {
+      this.log.error('Failed to get native WorldState handle', error);
+    }
+  }
 
   /**
-   * IPC path the underlying aztec-wsdb process listens on. The C++ AVM uses this to attach to the
-   * same world state instance the TS layer is using.
+   * Sends a message to the native instance and returns the response.
+   * @param messageType - The type of message to send
+   * @param body - The message body
+   * @param responseHandler - A callback accepting the response, executed on the job queue
+   * @param errorHandler - A callback called on request error, executed on the job queue
+   * @returns The response to the message
    */
-  getIpcPath(): string;
+  public async call<T extends WorldStateMessageType>(
+    messageType: T,
+    body: WorldStateRequest[T] & WorldStateRequestCategories,
+    // allows for the pre-processing of responses on the job queue before being passed back
+    responseHandler = (response: WorldStateResponse[T]): WorldStateResponse[T] => response,
+    errorHandler = (_: string) => {},
+  ): Promise<WorldStateResponse[T]> {
+    // Here we determine which fork the request is being executed against and whether it requires uncommitted data
+    // We use the fork Id to select the appropriate request queue and the uncommitted data flag to pass to the queue
+    let forkId = -1;
+    // We assume it includes uncommitted unless explicitly told otherwise
+    let committedOnly = false;
+
+    // Canonical requests ALWAYS go against the canonical fork
+    // These include things like block syncs/unwinds etc
+    // These requests don't contain a fork ID
+    if (isWithCanonical(body)) {
+      forkId = 0;
+    } else if (isWithForkId(body)) {
+      forkId = body.forkId;
+    } else if (isWithRevision(body)) {
+      forkId = body.revision.forkId;
+      committedOnly = body.revision.includeUncommitted === false;
+    } else {
+      const _: never = body;
+      throw new Error(`Unable to determine forkId for message=${WorldStateMessageType[messageType]}`);
+    }
+
+    // Get the queue or create a new one
+    let requestQueue = this.queues.get(forkId);
+    if (requestQueue === undefined) {
+      requestQueue = new WorldStateOpsQueue();
+      this.queues.set(forkId, requestQueue);
+    }
+
+    // Enqueue the request and wait for the response. The per-fork queue is cleaned up in `finally` even on
+    // error, so the JS-side queues map cannot outlive the native fork (e.g. when the native fork was already
+    // destroyed by an unwind/historical-prune and DELETE_FORK rejects with "Fork not found").
+    let shouldDeleteForkQueue = false;
+    try {
+      const response = await requestQueue.execute(
+        async () => {
+          assert.notEqual(messageType, WorldStateMessageType.CLOSE, 'Use close() to close the native instance');
+          assert.equal(this.open, true, 'Native instance is closed');
+          let response: WorldStateResponse[T];
+          try {
+            response = await this._sendMessage(messageType, body);
+          } catch (error: any) {
+            errorHandler(error.message);
+            throw error;
+          }
+          return responseHandler(response);
+        },
+        messageType,
+        committedOnly,
+      );
+      return response;
+    } catch (err: any) {
+      shouldDeleteForkQueue = forkId !== 0 && err?.message === 'Fork not found';
+      throw err;
+    } finally {
+      if (messageType === WorldStateMessageType.DELETE_FORK || shouldDeleteForkQueue) {
+        await requestQueue.stop();
+        this.queues.delete(forkId);
+      }
+    }
+  }
 
   /**
-   * Shut down the world state instance. Cancels any in-flight queues, closes the IPC channel, and
-   * terminates the underlying aztec-wsdb process. Idempotent.
+   * Stops the native instance.
    */
-  close(): Promise<void>;
+  public async close(): Promise<void> {
+    if (!this.open) {
+      return;
+    }
+    this.open = false;
+    const queue = this.queues.get(0)!;
+
+    await queue.execute(
+      async () => {
+        await this._sendMessage(WorldStateMessageType.CLOSE, { canonical: true });
+      },
+      WorldStateMessageType.CLOSE,
+      false,
+    );
+    await queue.stop();
+  }
+
+  private async _sendMessage<T extends WorldStateMessageType>(
+    messageType: T,
+    body: WorldStateRequest[T] & WorldStateRequestCategories,
+  ): Promise<WorldStateResponse[T]> {
+    let logMetadata: Record<string, any> = {};
+
+    if (body) {
+      if ('treeId' in body) {
+        logMetadata['treeId'] = MerkleTreeId[body.treeId];
+      }
+
+      if ('revision' in body) {
+        logMetadata = { ...logMetadata, ...body.revision };
+      }
+
+      if ('forkId' in body) {
+        logMetadata['forkId'] = body.forkId;
+      }
+
+      if ('blockNumber' in body) {
+        logMetadata['blockNumber'] = body.blockNumber;
+      }
+
+      if ('toBlockNumber' in body) {
+        logMetadata['toBlockNumber'] = body.toBlockNumber;
+      }
+
+      if ('leafIndex' in body) {
+        logMetadata['leafIndex'] = body.leafIndex;
+      }
+
+      if ('blockHeaderHash' in body) {
+        logMetadata['blockHeaderHash'] = '0x' + body.blockHeaderHash.toString('hex');
+      }
+
+      if ('leaves' in body) {
+        logMetadata['leavesCount'] = body.leaves.length;
+      }
+
+      // sync operation
+      if ('paddedNoteHashes' in body) {
+        logMetadata['notesCount'] = body.paddedNoteHashes.length;
+        logMetadata['nullifiersCount'] = body.paddedNullifiers.length;
+        logMetadata['l1ToL2MessagesCount'] = body.paddedL1ToL2Messages.length;
+        logMetadata['publicDataWritesCount'] = body.publicDataWrites.length;
+      }
+    }
+
+    try {
+      const { duration, response } = await this.instance.sendMessage(messageType, body);
+      this.log.trace(`Call ${WorldStateMessageType[messageType]} took (ms)`, {
+        duration,
+        ...logMetadata,
+      });
+
+      this.instrumentation.recordRoundTrip(duration.totalUs, messageType);
+      return response;
+    } catch (error) {
+      this.log.error(`Call ${WorldStateMessageType[messageType]} failed: ${error}`, error, logMetadata);
+      throw error;
+    }
+  }
 }

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.FINALIZE_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/errors.ts

@@ -1,5 +1,13 @@
+/**
+ * Thrown by {@link ServerWorldStateSynchronizer.syncImmediate} when world state cannot be synced to the requested
+ * target: either the block is not available from the block source (`block_not_available`, e.g. it was pruned away)
+ * or the synced block does not match the requested hash (`block_hash_mismatch`, i.e. a reorg). Both causes are
+ * transient from the caller's perspective: re-resolving the query against the current chain and retrying may succeed
+ * or produce a more precise error.
+ */
 export class WorldStateSynchronizerError extends Error {
   constructor(message: string, options?: ErrorOptions) {
     super(message, options);
+    this.name = 'WorldStateSynchronizerError';
   }
 }

package/src/synchronizer/factory.ts

@@ -73,6 +73,7 @@ export async function createWorldState(
         bindings,
       )
     : await NativeWorldStateService.tmp(
+        config.rollupAddress,
         !['true', '1'].includes(process.env.DEBUG_WORLD_STATE!),
         genesis,
         instrumentation,

package/src/synchronizer/index.ts

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