@aztec/merkle-tree 0.44.0 → 0.45.1

package/dest/index.d.ts

@@ -8,6 +8,7 @@ export * from './sparse_tree/sparse_tree.js';
 export { StandardIndexedTree } from './standard_indexed_tree/standard_indexed_tree.js';
 export { StandardIndexedTreeWithAppend } from './standard_indexed_tree/test/standard_indexed_tree_with_append.js';
 export * from './standard_tree/standard_tree.js';
+export * from './unbalanced_tree.js';
 export { INITIAL_LEAF, getTreeMeta } from './tree_base.js';
 export { newTree } from './new_tree.js';
 export { loadTree } from './load_tree.js';

package/dest/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kCAAkC,CAAC;AACjD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,8BAA8B,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AACvF,OAAO,EAAE,6BAA6B,EAAE,MAAM,mEAAmE,CAAC;AAClH,cAAc,kCAAkC,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qCAAqC,CAAC;AACpD,cAAc,sCAAsC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kCAAkC,CAAC;AACjD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,8BAA8B,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AACvF,OAAO,EAAE,6BAA6B,EAAE,MAAM,mEAAmE,CAAC;AAClH,cAAc,kCAAkC,CAAC;AACjD,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qCAAqC,CAAC;AACpD,cAAc,sCAAsC,CAAC"}

package/dest/index.js

@@ -8,6 +8,7 @@ export * from './sparse_tree/sparse_tree.js';
 export { StandardIndexedTree } from './standard_indexed_tree/standard_indexed_tree.js';
 export { StandardIndexedTreeWithAppend } from './standard_indexed_tree/test/standard_indexed_tree_with_append.js';
 export * from './standard_tree/standard_tree.js';
+export * from './unbalanced_tree.js';
 export { INITIAL_LEAF, getTreeMeta } from './tree_base.js';
 export { newTree } from './new_tree.js';
 export { loadTree } from './load_tree.js';
@@ -15,4 +16,4 @@ export * from './snapshots/snapshot_builder.js';
 export * from './snapshots/full_snapshot.js';
 export * from './snapshots/append_only_snapshot.js';
 export * from './snapshots/indexed_tree_snapshot.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxrQ0FBa0MsQ0FBQztBQUNqRCxjQUFjLDhCQUE4QixDQUFDO0FBQzdDLGNBQWMsNkJBQTZCLENBQUM7QUFDNUMsY0FBYyxrQ0FBa0MsQ0FBQztBQUNqRCxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLDhCQUE4QixDQUFDO0FBQzdDLE9BQU8sRUFBRSxtQkFBbUIsRUFBRSxNQUFNLGtEQUFrRCxDQUFDO0FBQ3ZGLE9BQU8sRUFBRSw2QkFBNkIsRUFBRSxNQUFNLG1FQUFtRSxDQUFDO0FBQ2xILGNBQWMsa0NBQWtDLENBQUM7QUFDakQsT0FBTyxFQUFFLFlBQVksRUFBRSxXQUFXLEVBQUUsTUFBTSxnQkFBZ0IsQ0FBQztBQUMzRCxPQUFPLEVBQUUsT0FBTyxFQUFFLE1BQU0sZUFBZSxDQUFDO0FBQ3hDLE9BQU8sRUFBRSxRQUFRLEVBQUUsTUFBTSxnQkFBZ0IsQ0FBQztBQUMxQyxjQUFjLGlDQUFpQyxDQUFDO0FBQ2hELGNBQWMsOEJBQThCLENBQUM7QUFDN0MsY0FBYyxxQ0FBcUMsQ0FBQztBQUNwRCxjQUFjLHNDQUFzQyxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxrQ0FBa0MsQ0FBQztBQUNqRCxjQUFjLDhCQUE4QixDQUFDO0FBQzdDLGNBQWMsNkJBQTZCLENBQUM7QUFDNUMsY0FBYyxrQ0FBa0MsQ0FBQztBQUNqRCxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLDhCQUE4QixDQUFDO0FBQzdDLE9BQU8sRUFBRSxtQkFBbUIsRUFBRSxNQUFNLGtEQUFrRCxDQUFDO0FBQ3ZGLE9BQU8sRUFBRSw2QkFBNkIsRUFBRSxNQUFNLG1FQUFtRSxDQUFDO0FBQ2xILGNBQWMsa0NBQWtDLENBQUM7QUFDakQsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxPQUFPLEVBQUUsWUFBWSxFQUFFLFdBQVcsRUFBRSxNQUFNLGdCQUFnQixDQUFDO0FBQzNELE9BQU8sRUFBRSxPQUFPLEVBQUUsTUFBTSxlQUFlLENBQUM7QUFDeEMsT0FBTyxFQUFFLFFBQVEsRUFBRSxNQUFNLGdCQUFnQixDQUFDO0FBQzFDLGNBQWMsaUNBQWlDLENBQUM7QUFDaEQsY0FBYyw4QkFBOEIsQ0FBQztBQUM3QyxjQUFjLHFDQUFxQyxDQUFDO0FBQ3BELGNBQWMsc0NBQXNDLENBQUMifQ==

package/dest/unbalanced_tree.d.ts

@@ -0,0 +1,108 @@
+/// <reference types="node" resolution-mode="require"/>
+import { SiblingPath } from '@aztec/circuit-types';
+import { type Bufferable, type FromBuffer } from '@aztec/foundation/serialize';
+import { type Hasher } from '@aztec/types/interfaces';
+import { HasherWithStats } from './hasher_with_stats.js';
+import { type MerkleTree } from './interfaces/merkle_tree.js';
+/**
+ * An ephemeral unbalanced Merkle tree implementation.
+ * Follows the rollup implementation which greedily hashes pairs of nodes up the tree.
+ * Remaining rightmost nodes are shifted up until they can be paired. See proving-state.ts -> findMergeLevel.
+ */
+export declare class UnbalancedTree<T extends Bufferable = Buffer> implements MerkleTree<T> {
+    private name;
+    private maxDepth;
+    protected deserializer: FromBuffer<T>;
+    private cache;
+    private valueCache;
+    protected size: bigint;
+    protected readonly maxIndex: bigint;
+    protected hasher: HasherWithStats;
+    root: Buffer;
+    constructor(hasher: Hasher, name: string, maxDepth: number, deserializer: FromBuffer<T>);
+    /**
+     * Returns the root of the tree.
+     * @returns The root of the tree.
+     */
+    getRoot(): Buffer;
+    /**
+     * Returns the number of leaves in the tree.
+     * @returns The number of leaves in the tree.
+     */
+    getNumLeaves(): bigint;
+    /**
+     * Returns the max depth of the tree.
+     * @returns The max depth of the tree.
+     */
+    getDepth(): number;
+    /**
+     * @remark A wonky tree is (currently) only ever ephemeral, so we don't use any db to commit to.
+     * The fn must exist to implement MerkleTree however.
+     */
+    commit(): Promise<void>;
+    /**
+     * Rolls back the not-yet-committed changes.
+     * @returns Empty promise.
+     */
+    rollback(): Promise<void>;
+    /**
+     * Clears the cache.
+     */
+    private clearCache;
+    /**
+     * @remark A wonky tree can validly have duplicate indices:
+     * e.g. 001 (index 1 at level 3) and 01 (index 1 at level 2)
+     * So this function cannot reliably give the expected leaf value.
+     * We cannot add level as an input as its based on the MerkleTree class's function.
+     */
+    getLeafValue(_index: bigint): undefined;
+    /**
+     * Returns the index of a leaf given its value, or undefined if no leaf with that value is found.
+     * @param leaf - The leaf value to look for.
+     * @returns The index of the first leaf found with a given value (undefined if not found).
+     * @remark This is NOT the index as inserted, but the index which will be used to calculate path structure.
+     */
+    findLeafIndex(value: T): bigint | undefined;
+    /**
+     * Returns the first index containing a leaf value after `startIndex`.
+     * @param value - The leaf value to look for.
+     * @param startIndex - The index to start searching from.
+     * @returns The index of the first leaf found with a given value (undefined if not found).
+     * @remark This is not really used for a wonky tree, but required to implement MerkleTree.
+     */
+    findLeafIndexAfter(value: T, startIndex: bigint): bigint | undefined;
+    /**
+     * Returns the node at the given level and index
+     * @param level - The level of the element (root is at level 0).
+     * @param index - The index of the element.
+     * @returns Leaf or node value, or undefined.
+     */
+    getNode(level: number, index: bigint): Buffer | undefined;
+    /**
+     * Returns a sibling path for the element at the given index.
+     * @param value - The value of the element.
+     * @returns A sibling path for the element.
+     * Note: The sibling path is an array of sibling hashes, with the lowest hash (leaf hash) first, and the highest hash last.
+     */
+    getSiblingPath<N extends number>(value: bigint): Promise<SiblingPath<N>>;
+    /**
+     * Appends the given leaves to the tree.
+     * @param leaves - The leaves to append.
+     * @returns Empty promise.
+     */
+    appendLeaves(leaves: T[]): Promise<void>;
+    /**
+     * Calculates root while adding leaves and nodes to the cache.
+     * @param leaves - The leaves to append.
+     * @returns Resulting root of the tree.
+     */
+    private batchInsert;
+    /**
+     * Stores the given node in the cache.
+     * @param value - The value to store.
+     * @param depth - The depth of the node in the full tree.
+     * @param index - The index of the node at the given depth.
+     */
+    private storeNode;
+}
+//# sourceMappingURL=unbalanced_tree.d.ts.map

package/dest/unbalanced_tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unbalanced_tree.d.ts","sourceRoot":"","sources":["../src/unbalanced_tree.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAqB,MAAM,6BAA6B,CAAC;AAClG,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAI9D;;;;GAIG;AACH,qBAAa,cAAc,CAAC,CAAC,SAAS,UAAU,GAAG,MAAM,CAAE,YAAW,UAAU,CAAC,CAAC,CAAC;IAa/E,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,QAAQ;IAChB,SAAS,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC,CAAC;IAbvC,OAAO,CAAC,KAAK,CAAiC;IAE9C,OAAO,CAAC,UAAU,CAAiC;IACnD,SAAS,CAAC,IAAI,EAAE,MAAM,CAAM;IAC5B,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAEpC,SAAS,CAAC,MAAM,EAAE,eAAe,CAAC;IAClC,IAAI,EAAE,MAAM,CAAoB;gBAG9B,MAAM,EAAE,MAAM,EACN,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAU,EAClB,YAAY,EAAE,UAAU,CAAC,CAAC,CAAC;IAMvC;;;OAGG;IACI,OAAO,IAAI,MAAM;IAIxB;;;OAGG;IACI,YAAY;IAInB;;;OAGG;IACI,QAAQ,IAAI,MAAM;IAIzB;;;OAGG;IACI,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B;;;OAGG;IACI,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAKhC;;OAEG;IACH,OAAO,CAAC,UAAU;IAKlB;;;;;OAKG;IACI,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS;IAI9C;;;;;OAKG;IACI,aAAa,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,GAAG,SAAS;IAMlD;;;;;;OAMG;IACI,kBAAkB,CAAC,KAAK,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAQ3E;;;;;OAKG;IACI,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAYhE;;;;;OAKG;IACI,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAgB/E;;;;OAIG;IACI,YAAY,CAAC,MAAM,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAc/C;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAyCnB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;CAKlB"}

package/dest/unbalanced_tree.js

@@ -0,0 +1,212 @@
+import { SiblingPath } from '@aztec/circuit-types';
+import { serializeToBuffer } from '@aztec/foundation/serialize';
+import { HasherWithStats } from './hasher_with_stats.js';
+const indexToKeyHash = (name, level, index) => `${name}:${level}:${index}`;
+/**
+ * An ephemeral unbalanced Merkle tree implementation.
+ * Follows the rollup implementation which greedily hashes pairs of nodes up the tree.
+ * Remaining rightmost nodes are shifted up until they can be paired. See proving-state.ts -> findMergeLevel.
+ */
+export class UnbalancedTree {
+    constructor(hasher, name, maxDepth = 0, deserializer) {
+        this.name = name;
+        this.maxDepth = maxDepth;
+        this.deserializer = deserializer;
+        // This map stores index and depth -> value
+        this.cache = {};
+        // This map stores value -> index and depth, since we have variable depth
+        this.valueCache = {};
+        this.size = 0n;
+        this.root = Buffer.alloc(32);
+        this.hasher = new HasherWithStats(hasher);
+        this.maxIndex = 2n ** BigInt(this.maxDepth) - 1n;
+    }
+    /**
+     * Returns the root of the tree.
+     * @returns The root of the tree.
+     */
+    getRoot() {
+        return this.root;
+    }
+    /**
+     * Returns the number of leaves in the tree.
+     * @returns The number of leaves in the tree.
+     */
+    getNumLeaves() {
+        return this.size;
+    }
+    /**
+     * Returns the max depth of the tree.
+     * @returns The max depth of the tree.
+     */
+    getDepth() {
+        return this.maxDepth;
+    }
+    /**
+     * @remark A wonky tree is (currently) only ever ephemeral, so we don't use any db to commit to.
+     * The fn must exist to implement MerkleTree however.
+     */
+    commit() {
+        throw new Error("Unsupported function - cannot commit on an unbalanced tree as it's always ephemeral.");
+        return Promise.resolve();
+    }
+    /**
+     * Rolls back the not-yet-committed changes.
+     * @returns Empty promise.
+     */
+    rollback() {
+        this.clearCache();
+        return Promise.resolve();
+    }
+    /**
+     * Clears the cache.
+     */
+    clearCache() {
+        this.cache = {};
+        this.size = 0n;
+    }
+    /**
+     * @remark A wonky tree can validly have duplicate indices:
+     * e.g. 001 (index 1 at level 3) and 01 (index 1 at level 2)
+     * So this function cannot reliably give the expected leaf value.
+     * We cannot add level as an input as its based on the MerkleTree class's function.
+     */
+    getLeafValue(_index) {
+        throw new Error('Unsupported function - cannot get leaf value from an index in an unbalanced tree.');
+    }
+    /**
+     * Returns the index of a leaf given its value, or undefined if no leaf with that value is found.
+     * @param leaf - The leaf value to look for.
+     * @returns The index of the first leaf found with a given value (undefined if not found).
+     * @remark This is NOT the index as inserted, but the index which will be used to calculate path structure.
+     */
+    findLeafIndex(value) {
+        const key = this.valueCache[serializeToBuffer(value).toString('hex')];
+        const [, , index] = key.split(':');
+        return BigInt(index);
+    }
+    /**
+     * Returns the first index containing a leaf value after `startIndex`.
+     * @param value - The leaf value to look for.
+     * @param startIndex - The index to start searching from.
+     * @returns The index of the first leaf found with a given value (undefined if not found).
+     * @remark This is not really used for a wonky tree, but required to implement MerkleTree.
+     */
+    findLeafIndexAfter(value, startIndex) {
+        const index = this.findLeafIndex(value);
+        if (!index || index < startIndex) {
+            return undefined;
+        }
+        return index;
+    }
+    /**
+     * Returns the node at the given level and index
+     * @param level - The level of the element (root is at level 0).
+     * @param index - The index of the element.
+     * @returns Leaf or node value, or undefined.
+     */
+    getNode(level, index) {
+        if (level < 0 || level > this.maxDepth) {
+            throw Error('Invalid level: ' + level);
+        }
+        if (index < 0 || index >= this.maxIndex) {
+            throw Error('Invalid index: ' + index);
+        }
+        return this.cache[indexToKeyHash(this.name, level, index)];
+    }
+    /**
+     * Returns a sibling path for the element at the given index.
+     * @param value - The value of the element.
+     * @returns A sibling path for the element.
+     * Note: The sibling path is an array of sibling hashes, with the lowest hash (leaf hash) first, and the highest hash last.
+     */
+    getSiblingPath(value) {
+        const path = [];
+        const [, depth, _index] = this.valueCache[serializeToBuffer(value).toString('hex')].split(':');
+        let level = parseInt(depth, 10);
+        let index = BigInt(_index);
+        while (level > 0) {
+            const isRight = index & 0x01n;
+            const key = indexToKeyHash(this.name, level, isRight ? index - 1n : index + 1n);
+            const sibling = this.cache[key];
+            path.push(sibling);
+            level -= 1;
+            index >>= 1n;
+        }
+        return Promise.resolve(new SiblingPath(parseInt(depth, 10), path));
+    }
+    /**
+     * Appends the given leaves to the tree.
+     * @param leaves - The leaves to append.
+     * @returns Empty promise.
+     */
+    appendLeaves(leaves) {
+        this.hasher.reset();
+        if (this.size != BigInt(0)) {
+            throw Error(`Can't re-append to an unbalanced tree. Current has ${this.size} leaves.`);
+        }
+        if (this.size + BigInt(leaves.length) - 1n > this.maxIndex) {
+            throw Error(`Can't append beyond max index. Max index: ${this.maxIndex}`);
+        }
+        const root = this.batchInsert(leaves);
+        this.root = root;
+        return Promise.resolve();
+    }
+    /**
+     * Calculates root while adding leaves and nodes to the cache.
+     * @param leaves - The leaves to append.
+     * @returns Resulting root of the tree.
+     */
+    batchInsert(_leaves) {
+        // If we have an even number of leaves, hash them all in pairs
+        // Otherwise, store the final leaf to be shifted up to the next odd sized level
+        let [layerWidth, nodeToShift] = _leaves.length & 1
+            ? [_leaves.length - 1, serializeToBuffer(_leaves[_leaves.length - 1])]
+            : [_leaves.length, Buffer.alloc(0)];
+        // Allocate this layer's leaves and init the next layer up
+        let thisLayer = _leaves.slice(0, layerWidth).map(l => serializeToBuffer(l));
+        let nextLayer = [];
+        // Store the bottom level leaves
+        thisLayer.forEach((leaf, i) => this.storeNode(leaf, this.maxDepth, BigInt(i)));
+        for (let i = 0; i < this.maxDepth; i++) {
+            for (let j = 0; j < layerWidth; j += 2) {
+                // Store the hash of each pair one layer up
+                nextLayer[j / 2] = this.hasher.hash(serializeToBuffer(thisLayer[j]), serializeToBuffer(thisLayer[j + 1]));
+                this.storeNode(nextLayer[j / 2], this.maxDepth - i - 1, BigInt(j >> 1));
+            }
+            layerWidth /= 2;
+            if (layerWidth & 1) {
+                if (nodeToShift.length) {
+                    // If the next layer has odd length, and we have a node that needs to be shifted up, add it here
+                    nextLayer.push(serializeToBuffer(nodeToShift));
+                    this.storeNode(nodeToShift, this.maxDepth - i - 1, BigInt((layerWidth * 2) >> 1));
+                    layerWidth += 1;
+                    nodeToShift = Buffer.alloc(0);
+                }
+                else {
+                    // If we don't have a node waiting to be shifted, store the next layer's final node to be shifted
+                    layerWidth -= 1;
+                    nodeToShift = nextLayer[layerWidth];
+                }
+            }
+            // reset the layers
+            thisLayer = nextLayer;
+            nextLayer = [];
+        }
+        this.size += BigInt(_leaves.length);
+        // return the root
+        return thisLayer[0];
+    }
+    /**
+     * Stores the given node in the cache.
+     * @param value - The value to store.
+     * @param depth - The depth of the node in the full tree.
+     * @param index - The index of the node at the given depth.
+     */
+    storeNode(value, depth, index) {
+        const key = indexToKeyHash(this.name, depth, index);
+        this.cache[key] = serializeToBuffer(value);
+        this.valueCache[serializeToBuffer(value).toString('hex')] = key;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidW5iYWxhbmNlZF90cmVlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL3VuYmFsYW5jZWRfdHJlZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsV0FBVyxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFDbkQsT0FBTyxFQUFvQyxpQkFBaUIsRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBR2xHLE9BQU8sRUFBRSxlQUFlLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQUd6RCxNQUFNLGNBQWMsR0FBRyxDQUFDLElBQVksRUFBRSxLQUFhLEVBQUUsS0FBYSxFQUFFLEVBQUUsQ0FBQyxHQUFHLElBQUksSUFBSSxLQUFLLElBQUksS0FBSyxFQUFFLENBQUM7QUFFbkc7Ozs7R0FJRztBQUNILE1BQU0sT0FBTyxjQUFjO0lBV3pCLFlBQ0UsTUFBYyxFQUNOLElBQVksRUFDWixXQUFtQixDQUFDLEVBQ2xCLFlBQTJCO1FBRjdCLFNBQUksR0FBSixJQUFJLENBQVE7UUFDWixhQUFRLEdBQVIsUUFBUSxDQUFZO1FBQ2xCLGlCQUFZLEdBQVosWUFBWSxDQUFlO1FBZHZDLDJDQUEyQztRQUNuQyxVQUFLLEdBQThCLEVBQUUsQ0FBQztRQUM5Qyx5RUFBeUU7UUFDakUsZUFBVSxHQUE4QixFQUFFLENBQUM7UUFDekMsU0FBSSxHQUFXLEVBQUUsQ0FBQztRQUk1QixTQUFJLEdBQVcsTUFBTSxDQUFDLEtBQUssQ0FBQyxFQUFFLENBQUMsQ0FBQztRQVE5QixJQUFJLENBQUMsTUFBTSxHQUFHLElBQUksZUFBZSxDQUFDLE1BQU0sQ0FBQyxDQUFDO1FBQzFDLElBQUksQ0FBQyxRQUFRLEdBQUcsRUFBRSxJQUFJLE1BQU0sQ0FBQyxJQUFJLENBQUMsUUFBUSxDQUFDLEdBQUcsRUFBRSxDQUFDO0lBQ25ELENBQUM7SUFFRDs7O09BR0c7SUFDSSxPQUFPO1FBQ1osT0FBTyxJQUFJLENBQUMsSUFBSSxDQUFDO0lBQ25CLENBQUM7SUFFRDs7O09BR0c7SUFDSSxZQUFZO1FBQ2pCLE9BQU8sSUFBSSxDQUFDLElBQUksQ0FBQztJQUNuQixDQUFDO0lBRUQ7OztPQUdHO0lBQ0ksUUFBUTtRQUNiLE9BQU8sSUFBSSxDQUFDLFFBQVEsQ0FBQztJQUN2QixDQUFDO0lBRUQ7OztPQUdHO0lBQ0ksTUFBTTtRQUNYLE1BQU0sSUFBSSxLQUFLLENBQUMsc0ZBQXNGLENBQUMsQ0FBQztRQUN4RyxPQUFPLE9BQU8sQ0FBQyxPQUFPLEVBQUUsQ0FBQztJQUMzQixDQUFDO0lBRUQ7OztPQUdHO0lBQ0ksUUFBUTtRQUNiLElBQUksQ0FBQyxVQUFVLEVBQUUsQ0FBQztRQUNsQixPQUFPLE9BQU8sQ0FBQyxPQUFPLEVBQUUsQ0FBQztJQUMzQixDQUFDO0lBRUQ7O09BRUc7SUFDSyxVQUFVO1FBQ2hCLElBQUksQ0FBQyxLQUFLLEdBQUcsRUFBRSxDQUFDO1FBQ2hCLElBQUksQ0FBQyxJQUFJLEdBQUcsRUFBRSxDQUFDO0lBQ2pCLENBQUM7SUFFRDs7Ozs7T0FLRztJQUNJLFlBQVksQ0FBQyxNQUFjO1FBQ2hDLE1BQU0sSUFBSSxLQUFLLENBQUMsbUZBQW1GLENBQUMsQ0FBQztJQUN2RyxDQUFDO0lBRUQ7Ozs7O09BS0c7SUFDSSxhQUFhLENBQUMsS0FBUTtRQUMzQixNQUFNLEdBQUcsR0FBRyxJQUFJLENBQUMsVUFBVSxDQUFDLGlCQUFpQixDQUFDLEtBQUssQ0FBQyxDQUFDLFFBQVEsQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDO1FBQ3RFLE1BQU0sQ0FBQyxFQUFFLEFBQUQsRUFBRyxLQUFLLENBQUMsR0FBRyxHQUFHLENBQUMsS0FBSyxDQUFDLEdBQUcsQ0FBQyxDQUFDO1FBQ25DLE9BQU8sTUFBTSxDQUFDLEtBQUssQ0FBQyxDQUFDO0lBQ3ZCLENBQUM7SUFFRDs7Ozs7O09BTUc7SUFDSSxrQkFBa0IsQ0FBQyxLQUFRLEVBQUUsVUFBa0I7UUFDcEQsTUFBTSxLQUFLLEdBQUcsSUFBSSxDQUFDLGFBQWEsQ0FBQyxLQUFLLENBQUMsQ0FBQztRQUN4QyxJQUFJLENBQUMsS0FBSyxJQUFJLEtBQUssR0FBRyxVQUFVLEVBQUUsQ0FBQztZQUNqQyxPQUFPLFNBQVMsQ0FBQztRQUNuQixDQUFDO1FBQ0QsT0FBTyxLQUFLLENBQUM7SUFDZixDQUFDO0lBRUQ7Ozs7O09BS0c7SUFDSSxPQUFPLENBQUMsS0FBYSxFQUFFLEtBQWE7UUFDekMsSUFBSSxLQUFLLEdBQUcsQ0FBQyxJQUFJLEtBQUssR0FBRyxJQUFJLENBQUMsUUFBUSxFQUFFLENBQUM7WUFDdkMsTUFBTSxLQUFLLENBQUMsaUJBQWlCLEdBQUcsS0FBSyxDQUFDLENBQUM7UUFDekMsQ0FBQztRQUVELElBQUksS0FBSyxHQUFHLENBQUMsSUFBSSxLQUFLLElBQUksSUFBSSxDQUFDLFFBQVEsRUFBRSxDQUFDO1lBQ3hDLE1BQU0sS0FBSyxDQUFDLGlCQUFpQixHQUFHLEtBQUssQ0FBQyxDQUFDO1FBQ3pDLENBQUM7UUFFRCxPQUFPLElBQUksQ0FBQyxLQUFLLENBQUMsY0FBYyxDQUFDLElBQUksQ0FBQyxJQUFJLEVBQUUsS0FBSyxFQUFFLEtBQUssQ0FBQyxDQUFDLENBQUM7SUFDN0QsQ0FBQztJQUVEOzs7OztPQUtHO0lBQ0ksY0FBYyxDQUFtQixLQUFhO1FBQ25ELE1BQU0sSUFBSSxHQUFhLEVBQUUsQ0FBQztRQUMxQixNQUFNLENBQUMsRUFBRSxLQUFLLEVBQUUsTUFBTSxDQUFDLEdBQUcsSUFBSSxDQUFDLFVBQVUsQ0FBQyxpQkFBaUIsQ0FBQyxLQUFLLENBQUMsQ0FBQyxRQUFRLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQyxLQUFLLENBQUMsR0FBRyxDQUFDLENBQUM7UUFDL0YsSUFBSSxLQUFLLEdBQUcsUUFBUSxDQUFDLEtBQUssRUFBRSxFQUFFLENBQUMsQ0FBQztRQUNoQyxJQUFJLEtBQUssR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDLENBQUM7UUFDM0IsT0FBTyxLQUFLLEdBQUcsQ0FBQyxFQUFFLENBQUM7WUFDakIsTUFBTSxPQUFPLEdBQUcsS0FBSyxHQUFHLEtBQUssQ0FBQztZQUM5QixNQUFNLEdBQUcsR0FBRyxjQUFjLENBQUMsSUFBSSxDQUFDLElBQUksRUFBRSxLQUFLLEVBQUUsT0FBTyxDQUFDLENBQUMsQ0FBQyxLQUFLLEdBQUcsRUFBRSxDQUFDLENBQUMsQ0FBQyxLQUFLLEdBQUcsRUFBRSxDQUFDLENBQUM7WUFDaEYsTUFBTSxPQUFPLEdBQUcsSUFBSSxDQUFDLEtBQUssQ0FBQyxHQUFHLENBQUMsQ0FBQztZQUNoQyxJQUFJLENBQUMsSUFBSSxDQUFDLE9BQU8sQ0FBQyxDQUFDO1lBQ25CLEtBQUssSUFBSSxDQUFDLENBQUM7WUFDWCxLQUFLLEtBQUssRUFBRSxDQUFDO1FBQ2YsQ0FBQztRQUNELE9BQU8sT0FBTyxDQUFDLE9BQU8sQ0FBQyxJQUFJLFdBQVcsQ0FBSSxRQUFRLENBQUMsS0FBSyxFQUFFLEVBQUUsQ0FBTSxFQUFFLElBQUksQ0FBQyxDQUFDLENBQUM7SUFDN0UsQ0FBQztJQUVEOzs7O09BSUc7SUFDSSxZQUFZLENBQUMsTUFBVztRQUM3QixJQUFJLENBQUMsTUFBTSxDQUFDLEtBQUssRUFBRSxDQUFDO1FBQ3BCLElBQUksSUFBSSxDQUFDLElBQUksSUFBSSxNQUFNLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQztZQUMzQixNQUFNLEtBQUssQ0FBQyxzREFBc0QsSUFBSSxDQUFDLElBQUksVUFBVSxDQUFDLENBQUM7UUFDekYsQ0FBQztRQUNELElBQUksSUFBSSxDQUFDLElBQUksR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDLE1BQU0sQ0FBQyxHQUFHLEVBQUUsR0FBRyxJQUFJLENBQUMsUUFBUSxFQUFFLENBQUM7WUFDM0QsTUFBTSxLQUFLLENBQUMsNkNBQTZDLElBQUksQ0FBQyxRQUFRLEVBQUUsQ0FBQyxDQUFDO1FBQzVFLENBQUM7UUFDRCxNQUFNLElBQUksR0FBRyxJQUFJLENBQUMsV0FBVyxDQUFDLE1BQU0sQ0FBQyxDQUFDO1FBQ3RDLElBQUksQ0FBQyxJQUFJLEdBQUcsSUFBSSxDQUFDO1FBRWpCLE9BQU8sT0FBTyxDQUFDLE9BQU8sRUFBRSxDQUFDO0lBQzNCLENBQUM7SUFFRDs7OztPQUlHO0lBQ0ssV0FBVyxDQUFDLE9BQVk7UUFDOUIsOERBQThEO1FBQzlELCtFQUErRTtRQUMvRSxJQUFJLENBQUMsVUFBVSxFQUFFLFdBQVcsQ0FBQyxHQUMzQixPQUFPLENBQUMsTUFBTSxHQUFHLENBQUM7WUFDaEIsQ0FBQyxDQUFDLENBQUMsT0FBTyxDQUFDLE1BQU0sR0FBRyxDQUFDLEVBQUUsaUJBQWlCLENBQUMsT0FBTyxDQUFDLE9BQU8sQ0FBQyxNQUFNLEdBQUcsQ0FBQyxDQUFDLENBQUMsQ0FBQztZQUN0RSxDQUFDLENBQUMsQ0FBQyxPQUFPLENBQUMsTUFBTSxFQUFFLE1BQU0sQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQztRQUN4QywwREFBMEQ7UUFDMUQsSUFBSSxTQUFTLEdBQUcsT0FBTyxDQUFDLEtBQUssQ0FBQyxDQUFDLEVBQUUsVUFBVSxDQUFDLENBQUMsR0FBRyxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUMsaUJBQWlCLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQztRQUM1RSxJQUFJLFNBQVMsR0FBRyxFQUFFLENBQUM7UUFDbkIsZ0NBQWdDO1FBQ2hDLFNBQVMsQ0FBQyxPQUFPLENBQUMsQ0FBQyxJQUFJLEVBQUUsQ0FBQyxFQUFFLEVBQUUsQ0FBQyxJQUFJLENBQUMsU0FBUyxDQUFDLElBQUksRUFBRSxJQUFJLENBQUMsUUFBUSxFQUFFLE1BQU0sQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUM7UUFDL0UsS0FBSyxJQUFJLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQyxHQUFHLElBQUksQ0FBQyxRQUFRLEVBQUUsQ0FBQyxFQUFFLEVBQUUsQ0FBQztZQUN2QyxLQUFLLElBQUksQ0FBQyxHQUFHLENBQUMsRUFBRSxDQUFDLEdBQUcsVUFBVSxFQUFFLENBQUMsSUFBSSxDQUFDLEVBQUUsQ0FBQztnQkFDdkMsMkNBQTJDO2dCQUMzQyxTQUFTLENBQUMsQ0FBQyxHQUFHLENBQUMsQ0FBQyxHQUFHLElBQUksQ0FBQyxNQUFNLENBQUMsSUFBSSxDQUFDLGlCQUFpQixDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxFQUFFLGlCQUFpQixDQUFDLFNBQVMsQ0FBQyxDQUFDLEdBQUcsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDO2dCQUMxRyxJQUFJLENBQUMsU0FBUyxDQUFDLFNBQVMsQ0FBQyxDQUFDLEdBQUcsQ0FBQyxDQUFDLEVBQUUsSUFBSSxDQUFDLFFBQVEsR0FBRyxDQUFDLEdBQUcsQ0FBQyxFQUFFLE1BQU0sQ0FBQyxDQUFDLElBQUksQ0FBQyxDQUFDLENBQUMsQ0FBQztZQUMxRSxDQUFDO1lBQ0QsVUFBVSxJQUFJLENBQUMsQ0FBQztZQUNoQixJQUFJLFVBQVUsR0FBRyxDQUFDLEVBQUUsQ0FBQztnQkFDbkIsSUFBSSxXQUFXLENBQUMsTUFBTSxFQUFFLENBQUM7b0JBQ3ZCLGdHQUFnRztvQkFDaEcsU0FBUyxDQUFDLElBQUksQ0FBQyxpQkFBaUIsQ0FBQyxXQUFXLENBQUMsQ0FBQyxDQUFDO29CQUMvQyxJQUFJLENBQUMsU0FBUyxDQUFDLFdBQVcsRUFBRSxJQUFJLENBQUMsUUFBUSxHQUFHLENBQUMsR0FBRyxDQUFDLEVBQUUsTUFBTSxDQUFDLENBQUMsVUFBVSxHQUFHLENBQUMsQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDLENBQUM7b0JBQ2xGLFVBQVUsSUFBSSxDQUFDLENBQUM7b0JBQ2hCLFdBQVcsR0FBRyxNQUFNLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQyxDQUFDO2dCQUNoQyxDQUFDO3FCQUFNLENBQUM7b0JBQ04saUdBQWlHO29CQUNqRyxVQUFVLElBQUksQ0FBQyxDQUFDO29CQUNoQixXQUFXLEdBQUcsU0FBUyxDQUFDLFVBQVUsQ0FBQyxDQUFDO2dCQUN0QyxDQUFDO1lBQ0gsQ0FBQztZQUNELG1CQUFtQjtZQUNuQixTQUFTLEdBQUcsU0FBUyxDQUFDO1lBQ3RCLFNBQVMsR0FBRyxFQUFFLENBQUM7UUFDakIsQ0FBQztRQUNELElBQUksQ0FBQyxJQUFJLElBQUksTUFBTSxDQUFDLE9BQU8sQ0FBQyxNQUFNLENBQUMsQ0FBQztRQUNwQyxrQkFBa0I7UUFDbEIsT0FBTyxTQUFTLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDdEIsQ0FBQztJQUVEOzs7OztPQUtHO0lBQ0ssU0FBUyxDQUFDLEtBQWlCLEVBQUUsS0FBYSxFQUFFLEtBQWE7UUFDL0QsTUFBTSxHQUFHLEdBQUcsY0FBYyxDQUFDLElBQUksQ0FBQyxJQUFJLEVBQUUsS0FBSyxFQUFFLEtBQUssQ0FBQyxDQUFDO1FBQ3BELElBQUksQ0FBQyxLQUFLLENBQUMsR0FBRyxDQUFDLEdBQUcsaUJBQWlCLENBQUMsS0FBSyxDQUFDLENBQUM7UUFDM0MsSUFBSSxDQUFDLFVBQVUsQ0FBQyxpQkFBaUIsQ0FBQyxLQUFLLENBQUMsQ0FBQyxRQUFRLENBQUMsS0FBSyxDQUFDLENBQUMsR0FBRyxHQUFHLENBQUM7SUFDbEUsQ0FBQztDQUNGIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/merkle-tree",
-  "version": "0.44.0",
+  "version": "0.45.1",
   "type": "module",
   "exports": "./dest/index.js",
   "typedocOptions": {
@@ -55,10 +55,10 @@
     ]
   },
   "dependencies": {
-    "@aztec/circuit-types": "0.44.0",
-    "@aztec/foundation": "0.44.0",
-    "@aztec/kv-store": "0.44.0",
-    "@aztec/types": "0.44.0",
+    "@aztec/circuit-types": "0.45.1",
+    "@aztec/foundation": "0.45.1",
+    "@aztec/kv-store": "0.45.1",
+    "@aztec/types": "0.45.1",
     "sha256": "^0.2.0",
     "tslib": "^2.4.0"
   },

package/src/index.ts

@@ -8,6 +8,7 @@ export * from './sparse_tree/sparse_tree.js';
 export { StandardIndexedTree } from './standard_indexed_tree/standard_indexed_tree.js';
 export { StandardIndexedTreeWithAppend } from './standard_indexed_tree/test/standard_indexed_tree_with_append.js';
 export * from './standard_tree/standard_tree.js';
+export * from './unbalanced_tree.js';
 export { INITIAL_LEAF, getTreeMeta } from './tree_base.js';
 export { newTree } from './new_tree.js';
 export { loadTree } from './load_tree.js';

package/src/unbalanced_tree.ts

@@ -0,0 +1,239 @@
+import { SiblingPath } from '@aztec/circuit-types';
+import { type Bufferable, type FromBuffer, serializeToBuffer } from '@aztec/foundation/serialize';
+import { type Hasher } from '@aztec/types/interfaces';
+
+import { HasherWithStats } from './hasher_with_stats.js';
+import { type MerkleTree } from './interfaces/merkle_tree.js';
+
+const indexToKeyHash = (name: string, level: number, index: bigint) => `${name}:${level}:${index}`;
+
+/**
+ * An ephemeral unbalanced Merkle tree implementation.
+ * Follows the rollup implementation which greedily hashes pairs of nodes up the tree.
+ * Remaining rightmost nodes are shifted up until they can be paired. See proving-state.ts -> findMergeLevel.
+ */
+export class UnbalancedTree<T extends Bufferable = Buffer> implements MerkleTree<T> {
+  // This map stores index and depth -> value
+  private cache: { [key: string]: Buffer } = {};
+  // This map stores value -> index and depth, since we have variable depth
+  private valueCache: { [key: string]: string } = {};
+  protected size: bigint = 0n;
+  protected readonly maxIndex: bigint;
+
+  protected hasher: HasherWithStats;
+  root: Buffer = Buffer.alloc(32);
+
+  public constructor(
+    hasher: Hasher,
+    private name: string,
+    private maxDepth: number = 0,
+    protected deserializer: FromBuffer<T>,
+  ) {
+    this.hasher = new HasherWithStats(hasher);
+    this.maxIndex = 2n ** BigInt(this.maxDepth) - 1n;
+  }
+
+  /**
+   * Returns the root of the tree.
+   * @returns The root of the tree.
+   */
+  public getRoot(): Buffer {
+    return this.root;
+  }
+
+  /**
+   * Returns the number of leaves in the tree.
+   * @returns The number of leaves in the tree.
+   */
+  public getNumLeaves() {
+    return this.size;
+  }
+
+  /**
+   * Returns the max depth of the tree.
+   * @returns The max depth of the tree.
+   */
+  public getDepth(): number {
+    return this.maxDepth;
+  }
+
+  /**
+   * @remark A wonky tree is (currently) only ever ephemeral, so we don't use any db to commit to.
+   * The fn must exist to implement MerkleTree however.
+   */
+  public commit(): Promise<void> {
+    throw new Error("Unsupported function - cannot commit on an unbalanced tree as it's always ephemeral.");
+    return Promise.resolve();
+  }
+
+  /**
+   * Rolls back the not-yet-committed changes.
+   * @returns Empty promise.
+   */
+  public rollback(): Promise<void> {
+    this.clearCache();
+    return Promise.resolve();
+  }
+
+  /**
+   * Clears the cache.
+   */
+  private clearCache() {
+    this.cache = {};
+    this.size = 0n;
+  }
+
+  /**
+   * @remark A wonky tree can validly have duplicate indices:
+   * e.g. 001 (index 1 at level 3) and 01 (index 1 at level 2)
+   * So this function cannot reliably give the expected leaf value.
+   * We cannot add level as an input as its based on the MerkleTree class's function.
+   */
+  public getLeafValue(_index: bigint): undefined {
+    throw new Error('Unsupported function - cannot get leaf value from an index in an unbalanced tree.');
+  }
+
+  /**
+   * Returns the index of a leaf given its value, or undefined if no leaf with that value is found.
+   * @param leaf - The leaf value to look for.
+   * @returns The index of the first leaf found with a given value (undefined if not found).
+   * @remark This is NOT the index as inserted, but the index which will be used to calculate path structure.
+   */
+  public findLeafIndex(value: T): bigint | undefined {
+    const key = this.valueCache[serializeToBuffer(value).toString('hex')];
+    const [, , index] = key.split(':');
+    return BigInt(index);
+  }
+
+  /**
+   * Returns the first index containing a leaf value after `startIndex`.
+   * @param value - The leaf value to look for.
+   * @param startIndex - The index to start searching from.
+   * @returns The index of the first leaf found with a given value (undefined if not found).
+   * @remark This is not really used for a wonky tree, but required to implement MerkleTree.
+   */
+  public findLeafIndexAfter(value: T, startIndex: bigint): bigint | undefined {
+    const index = this.findLeafIndex(value);
+    if (!index || index < startIndex) {
+      return undefined;
+    }
+    return index;
+  }
+
+  /**
+   * Returns the node at the given level and index
+   * @param level - The level of the element (root is at level 0).
+   * @param index - The index of the element.
+   * @returns Leaf or node value, or undefined.
+   */
+  public getNode(level: number, index: bigint): Buffer | undefined {
+    if (level < 0 || level > this.maxDepth) {
+      throw Error('Invalid level: ' + level);
+    }
+
+    if (index < 0 || index >= this.maxIndex) {
+      throw Error('Invalid index: ' + index);
+    }
+
+    return this.cache[indexToKeyHash(this.name, level, index)];
+  }
+
+  /**
+   * Returns a sibling path for the element at the given index.
+   * @param value - The value of the element.
+   * @returns A sibling path for the element.
+   * Note: The sibling path is an array of sibling hashes, with the lowest hash (leaf hash) first, and the highest hash last.
+   */
+  public getSiblingPath<N extends number>(value: bigint): Promise<SiblingPath<N>> {
+    const path: Buffer[] = [];
+    const [, depth, _index] = this.valueCache[serializeToBuffer(value).toString('hex')].split(':');
+    let level = parseInt(depth, 10);
+    let index = BigInt(_index);
+    while (level > 0) {
+      const isRight = index & 0x01n;
+      const key = indexToKeyHash(this.name, level, isRight ? index - 1n : index + 1n);
+      const sibling = this.cache[key];
+      path.push(sibling);
+      level -= 1;
+      index >>= 1n;
+    }
+    return Promise.resolve(new SiblingPath<N>(parseInt(depth, 10) as N, path));
+  }
+
+  /**
+   * Appends the given leaves to the tree.
+   * @param leaves - The leaves to append.
+   * @returns Empty promise.
+   */
+  public appendLeaves(leaves: T[]): Promise<void> {
+    this.hasher.reset();
+    if (this.size != BigInt(0)) {
+      throw Error(`Can't re-append to an unbalanced tree. Current has ${this.size} leaves.`);
+    }
+    if (this.size + BigInt(leaves.length) - 1n > this.maxIndex) {
+      throw Error(`Can't append beyond max index. Max index: ${this.maxIndex}`);
+    }
+    const root = this.batchInsert(leaves);
+    this.root = root;
+
+    return Promise.resolve();
+  }
+
+  /**
+   * Calculates root while adding leaves and nodes to the cache.
+   * @param leaves - The leaves to append.
+   * @returns Resulting root of the tree.
+   */
+  private batchInsert(_leaves: T[]): Buffer {
+    // If we have an even number of leaves, hash them all in pairs
+    // Otherwise, store the final leaf to be shifted up to the next odd sized level
+    let [layerWidth, nodeToShift] =
+      _leaves.length & 1
+        ? [_leaves.length - 1, serializeToBuffer(_leaves[_leaves.length - 1])]
+        : [_leaves.length, Buffer.alloc(0)];
+    // Allocate this layer's leaves and init the next layer up
+    let thisLayer = _leaves.slice(0, layerWidth).map(l => serializeToBuffer(l));
+    let nextLayer = [];
+    // Store the bottom level leaves
+    thisLayer.forEach((leaf, i) => this.storeNode(leaf, this.maxDepth, BigInt(i)));
+    for (let i = 0; i < this.maxDepth; i++) {
+      for (let j = 0; j < layerWidth; j += 2) {
+        // Store the hash of each pair one layer up
+        nextLayer[j / 2] = this.hasher.hash(serializeToBuffer(thisLayer[j]), serializeToBuffer(thisLayer[j + 1]));
+        this.storeNode(nextLayer[j / 2], this.maxDepth - i - 1, BigInt(j >> 1));
+      }
+      layerWidth /= 2;
+      if (layerWidth & 1) {
+        if (nodeToShift.length) {
+          // If the next layer has odd length, and we have a node that needs to be shifted up, add it here
+          nextLayer.push(serializeToBuffer(nodeToShift));
+          this.storeNode(nodeToShift, this.maxDepth - i - 1, BigInt((layerWidth * 2) >> 1));
+          layerWidth += 1;
+          nodeToShift = Buffer.alloc(0);
+        } else {
+          // If we don't have a node waiting to be shifted, store the next layer's final node to be shifted
+          layerWidth -= 1;
+          nodeToShift = nextLayer[layerWidth];
+        }
+      }
+      // reset the layers
+      thisLayer = nextLayer;
+      nextLayer = [];
+    }
+    this.size += BigInt(_leaves.length);
+    // return the root
+    return thisLayer[0];
+  }
+
+  /**
+   * Stores the given node in the cache.
+   * @param value - The value to store.
+   * @param depth - The depth of the node in the full tree.
+   * @param index - The index of the node at the given depth.
+   */
+  private storeNode(value: T | Buffer, depth: number, index: bigint) {
+    const key = indexToKeyHash(this.name, depth, index);
+    this.cache[key] = serializeToBuffer(value);
+    this.valueCache[serializeToBuffer(value).toString('hex')] = key;
+  }
+}