@aztec/merkle-tree 0.1.0-alpha10

package/src/standard_tree/standard_tree.ts

@@ -0,0 +1,54 @@
+import { AppendOnlyTree } from '../interfaces/append_only_tree.js';
+import { TreeBase, indexToKeyHash } from '../tree_base.js';
+
+/**
+ * A Merkle tree implementation that uses a LevelDB database to store the tree.
+ */
+export class StandardTree extends TreeBase implements AppendOnlyTree {
+  /**
+   * Appends the given leaves to the tree.
+   * @param leaves - The leaves to append.
+   * @returns Empty promise.
+   *
+   * @remarks The batch insertion algorithm works as follows:
+   *          1. Insert all the leaves,
+   *          2. start iterating over levels from the bottom up,
+   *          3. on each level iterate over all the affected nodes (i.e. nodes whose preimages have changed),
+   *          4. fetch the preimage, hash it and insert the updated value.
+   * @remarks This algorithm is optimal when it comes to the number of hashing operations. It might not be optimal when
+   *          it comes to the number of database reads, but that should be irrelevant given that most of the time
+   *          `getLatestValueAtIndex` will return a value from cache (because at least one of the 2 children was
+   *          touched in previous iteration).
+   */
+  public async appendLeaves(leaves: Buffer[]): Promise<void> {
+    const numLeaves = this.getNumLeaves(true);
+    if (numLeaves + BigInt(leaves.length) - 1n > this.maxIndex) {
+      throw Error(`Can't append beyond max index. Max index: ${this.maxIndex}`);
+    }
+
+    // 1. Insert all the leaves
+    let firstIndex = numLeaves;
+    let level = this.depth;
+    for (let i = 0; i < leaves.length; i++) {
+      const cacheKey = indexToKeyHash(this.name, level, firstIndex + BigInt(i));
+      this.cache[cacheKey] = leaves[i];
+    }
+
+    let lastIndex = firstIndex + BigInt(leaves.length);
+    // 2. Iterate over all the levels from the bottom up
+    while (level > 0) {
+      firstIndex >>= 1n;
+      lastIndex >>= 1n;
+      // 3.Iterate over all the affected nodes at this level and update them
+      for (let index = firstIndex; index <= lastIndex; index++) {
+        const lhs = await this.getLatestValueAtIndex(level, index * 2n, true);
+        const rhs = await this.getLatestValueAtIndex(level, index * 2n + 1n, true);
+        const cacheKey = indexToKeyHash(this.name, level - 1, index);
+        this.cache[cacheKey] = this.hasher.compress(lhs, rhs);
+      }
+
+      level -= 1;
+    }
+    this.cachedSize = numLeaves + BigInt(leaves.length);
+  }
+}

package/src/test/standard_based_test_suite.ts

@@ -0,0 +1,139 @@
+import { default as levelup } from 'levelup';
+import { Hasher, INITIAL_LEAF, Pedersen, SiblingPath } from '../index.js';
+import { appendLeaves } from './utils/append_leaves.js';
+import { createMemDown } from './utils/create_mem_down.js';
+import { randomBytes } from 'crypto';
+import { AppendOnlyTree } from '../interfaces/append_only_tree.js';
+import { UpdateOnlyTree } from '../interfaces/update_only_tree.js';
+import { IWasmModule } from '@aztec/foundation/wasm';
+import { CircuitsWasm } from '@aztec/circuits.js';
+
+const TEST_TREE_DEPTH = 2;
+
+export const standardBasedTreeTestSuite = (
+  testName: string,
+  createDb: (
+    levelup: levelup.LevelUp,
+    hasher: Hasher,
+    name: string,
+    depth: number,
+  ) => Promise<AppendOnlyTree | UpdateOnlyTree>,
+) => {
+  describe(testName, () => {
+    let wasm: IWasmModule;
+    let pedersen: Pedersen;
+    const values: Buffer[] = [];
+
+    beforeAll(async () => {
+      wasm = await CircuitsWasm.get();
+      pedersen = new Pedersen(wasm);
+
+      for (let i = 0; i < 4; ++i) {
+        const v = Buffer.alloc(32, i + 1);
+        v.writeUInt32BE(i, 28);
+        values[i] = v;
+      }
+    });
+
+    it('should have correct empty tree root for depth 32', async () => {
+      const db = levelup(createMemDown());
+      const tree = await createDb(db, pedersen, 'test', 32);
+      const root = tree.getRoot(false);
+      expect(root.toString('hex')).toEqual('20efbe2c7b675f26ab71689279908bbab33a6963e7e0dcb80e4c46583d094113');
+    });
+
+    it('should throw when appending beyond max index', async () => {
+      const db = levelup(createMemDown());
+      const tree = await createDb(db, pedersen, 'test', 2);
+      const leaves = Array.from({ length: 5 }, _ => randomBytes(32));
+      await expect(appendLeaves(tree, leaves)).rejects.toThrow();
+    });
+
+    it('should have correct root and sibling paths', async () => {
+      const db = levelup(createMemDown());
+      const tree = await createDb(db, pedersen, 'test', 2);
+
+      const level1ZeroHash = pedersen.compress(INITIAL_LEAF, INITIAL_LEAF);
+      expect(tree.getNumLeaves(false)).toEqual(0n);
+      expect(tree.getRoot(false)).toEqual(pedersen.compress(level1ZeroHash, level1ZeroHash));
+      expect(await tree.getSiblingPath(0n, false)).toEqual(
+        new SiblingPath(TEST_TREE_DEPTH, [INITIAL_LEAF, level1ZeroHash]),
+      );
+
+      await appendLeaves(tree, [values[0]]);
+      expect(tree.getNumLeaves(true)).toEqual(1n);
+      expect(tree.getNumLeaves(false)).toEqual(0n);
+      expect(tree.getRoot(true)).toEqual(pedersen.compress(pedersen.compress(values[0], INITIAL_LEAF), level1ZeroHash));
+      expect(await tree.getSiblingPath(0n, true)).toEqual(
+        new SiblingPath(TEST_TREE_DEPTH, [INITIAL_LEAF, level1ZeroHash]),
+      );
+      expect(tree.getRoot(false)).toEqual(pedersen.compress(level1ZeroHash, level1ZeroHash));
+      expect(await tree.getSiblingPath(0n, false)).toEqual(
+        new SiblingPath(TEST_TREE_DEPTH, [INITIAL_LEAF, level1ZeroHash]),
+      );
+
+      await appendLeaves(tree, [values[1]]);
+      expect(tree.getNumLeaves(true)).toEqual(2n);
+      expect(tree.getRoot(true)).toEqual(pedersen.compress(pedersen.compress(values[0], values[1]), level1ZeroHash));
+      expect(await tree.getSiblingPath(1n, true)).toEqual(
+        new SiblingPath(TEST_TREE_DEPTH, [values[0], level1ZeroHash]),
+      );
+      expect(tree.getNumLeaves(false)).toEqual(0n);
+      expect(tree.getRoot(false)).toEqual(pedersen.compress(level1ZeroHash, level1ZeroHash));
+      expect(await tree.getSiblingPath(1n, false)).toEqual(
+        new SiblingPath(TEST_TREE_DEPTH, [INITIAL_LEAF, level1ZeroHash]),
+      );
+
+      await appendLeaves(tree, [values[2]]);
+      expect(tree.getNumLeaves(true)).toEqual(3n);
+      expect(tree.getRoot(true)).toEqual(
+        pedersen.compress(pedersen.compress(values[0], values[1]), pedersen.compress(values[2], INITIAL_LEAF)),
+      );
+      expect(await tree.getSiblingPath(2n, true)).toEqual(
+        new SiblingPath(TEST_TREE_DEPTH, [INITIAL_LEAF, pedersen.compress(values[0], values[1])]),
+      );
+      expect(tree.getNumLeaves(false)).toEqual(0n);
+      expect(tree.getRoot(false)).toEqual(pedersen.compress(level1ZeroHash, level1ZeroHash));
+      expect(await tree.getSiblingPath(2n, false)).toEqual(
+        new SiblingPath(TEST_TREE_DEPTH, [INITIAL_LEAF, level1ZeroHash]),
+      );
+
+      await appendLeaves(tree, [values[3]]);
+      expect(tree.getNumLeaves(true)).toEqual(4n);
+      expect(tree.getRoot(true)).toEqual(
+        pedersen.compress(pedersen.compress(values[0], values[1]), pedersen.compress(values[2], values[3])),
+      );
+      expect(await tree.getSiblingPath(3n, true)).toEqual(
+        new SiblingPath(TEST_TREE_DEPTH, [values[2], pedersen.compress(values[0], values[1])]),
+      );
+      expect(tree.getNumLeaves(false)).toEqual(0n);
+      expect(tree.getRoot(false)).toEqual(pedersen.compress(level1ZeroHash, level1ZeroHash));
+      expect(await tree.getSiblingPath(3n, false)).toEqual(
+        new SiblingPath(TEST_TREE_DEPTH, [INITIAL_LEAF, level1ZeroHash]),
+      );
+      // Lifted from memory_tree.test.cpp to ensure consistency.
+      //expect(root.toString('hex')).toEqual('0bf2e78afd70f72b0e6eafb03c41faef167a82441b05e517cdf35d813302061f');
+      expect(await tree.getSiblingPath(0n, true)).toEqual(
+        new SiblingPath(TEST_TREE_DEPTH, [values[1], pedersen.compress(values[2], values[3])]),
+      );
+      expect(await tree.getSiblingPath(1n, true)).toEqual(
+        new SiblingPath(TEST_TREE_DEPTH, [values[0], pedersen.compress(values[2], values[3])]),
+      );
+      expect(await tree.getSiblingPath(2n, true)).toEqual(
+        new SiblingPath(TEST_TREE_DEPTH, [values[3], pedersen.compress(values[0], values[1])]),
+      );
+      expect(await tree.getSiblingPath(3n, true)).toEqual(
+        new SiblingPath(TEST_TREE_DEPTH, [values[2], pedersen.compress(values[0], values[1])]),
+      );
+
+      await tree.commit();
+      // now committed state should equal uncommitted state
+      expect(await tree.getSiblingPath(0n, false)).toEqual(await tree.getSiblingPath(0n, true));
+      expect(await tree.getSiblingPath(1n, false)).toEqual(await tree.getSiblingPath(1n, true));
+      expect(await tree.getSiblingPath(2n, false)).toEqual(await tree.getSiblingPath(2n, true));
+      expect(await tree.getSiblingPath(3n, false)).toEqual(await tree.getSiblingPath(3n, true));
+      expect(tree.getNumLeaves(false)).toEqual(tree.getNumLeaves(true));
+      expect(tree.getRoot(false)).toEqual(tree.getRoot(true));
+    });
+  });
+};

package/src/test/test_suite.ts

@@ -0,0 +1,162 @@
+import { IWasmModule } from '@aztec/foundation/wasm';
+import { default as levelup } from 'levelup';
+import { Hasher, Pedersen, SiblingPath } from '../index.js';
+import { appendLeaves } from './utils/append_leaves.js';
+import { createMemDown } from './utils/create_mem_down.js';
+import { AppendOnlyTree } from '../interfaces/append_only_tree.js';
+import { UpdateOnlyTree } from '../interfaces/update_only_tree.js';
+import { CircuitsWasm } from '@aztec/circuits.js';
+
+const expectSameTrees = async (
+  tree1: AppendOnlyTree | UpdateOnlyTree,
+  tree2: AppendOnlyTree | UpdateOnlyTree,
+  includeUncommitted = true,
+) => {
+  const size = tree1.getNumLeaves(includeUncommitted);
+  expect(size).toBe(tree2.getNumLeaves(includeUncommitted));
+  expect(tree1.getRoot(includeUncommitted).toString('hex')).toBe(tree2.getRoot(includeUncommitted).toString('hex'));
+
+  for (let i = 0; i < size; ++i) {
+    const siblingPath1 = await tree1.getSiblingPath(BigInt(i), includeUncommitted);
+    const siblingPath2 = await tree2.getSiblingPath(BigInt(i), includeUncommitted);
+    expect(siblingPath2).toStrictEqual(siblingPath1);
+  }
+};
+
+export const treeTestSuite = (
+  testName: string,
+  createDb: (
+    levelup: levelup.LevelUp,
+    hasher: Hasher,
+    name: string,
+    depth: number,
+  ) => Promise<AppendOnlyTree | UpdateOnlyTree>,
+  createFromName: (levelup: levelup.LevelUp, hasher: Hasher, name: string) => Promise<AppendOnlyTree | UpdateOnlyTree>,
+) => {
+  describe(testName, () => {
+    const values: Buffer[] = [];
+    let wasm: IWasmModule;
+    let pedersen: Pedersen;
+
+    beforeAll(() => {
+      for (let i = 0; i < 32; ++i) {
+        const v = Buffer.alloc(32, i + 1);
+        v.writeUInt32BE(i, 28);
+        values[i] = v;
+      }
+    });
+
+    beforeEach(async () => {
+      wasm = await CircuitsWasm.get();
+      pedersen = new Pedersen(wasm);
+    });
+
+    it('should revert changes on rollback', async () => {
+      const levelDownEmpty = createMemDown();
+      const dbEmpty = levelup(levelDownEmpty);
+      const emptyTree = await createDb(dbEmpty, pedersen, 'test', 10);
+
+      const levelDown = createMemDown();
+      const db = levelup(levelDown);
+      const tree = await createDb(db, pedersen, 'test2', 10);
+      await appendLeaves(tree, values.slice(0, 4));
+
+      const firstRoot = tree.getRoot(true);
+      expect(firstRoot).not.toEqual(emptyTree.getRoot(true));
+      // committed root should still be the empty root
+      expect(tree.getRoot(false)).toEqual(emptyTree.getRoot(false));
+
+      await tree.rollback();
+
+      // both committed and uncommitted trees should be equal to the empty tree
+      await expectSameTrees(tree, emptyTree, true);
+      await expectSameTrees(tree, emptyTree, false);
+
+      // append the leaves again
+      await appendLeaves(tree, values.slice(0, 4));
+
+      expect(tree.getRoot(true)).toEqual(firstRoot);
+      // committed root should still be the empty root
+      expect(tree.getRoot(false)).toEqual(emptyTree.getRoot(false));
+
+      expect(firstRoot).not.toEqual(emptyTree.getRoot(true));
+
+      await tree.rollback();
+
+      // both committed and uncommitted trees should be equal to the empty tree
+      await expectSameTrees(tree, emptyTree, true);
+      await expectSameTrees(tree, emptyTree, false);
+    });
+
+    it('should not revert changes after commit', async () => {
+      const levelDownEmpty = createMemDown();
+      const dbEmpty = levelup(levelDownEmpty);
+      const emptyTree = await createDb(dbEmpty, pedersen, 'test', 10);
+
+      const levelDown = createMemDown();
+      const db = levelup(levelDown);
+      const tree = await createDb(db, pedersen, 'test2', 10);
+      await appendLeaves(tree, values.slice(0, 4));
+
+      expect(tree.getRoot(true)).not.toEqual(emptyTree.getRoot(true));
+      // committed root should still be the empty root
+      expect(tree.getRoot(false)).toEqual(emptyTree.getRoot(false));
+
+      await tree.commit();
+      await tree.rollback();
+
+      expect(tree.getRoot(true)).not.toEqual(emptyTree.getRoot(true));
+      expect(tree.getRoot(false)).not.toEqual(emptyTree.getRoot(true));
+    });
+
+    it('should be able to restore from previous committed data', async () => {
+      const levelDown = createMemDown();
+      const db = levelup(levelDown);
+      const tree = await createDb(db, pedersen, 'test', 10);
+      await appendLeaves(tree, values.slice(0, 4));
+      await tree.commit();
+
+      const db2 = levelup(levelDown);
+      const tree2 = await createFromName(db2, pedersen, 'test');
+
+      // both committed and uncommitted should be equal to the restored data
+      expect(tree.getRoot(true)).toEqual(tree2.getRoot(true));
+      expect(tree.getRoot(false)).toEqual(tree2.getRoot(false));
+      for (let i = 0; i < 4; ++i) {
+        expect(await tree.getSiblingPath(BigInt(i), true)).toEqual(await tree2.getSiblingPath(BigInt(i), true));
+        expect(await tree.getSiblingPath(BigInt(i), false)).toEqual(await tree2.getSiblingPath(BigInt(i), false));
+      }
+    });
+
+    it('should throw an error if previous data does not exist for the given name', async () => {
+      const db = levelup(createMemDown());
+      await expect(
+        (async () => {
+          await createFromName(db, pedersen, 'a_whole_new_tree');
+        })(),
+      ).rejects.toThrow();
+    });
+
+    it('should serialize sibling path data to a buffer and be able to deserialize it back', async () => {
+      const db = levelup(createMemDown());
+      const tree = await createDb(db, pedersen, 'test', 10);
+      await appendLeaves(tree, values.slice(0, 1));
+
+      const siblingPath = await tree.getSiblingPath(0n, true);
+      const buf = siblingPath.toBuffer();
+      const recovered = SiblingPath.fromBuffer(buf);
+      expect(recovered).toEqual(siblingPath);
+      const deserialized = SiblingPath.deserialize(buf);
+      expect(deserialized.elem).toEqual(siblingPath);
+      expect(deserialized.adv).toBe(4 + 10 * 32);
+
+      const dummyData = Buffer.alloc(23, 1);
+      const paddedBuf = Buffer.concat([dummyData, buf]);
+      const recovered2 = SiblingPath.fromBuffer(paddedBuf, 23);
+      expect(recovered2).toEqual(siblingPath);
+      const deserialized2 = SiblingPath.deserialize(buf);
+      expect(deserialized2.elem).toEqual(siblingPath);
+      expect(deserialized2.adv).toBe(4 + 10 * 32);
+    });
+  });
+};

package/src/test/utils/append_leaves.ts

@@ -0,0 +1,15 @@
+import { AppendOnlyTree } from '../../interfaces/append_only_tree.js';
+import { UpdateOnlyTree } from '../../interfaces/update_only_tree.js';
+
+export const appendLeaves = async (tree: AppendOnlyTree | UpdateOnlyTree, leaves: Buffer[]) => {
+  if ('appendLeaves' in tree) {
+    // This branch is used by the standard tree test suite, which implements appendLeaves
+    await tree.appendLeaves(leaves);
+  } else {
+    // This branch is used by the sparse tree test suite, which does not implement appendLeaves
+    for (const value of leaves) {
+      const index = tree.getNumLeaves(true);
+      await tree.updateLeaf(value, index);
+    }
+  }
+};

package/src/test/utils/create_mem_down.ts

@@ -0,0 +1,3 @@
+import { default as memdown, type MemDown } from 'memdown';
+
+export const createMemDown = () => (memdown as any)() as MemDown<any, any>;

package/src/test/utils/pedersen_with_counter.ts

@@ -0,0 +1,30 @@
+import { Pedersen } from '../../index.js';
+
+/**
+ * A test utility allowing us to count the number of times the compress function has been called.
+ */
+export class PedersenWithCounter extends Pedersen {
+  /**
+   * The number of times the compress function has been called.
+   */
+  public compressCounter = 0;
+
+  /**
+   * Compresses two 32-byte hashes.
+   * @param lhs - The first hash.
+   * @param rhs - The second hash.
+   * @returns The new 32-byte hash.
+   */
+  public compress(lhs: Uint8Array, rhs: Uint8Array): Buffer {
+    this.compressCounter++;
+    return super.compress(lhs, rhs);
+  }
+
+  /**
+   * Resets the compress counter.
+   * @returns void
+   */
+  public resetCounter() {
+    this.compressCounter = 0;
+  }
+}

package/src/tree_base.ts

@@ -0,0 +1,242 @@
+import { LevelUp, LevelUpChain } from 'levelup';
+import { SiblingPath } from './sibling_path/sibling_path.js';
+import { Hasher } from './hasher.js';
+import { MerkleTree } from './interfaces/merkle_tree.js';
+import { toBigIntLE, toBufferLE } from '@aztec/foundation/bigint-buffer';
+
+const MAX_DEPTH = 254;
+
+export const indexToKeyHash = (name: string, level: number, index: bigint) => `${name}:${level}:${index}`;
+const encodeMeta = (root: Buffer, depth: number, size: bigint) => {
+  const data = Buffer.alloc(36);
+  root.copy(data);
+  data.writeUInt32LE(depth, 32);
+  return Buffer.concat([data, toBufferLE(size, 32)]);
+};
+export const decodeMeta = (meta: Buffer) => {
+  const root = meta.subarray(0, 32);
+  const depth = meta.readUInt32LE(32);
+  const size = toBigIntLE(meta.subarray(36));
+  return {
+    root,
+    depth,
+    size,
+  };
+};
+
+export const INITIAL_LEAF = Buffer.from('0000000000000000000000000000000000000000000000000000000000000000', 'hex');
+
+/**
+ * A Merkle tree implementation that uses a LevelDB database to store the tree.
+ */
+export abstract class TreeBase implements MerkleTree {
+  protected readonly maxIndex: bigint;
+  protected cachedSize?: bigint;
+  private root!: Buffer;
+  private zeroHashes: Buffer[] = [];
+  protected cache: { [key: string]: Buffer } = {};
+
+  public constructor(
+    protected db: LevelUp,
+    protected hasher: Hasher,
+    protected name: string,
+    protected depth: number,
+    protected size: bigint = 0n,
+    root?: Buffer,
+  ) {
+    if (!(depth >= 1 && depth <= MAX_DEPTH)) {
+      throw Error('Invalid depth');
+    }
+
+    // Compute the zero values at each layer.
+    let current = INITIAL_LEAF;
+    for (let i = depth - 1; i >= 0; --i) {
+      this.zeroHashes[i] = current;
+      current = hasher.compress(current, current);
+    }
+
+    this.root = root ? root : current;
+    this.maxIndex = 2n ** BigInt(depth) - 1n;
+  }
+
+  /**
+   * Returns the root of the tree.
+   * @param includeUncommitted - If true, root incorporating uncomitted changes is returned.
+   * @returns The root of the tree.
+   */
+  public getRoot(includeUncommitted: boolean): Buffer {
+    return !includeUncommitted ? this.root : this.cache[indexToKeyHash(this.name, 0, 0n)] ?? this.root;
+  }
+
+  /**
+   * Returns the number of leaves in the tree.
+   * @param includeUncommitted - If true, the returned number of leaves includes uncomitted changes.
+   * @returns The number of leaves in the tree.
+   */
+  public getNumLeaves(includeUncommitted: boolean) {
+    return !includeUncommitted ? this.size : this.cachedSize ?? this.size;
+  }
+
+  /**
+   * Returns the name of the tree.
+   * @returns The name of the tree.
+   */
+  public getName(): string {
+    return this.name;
+  }
+
+  /**
+   * Returns the depth of the tree.
+   * @returns The depth of the tree.
+   */
+  public getDepth(): number {
+    return this.depth;
+  }
+
+  /**
+   * Returns a sibling path for the element at the given index.
+   * @param index - The index of the element.
+   * @param includeUncommitted - Indicates whether to get a sibling path incorporating uncommitted changes.
+   * @returns A sibling path for the element at the given index.
+   * Note: The sibling path is an array of sibling hashes, with the lowest hash (leaf hash) first, and the highest hash last.
+   */
+  public async getSiblingPath<N extends number>(index: bigint, includeUncommitted: boolean): Promise<SiblingPath<N>> {
+    const path: Buffer[] = [];
+    let level = this.depth;
+    while (level > 0) {
+      const isRight = index & 0x01n;
+      const sibling = await this.getLatestValueAtIndex(level, isRight ? index - 1n : index + 1n, includeUncommitted);
+      path.push(sibling);
+      level -= 1;
+      index >>= 1n;
+    }
+    return new SiblingPath<N>(this.depth as N, path);
+  }
+
+  /**
+   * Commits the changes to the database.
+   * @returns Empty promise.
+   */
+  public async commit(): Promise<void> {
+    const batch = this.db.batch();
+    const keys = Object.getOwnPropertyNames(this.cache);
+    for (const key of keys) {
+      batch.put(key, this.cache[key]);
+    }
+    this.size = this.getNumLeaves(true);
+    this.root = this.getRoot(true);
+    await this.writeMeta(batch);
+    await batch.write();
+    this.clearCache();
+  }
+
+  /**
+   * Rolls back the not-yet-committed changes.
+   * @returns Empty promise.
+   */
+  public rollback(): Promise<void> {
+    this.clearCache();
+    return Promise.resolve();
+  }
+
+  /**
+   * Gets the value at the given index.
+   * @param index - The index of the leaf.
+   * @param includeUncommitted - Indicates whether to include uncommitted changes.
+   * @returns Leaf value at the given index or undefined.
+   */
+  public getLeafValue(index: bigint, includeUncommitted: boolean): Promise<Buffer | undefined> {
+    return this.getLatestValueAtIndex(this.depth, index, includeUncommitted);
+  }
+
+  /**
+   * Clears the cache.
+   */
+  private clearCache() {
+    this.cache = {};
+    this.cachedSize = undefined;
+  }
+
+  /**
+   * Adds a leaf and all the hashes above it to the cache.
+   * @param leaf - Leaf to add to cache.
+   * @param index - Index of the leaf (used to derive the cache key).
+   */
+  protected async addLeafToCacheAndHashToRoot(leaf: Buffer, index: bigint) {
+    const key = indexToKeyHash(this.name, this.depth, index);
+    let current = leaf;
+    this.cache[key] = current;
+    let level = this.depth;
+    while (level > 0) {
+      const isRight = index & 0x01n;
+      const sibling = await this.getLatestValueAtIndex(level, isRight ? index - 1n : index + 1n, true);
+      const lhs = isRight ? sibling : current;
+      const rhs = isRight ? current : sibling;
+      current = this.hasher.compress(lhs, rhs);
+      level -= 1;
+      index >>= 1n;
+      const cacheKey = indexToKeyHash(this.name, level, index);
+      this.cache[cacheKey] = current;
+    }
+  }
+
+  /**
+   * Returns the latest value at the given index.
+   * @param level - The level of the tree.
+   * @param index - The index of the element.
+   * @param includeUncommitted - Indicates, whether to get include uncommitted changes.
+   * @returns The latest value at the given index.
+   * Note: If the value is not in the cache, it will be fetched from the database.
+   */
+  protected async getLatestValueAtIndex(level: number, index: bigint, includeUncommitted: boolean): Promise<Buffer> {
+    const key = indexToKeyHash(this.name, level, index);
+    if (includeUncommitted && this.cache[key] !== undefined) {
+      return this.cache[key];
+    }
+    const committed = await this.dbGet(key);
+    if (committed !== undefined) {
+      return committed;
+    }
+    return this.zeroHashes[level - 1];
+  }
+
+  /**
+   * Gets a value from db by key.
+   * @param key - The key to by which to get the value.
+   * @returns A value from the db based on the key.
+   */
+  private async dbGet(key: string): Promise<Buffer | undefined> {
+    return await this.db.get(key).catch(() => {});
+  }
+
+  /**
+   * Initializes the tree.
+   * @param prefilledSize - A number of leaves that are prefilled with values.
+   * @returns Empty promise.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public async init(prefilledSize: number): Promise<void> {
+    // prefilledSize is used only by Indexed Tree.
+    await this.writeMeta();
+  }
+
+  /**
+   * Initializes the tree from the database.
+   */
+  public async initFromDb(): Promise<void> {
+    // Implemented only by Inedexed Tree to populate the leaf cache.
+  }
+
+  /**
+   * Writes meta data to the provided batch.
+   * @param batch - The batch to which to write the meta data.
+   */
+  protected async writeMeta(batch?: LevelUpChain<string, Buffer>) {
+    const data = encodeMeta(this.getRoot(true), this.depth, this.getNumLeaves(true));
+    if (batch) {
+      batch.put(this.name, data);
+    } else {
+      await this.db.put(this.name, data);
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": "..",
+  "compilerOptions": {
+    "outDir": "dest",
+    "rootDir": "src",
+    "tsBuildInfoFile": ".tsbuildinfo"
+  },
+  "references": [
+    {
+      "path": "../circuits.js"
+    },
+    {
+      "path": "../foundation"
+    }
+  ],
+  "include": ["src"]
+}