@aztec/world-state 0.23.0 → 0.26.1

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

@@ -0,0 +1,50 @@
+import { MAX_NEW_NULLIFIERS_PER_TX, MAX_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX } from '@aztec/circuits.js';
+import { IndexedTreeSnapshot, TreeSnapshot } from '@aztec/merkle-tree';
+
+import { MerkleTreeOperations } from './merkle_tree_operations.js';
+
+/**
+ *
+ * @remarks Short explanation:
+ *    The nullifier tree must be initially padded as the pre-populated 0 index prevents efficient subtree insertion.
+ *    Padding with some values solves this issue.
+ *
+ * @remarks Thorough explanation:
+ *    There needs to be an initial (0,0,0) leaf in the tree, so that when we insert the first 'proper' leaf, we can
+ *    prove that any value greater than 0 doesn't exist in the tree yet. We prefill/pad the tree with "the number of
+ *    leaves that are added by one block" so that the first 'proper' block can insert a full subtree.
+ *
+ *    Without this padding, there would be a leaf (0,0,0) at leaf index 0, making it really difficult to insert e.g.
+ *    1024 leaves for the first block, because there's only neat space for 1023 leaves after 0. By padding with 1023
+ *    more leaves, we can then insert the first block of 1024 leaves into indices 1024:2047.
+ */
+export const INITIAL_NULLIFIER_TREE_SIZE = 2 * MAX_NEW_NULLIFIERS_PER_TX;
+
+export const INITIAL_PUBLIC_DATA_TREE_SIZE = 2 * MAX_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' | 'commit' | 'rollback' | 'handleL2Block' | 'batchInsert';
+
+/**
+ * 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<ReadonlyArray<TreeSnapshot | IndexedTreeSnapshot>>;
+  };

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

@@ -0,0 +1,178 @@
+import { L2Block, MerkleTreeId, SiblingPath } from '@aztec/circuit-types';
+import { Header, NullifierLeafPreimage, StateReference } from '@aztec/circuits.js';
+import { createDebugLogger } from '@aztec/foundation/log';
+import { IndexedTreeLeafPreimage } from '@aztec/foundation/trees';
+import { BatchInsertionResult } from '@aztec/merkle-tree';
+
+/**
+ * Type alias for the nullifier tree ID.
+ */
+export type IndexedTreeId = MerkleTreeId.NULLIFIER_TREE | MerkleTreeId.PUBLIC_DATA_TREE;
+
+/**
+ *  Defines tree information.
+ */
+export interface TreeInfo {
+  /**
+   * The tree ID.
+   */
+  treeId: MerkleTreeId;
+  /**
+   * The tree root.
+   */
+  root: Buffer;
+  /**
+   * The number of leaves in the tree.
+   */
+  size: bigint;
+
+  /**
+   * The depth of the tree.
+   */
+  depth: number;
+}
+
+/**
+ * Defines the interface for operations on a set of Merkle Trees.
+ */
+export interface MerkleTreeOperations {
+  /**
+   * Appends leaves to a given tree.
+   * @param treeId - The tree to be updated.
+   * @param leaves - The set of leaves to be appended.
+   */
+  appendLeaves(treeId: MerkleTreeId, leaves: Buffer[]): Promise<void>;
+
+  /**
+   * Returns information about the given tree.
+   * @param treeId - The tree to be queried.
+   */
+  getTreeInfo(treeId: MerkleTreeId): Promise<TreeInfo>;
+
+  /**
+   * Gets the current state reference.
+   */
+  getStateReference(): Promise<StateReference>;
+
+  /**
+   * Builds the initial header.
+   */
+  buildInitialHeader(): Promise<Header>;
+
+  /**
+   * Gets sibling path for a leaf.
+   * @param treeId - The tree to be queried for a sibling path.
+   * @param index - The index of the leaf for which a sibling path should be returned.
+   */
+  getSiblingPath<N extends number>(treeId: MerkleTreeId, index: bigint): Promise<SiblingPath<N>>;
+
+  /**
+   * Returns the previous index for a given value in an indexed tree.
+   * @param treeId - The tree for which the previous value index is required.
+   * @param value - The value to be queried.
+   */
+  getPreviousValueIndex(
+    treeId: IndexedTreeId,
+    value: bigint,
+  ): Promise<
+    | {
+        /**
+         * The index of the found leaf.
+         */
+        index: bigint;
+        /**
+         * A flag indicating if the corresponding leaf's value is equal to `newValue`.
+         */
+        alreadyPresent: boolean;
+      }
+    | undefined
+  >;
+
+  /**
+   * Returns the data at a specific leaf.
+   * @param treeId - The tree for which leaf data should be returned.
+   * @param index - The index of the leaf required.
+   */
+  getLeafPreimage(treeId: IndexedTreeId, index: bigint): Promise<IndexedTreeLeafPreimage | undefined>;
+
+  /**
+   * Update the leaf data at the given index.
+   * @param treeId - The tree for which leaf data should be edited.
+   * @param leaf - The updated leaf value.
+   * @param index - The index of the leaf to be updated.
+   */
+  updateLeaf(treeId: IndexedTreeId, leaf: NullifierLeafPreimage | Buffer, index: bigint): Promise<void>;
+
+  /**
+   * Returns the index containing a leaf value.
+   * @param treeId - The tree for which the index should be returned.
+   * @param value - The value to search for in the tree.
+   */
+  findLeafIndex(treeId: MerkleTreeId, value: Buffer): Promise<bigint | undefined>;
+
+  /**
+   * Gets the value for a leaf in the tree.
+   * @param treeId - The tree for which the index should be returned.
+   * @param index - The index of the leaf.
+   */
+  getLeafValue(treeId: MerkleTreeId, index: bigint): Promise<Buffer | undefined>;
+
+  /**
+   * Inserts the block hash into the archive.
+   * This includes all of the current roots of all of the data trees and the current blocks global vars.
+   * @param header - The header to insert into the archive.
+   */
+  updateArchive(header: Header): Promise<void>;
+
+  /**
+   * Batch insert multiple leaves into the tree.
+   * @param leaves - Leaves to insert into the tree.
+   * @param treeId - The tree on which to insert.
+   * @param subtreeHeight - Height of the subtree.
+   * @returns The witness data for the leaves to be updated when inserting the new ones.
+   */
+  batchInsert<TreeHeight extends number, SubtreeSiblingPathHeight extends number>(
+    treeId: MerkleTreeId,
+    leaves: Buffer[],
+    subtreeHeight: number,
+  ): Promise<BatchInsertionResult<TreeHeight, SubtreeSiblingPathHeight>>;
+
+  /**
+   * Handles a single L2 block (i.e. Inserts the new note hashes into the merkle tree).
+   * @param block - The L2 block to handle.
+   */
+  handleL2Block(block: L2Block): Promise<HandleL2BlockResult>;
+
+  /**
+   * Commits pending changes to the underlying store.
+   */
+  commit(): Promise<void>;
+
+  /**
+   * Rolls back pending changes.
+   */
+  rollback(): Promise<void>;
+}
+
+/** Return type for handleL2Block */
+export type HandleL2BlockResult = {
+  /** Whether the block processed was emitted by our sequencer */ isBlockOurs: boolean;
+};
+
+/**
+ * Outputs a tree leaves using for debugging purposes.
+ */
+export async function inspectTree(
+  db: MerkleTreeOperations,
+  treeId: MerkleTreeId,
+  log = createDebugLogger('aztec:inspect-tree'),
+) {
+  const info = await db.getTreeInfo(treeId);
+  const output = [`Tree id=${treeId} size=${info.size} root=0x${info.root.toString('hex')}`];
+  for (let i = 0; i < info.size; i++) {
+    output.push(
+      ` Leaf ${i}: ${await db.getLeafValue(treeId, BigInt(i)).then(x => x?.toString('hex') ?? '[undefined]')}`,
+    );
+  }
+  log(output.join('\n'));
+}

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

@@ -0,0 +1,182 @@
+import { L2Block, MerkleTreeId, SiblingPath } from '@aztec/circuit-types';
+import { Header, NullifierLeafPreimage, StateReference } from '@aztec/circuits.js';
+import { IndexedTreeLeafPreimage } from '@aztec/foundation/trees';
+import { BatchInsertionResult } from '@aztec/merkle-tree';
+
+import { MerkleTreeDb } from './merkle_tree_db.js';
+import { HandleL2BlockResult, MerkleTreeOperations, TreeInfo } from './merkle_tree_operations.js';
+
+/**
+ * Wraps a MerkleTreeDbOperations to call all functions with a preset includeUncommitted flag.
+ */
+export class MerkleTreeOperationsFacade implements MerkleTreeOperations {
+  constructor(private trees: MerkleTreeDb, private includeUncommitted: boolean) {}
+
+  /**
+   * Returns the tree info for the specified tree id.
+   * @param treeId - Id of the tree to get information from.
+   * @param includeUncommitted - Indicates whether to include uncommitted data.
+   * @returns The tree info for the specified tree.
+   */
+  getTreeInfo(treeId: MerkleTreeId): Promise<TreeInfo> {
+    return this.trees.getTreeInfo(treeId, this.includeUncommitted);
+  }
+
+  /**
+   * Get the current state reference.
+   * @returns The current state reference.
+   */
+  getStateReference(): Promise<StateReference> {
+    return this.trees.getStateReference(this.includeUncommitted);
+  }
+
+  /**
+   * Builds the initial header.
+   * @returns The initial header.
+   */
+  buildInitialHeader(): Promise<Header> {
+    return this.trees.buildInitialHeader(this.includeUncommitted);
+  }
+
+  /**
+   * Appends a set of leaf values to the tree.
+   * @param treeId - Id of the tree to append leaves to.
+   * @param leaves - The set of leaves to be appended.
+   * @returns The tree info of the specified tree.
+   */
+  appendLeaves(treeId: MerkleTreeId, leaves: Buffer[]): Promise<void> {
+    return this.trees.appendLeaves(treeId, leaves);
+  }
+
+  /**
+   * Returns the sibling path for a requested leaf index.
+   * @param treeId - Id of the tree to get the sibling path from.
+   * @param index - The index of the leaf for which a sibling path is required.
+   * @returns A promise with the sibling path of the specified leaf index.
+   */
+  async getSiblingPath<N extends number>(treeId: MerkleTreeId, index: bigint): Promise<SiblingPath<N>> {
+    const path = await this.trees.getSiblingPath(treeId, index, this.includeUncommitted);
+    return path as unknown as SiblingPath<N>;
+  }
+
+  /**
+   * Finds the index of the largest leaf whose value is less than or equal to the provided value.
+   * @param treeId - The ID of the tree to search.
+   * @param value - The value to be inserted into the tree.
+   * @param includeUncommitted - If true, the uncommitted changes are included in the search.
+   * @returns The found leaf index and a flag indicating if the corresponding leaf's value is equal to `newValue`.
+   */
+  getPreviousValueIndex(
+    treeId: MerkleTreeId.NULLIFIER_TREE,
+    value: bigint,
+  ): Promise<
+    | {
+        /**
+         * The index of the found leaf.
+         */
+        index: bigint;
+        /**
+         * A flag indicating if the corresponding leaf's value is equal to `newValue`.
+         */
+        alreadyPresent: boolean;
+      }
+    | undefined
+  > {
+    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(treeId: MerkleTreeId.NULLIFIER_TREE, 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.
+   * @param index - The index of the leaf to get.
+   * @returns Leaf preimage.
+   */
+  async getLeafPreimage(
+    treeId: MerkleTreeId.NULLIFIER_TREE,
+    index: bigint,
+  ): Promise<IndexedTreeLeafPreimage | undefined> {
+    const preimage = await this.trees.getLeafPreimage(treeId, index, this.includeUncommitted);
+    return preimage as IndexedTreeLeafPreimage | undefined;
+  }
+
+  /**
+   * Returns the index of a leaf given its value, or undefined if no leaf with that value is found.
+   * @param treeId - The ID of the tree.
+   * @param value - The leaf value to look for.
+   * @returns The index of the first leaf found with a given value (undefined if not found).
+   */
+  findLeafIndex(treeId: MerkleTreeId, value: Buffer): Promise<bigint | undefined> {
+    return this.trees.findLeafIndex(treeId, value, this.includeUncommitted);
+  }
+
+  /**
+   * Gets the value at the given index.
+   * @param treeId - The ID of the tree to get the leaf value from.
+   * @param index - The index of the leaf.
+   * @param includeUncommitted - Indicates whether to include uncommitted changes.
+   * @returns Leaf value at the given index (undefined if not found).
+   */
+  getLeafValue(treeId: MerkleTreeId, index: bigint): Promise<Buffer | undefined> {
+    return this.trees.getLeafValue(treeId, index, this.includeUncommitted);
+  }
+
+  /**
+   * Inserts the new block hash into the archive.
+   * This includes all of the current roots of all of the data trees and the current blocks global vars.
+   * @param header - The header to insert into the archive.
+   */
+  public updateArchive(header: Header): Promise<void> {
+    return this.trees.updateArchive(header, this.includeUncommitted);
+  }
+
+  /**
+   * Handles a single L2 block (i.e. Inserts the new note hashes into the merkle tree).
+   * @param block - The L2 block to handle.
+   * @returns Whether the block handled was produced by this same node.
+   */
+  public handleL2Block(block: L2Block): Promise<HandleL2BlockResult> {
+    return this.trees.handleL2Block(block);
+  }
+
+  /**
+   * 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();
+  }
+
+  /**
+   * Batch insert multiple leaves into the tree.
+   * @param treeId - The ID of the tree.
+   * @param leaves - Leaves to insert into the tree.
+   * @param subtreeHeight - Height of the subtree.
+   * @returns The data for the leaves to be updated when inserting the new ones.
+   */
+  public batchInsert<TreeHeight extends number, SubtreeSiblingPathHeight extends number>(
+    treeId: MerkleTreeId,
+    leaves: Buffer[],
+    subtreeHeight: number,
+  ): Promise<BatchInsertionResult<TreeHeight, SubtreeSiblingPathHeight>> {
+    return this.trees.batchInsert(treeId, leaves, subtreeHeight);
+  }
+}

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

@@ -0,0 +1,157 @@
+import { MerkleTreeId, SiblingPath } from '@aztec/circuit-types';
+import { AppendOnlyTreeSnapshot, Fr, Header, PartialStateReference, StateReference } from '@aztec/circuits.js';
+import { IndexedTreeLeafPreimage } from '@aztec/foundation/trees';
+import { BatchInsertionResult, IndexedTreeSnapshot, TreeSnapshot } from '@aztec/merkle-tree';
+
+import { MerkleTreeDb } from './merkle_tree_db.js';
+import { HandleL2BlockResult, MerkleTreeOperations, TreeInfo } from './merkle_tree_operations.js';
+
+/**
+ * Merkle tree operations on readonly tree snapshots.
+ */
+export class MerkleTreeSnapshotOperationsFacade implements MerkleTreeOperations {
+  #treesDb: MerkleTreeDb;
+  #blockNumber: number;
+  #treeSnapshots: ReadonlyArray<TreeSnapshot | IndexedTreeSnapshot> = [];
+
+  constructor(trees: MerkleTreeDb, blockNumber: number) {
+    this.#treesDb = trees;
+    this.#blockNumber = blockNumber;
+  }
+
+  async #getTreeSnapshot(merkleTreeId: number): Promise<TreeSnapshot | IndexedTreeSnapshot> {
+    if (this.#treeSnapshots[merkleTreeId]) {
+      return this.#treeSnapshots[merkleTreeId];
+    }
+
+    this.#treeSnapshots = await this.#treesDb.getSnapshot(this.#blockNumber);
+    return this.#treeSnapshots[merkleTreeId]!;
+  }
+
+  async findLeafIndex(treeId: MerkleTreeId, value: Buffer): Promise<bigint | undefined> {
+    const tree = await this.#getTreeSnapshot(treeId);
+    return tree.findLeafIndex(value);
+  }
+
+  async getLeafPreimage(
+    treeId: MerkleTreeId.NULLIFIER_TREE,
+    index: bigint,
+  ): Promise<IndexedTreeLeafPreimage | undefined> {
+    const snapshot = (await this.#getTreeSnapshot(treeId)) as IndexedTreeSnapshot;
+    return snapshot.getLatestLeafPreimageCopy(BigInt(index));
+  }
+
+  async getLeafValue(treeId: MerkleTreeId, index: bigint): Promise<Buffer | undefined> {
+    const snapshot = await this.#getTreeSnapshot(treeId);
+    return snapshot.getLeafValue(BigInt(index));
+  }
+
+  async getPreviousValueIndex(
+    treeId: MerkleTreeId.NULLIFIER_TREE,
+    value: bigint,
+  ): Promise<
+    | {
+        /**
+         * The index of the found leaf.
+         */
+        index: bigint;
+        /**
+         * A flag indicating if the corresponding leaf's value is equal to `newValue`.
+         */
+        alreadyPresent: boolean;
+      }
+    | undefined
+  > {
+    const snapshot = (await this.#getTreeSnapshot(treeId)) as IndexedTreeSnapshot;
+    return snapshot.findIndexOfPreviousKey(value);
+  }
+
+  async getSiblingPath<N extends number>(treeId: MerkleTreeId, index: bigint): Promise<SiblingPath<N>> {
+    const snapshot = await this.#getTreeSnapshot(treeId);
+    return snapshot.getSiblingPath(index);
+  }
+
+  async getTreeInfo(treeId: MerkleTreeId): Promise<TreeInfo> {
+    const snapshot = await this.#getTreeSnapshot(treeId);
+    return {
+      depth: snapshot.getDepth(),
+      root: snapshot.getRoot(),
+      size: snapshot.getNumLeaves(),
+      treeId,
+    };
+  }
+
+  async getStateReference(): Promise<StateReference> {
+    const snapshots = await Promise.all([
+      this.#getTreeSnapshot(MerkleTreeId.CONTRACT_TREE),
+      this.#getTreeSnapshot(MerkleTreeId.NULLIFIER_TREE),
+      this.#getTreeSnapshot(MerkleTreeId.NOTE_HASH_TREE),
+      this.#getTreeSnapshot(MerkleTreeId.PUBLIC_DATA_TREE),
+      this.#getTreeSnapshot(MerkleTreeId.L1_TO_L2_MESSAGE_TREE),
+      this.#getTreeSnapshot(MerkleTreeId.ARCHIVE),
+    ]);
+
+    return new StateReference(
+      new AppendOnlyTreeSnapshot(
+        Fr.fromBuffer(snapshots[MerkleTreeId.L1_TO_L2_MESSAGE_TREE].getRoot()),
+        Number(snapshots[MerkleTreeId.L1_TO_L2_MESSAGE_TREE].getNumLeaves()),
+      ),
+      new PartialStateReference(
+        new AppendOnlyTreeSnapshot(
+          Fr.fromBuffer(snapshots[MerkleTreeId.NOTE_HASH_TREE].getRoot()),
+          Number(snapshots[MerkleTreeId.NOTE_HASH_TREE].getNumLeaves()),
+        ),
+        new AppendOnlyTreeSnapshot(
+          Fr.fromBuffer(snapshots[MerkleTreeId.NULLIFIER_TREE].getRoot()),
+          Number(snapshots[MerkleTreeId.NULLIFIER_TREE].getNumLeaves()),
+        ),
+        new AppendOnlyTreeSnapshot(
+          Fr.fromBuffer(snapshots[MerkleTreeId.CONTRACT_TREE].getRoot()),
+          Number(snapshots[MerkleTreeId.CONTRACT_TREE].getNumLeaves()),
+        ),
+        new AppendOnlyTreeSnapshot(
+          Fr.fromBuffer(snapshots[MerkleTreeId.PUBLIC_DATA_TREE].getRoot()),
+          Number(snapshots[MerkleTreeId.PUBLIC_DATA_TREE].getNumLeaves()),
+        ),
+      ),
+    );
+  }
+
+  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'));
+  }
+
+  handleL2Block(): Promise<HandleL2BlockResult> {
+    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'));
+  }
+
+  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'));
+  }
+
+  buildInitialHeader(): Promise<Header> {
+    throw new Error('Building initial header not supported on snapshot.');
+  }
+}