@aztec/merkle-tree 0.16.1 → 0.16.2

package/src/snapshots/append_only_snapshot.ts

@@ -0,0 +1,243 @@
+import { Hasher, SiblingPath } from '@aztec/types';
+
+import { LevelUp } from 'levelup';
+
+import { AppendOnlyTree } from '../interfaces/append_only_tree.js';
+import { TreeBase } from '../tree_base.js';
+import { TreeSnapshot, TreeSnapshotBuilder } from './snapshot_builder.js';
+
+// stores the last block that modified this node
+const nodeModifiedAtBlockKey = (treeName: string, level: number, index: bigint) =>
+  `snapshot:node:${treeName}:${level}:${index}:block`;
+
+// stores the value of the node at the above block
+const historicalNodeKey = (treeName: string, level: number, index: bigint) =>
+  `snapshot:node:${treeName}:${level}:${index}:value`;
+
+// metadata for a snapshot
+const snapshotRootKey = (treeName: string, block: number) => `snapshot:root:${treeName}:${block}`;
+const snapshotNumLeavesKey = (treeName: string, block: number) => `snapshot:numLeaves:${treeName}:${block}`;
+
+/**
+ * A more space-efficient way of storing snapshots of AppendOnlyTrees that trades space need for slower
+ * sibling path reads.
+ *
+ * Complexity:
+ *
+ * N - count of non-zero nodes in tree
+ * M - count of snapshots
+ * H - tree height
+ *
+ * Space complexity: O(N + M) (N nodes - stores the last snapshot for each node and M - ints, for each snapshot stores up to which leaf its written to)
+ * Sibling path access:
+ *  Best case: O(H) database reads + O(1) hashes
+ *  Worst case: O(H) database reads + O(H) hashes
+ */
+export class AppendOnlySnapshotBuilder implements TreeSnapshotBuilder {
+  constructor(private db: LevelUp, private tree: TreeBase & AppendOnlyTree, private hasher: Hasher) {}
+  async getSnapshot(block: number): Promise<TreeSnapshot> {
+    const meta = await this.#getSnapshotMeta(block);
+
+    if (typeof meta === 'undefined') {
+      throw new Error(`Snapshot for tree ${this.tree.getName()} at block ${block} does not exist`);
+    }
+
+    return new AppendOnlySnapshot(this.db, block, meta.numLeaves, meta.root, this.tree, this.hasher);
+  }
+
+  async snapshot(block: number): Promise<TreeSnapshot> {
+    const meta = await this.#getSnapshotMeta(block);
+    if (typeof meta !== 'undefined') {
+      // no-op, we already have a snapshot
+      return new AppendOnlySnapshot(this.db, block, meta.numLeaves, meta.root, this.tree, this.hasher);
+    }
+
+    const batch = this.db.batch();
+    const root = this.tree.getRoot(false);
+    const depth = this.tree.getDepth();
+    const treeName = this.tree.getName();
+    const queue: [Buffer, number, bigint][] = [[root, 0, 0n]];
+
+    // walk the tree in BF and store latest nodes
+    while (queue.length > 0) {
+      const [node, level, index] = queue.shift()!;
+
+      const historicalValue = await this.db.get(historicalNodeKey(treeName, level, index)).catch(() => undefined);
+      if (!historicalValue || !node.equals(historicalValue)) {
+        // we've never seen this node before or it's different than before
+        // update the historical tree and tag it with the block that modified it
+        batch.put(nodeModifiedAtBlockKey(treeName, level, index), String(block));
+        batch.put(historicalNodeKey(treeName, level, index), node);
+      } else {
+        // if this node hasn't changed, that means, nothing below it has changed either
+        continue;
+      }
+
+      if (level + 1 > depth) {
+        // short circuit if we've reached the leaf level
+        // otherwise getNode might throw if we ask for the children of a leaf
+        continue;
+      }
+
+      // these could be undefined because zero hashes aren't stored in the tree
+      const [lhs, rhs] = await Promise.all([
+        this.tree.getNode(level + 1, 2n * index),
+        this.tree.getNode(level + 1, 2n * index + 1n),
+      ]);
+
+      if (lhs) {
+        queue.push([lhs, level + 1, 2n * index]);
+      }
+
+      if (rhs) {
+        queue.push([rhs, level + 1, 2n * index + 1n]);
+      }
+    }
+
+    const numLeaves = this.tree.getNumLeaves(false);
+    batch.put(snapshotNumLeavesKey(treeName, block), String(numLeaves));
+    batch.put(snapshotRootKey(treeName, block), root);
+    await batch.write();
+
+    return new AppendOnlySnapshot(this.db, block, numLeaves, root, this.tree, this.hasher);
+  }
+
+  async #getSnapshotMeta(block: number): Promise<
+    | {
+        /** The root of the tree snapshot */
+        root: Buffer;
+        /** The number of leaves in the tree snapshot */
+        numLeaves: bigint;
+      }
+    | undefined
+  > {
+    try {
+      const treeName = this.tree.getName();
+      const root = await this.db.get(snapshotRootKey(treeName, block));
+      const numLeaves = BigInt(await this.db.get(snapshotNumLeavesKey(treeName, block)));
+      return { root, numLeaves };
+    } catch (err) {
+      return undefined;
+    }
+  }
+}
+
+/**
+ * a
+ */
+class AppendOnlySnapshot implements TreeSnapshot {
+  constructor(
+    private db: LevelUp,
+    private block: number,
+    private leafCount: bigint,
+    private historicalRoot: Buffer,
+    private tree: TreeBase & AppendOnlyTree,
+    private hasher: Hasher,
+  ) {}
+
+  public async getSiblingPath<N extends number>(index: bigint): Promise<SiblingPath<N>> {
+    const path: Buffer[] = [];
+    const depth = this.tree.getDepth();
+    let level = depth;
+
+    while (level > 0) {
+      const isRight = index & 0x01n;
+      const siblingIndex = isRight ? index - 1n : index + 1n;
+
+      const sibling = await this.#getHistoricalNodeValue(level, siblingIndex);
+      path.push(sibling);
+
+      level -= 1;
+      index >>= 1n;
+    }
+
+    return new SiblingPath<N>(depth as N, path);
+  }
+
+  getDepth(): number {
+    return this.tree.getDepth();
+  }
+
+  getNumLeaves(): bigint {
+    return this.leafCount;
+  }
+
+  getRoot(): Buffer {
+    // we could recompute it, but it's way cheaper to just store the root
+    return this.historicalRoot;
+  }
+
+  async getLeafValue(index: bigint): Promise<Buffer | undefined> {
+    const leafLevel = this.getDepth();
+    const blockNumber = await this.#getBlockNumberThatModifiedNode(leafLevel, index);
+
+    // leaf hasn't been set yet
+    if (typeof blockNumber === 'undefined') {
+      return undefined;
+    }
+
+    // leaf was set some time in the past
+    if (blockNumber <= this.block) {
+      return this.db.get(historicalNodeKey(this.tree.getName(), leafLevel, index));
+    }
+
+    // leaf has been set but in a block in the future
+    return undefined;
+  }
+
+  async #getHistoricalNodeValue(level: number, index: bigint): Promise<Buffer> {
+    const blockNumber = await this.#getBlockNumberThatModifiedNode(level, index);
+
+    // node has never been set
+    if (typeof blockNumber === 'undefined') {
+      return this.tree.getZeroHash(level);
+    }
+
+    // node was set some time in the past
+    if (blockNumber <= this.block) {
+      return this.db.get(historicalNodeKey(this.tree.getName(), level, index));
+    }
+
+    // the node has been modified since this snapshot was taken
+    // because we're working with an AppendOnly tree, historical leaves never change
+    // so what we do instead is rebuild this Merkle path up using zero hashes as needed
+    // worst case this will do O(H) hashes
+    //
+    // we first check if this subtree was touched by the block
+    // compare how many leaves this block added to the leaf interval of this subtree
+    // if they don't intersect then the whole subtree was a hash of zero
+    // if they do then we need to rebuild the merkle tree
+    const depth = this.tree.getDepth();
+    const leafStart = index * 2n ** BigInt(depth - level);
+    if (leafStart >= this.leafCount) {
+      return this.tree.getZeroHash(level);
+    }
+
+    const [lhs, rhs] = await Promise.all([
+      this.#getHistoricalNodeValue(level + 1, 2n * index),
+      this.#getHistoricalNodeValue(level + 1, 2n * index + 1n),
+    ]);
+
+    return this.hasher.hash(lhs, rhs);
+  }
+
+  async #getBlockNumberThatModifiedNode(level: number, index: bigint): Promise<number | undefined> {
+    try {
+      const value: Buffer | string = await this.db.get(nodeModifiedAtBlockKey(this.tree.getName(), level, index));
+      return parseInt(value.toString(), 10);
+    } catch (err) {
+      return undefined;
+    }
+  }
+
+  async findLeafIndex(value: Buffer): Promise<bigint | undefined> {
+    const numLeaves = this.getNumLeaves();
+    for (let i = 0n; i < numLeaves; i++) {
+      const currentValue = await this.getLeafValue(i);
+      if (currentValue && currentValue.equals(value)) {
+        return i;
+      }
+    }
+    return undefined;
+  }
+}

package/src/snapshots/base_full_snapshot.ts

@@ -0,0 +1,232 @@
+import { SiblingPath } from '@aztec/types';
+
+import { LevelUp, LevelUpChain } from 'levelup';
+
+import { TreeBase } from '../tree_base.js';
+import { TreeSnapshot, TreeSnapshotBuilder } from './snapshot_builder.js';
+
+// key for a node's children
+const snapshotChildKey = (node: Buffer, child: 0 | 1) =>
+  Buffer.concat([Buffer.from('snapshot:node:'), node, Buffer.from(':' + child)]);
+
+// metadata for a snapshot
+const snapshotRootKey = (treeName: string, block: number) => `snapshot:root:${treeName}:${block}`;
+const snapshotNumLeavesKey = (treeName: string, block: number) => `snapshot:numLeaves:${treeName}:${block}`;
+
+/**
+ * Builds a full snapshot of a tree. This implementation works for any Merkle tree and stores
+ * it in a database in a similar way to how a tree is stored in memory, using pointers.
+ *
+ * Sharing the same database between versions and trees is recommended as the trees would share
+ * structure.
+ *
+ * Implement the protected method `handleLeaf` to store any additional data you need for each leaf.
+ *
+ * Complexity:
+ * N - count of non-zero nodes in tree
+ * M - count of snapshots
+ * H - tree height
+ * Worst case space complexity: O(N * M)
+ * Sibling path access: O(H) database reads
+ */
+export abstract class BaseFullTreeSnapshotBuilder<T extends TreeBase, S extends TreeSnapshot>
+  implements TreeSnapshotBuilder<S>
+{
+  constructor(protected db: LevelUp, protected tree: T) {}
+
+  async snapshot(block: number): Promise<S> {
+    const snapshotMetadata = await this.#getSnapshotMeta(block);
+
+    if (snapshotMetadata) {
+      return this.openSnapshot(snapshotMetadata.root, snapshotMetadata.numLeaves);
+    }
+
+    const batch = this.db.batch();
+    const root = this.tree.getRoot(false);
+    const numLeaves = this.tree.getNumLeaves(false);
+    const depth = this.tree.getDepth();
+    const queue: [Buffer, number, bigint][] = [[root, 0, 0n]];
+
+    // walk the tree breadth-first and store each of its nodes in the database
+    // for each node we save two keys
+    //   <node hash>:0 -> <left child's hash>
+    //   <node hash>:1 -> <right child's hash>
+    while (queue.length > 0) {
+      const [node, level, i] = queue.shift()!;
+      // check if the database already has a child for this tree
+      // if it does, then we know we've seen the whole subtree below it before
+      // and we don't have to traverse it anymore
+      // we use the left child here, but it could be anything that shows we've stored the node before
+      const exists: Buffer | undefined = await this.db.get(snapshotChildKey(node, 0)).catch(() => undefined);
+      if (exists) {
+        continue;
+      }
+
+      if (level + 1 > depth) {
+        // short circuit if we've reached the leaf level
+        // otherwise getNode might throw if we ask for the children of a leaf
+        await this.handleLeaf(i, node, batch);
+        continue;
+      }
+
+      const [lhs, rhs] = await Promise.all([
+        this.tree.getNode(level + 1, 2n * i),
+        this.tree.getNode(level + 1, 2n * i + 1n),
+      ]);
+
+      // we want the zero hash at the children's level, not the node's level
+      const zeroHash = this.tree.getZeroHash(level + 1);
+
+      batch.put(snapshotChildKey(node, 0), lhs ?? zeroHash);
+      batch.put(snapshotChildKey(node, 1), rhs ?? zeroHash);
+
+      // enqueue the children only if they're not zero hashes
+      if (lhs) {
+        queue.push([lhs, level + 1, 2n * i]);
+      }
+
+      if (rhs) {
+        queue.push([rhs, level + 1, 2n * i + 1n]);
+      }
+    }
+
+    batch.put(snapshotRootKey(this.tree.getName(), block), root);
+    batch.put(snapshotNumLeavesKey(this.tree.getName(), block), String(numLeaves));
+    await batch.write();
+
+    return this.openSnapshot(root, numLeaves);
+  }
+
+  protected handleLeaf(_index: bigint, _node: Buffer, _batch: LevelUpChain) {
+    return Promise.resolve();
+  }
+
+  async getSnapshot(version: number): Promise<S> {
+    const snapshotMetadata = await this.#getSnapshotMeta(version);
+
+    if (!snapshotMetadata) {
+      throw new Error(`Version ${version} does not exist for tree ${this.tree.getName()}`);
+    }
+
+    return this.openSnapshot(snapshotMetadata.root, snapshotMetadata.numLeaves);
+  }
+
+  protected abstract openSnapshot(root: Buffer, numLeaves: bigint): S;
+
+  async #getSnapshotMeta(block: number): Promise<
+    | {
+        /** The root of the tree snapshot */
+        root: Buffer;
+        /** The number of leaves in the tree snapshot */
+        numLeaves: bigint;
+      }
+    | undefined
+  > {
+    try {
+      const treeName = this.tree.getName();
+      const root = await this.db.get(snapshotRootKey(treeName, block));
+      const numLeaves = BigInt(await this.db.get(snapshotNumLeavesKey(treeName, block)));
+      return { root, numLeaves };
+    } catch (err) {
+      return undefined;
+    }
+  }
+}
+
+/**
+ * A source of sibling paths from a snapshot tree
+ */
+export class BaseFullTreeSnapshot implements TreeSnapshot {
+  constructor(
+    protected db: LevelUp,
+    protected historicRoot: Buffer,
+    protected numLeaves: bigint,
+    protected tree: TreeBase,
+  ) {}
+
+  async getSiblingPath<N extends number>(index: bigint): Promise<SiblingPath<N>> {
+    const siblings: Buffer[] = [];
+
+    for await (const [_node, sibling] of this.pathFromRootToLeaf(index)) {
+      siblings.push(sibling);
+    }
+
+    // we got the siblings we were looking for, but they are in root-leaf order
+    // reverse them here so we have leaf-root (what SiblingPath expects)
+    siblings.reverse();
+
+    return new SiblingPath<N>(this.tree.getDepth() as N, siblings);
+  }
+
+  async getLeafValue(index: bigint): Promise<Buffer | undefined> {
+    let leafNode: Buffer | undefined = undefined;
+    for await (const [node, _sibling] of this.pathFromRootToLeaf(index)) {
+      leafNode = node;
+    }
+
+    return leafNode;
+  }
+
+  getDepth(): number {
+    return this.tree.getDepth();
+  }
+
+  getRoot(): Buffer {
+    return this.historicRoot;
+  }
+
+  getNumLeaves(): bigint {
+    return this.numLeaves;
+  }
+
+  protected async *pathFromRootToLeaf(leafIndex: bigint) {
+    const root = this.historicRoot;
+    const pathFromRoot = this.#getPathFromRoot(leafIndex);
+
+    let node: Buffer = root;
+    for (let i = 0; i < pathFromRoot.length; i++) {
+      // get both children. We'll need both anyway (one to keep track of, the other to walk down to)
+      const children: [Buffer, Buffer] = await Promise.all([
+        this.db.get(snapshotChildKey(node, 0)),
+        this.db.get(snapshotChildKey(node, 1)),
+      ]).catch(() => [this.tree.getZeroHash(i + 1), this.tree.getZeroHash(i + 1)]);
+      const next = children[pathFromRoot[i]];
+      const sibling = children[(pathFromRoot[i] + 1) % 2];
+
+      yield [next, sibling];
+
+      node = next;
+    }
+  }
+
+  /**
+   * Calculates the path from the root to the target leaf. Returns an array of 0s and 1s,
+   * each 0 represents walking down a left child and each 1 walking down to the child on the right.
+   *
+   * @param leafIndex - The target leaf
+   * @returns An array of 0s and 1s
+   */
+  #getPathFromRoot(leafIndex: bigint): ReadonlyArray<0 | 1> {
+    const path: Array<0 | 1> = [];
+    let level = this.tree.getDepth();
+    while (level > 0) {
+      path.push(leafIndex & 0x01n ? 1 : 0);
+      leafIndex >>= 1n;
+      level--;
+    }
+
+    path.reverse();
+    return path;
+  }
+
+  async findLeafIndex(value: Buffer): Promise<bigint | undefined> {
+    const numLeaves = this.getNumLeaves();
+    for (let i = 0n; i < numLeaves; i++) {
+      const currentValue = await this.getLeafValue(i);
+      if (currentValue && currentValue.equals(value)) {
+        return i;
+      }
+    }
+    return undefined;
+  }
+}

package/src/snapshots/full_snapshot.ts

@@ -0,0 +1,26 @@
+import { TreeBase } from '../tree_base.js';
+import { BaseFullTreeSnapshot, BaseFullTreeSnapshotBuilder } from './base_full_snapshot.js';
+import { TreeSnapshot, TreeSnapshotBuilder } from './snapshot_builder.js';
+
+/**
+ * Builds a full snapshot of a tree. This implementation works for any Merkle tree and stores
+ * it in a database in a similar way to how a tree is stored in memory, using pointers.
+ *
+ * Sharing the same database between versions and trees is recommended as the trees would share
+ * structure.
+ *
+ * Complexity:
+ * N - count of non-zero nodes in tree
+ * M - count of snapshots
+ * H - tree height
+ * Worst case space complexity: O(N * M)
+ * Sibling path access: O(H) database reads
+ */
+export class FullTreeSnapshotBuilder
+  extends BaseFullTreeSnapshotBuilder<TreeBase, TreeSnapshot>
+  implements TreeSnapshotBuilder<TreeSnapshot>
+{
+  protected openSnapshot(root: Buffer, numLeaves: bigint): TreeSnapshot {
+    return new BaseFullTreeSnapshot(this.db, root, numLeaves, this.tree);
+  }
+}

package/src/snapshots/indexed_tree_snapshot.ts

@@ -0,0 +1,108 @@
+import { IndexedTreeLeafPreimage } from '@aztec/foundation/trees';
+
+import { LevelUp, LevelUpChain } from 'levelup';
+
+import { IndexedTree } from '../interfaces/indexed_tree.js';
+import { PreimageFactory } from '../standard_indexed_tree/standard_indexed_tree.js';
+import { TreeBase } from '../tree_base.js';
+import { BaseFullTreeSnapshot, BaseFullTreeSnapshotBuilder } from './base_full_snapshot.js';
+import { IndexedTreeSnapshot, TreeSnapshotBuilder } from './snapshot_builder.js';
+
+const snapshotLeafValue = (node: Buffer, index: bigint) =>
+  Buffer.concat([Buffer.from('snapshot:leaf:'), node, Buffer.from(':' + index)]);
+
+/** a */
+export class IndexedTreeSnapshotBuilder
+  extends BaseFullTreeSnapshotBuilder<IndexedTree & TreeBase, IndexedTreeSnapshot>
+  implements TreeSnapshotBuilder<IndexedTreeSnapshot>
+{
+  constructor(db: LevelUp, tree: IndexedTree & TreeBase, private leafPreimageBuilder: PreimageFactory) {
+    super(db, tree);
+  }
+
+  protected openSnapshot(root: Buffer, numLeaves: bigint): IndexedTreeSnapshot {
+    return new IndexedTreeSnapshotImpl(this.db, root, numLeaves, this.tree, this.leafPreimageBuilder);
+  }
+
+  protected async handleLeaf(index: bigint, node: Buffer, batch: LevelUpChain) {
+    const leafPreimage = await this.tree.getLatestLeafPreimageCopy(index, false);
+    if (leafPreimage) {
+      batch.put(snapshotLeafValue(node, index), leafPreimage.toBuffer());
+    }
+  }
+}
+
+/** A snapshot of an indexed tree at a particular point in time */
+class IndexedTreeSnapshotImpl extends BaseFullTreeSnapshot implements IndexedTreeSnapshot {
+  constructor(
+    db: LevelUp,
+    historicRoot: Buffer,
+    numLeaves: bigint,
+    tree: IndexedTree & TreeBase,
+    private leafPreimageBuilder: PreimageFactory,
+  ) {
+    super(db, historicRoot, numLeaves, tree);
+  }
+
+  async getLeafValue(index: bigint): Promise<Buffer | undefined> {
+    const leafPreimage = await this.getLatestLeafPreimageCopy(index);
+    return leafPreimage?.toBuffer();
+  }
+
+  async getLatestLeafPreimageCopy(index: bigint): Promise<IndexedTreeLeafPreimage | undefined> {
+    const leafNode = await super.getLeafValue(index);
+    const leafValue = await this.db.get(snapshotLeafValue(leafNode!, index)).catch(() => undefined);
+    if (leafValue) {
+      return this.leafPreimageBuilder.fromBuffer(leafValue);
+    } else {
+      return undefined;
+    }
+  }
+
+  async findIndexOfPreviousKey(newValue: 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;
+  }> {
+    const numLeaves = this.getNumLeaves();
+    const diff: bigint[] = [];
+
+    for (let i = 0; i < numLeaves; i++) {
+      // this is very inefficient
+      const storedLeaf = await this.getLatestLeafPreimageCopy(BigInt(i))!;
+
+      // The stored leaf can be undefined if it addresses an empty leaf
+      // If the leaf is empty we do the same as if the leaf was larger
+      if (storedLeaf === undefined) {
+        diff.push(newValue);
+      } else if (storedLeaf.getKey() > newValue) {
+        diff.push(newValue);
+      } else if (storedLeaf.getKey() === newValue) {
+        return { index: BigInt(i), alreadyPresent: true };
+      } else {
+        diff.push(newValue - storedLeaf.getKey());
+      }
+    }
+
+    let minIndex = 0;
+    for (let i = 1; i < diff.length; i++) {
+      if (diff[i] < diff[minIndex]) {
+        minIndex = i;
+      }
+    }
+
+    return { index: BigInt(minIndex), alreadyPresent: false };
+  }
+
+  async findLeafIndex(value: Buffer): Promise<bigint | undefined> {
+    const index = await this.tree.findLeafIndex(value, false);
+    if (index !== undefined && index < this.getNumLeaves()) {
+      return index;
+    }
+  }
+}

package/src/snapshots/snapshot_builder.ts

@@ -0,0 +1,84 @@
+import { IndexedTreeLeafPreimage } from '@aztec/foundation/trees';
+import { SiblingPath } from '@aztec/types';
+
+/**
+ * An interface for a tree that can record snapshots of its contents.
+ */
+export interface TreeSnapshotBuilder<S extends TreeSnapshot = TreeSnapshot> {
+  /**
+   * Creates a snapshot of the tree at the given version.
+   * @param block - The version to snapshot the tree at.
+   */
+  snapshot(block: number): Promise<S>;
+
+  /**
+   * Returns a snapshot of the tree at the given version.
+   * @param block - The version of the snapshot to return.
+   */
+  getSnapshot(block: number): Promise<S>;
+}
+
+/**
+ * A tree snapshot
+ */
+export interface TreeSnapshot {
+  /**
+   * Returns the current root of the tree.
+   */
+  getRoot(): Buffer;
+
+  /**
+   * Returns the number of leaves in the tree.
+   */
+  getDepth(): number;
+
+  /**
+   * Returns the number of leaves in the tree.
+   */
+  getNumLeaves(): bigint;
+
+  /**
+   * Returns the value of a leaf at the specified index.
+   * @param index - The index of the leaf value to be returned.
+   */
+  getLeafValue(index: bigint): Promise<Buffer | undefined>;
+
+  /**
+   * Returns the sibling path for a requested leaf index.
+   * @param index - The index of the leaf for which a sibling path is required.
+   */
+  getSiblingPath<N extends number>(index: bigint): Promise<SiblingPath<N>>;
+
+  /**
+   * 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(value: Buffer): Promise<bigint | undefined>;
+}
+
+/** A snapshot of an indexed tree */
+export interface IndexedTreeSnapshot extends TreeSnapshot {
+  /**
+   * Gets the historical data for a leaf
+   * @param index - The index of the leaf to get the data for
+   */
+  getLatestLeafPreimageCopy(index: bigint): Promise<IndexedTreeLeafPreimage | undefined>;
+
+  /**
+   * Finds the index of the largest leaf whose value is less than or equal to the provided value.
+   * @param newValue - The new value to be inserted into the tree.
+   * @returns The found leaf index and a flag indicating if the corresponding leaf's value is equal to `newValue`.
+   */
+  findIndexOfPreviousKey(newValue: 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;
+  }>;
+}