@aztec/world-state 0.0.0-test.0

package/src/native/native_world_state.ts

@@ -0,0 +1,317 @@
+import { MAX_NOTE_HASHES_PER_TX, MAX_NULLIFIERS_PER_TX, NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP } from '@aztec/constants';
+import { padArrayEnd } from '@aztec/foundation/collection';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { Fr } from '@aztec/foundation/fields';
+import { createLogger } from '@aztec/foundation/log';
+import type { L2Block } from '@aztec/stdlib/block';
+import { DatabaseVersionManager } from '@aztec/stdlib/database-version';
+import type {
+  IndexedTreeId,
+  MerkleTreeReadOperations,
+  MerkleTreeWriteOperations,
+} from '@aztec/stdlib/interfaces/server';
+import { MerkleTreeId, NullifierLeaf, type NullifierLeafPreimage, PublicDataTreeLeaf } from '@aztec/stdlib/trees';
+import { BlockHeader, PartialStateReference, StateReference } from '@aztec/stdlib/tx';
+import { getTelemetryClient } from '@aztec/telemetry-client';
+
+import assert from 'assert/strict';
+import { mkdtemp, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+import { WorldStateInstrumentation } from '../instrumentation/instrumentation.js';
+import type { MerkleTreeAdminDatabase as MerkleTreeDatabase } from '../world-state-db/merkle_tree_db.js';
+import { MerkleTreesFacade, MerkleTreesForkFacade, serializeLeaf } from './merkle_trees_facade.js';
+import {
+  WorldStateMessageType,
+  type WorldStateStatusFull,
+  type WorldStateStatusSummary,
+  blockStateReference,
+  sanitiseFullStatus,
+  sanitiseSummary,
+  treeStateReferenceToSnapshot,
+  worldStateRevision,
+} from './message.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
+export const WORLD_STATE_DB_VERSION = 1; // The initial version
+
+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 readonly instance: NativeWorldState,
+    protected readonly worldStateInstrumentation: WorldStateInstrumentation,
+    protected readonly log = createLogger('world-state:database'),
+    private readonly cleanup = () => Promise.resolve(),
+  ) {}
+
+  static async new(
+    rollupAddress: EthAddress,
+    dataDir: string,
+    dbMapSizeKb: number,
+    prefilledPublicData: PublicDataTreeLeaf[] = [],
+    instrumentation = new WorldStateInstrumentation(getTelemetryClient()),
+    log = createLogger('world-state:database'),
+    cleanup = () => Promise.resolve(),
+  ): Promise<NativeWorldStateService> {
+    const worldStateDirectory = join(dataDir, 'world_state');
+    // Create a version manager to handle versioning
+    const versionManager = new DatabaseVersionManager(
+      WORLD_STATE_DB_VERSION,
+      rollupAddress,
+      worldStateDirectory,
+      (dir: string) => {
+        return Promise.resolve(new NativeWorldState(dir, dbMapSizeKb, prefilledPublicData, instrumentation));
+      },
+    );
+
+    const [instance] = await versionManager.open();
+    const worldState = new this(instance, instrumentation, log, cleanup);
+    try {
+      await worldState.init();
+    } catch (e) {
+      log.error(`Error initialising world state: ${e}`);
+      throw e;
+    }
+
+    return worldState;
+  }
+
+  static async tmp(
+    rollupAddress = EthAddress.ZERO,
+    cleanupTmpDir = true,
+    prefilledPublicData: PublicDataTreeLeaf[] = [],
+    instrumentation = new WorldStateInstrumentation(getTelemetryClient()),
+  ): Promise<NativeWorldStateService> {
+    const log = createLogger('world-state:database');
+    const dataDir = await mkdtemp(join(tmpdir(), 'aztec-world-state-'));
+    const dbMapSizeKb = 10 * 1024 * 1024;
+    log.debug(`Created temporary world state database at: ${dataDir} with size: ${dbMapSizeKb}`);
+
+    // pass a cleanup callback because process.on('beforeExit', cleanup) does not work under Jest
+    const cleanup = async () => {
+      if (cleanupTmpDir) {
+        await rm(dataDir, { recursive: true, force: true, maxRetries: 3 });
+        log.debug(`Deleted temporary world state database: ${dataDir}`);
+      } else {
+        log.debug(`Leaving temporary world state database: ${dataDir}`);
+      }
+    };
+
+    return this.new(rollupAddress, dataDir, dbMapSizeKb, prefilledPublicData, instrumentation, log, cleanup);
+  }
+
+  protected async init() {
+    const status = await this.getStatusSummary();
+    if (!status.treesAreSynched) {
+      throw new Error('World state trees are out of sync, please delete your data directory and re-sync');
+    }
+    this.initialHeader = await this.buildInitialHeader();
+    const committed = this.getCommitted();
+
+    // validate the initial state
+    const archive = await committed.getTreeInfo(MerkleTreeId.ARCHIVE);
+    if (archive.size === 0n) {
+      throw new Error("Archive tree can't be empty");
+    }
+
+    // the initial header _must_ be the first element in the archive tree
+    // if this assertion fails, check that the hashing done in Header in yarn-project matches the initial header hash done in world_state.cpp
+    const indices = await committed.findLeafIndices(MerkleTreeId.ARCHIVE, [await this.initialHeader.hash()]);
+    const initialHeaderIndex = indices[0];
+    assert.strictEqual(initialHeaderIndex, 0n, 'Invalid initial archive state');
+  }
+
+  public getCommitted(): MerkleTreeReadOperations {
+    return new MerkleTreesFacade(this.instance, this.initialHeader!, worldStateRevision(false, 0, 0));
+  }
+
+  public getSnapshot(blockNumber: number): MerkleTreeReadOperations {
+    return new MerkleTreesFacade(this.instance, this.initialHeader!, worldStateRevision(false, 0, blockNumber));
+  }
+
+  public async fork(blockNumber?: number): Promise<MerkleTreeWriteOperations> {
+    const resp = await this.instance.call(WorldStateMessageType.CREATE_FORK, {
+      latest: blockNumber === undefined,
+      blockNumber: blockNumber ?? 0,
+      canonical: true,
+    });
+    return new MerkleTreesForkFacade(this.instance, this.initialHeader!, worldStateRevision(true, resp.forkId, 0));
+  }
+
+  public getInitialHeader(): BlockHeader {
+    return this.initialHeader!;
+  }
+
+  public async handleL2BlockAndMessages(l2Block: L2Block, l1ToL2Messages: Fr[]): Promise<WorldStateStatusFull> {
+    // We have to pad both the values within tx effects because that's how the trees are built by circuits.
+    const paddedNoteHashes = l2Block.body.txEffects.flatMap(txEffect =>
+      padArrayEnd(txEffect.noteHashes, Fr.ZERO, MAX_NOTE_HASHES_PER_TX),
+    );
+    const paddedL1ToL2Messages = padArrayEnd(l1ToL2Messages, Fr.ZERO, NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP);
+
+    const paddedNullifiers = l2Block.body.txEffects
+      .flatMap(txEffect => padArrayEnd(txEffect.nullifiers, Fr.ZERO, MAX_NULLIFIERS_PER_TX))
+      .map(nullifier => new NullifierLeaf(nullifier));
+
+    const publicDataWrites: PublicDataTreeLeaf[] = l2Block.body.txEffects.flatMap(txEffect => {
+      return txEffect.publicDataWrites.map(write => {
+        if (write.isEmpty()) {
+          throw new Error('Public data write must not be empty when syncing');
+        }
+        return new PublicDataTreeLeaf(write.leafSlot, write.value);
+      });
+    });
+
+    try {
+      return await this.instance.call(
+        WorldStateMessageType.SYNC_BLOCK,
+        {
+          blockNumber: l2Block.number,
+          blockHeaderHash: await l2Block.header.hash(),
+          paddedL1ToL2Messages: paddedL1ToL2Messages.map(serializeLeaf),
+          paddedNoteHashes: paddedNoteHashes.map(serializeLeaf),
+          paddedNullifiers: paddedNullifiers.map(serializeLeaf),
+          publicDataWrites: publicDataWrites.map(serializeLeaf),
+          blockStateRef: blockStateReference(l2Block.header.state),
+          canonical: true,
+        },
+        this.sanitiseAndCacheSummaryFromFull.bind(this),
+        this.deleteCachedSummary.bind(this),
+      );
+    } catch (err) {
+      this.worldStateInstrumentation.incCriticalErrors('synch_pending_block');
+      throw err;
+    }
+  }
+
+  public async close(): Promise<void> {
+    await this.instance.close();
+    await this.cleanup();
+  }
+
+  private async buildInitialHeader(): Promise<BlockHeader> {
+    const state = await this.getInitialStateReference();
+    return BlockHeader.empty({ state });
+  }
+
+  private sanitiseAndCacheSummaryFromFull(response: WorldStateStatusFull) {
+    const sanitised = sanitiseFullStatus(response);
+    this.cachedStatusSummary = { ...sanitised.summary };
+    return sanitised;
+  }
+
+  private sanitiseAndCacheSummary(response: WorldStateStatusSummary) {
+    const sanitised = sanitiseSummary(response);
+    this.cachedStatusSummary = { ...sanitised };
+    return sanitised;
+  }
+
+  private deleteCachedSummary(_: string) {
+    this.cachedStatusSummary = undefined;
+  }
+
+  /**
+   * Advances the finalised block number to be the number provided
+   * @param toBlockNumber The block number that is now the tip of the finalised chain
+   * @returns The new WorldStateStatus
+   */
+  public async setFinalised(toBlockNumber: bigint) {
+    try {
+      await this.instance.call(
+        WorldStateMessageType.FINALISE_BLOCKS,
+        {
+          toBlockNumber,
+          canonical: true,
+        },
+        this.sanitiseAndCacheSummary.bind(this),
+        this.deleteCachedSummary.bind(this),
+      );
+    } catch (err) {
+      this.worldStateInstrumentation.incCriticalErrors('finalize_block');
+      throw err;
+    }
+    return this.getStatusSummary();
+  }
+
+  /**
+   * Removes all historical snapshots up to but not including the given block number
+   * @param toBlockNumber The block number of the new oldest historical block
+   * @returns The new WorldStateStatus
+   */
+  public async removeHistoricalBlocks(toBlockNumber: bigint) {
+    try {
+      return await this.instance.call(
+        WorldStateMessageType.REMOVE_HISTORICAL_BLOCKS,
+        {
+          toBlockNumber,
+          canonical: true,
+        },
+        this.sanitiseAndCacheSummaryFromFull.bind(this),
+        this.deleteCachedSummary.bind(this),
+      );
+    } catch (err) {
+      this.worldStateInstrumentation.incCriticalErrors('prune_historical_block');
+      throw err;
+    }
+  }
+
+  /**
+   * Removes all pending blocks down to but not including the given block number
+   * @param toBlockNumber The block number of the new tip of the pending chain,
+   * @returns The new WorldStateStatus
+   */
+  public async unwindBlocks(toBlockNumber: bigint) {
+    try {
+      return await this.instance.call(
+        WorldStateMessageType.UNWIND_BLOCKS,
+        {
+          toBlockNumber,
+          canonical: true,
+        },
+        this.sanitiseAndCacheSummaryFromFull.bind(this),
+        this.deleteCachedSummary.bind(this),
+      );
+    } catch (err) {
+      this.worldStateInstrumentation.incCriticalErrors('prune_pending_block');
+      throw err;
+    }
+  }
+
+  public async getStatusSummary() {
+    if (this.cachedStatusSummary !== undefined) {
+      return { ...this.cachedStatusSummary };
+    }
+    return await this.instance.call(
+      WorldStateMessageType.GET_STATUS,
+      { canonical: true },
+      this.sanitiseAndCacheSummary.bind(this),
+    );
+  }
+
+  updateLeaf<ID extends IndexedTreeId>(
+    _treeId: ID,
+    _leaf: NullifierLeafPreimage | Buffer,
+    _index: bigint,
+  ): Promise<void> {
+    return Promise.reject(new Error('Method not implemented'));
+  }
+
+  private async getInitialStateReference(): Promise<StateReference> {
+    const resp = await this.instance.call(WorldStateMessageType.GET_INITIAL_STATE_REFERENCE, { canonical: true });
+
+    return new StateReference(
+      treeStateReferenceToSnapshot(resp.state[MerkleTreeId.L1_TO_L2_MESSAGE_TREE]),
+      new PartialStateReference(
+        treeStateReferenceToSnapshot(resp.state[MerkleTreeId.NOTE_HASH_TREE]),
+        treeStateReferenceToSnapshot(resp.state[MerkleTreeId.NULLIFIER_TREE]),
+        treeStateReferenceToSnapshot(resp.state[MerkleTreeId.PUBLIC_DATA_TREE]),
+      ),
+    );
+  }
+}

package/src/native/native_world_state_instance.ts

@@ -0,0 +1,238 @@
+import {
+  ARCHIVE_HEIGHT,
+  GeneratorIndex,
+  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 { createLogger } from '@aztec/foundation/log';
+import { NativeWorldState as BaseNativeWorldState, MsgpackChannel } from '@aztec/native';
+import { MerkleTreeId } from '@aztec/stdlib/trees';
+import type { PublicDataTreeLeaf } from '@aztec/stdlib/trees';
+
+import assert from 'assert';
+import { cpus } from 'os';
+
+import type { WorldStateInstrumentation } from '../instrumentation/instrumentation.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]>;
+}
+
+/**
+ * Strongly-typed interface to access the WorldState class in the native world_state_napi module.
+ */
+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(
+    dataDir: string,
+    dbMapSizeKb: number,
+    prefilledPublicData: PublicDataTreeLeaf[] = [],
+    private instrumentation: WorldStateInstrumentation,
+    private log = createLogger('world-state:database'),
+  ) {
+    const threads = Math.min(cpus().length, MAX_WORLD_STATE_THREADS);
+    log.info(
+      `Creating world state data store at directory ${dataDir} with map size ${dbMapSizeKb} KB and ${threads} threads.`,
+    );
+    const prefilledPublicDataBufferArray = prefilledPublicData.map(d => [d.slot.toBuffer(), d.value.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,
+      GeneratorIndex.BLOCK_HASH,
+      dbMapSizeKb,
+      threads,
+    );
+    this.instance = new MsgpackChannel(ws);
+    // Manually create the queue for the canonical fork
+    this.queues.set(0, new WorldStateOpsQueue());
+  }
+
+  /**
+   * 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
+   */
+  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
+    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,
+    );
+
+    // If the request was to delete the fork then we clean it up here
+    if (messageType === WorldStateMessageType.DELETE_FORK) {
+      await requestQueue.stop();
+      this.queues.delete(forkId);
+    }
+    return response;
+  }
+
+  /**
+   * Stops the native instance.
+   */
+  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;
+    }
+  }
+}