@aztec/world-state 0.57.0 → 0.59.0

package/src/world-state-db/merkle_tree_db.ts

@@ -1,8 +1,10 @@
-import { type MerkleTreeId } from '@aztec/circuit-types';
-import { type MerkleTreeAdminOperations, type MerkleTreeOperations } from '@aztec/circuit-types/interfaces';
+import { type L2Block, type MerkleTreeId } from '@aztec/circuit-types';
+import { type MerkleTreeReadOperations, type MerkleTreeWriteOperations } from '@aztec/circuit-types/interfaces';
 import { type Fr, MAX_NULLIFIERS_PER_TX, MAX_TOTAL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX } from '@aztec/circuits.js';
 import { type IndexedTreeSnapshot, type TreeSnapshot } from '@aztec/merkle-tree';
 
+import { type WorldStateStatus } from '../native/message.js';
+
 /**
  *
  * @remarks Short explanation:
@@ -22,20 +24,6 @@ export const INITIAL_NULLIFIER_TREE_SIZE = 2 * MAX_NULLIFIERS_PER_TX;
 
 export const INITIAL_PUBLIC_DATA_TREE_SIZE = 2 * MAX_TOTAL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX;
 
-/**
- * Adds a last boolean flag in each function on the type.
- */
-type WithIncludeUncommitted<F> = F extends (...args: [...infer Rest]) => infer Return
-  ? (...args: [...Rest, boolean]) => Return
-  : F;
-
-/**
- * Defines the names of the setters on Merkle Trees.
- */
-type MerkleTreeSetters = 'appendLeaves' | 'updateLeaf' | 'batchInsert';
-
-type MerkleTreeAdmin = 'commit' | 'rollback' | 'handleL2BlockAndMessages';
-
 export type TreeSnapshots = {
   [MerkleTreeId.NULLIFIER_TREE]: IndexedTreeSnapshot;
   [MerkleTreeId.NOTE_HASH_TREE]: TreeSnapshot<Fr>;
@@ -44,40 +32,58 @@ export type TreeSnapshots = {
   [MerkleTreeId.ARCHIVE]: TreeSnapshot<Fr>;
 };
 
-/** Defines the interface for operations on a set of Merkle Trees configuring whether to return committed or uncommitted data. */
-export type MerkleTreeDb = {
-  [Property in keyof MerkleTreeOperations as Exclude<Property, MerkleTreeSetters>]: WithIncludeUncommitted<
-    MerkleTreeOperations[Property]
-  >;
-} & Pick<MerkleTreeOperations, MerkleTreeSetters> & {
-    /**
-     * Returns a snapshot of the current state of the trees.
-     * @param block - The block number to take the snapshot at.
-     */
-    getSnapshot(block: number): Promise<TreeSnapshots>;
-  };
+export interface MerkleTreeAdminDatabase {
+  /**
+   * Handles a single L2 block (i.e. Inserts the new note hashes into the merkle tree).
+   * @param block - The L2 block to handle.
+   * @param l1ToL2Messages - The L1 to L2 messages for the block.
+   */
+  handleL2BlockAndMessages(block: L2Block, l1ToL2Messages: Fr[]): Promise<WorldStateStatus>;
+
+  /**
+   * Gets a handle that allows reading the latest committed state
+   */
+  getCommitted(): MerkleTreeReadOperations;
+
+  /**
+   * Gets a handle that allows reading the state as it was at the given block number
+   * @param blockNumber - The block number to get the snapshot for
+   */
+  getSnapshot(blockNumber: number): MerkleTreeReadOperations;
+
+  /**
+   * Forks the database at its current state.
+   * @param blockNumber - The block number to fork at. If not provided, the current block number is used.
+   */
+  fork(blockNumber?: number): Promise<MerkleTreeWriteOperations>;
+
+  /**
+   * 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
+   */
+  removeHistoricalBlocks(toBlockNumber: bigint): Promise<WorldStateStatus>;
 
-/** Extends operations on MerkleTreeDb to include modifying the underlying store */
-export type MerkleTreeAdminDb = {
-  [Property in keyof MerkleTreeAdminOperations as Exclude<
-    Property,
-    MerkleTreeSetters | MerkleTreeAdmin
-  >]: WithIncludeUncommitted<MerkleTreeAdminOperations[Property]>;
-} & Pick<MerkleTreeAdminOperations, MerkleTreeSetters | MerkleTreeAdmin> & {
-    /**
-     * Returns a snapshot of the current state of the trees.
-     * @param block - The block number to take the snapshot at.
-     */
-    getSnapshot(block: number): Promise<TreeSnapshots>;
+  /**
+   * 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
+   */
+  unwindBlocks(toBlockNumber: bigint): Promise<WorldStateStatus>;
 
-    /**
-     * Forks the database at its current state.
-     */
-    fork(): Promise<MerkleTreeDb>;
+  /**
+   * 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
+   */
+  setFinalised(toBlockNumber: bigint): Promise<WorldStateStatus>;
 
-    /** Deletes this database. */
-    delete(): Promise<void>;
+  /**
+   * Gets the current status of the database.
+   * @returns The current WorldStateStatus.
+   */
+  getStatus(): Promise<WorldStateStatus>;
 
-    /** Stops the database */
-    stop(): Promise<void>;
-  };
+  /** Stops the database */
+  close(): Promise<void>;
+}

package/src/world-state-db/merkle_tree_operations_facade.ts

@@ -1,22 +1,20 @@
-import { type BatchInsertionResult, type L2Block, type MerkleTreeId, type SiblingPath } from '@aztec/circuit-types';
+import { type BatchInsertionResult, type MerkleTreeId, type SiblingPath } from '@aztec/circuit-types';
 import {
-  type HandleL2BlockAndMessagesResult,
   type IndexedTreeId,
-  type MerkleTreeAdminOperations,
   type MerkleTreeLeafType,
-  type MerkleTreeOperations,
+  type MerkleTreeWriteOperations,
   type TreeInfo,
 } from '@aztec/circuit-types/interfaces';
-import { type Fr, type Header, type NullifierLeafPreimage, type StateReference } from '@aztec/circuits.js';
+import { type Header, type StateReference } from '@aztec/circuits.js';
 import { type IndexedTreeLeafPreimage } from '@aztec/foundation/trees';
 
-import { type MerkleTreeAdminDb, type MerkleTreeDb } from './merkle_tree_db.js';
+import { type MerkleTrees } from './merkle_trees.js';
 
 /**
  * Wraps a MerkleTreeDbOperations to call all functions with a preset includeUncommitted flag.
  */
-export class MerkleTreeOperationsFacade implements MerkleTreeOperations {
-  constructor(protected trees: MerkleTreeDb, protected includeUncommitted: boolean) {}
+export class MerkleTreeReadOperationsFacade implements MerkleTreeWriteOperations {
+  constructor(protected trees: MerkleTrees, protected includeUncommitted: boolean) {}
 
   /**
    * Returns the tree info for the specified tree id.
@@ -41,7 +39,7 @@ export class MerkleTreeOperationsFacade implements MerkleTreeOperations {
    * @returns The initial header.
    */
   getInitialHeader(): Header {
-    return this.trees.getInitialHeader(this.includeUncommitted);
+    return this.trees.getInitialHeader();
   }
 
   /**
@@ -91,17 +89,6 @@ export class MerkleTreeOperationsFacade implements MerkleTreeOperations {
     return this.trees.getPreviousValueIndex(treeId, value, this.includeUncommitted);
   }
 
-  /**
-   * Updates a leaf in a tree at a given index.
-   * @param treeId - The ID of the tree.
-   * @param leaf - The new leaf value.
-   * @param index - The index to insert into.
-   * @returns Empty promise.
-   */
-  updateLeaf<ID extends IndexedTreeId>(treeId: ID, leaf: NullifierLeafPreimage, index: bigint): Promise<void> {
-    return this.trees.updateLeaf(treeId, leaf, index);
-  }
-
   /**
    * Gets the leaf data at a given index and tree.
    * @param treeId - The ID of the tree get the leaf from.
@@ -162,7 +149,7 @@ export class MerkleTreeOperationsFacade implements MerkleTreeOperations {
    * @param header - The header to insert into the archive.
    */
   public updateArchive(header: Header): Promise<void> {
-    return this.trees.updateArchive(header, this.includeUncommitted);
+    return this.trees.updateArchive(header);
   }
 
   /**
@@ -179,40 +166,8 @@ export class MerkleTreeOperationsFacade implements MerkleTreeOperations {
   ): Promise<BatchInsertionResult<TreeHeight, SubtreeSiblingPathHeight>> {
     return this.trees.batchInsert(treeId, leaves, subtreeHeight);
   }
-}
-
-export class MerkleTreeAdminOperationsFacade extends MerkleTreeOperationsFacade implements MerkleTreeAdminOperations {
-  constructor(protected override trees: MerkleTreeAdminDb, includeUncommitted: boolean) {
-    super(trees, includeUncommitted);
-  }
-
-  /**
-   * Handles a single L2 block (i.e. Inserts the new note hashes into the merkle tree).
-   * @param block - 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.
-   */
-  public handleL2BlockAndMessages(block: L2Block, l1ToL2Messages: Fr[]): Promise<HandleL2BlockAndMessagesResult> {
-    return this.trees.handleL2BlockAndMessages(block, l1ToL2Messages);
-  }
-
-  /**
-   * Commits all pending updates.
-   * @returns Empty promise.
-   */
-  public async commit(): Promise<void> {
-    return await this.trees.commit();
-  }
-
-  /**
-   * Rolls back all pending updates.
-   * @returns Empty promise.
-   */
-  public async rollback(): Promise<void> {
-    return await this.trees.rollback();
-  }
 
-  public delete(): Promise<void> {
-    return this.trees.delete();
+  close(): Promise<void> {
+    return Promise.resolve();
   }
 }

package/src/world-state-db/merkle_tree_snapshot_operations_facade.ts

@@ -1,27 +1,26 @@
 import { MerkleTreeId, type SiblingPath } from '@aztec/circuit-types';
 import {
-  type BatchInsertionResult,
-  type HandleL2BlockAndMessagesResult,
   type IndexedTreeId,
   type MerkleTreeLeafType,
-  type MerkleTreeOperations,
+  type MerkleTreeReadOperations,
   type TreeInfo,
 } from '@aztec/circuit-types/interfaces';
 import { AppendOnlyTreeSnapshot, Fr, type Header, PartialStateReference, StateReference } from '@aztec/circuits.js';
 import { type IndexedTreeLeafPreimage } from '@aztec/foundation/trees';
 import { type IndexedTreeSnapshot } from '@aztec/merkle-tree';
 
-import { type MerkleTreeDb, type TreeSnapshots } from './merkle_tree_db.js';
+import { type TreeSnapshots } from './merkle_tree_db.js';
+import { type MerkleTrees } from './merkle_trees.js';
 
 /**
  * Merkle tree operations on readonly tree snapshots.
  */
-export class MerkleTreeSnapshotOperationsFacade implements MerkleTreeOperations {
-  #treesDb: MerkleTreeDb;
+export class MerkleTreeSnapshotOperationsFacade implements MerkleTreeReadOperations {
+  #treesDb: MerkleTrees;
   #blockNumber: number;
   #treeSnapshots: TreeSnapshots = {} as any;
 
-  constructor(trees: MerkleTreeDb, blockNumber: number) {
+  constructor(trees: MerkleTrees, blockNumber: number) {
     this.#treesDb = trees;
     this.#blockNumber = blockNumber;
   }
@@ -31,7 +30,7 @@ export class MerkleTreeSnapshotOperationsFacade implements MerkleTreeOperations
       return this.#treeSnapshots[treeId];
     }
 
-    this.#treeSnapshots = await this.#treesDb.getSnapshot(this.#blockNumber);
+    this.#treeSnapshots = await this.#treesDb.getTreeSnapshots(this.#blockNumber);
     return this.#treeSnapshots[treeId]!;
   }
 
@@ -133,44 +132,6 @@ export class MerkleTreeSnapshotOperationsFacade implements MerkleTreeOperations
     );
   }
 
-  appendLeaves(): Promise<void> {
-    return Promise.reject(new Error('Tree snapshot operations are read-only'));
-  }
-
-  batchInsert<TreeHeight extends number, SubtreeSiblingPathHeight extends number>(): Promise<
-    BatchInsertionResult<TreeHeight, SubtreeSiblingPathHeight>
-  > {
-    return Promise.reject(new Error('Tree snapshot operations are read-only'));
-  }
-
-  updateArchive(): Promise<void> {
-    return Promise.reject(new Error('Tree snapshot operations are read-only'));
-  }
-
-  commit(): Promise<void> {
-    return Promise.reject(new Error('Tree snapshot operations are read-only'));
-  }
-
-  handleL2BlockAndMessages(): Promise<HandleL2BlockAndMessagesResult> {
-    return Promise.reject(new Error('Tree snapshot operations are read-only'));
-  }
-
-  rollback(): Promise<void> {
-    return Promise.reject(new Error('Tree snapshot operations are read-only'));
-  }
-
-  delete(): Promise<void> {
-    return Promise.reject(new Error('Tree snapshot operations are read-only'));
-  }
-
-  updateHistoricArchive(): Promise<void> {
-    return Promise.reject(new Error('Tree snapshot operations are read-only'));
-  }
-
-  updateLeaf(): Promise<void> {
-    return Promise.reject(new Error('Tree snapshot operations are read-only'));
-  }
-
   getInitialHeader(): Header {
     throw new Error('Getting initial header not supported on snapshot.');
   }

package/src/world-state-db/merkle_trees.ts

@@ -1,10 +1,10 @@
 import { type L2Block, MerkleTreeId, PublicDataWrite, type SiblingPath, TxEffect } from '@aztec/circuit-types';
 import {
   type BatchInsertionResult,
-  type HandleL2BlockAndMessagesResult,
   type IndexedTreeId,
-  type MerkleTreeAdminOperations,
   type MerkleTreeLeafType,
+  type MerkleTreeReadOperations,
+  type MerkleTreeWriteOperations,
   type TreeInfo,
 } from '@aztec/circuit-types/interfaces';
 import {
@@ -42,7 +42,6 @@ import {
   Poseidon,
   StandardIndexedTree,
   StandardTree,
-  type UpdateOnlyTree,
   getTreeMeta,
   loadTree,
   newTree,
@@ -51,14 +50,16 @@ import { type TelemetryClient } from '@aztec/telemetry-client';
 import { NoopTelemetryClient } from '@aztec/telemetry-client/noop';
 import { type Hasher } from '@aztec/types/interfaces';
 
+import { type WorldStateStatus } from '../native/message.js';
 import {
   INITIAL_NULLIFIER_TREE_SIZE,
   INITIAL_PUBLIC_DATA_TREE_SIZE,
-  type MerkleTreeDb,
+  type MerkleTreeAdminDatabase,
   type TreeSnapshots,
 } from './merkle_tree_db.js';
 import { type MerkleTreeMap } from './merkle_tree_map.js';
-import { MerkleTreeAdminOperationsFacade } from './merkle_tree_operations_facade.js';
+import { MerkleTreeReadOperationsFacade } from './merkle_tree_operations_facade.js';
+import { MerkleTreeSnapshotOperationsFacade } from './merkle_tree_snapshot_operations_facade.js';
 import { WorldStateMetrics } from './metrics.js';
 
 /**
@@ -98,7 +99,7 @@ class PublicDataTree extends StandardIndexedTree {
 /**
  * A convenience class for managing multiple merkle trees.
  */
-export class MerkleTrees implements MerkleTreeDb {
+export class MerkleTrees implements MerkleTreeAdminDatabase {
   // gets initialized in #init
   private trees: MerkleTreeMap = null as any;
   private jobQueue = new SerialQueue();
@@ -189,35 +190,54 @@ export class MerkleTrees implements MerkleTreeDb {
       // and persist the initial header state reference so we can later load it when requested.
       const initialState = await this.getStateReference(true);
       await this.#saveInitialStateReference(initialState);
-      await this.#updateArchive(this.getInitialHeader(), true);
+      await this.#updateArchive(this.getInitialHeader());
 
       // And commit anything we did to initialize this set of trees
       await this.#commit();
     }
   }
 
-  public async fork(): Promise<MerkleTrees> {
+  public removeHistoricalBlocks(_toBlockNumber: bigint): Promise<WorldStateStatus> {
+    throw new Error('Method not implemented.');
+  }
+
+  public unwindBlocks(_toBlockNumber: bigint): Promise<WorldStateStatus> {
+    throw new Error('Method not implemented.');
+  }
+
+  public setFinalised(_toBlockNumber: bigint): Promise<WorldStateStatus> {
+    throw new Error('Method not implemented.');
+  }
+
+  public getStatus(): Promise<WorldStateStatus> {
+    throw new Error('Method not implemented.');
+  }
+
+  public async fork(blockNumber?: number): Promise<MerkleTreeWriteOperations> {
+    if (blockNumber) {
+      throw new Error('Block number forking is not supported in js world state');
+    }
     const [ms, db] = await elapsed(async () => {
       const forked = await this.store.fork();
       return MerkleTrees.new(forked, this.telemetryClient, this.log);
     });
 
     this.metrics.recordForkDuration(ms);
-    return db;
+    return new MerkleTreeReadOperationsFacade(db, true);
   }
 
   // REFACTOR: We're hiding the `commit` operations in the tree behind a type check only, but
   // we should make sure it's not accidentally called elsewhere by splitting this class into one
   // that can work on a read-only store and one that actually writes to the store. This implies
   // having read-only versions of the kv-stores, all kv-containers, and all trees.
-  public async ephemeralFork(): Promise<MerkleTreeDb> {
+  public async ephemeralFork(): Promise<MerkleTreeWriteOperations> {
     const forked = new MerkleTrees(
       this.store,
       this.telemetryClient,
       createDebugLogger('aztec:merkle_trees:ephemeral_fork'),
     );
     await forked.#init(true);
-    return forked;
+    return new MerkleTreeReadOperationsFacade(forked, true);
   }
 
   public async delete() {
@@ -231,7 +251,7 @@ export class MerkleTrees implements MerkleTreeDb {
   /**
    * Stops the job queue (waits for all jobs to finish).
    */
-  public async stop() {
+  public async close() {
     await this.jobQueue.end();
   }
 
@@ -239,16 +259,20 @@ export class MerkleTrees implements MerkleTreeDb {
    * Gets a view of this db that returns uncommitted data.
    * @returns - A facade for this instance.
    */
-  public asLatest(): MerkleTreeAdminOperations {
-    return new MerkleTreeAdminOperationsFacade(this, true);
+  public getLatest(): Promise<MerkleTreeWriteOperations> {
+    return Promise.resolve(new MerkleTreeReadOperationsFacade(this, true));
   }
 
   /**
    * Gets a view of this db that returns committed data only.
    * @returns - A facade for this instance.
    */
-  public asCommitted(): MerkleTreeAdminOperations {
-    return new MerkleTreeAdminOperationsFacade(this, false);
+  public getCommitted(): MerkleTreeReadOperations {
+    return new MerkleTreeReadOperationsFacade(this, false);
+  }
+
+  public getSnapshot(blockNumber: number): MerkleTreeReadOperations {
+    return new MerkleTreeSnapshotOperationsFacade(this, blockNumber);
   }
 
   /**
@@ -256,8 +280,8 @@ export class MerkleTrees implements MerkleTreeDb {
    * @param header - The header whose hash to insert into the archive.
    * @param includeUncommitted - Indicates whether to include uncommitted data.
    */
-  public async updateArchive(header: Header, includeUncommitted: boolean) {
-    await this.synchronize(() => this.#updateArchive(header, includeUncommitted));
+  public async updateArchive(header: Header) {
+    await this.synchronize(() => this.#updateArchive(header));
   }
 
   /**
@@ -436,24 +460,13 @@ export class MerkleTrees implements MerkleTreeDb {
     });
   }
 
-  /**
-   * Updates a leaf in a tree at a given index.
-   * @param treeId - The ID of the tree.
-   * @param leaf - The new leaf value.
-   * @param index - The index to insert into.
-   * @returns Empty promise.
-   */
-  public async updateLeaf(treeId: IndexedTreeId, leaf: Buffer, index: bigint): Promise<void> {
-    return await this.synchronize(() => this.#updateLeaf(treeId, leaf, index));
-  }
-
   /**
    * Handles a single L2 block (i.e. Inserts the new note hashes into the merkle tree).
    * @param block - 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.
    */
-  public async handleL2BlockAndMessages(block: L2Block, l1ToL2Messages: Fr[]): Promise<HandleL2BlockAndMessagesResult> {
+  public async handleL2BlockAndMessages(block: L2Block, l1ToL2Messages: Fr[]): Promise<WorldStateStatus> {
     return await this.synchronize(() => this.#handleL2BlockAndMessages(block, l1ToL2Messages));
   }
 
@@ -501,8 +514,8 @@ export class MerkleTrees implements MerkleTreeDb {
     return StateReference.fromBuffer(serialized);
   }
 
-  async #updateArchive(header: Header, includeUncommitted: boolean) {
-    const state = await this.getStateReference(includeUncommitted);
+  async #updateArchive(header: Header) {
+    const state = await this.getStateReference(true);
 
     // This method should be called only when the block builder already updated the state so we sanity check that it's
     // the case here.
@@ -554,14 +567,6 @@ export class MerkleTrees implements MerkleTreeDb {
     return await tree.appendLeaves(leaves as any[]);
   }
 
-  async #updateLeaf(treeId: IndexedTreeId, leaf: MerkleTreeLeafType<typeof treeId>, index: bigint): Promise<void> {
-    const tree = this.trees[treeId];
-    if (!('updateLeaf' in tree)) {
-      throw new Error('Tree does not support `updateLeaf` method');
-    }
-    return await (tree as UpdateOnlyTree<typeof leaf>).updateLeaf(leaf, index);
-  }
-
   /**
    * Commits all pending updates.
    * @returns Empty promise.
@@ -582,7 +587,7 @@ export class MerkleTrees implements MerkleTreeDb {
     }
   }
 
-  public async getSnapshot(blockNumber: number): Promise<TreeSnapshots> {
+  public async getTreeSnapshots(blockNumber: number): Promise<TreeSnapshots> {
     const snapshots = await Promise.all([
       this.trees[MerkleTreeId.NULLIFIER_TREE].getSnapshot(blockNumber),
       this.trees[MerkleTreeId.NOTE_HASH_TREE].getSnapshot(blockNumber),
@@ -611,7 +616,7 @@ export class MerkleTrees implements MerkleTreeDb {
    * @param l2Block - The L2 block to handle.
    * @param l1ToL2Messages - The L1 to L2 messages for the block.
    */
-  async #handleL2BlockAndMessages(l2Block: L2Block, l1ToL2Messages: Fr[]): Promise<HandleL2BlockAndMessagesResult> {
+  async #handleL2BlockAndMessages(l2Block: L2Block, l1ToL2Messages: Fr[]): Promise<WorldStateStatus> {
     const timer = new Timer();
 
     const treeRootWithIdPairs = [
@@ -680,7 +685,7 @@ export class MerkleTrees implements MerkleTreeDb {
       }
 
       // The last thing remaining is to update the archive
-      await this.#updateArchive(l2Block.header, true);
+      await this.#updateArchive(l2Block.header);
 
       await this.#commit();
     }
@@ -703,8 +708,8 @@ export class MerkleTrees implements MerkleTreeDb {
     await this.#snapshot(l2Block.number);
 
     this.metrics.recordDbSize(this.store.estimateSize().bytes);
-    this.metrics.recordSyncDuration(ourBlock ? 'commit' : 'rollback_and_update', timer);
-    return { isBlockOurs: ourBlock };
+    this.metrics.recordSyncDuration('commit', timer);
+    return { unfinalisedBlockNumber: 0n, finalisedBlockNumber: 0n, oldestHistoricalBlock: 0n } as WorldStateStatus;
   }
 
   #isDbPopulated(): boolean {