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

package/src/native/native_world_state.ts

@@ -3,6 +3,7 @@ import { BlockNumber } from '@aztec/foundation/branded-types';
 import { fromEntries, padArrayEnd } from '@aztec/foundation/collection';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { EthAddress } from '@aztec/foundation/eth-address';
+import { tryRmDir } from '@aztec/foundation/fs';
 import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
 import type { L2Block } from '@aztec/stdlib/block';
 import { DatabaseVersionManager } from '@aztec/stdlib/database-version/manager';
@@ -18,16 +19,16 @@ import { EMPTY_GENESIS_DATA, type GenesisData, WorldStateRevision } from '@aztec
 import { getTelemetryClient } from '@aztec/telemetry-client';
 
 import assert from 'assert/strict';
-import { mkdir, mkdtemp, rm } from 'fs/promises';
+import { mkdtemp, rm } from 'fs/promises';
 import { tmpdir } from 'os';
 import { join } from 'path';
 
 import { WorldStateInstrumentation } from '../instrumentation/instrumentation.js';
 import type { WorldStateTreeMapSizes } from '../synchronizer/factory.js';
 import type { MerkleTreeAdminDatabase as MerkleTreeDatabase } from '../world-state-db/merkle_tree_db.js';
-import { IpcWorldState } from './ipc_world_state_instance.js';
 import { MerkleTreesFacade, MerkleTreesForkFacade, serializeLeaf } from './merkle_trees_facade.js';
 import {
+  WorldStateMessageType,
   type WorldStateStatusFull,
   type WorldStateStatusSummary,
   blockStateReference,
@@ -35,7 +36,7 @@ import {
   sanitizeSummary,
   treeStateReferenceToSnapshot,
 } from './message.js';
-import type { NativeWorldStateInstance } from './native_world_state_instance.js';
+import { NativeWorldState } from './native_world_state_instance.js';
 
 // The current version of the world state database schema
 // Increment this when making incompatible changes to the database schema
@@ -43,21 +44,47 @@ export const WORLD_STATE_DB_VERSION = 2; // The initial version
 
 export const WORLD_STATE_DIR = 'world_state';
 
+const DEFAULT_TMP_TREE_MAP_SIZE_KB = 10 * 1024 * 1024;
+
+/**
+ * Sets up a fresh `mkdtemp` directory + default `WorldStateTreeMapSizes` shared by both
+ * the `.tmp` (fsync-on) and `.ephemeral` (fsync-off) factories. Returns the raw tmpdir,
+ * the tree map sizes, and the package logger.
+ */
+async function createTmpWorldStateDir(
+  bindings?: LoggerBindings,
+): Promise<{ dataDir: string; wsTreeMapSizes: WorldStateTreeMapSizes; log: Logger }> {
+  const log = createLogger('world-state:database', bindings);
+  const dataDir = await mkdtemp(join(tmpdir(), 'aztec-world-state-'));
+  const wsTreeMapSizes: WorldStateTreeMapSizes = {
+    archiveTreeMapSizeKb: DEFAULT_TMP_TREE_MAP_SIZE_KB,
+    nullifierTreeMapSizeKb: DEFAULT_TMP_TREE_MAP_SIZE_KB,
+    noteHashTreeMapSizeKb: DEFAULT_TMP_TREE_MAP_SIZE_KB,
+    messageTreeMapSizeKb: DEFAULT_TMP_TREE_MAP_SIZE_KB,
+    publicDataTreeMapSizeKb: DEFAULT_TMP_TREE_MAP_SIZE_KB,
+  };
+  log.debug(`Created temporary world state database at: ${dataDir} (map size ${DEFAULT_TMP_TREE_MAP_SIZE_KB} KB)`);
+  return { dataDir, wsTreeMapSizes, log };
+}
+
 export class NativeWorldStateService implements MerkleTreeDatabase {
   protected initialHeader: BlockHeader | undefined;
   // This is read heavily and only changes when data is persisted, so we cache it
   private cachedStatusSummary: WorldStateStatusSummary | undefined;
 
   protected constructor(
-    protected instance: NativeWorldStateInstance,
+    protected instance: NativeWorldState,
     protected readonly worldStateInstrumentation: WorldStateInstrumentation,
     protected readonly log: Logger,
     private readonly genesis: GenesisData = EMPTY_GENESIS_DATA,
     private readonly cleanup = () => Promise.resolve(),
-    /** Factory to recreate a fresh IpcWorldState after clear(). */
-    private readonly recreateInstance?: () => Promise<NativeWorldStateInstance>,
   ) {}
 
+  /**
+   * Opens a persistent world state at `dataDir`. Goes through `DatabaseVersionManager` so the
+   * caller's rollup address is bound to the on-disk schema and incompatible versions surface
+   * loudly. The LMDB envs commit with full fsync.
+   */
   static async new(
     rollupAddress: EthAddress,
     dataDir: string,
@@ -67,31 +94,28 @@ export class NativeWorldStateService implements MerkleTreeDatabase {
     bindings?: LoggerBindings,
     cleanup = () => Promise.resolve(),
   ): Promise<NativeWorldStateService> {
-    for (const [key, value] of Object.entries(wsTreeMapSizes)) {
-      if (value <= 0) {
-        throw new Error(`Map size must be a positive number, got ${value} for ${key}`);
-      }
-    }
-
     const log = createLogger('world-state:database', bindings);
     const worldStateDirectory = join(dataDir, WORLD_STATE_DIR);
-
     const versionManager = new DatabaseVersionManager({
       schemaVersion: WORLD_STATE_DB_VERSION,
       rollupAddress,
       dataDirectory: worldStateDirectory,
-      onOpen: dir => IpcWorldState.spawn(dir, wsTreeMapSizes, genesis, instrumentation, bindings),
+      onOpen: (dir: string) =>
+        Promise.resolve(
+          new NativeWorldState(
+            dir,
+            wsTreeMapSizes,
+            genesis,
+            instrumentation,
+            bindings,
+            undefined,
+            /*ephemeral=*/ false,
+          ),
+        ),
     });
 
     const [instance] = await versionManager.open();
-
-    const recreateInstance = async () => {
-      await rm(worldStateDirectory, { recursive: true, force: true, maxRetries: 3 });
-      await mkdir(worldStateDirectory, { recursive: true });
-      return IpcWorldState.spawn(worldStateDirectory, wsTreeMapSizes, genesis, instrumentation, bindings);
-    };
-
-    const worldState = new this(instance, instrumentation, log, genesis, cleanup, recreateInstance);
+    const worldState = new this(instance, instrumentation, log, genesis, cleanup);
     try {
       await worldState.init();
     } catch (e) {
@@ -102,30 +126,23 @@ export class NativeWorldStateService implements MerkleTreeDatabase {
     return worldState;
   }
 
+  /**
+   * Opens a world state in a fresh tmpdir with full fsync semantics. Use when you need the
+   * on-disk file to remain crash-recoverable (e.g. for snapshot/backup tests) but don't
+   * want a persistent dataDir. Pass `cleanupTmpDir=false` to keep the directory after
+   * close for inspection.
+   *
+   * If you don't care about crash-recoverability — i.e. you just want a fast scratch
+   * database for tests — use {@link ephemeral} instead.
+   */
   static async tmp(
+    rollupAddress = EthAddress.ZERO,
     cleanupTmpDir = true,
     genesis: GenesisData = EMPTY_GENESIS_DATA,
     instrumentation = new WorldStateInstrumentation(getTelemetryClient()),
     bindings?: LoggerBindings,
   ): Promise<NativeWorldStateService> {
-    const log = createLogger('world-state:database', bindings);
-    const dataDir = await mkdtemp(join(tmpdir(), 'aztec-world-state-'));
-    // Temporary (test/dev) world states are small and short-lived. Keep the LMDB
-    // map sizes in the MB range: with the IPC backend each tmp() spawns a separate
-    // aztec-wsdb that maps these per tree, and oversized maps add real cold-start
-    // I/O under parallel CI load. 256 MB/tree is ample for tests.
-    const dbMapSizeKb = 256 * 1024;
-    const worldStateTreeMapSizes: WorldStateTreeMapSizes = {
-      archiveTreeMapSizeKb: dbMapSizeKb,
-      nullifierTreeMapSizeKb: dbMapSizeKb,
-      noteHashTreeMapSizeKb: dbMapSizeKb,
-      messageTreeMapSizeKb: dbMapSizeKb,
-      publicDataTreeMapSizeKb: dbMapSizeKb,
-    };
-    log.debug(`Created temporary world state database at: ${dataDir} with tree map size: ${dbMapSizeKb}`);
-
-    const instance = await IpcWorldState.spawn(dataDir, worldStateTreeMapSizes, genesis, instrumentation, bindings);
-
+    const { dataDir, wsTreeMapSizes, log } = await createTmpWorldStateDir(bindings);
     const cleanup = async () => {
       if (cleanupTmpDir) {
         await rm(dataDir, { recursive: true, force: true, maxRetries: 3 });
@@ -134,46 +151,47 @@ export class NativeWorldStateService implements MerkleTreeDatabase {
         log.debug(`Leaving temporary world state database: ${dataDir}`);
       }
     };
+    return this.new(rollupAddress, dataDir, wsTreeMapSizes, genesis, instrumentation, bindings, cleanup);
+  }
 
-    const recreateInstance = async () => {
+  /**
+   * Opens a fully-ephemeral world state. The directory is created in `os.tmpdir()`, the LMDB
+   * envs open with `MDB_NOSYNC | MDB_NOMETASYNC` so commits never block on fsync, and the
+   * directory is removed on dispose. A crash mid-write leaves the env unrecoverable.
+   *
+   * For unit tests and other isolated runs. Use {@link tmp} when you need fsync semantics in a
+   * tmp dir, and {@link new} for a persistent store. Skips {@link DatabaseVersionManager} —
+   * there is no on-disk schema to bind to and no rollup address is taken.
+   */
+  static async ephemeral(
+    genesis: GenesisData = EMPTY_GENESIS_DATA,
+    instrumentation = new WorldStateInstrumentation(getTelemetryClient()),
+    bindings?: LoggerBindings,
+  ): Promise<NativeWorldStateService> {
+    const { dataDir, wsTreeMapSizes, log } = await createTmpWorldStateDir(bindings);
+    const cleanup = async () => {
       await rm(dataDir, { recursive: true, force: true, maxRetries: 3 });
-      await mkdir(dataDir, { recursive: true });
-      return IpcWorldState.spawn(dataDir, worldStateTreeMapSizes, genesis, instrumentation, bindings);
+      log.debug(`Deleted ephemeral world state database: ${dataDir}`);
     };
-
-    const worldState = new this(instance, instrumentation, log, genesis, cleanup, recreateInstance);
+    const instance = new NativeWorldState(
+      join(dataDir, WORLD_STATE_DIR),
+      wsTreeMapSizes,
+      genesis,
+      instrumentation,
+      bindings,
+      undefined,
+      /*ephemeral=*/ true,
+    );
+    const worldState = new this(instance, instrumentation, log, genesis, cleanup);
     try {
       await worldState.init();
     } catch (e) {
-      log.error(`Error initializing tmp world state: ${e}`);
+      log.error(`Error initializing ephemeral world state: ${e}`);
       throw e;
     }
     return worldState;
   }
 
-  static ephemeral(
-    genesis: GenesisData = EMPTY_GENESIS_DATA,
-    instrumentation = new WorldStateInstrumentation(getTelemetryClient()),
-    bindings?: LoggerBindings,
-  ): Promise<NativeWorldStateService> {
-    return this.tmp(/*cleanupTmpDir=*/ true, genesis, instrumentation, bindings);
-  }
-
-  static async fromIpc(
-    wsdbBackend: ConstructorParameters<typeof IpcWorldState>[0],
-    instrumentation = new WorldStateInstrumentation(getTelemetryClient()),
-    bindings?: LoggerBindings,
-    genesis: GenesisData = EMPTY_GENESIS_DATA,
-    cleanup = () => Promise.resolve(),
-    recreateInstance?: () => Promise<NativeWorldStateInstance>,
-  ): Promise<NativeWorldStateService> {
-    const log = createLogger('world-state:database', bindings);
-    const instance = new IpcWorldState(wsdbBackend, instrumentation, bindings);
-    const worldState = new this(instance, instrumentation, log, genesis, cleanup, recreateInstance);
-    await worldState.init();
-    return worldState;
-  }
-
   protected async init() {
     const status = await this.getStatusSummary();
     if (!status.treesAreSynched) {
@@ -195,24 +213,11 @@ export class NativeWorldStateService implements MerkleTreeDatabase {
     assert.strictEqual(initialHeaderIndex, 0n, 'Invalid initial archive state');
   }
 
-  public async clear(): Promise<void> {
-    if (!this.recreateInstance) {
-      throw new Error('clear() is not available for externally-managed IPC backends');
-    }
-    this.log.warn('Clearing world state: shutting down WSDB, deleting data, and recreating');
+  public async clear() {
     await this.instance.close();
     this.cachedStatusSummary = undefined;
-    this.instance = await this.recreateInstance();
-    await this.init();
-    this.log.info('World state cleared and reinitialized from genesis');
-  }
-
-  /** Returns the IPC path of the underlying IPC backend, if available. */
-  public getIpcPath(): string {
-    if (this.instance instanceof IpcWorldState) {
-      return this.instance.getIpcPath();
-    }
-    throw new Error('getIpcPath() is only available with IPC world state');
+    await tryRmDir(this.instance.getDataDir(), this.log);
+    this.instance = this.instance.clone();
   }
 
   public getCommitted(): MerkleTreeReadOperations {
@@ -231,15 +236,16 @@ export class NativeWorldStateService implements MerkleTreeDatabase {
     blockNumber?: BlockNumber,
     opts: { closeDelayMs?: number } = {},
   ): Promise<MerkleTreeWriteOperations> {
-    const forkId = await this.instance.createFork({
+    const resp = await this.instance.call(WorldStateMessageType.CREATE_FORK, {
       latest: blockNumber === undefined,
       blockNumber: blockNumber ?? BlockNumber.ZERO,
+      canonical: true,
     });
     return new MerkleTreesForkFacade(
       this.instance,
       this.initialHeader!,
       new WorldStateRevision(
-        /*forkId=*/ forkId,
+        /*forkId=*/ resp.forkId,
         /* blockNumber=*/ WorldStateRevision.LATEST,
         /* includeUncommitted=*/ true,
       ),
@@ -283,33 +289,33 @@ export class NativeWorldStateService implements MerkleTreeDatabase {
     });
 
     try {
-      const status = await this.instance.syncBlock({
-        blockNumber: l2Block.number,
-        blockHeaderHash: (await l2Block.hash()).toBuffer(),
-        paddedL1ToL2Messages: paddedL1ToL2Messages.map(serializeLeaf),
-        paddedNoteHashes: paddedNoteHashes.map(serializeLeaf),
-        paddedNullifiers: paddedNullifiers.map(serializeLeaf),
-        publicDataWrites: publicDataWrites.map(serializeLeaf),
-        blockStateRef: blockStateReference(l2Block.header.state),
-      });
-      return this.sanitizeAndCacheSummaryFromFull(status);
+      return await this.instance.call(
+        WorldStateMessageType.SYNC_BLOCK,
+        {
+          blockNumber: l2Block.number,
+          blockHeaderHash: (await l2Block.hash()).toBuffer(),
+          // Forwarded so the native sync verifies the archive root against canonical and rejects a divergent tree.
+          expectedArchiveRoot: l2Block.archive.root.toBuffer(),
+          expectedPreviousArchiveRoot: l2Block.header.lastArchive.root.toBuffer(),
+          paddedL1ToL2Messages: paddedL1ToL2Messages.map(serializeLeaf),
+          paddedNoteHashes: paddedNoteHashes.map(serializeLeaf),
+          paddedNullifiers: paddedNullifiers.map(serializeLeaf),
+          publicDataWrites: publicDataWrites.map(serializeLeaf),
+          blockStateRef: blockStateReference(l2Block.header.state),
+          canonical: true,
+        },
+        this.sanitizeAndCacheSummaryFromFull.bind(this),
+        this.deleteCachedSummary.bind(this),
+      );
     } catch (err) {
-      this.deleteCachedSummary();
       this.worldStateInstrumentation.incCriticalErrors('synch_pending_block');
       throw err;
     }
   }
 
   public async close(): Promise<void> {
-    try {
-      await this.instance.close();
-    } finally {
-      await this.cleanup();
-    }
-  }
-
-  async [Symbol.asyncDispose](): Promise<void> {
-    await this.close();
+    await this.instance.close();
+    await this.cleanup();
   }
 
   private async buildInitialHeader(): Promise<BlockHeader> {
@@ -332,7 +338,7 @@ export class NativeWorldStateService implements MerkleTreeDatabase {
     return sanitized;
   }
 
-  private deleteCachedSummary() {
+  private deleteCachedSummary(_: string) {
     this.cachedStatusSummary = undefined;
   }
 
@@ -343,9 +349,16 @@ export class NativeWorldStateService implements MerkleTreeDatabase {
    */
   public async setFinalized(toBlockNumber: BlockNumber) {
     try {
-      this.sanitizeAndCacheSummary(await this.instance.finalizeBlocks(toBlockNumber));
+      await this.instance.call(
+        WorldStateMessageType.FINALIZE_BLOCKS,
+        {
+          toBlockNumber,
+          canonical: true,
+        },
+        this.sanitizeAndCacheSummary.bind(this),
+        this.deleteCachedSummary.bind(this),
+      );
     } catch (err) {
-      this.deleteCachedSummary();
       this.worldStateInstrumentation.incCriticalErrors('finalize_block');
       throw err;
     }
@@ -359,9 +372,16 @@ export class NativeWorldStateService implements MerkleTreeDatabase {
    */
   public async removeHistoricalBlocks(toBlockNumber: BlockNumber) {
     try {
-      return this.sanitizeAndCacheSummaryFromFull(await this.instance.removeHistoricalBlocks(toBlockNumber));
+      return await this.instance.call(
+        WorldStateMessageType.REMOVE_HISTORICAL_BLOCKS,
+        {
+          toBlockNumber,
+          canonical: true,
+        },
+        this.sanitizeAndCacheSummaryFromFull.bind(this),
+        this.deleteCachedSummary.bind(this),
+      );
     } catch (err) {
-      this.deleteCachedSummary();
       this.worldStateInstrumentation.incCriticalErrors('prune_historical_block');
       throw err;
     }
@@ -374,9 +394,16 @@ export class NativeWorldStateService implements MerkleTreeDatabase {
    */
   public async unwindBlocks(toBlockNumber: BlockNumber) {
     try {
-      return this.sanitizeAndCacheSummaryFromFull(await this.instance.unwindBlocks(toBlockNumber));
+      return await this.instance.call(
+        WorldStateMessageType.UNWIND_BLOCKS,
+        {
+          toBlockNumber,
+          canonical: true,
+        },
+        this.sanitizeAndCacheSummaryFromFull.bind(this),
+        this.deleteCachedSummary.bind(this),
+      );
     } catch (err) {
-      this.deleteCachedSummary();
       this.worldStateInstrumentation.incCriticalErrors('prune_pending_block');
       throw err;
     }
@@ -386,7 +413,11 @@ export class NativeWorldStateService implements MerkleTreeDatabase {
     if (this.cachedStatusSummary !== undefined) {
       return { ...this.cachedStatusSummary };
     }
-    return this.sanitizeAndCacheSummary(await this.instance.getStatus());
+    return await this.instance.call(
+      WorldStateMessageType.GET_STATUS,
+      { canonical: true },
+      this.sanitizeAndCacheSummary.bind(this),
+    );
   }
 
   updateLeaf<ID extends IndexedTreeId>(
@@ -398,14 +429,14 @@ export class NativeWorldStateService implements MerkleTreeDatabase {
   }
 
   private async getInitialStateReference(): Promise<StateReference> {
-    const state = await this.instance.getInitialStateReference();
+    const resp = await this.instance.call(WorldStateMessageType.GET_INITIAL_STATE_REFERENCE, { canonical: true });
 
     return new StateReference(
-      treeStateReferenceToSnapshot(state[MerkleTreeId.L1_TO_L2_MESSAGE_TREE]),
+      treeStateReferenceToSnapshot(resp.state[MerkleTreeId.L1_TO_L2_MESSAGE_TREE]),
       new PartialStateReference(
-        treeStateReferenceToSnapshot(state[MerkleTreeId.NOTE_HASH_TREE]),
-        treeStateReferenceToSnapshot(state[MerkleTreeId.NULLIFIER_TREE]),
-        treeStateReferenceToSnapshot(state[MerkleTreeId.PUBLIC_DATA_TREE]),
+        treeStateReferenceToSnapshot(resp.state[MerkleTreeId.NOTE_HASH_TREE]),
+        treeStateReferenceToSnapshot(resp.state[MerkleTreeId.NULLIFIER_TREE]),
+        treeStateReferenceToSnapshot(resp.state[MerkleTreeId.PUBLIC_DATA_TREE]),
       ),
     );
   }
@@ -414,7 +445,11 @@ export class NativeWorldStateService implements MerkleTreeDatabase {
     dstPath: string,
     compact: boolean = true,
   ): Promise<Record<Exclude<SnapshotDataKeys, 'archiver'>, string>> {
-    await this.instance.copyStores(dstPath, compact);
+    await this.instance.call(WorldStateMessageType.COPY_STORES, {
+      dstPath,
+      compact,
+      canonical: true,
+    });
     return fromEntries(NATIVE_WORLD_STATE_DBS.map(([name, dir]) => [name, join(dstPath, dir, 'data.mdb')] as const));
   }
 }