@aztec/merkle-tree 0.1.0-alpha10

package/dest/tree_base.js

@@ -0,0 +1,214 @@
+import { SiblingPath } from './sibling_path/sibling_path.js';
+import { toBigIntLE, toBufferLE } from '@aztec/foundation/bigint-buffer';
+const MAX_DEPTH = 254;
+export const indexToKeyHash = (name, level, index) => `${name}:${level}:${index}`;
+const encodeMeta = (root, depth, size) => {
+    const data = Buffer.alloc(36);
+    root.copy(data);
+    data.writeUInt32LE(depth, 32);
+    return Buffer.concat([data, toBufferLE(size, 32)]);
+};
+export const decodeMeta = (meta) => {
+    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 class TreeBase {
+    constructor(db, hasher, name, depth, size = 0n, root) {
+        this.db = db;
+        this.hasher = hasher;
+        this.name = name;
+        this.depth = depth;
+        this.size = size;
+        this.zeroHashes = [];
+        this.cache = {};
+        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.
+     */
+    getRoot(includeUncommitted) {
+        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.
+     */
+    getNumLeaves(includeUncommitted) {
+        return !includeUncommitted ? this.size : this.cachedSize ?? this.size;
+    }
+    /**
+     * Returns the name of the tree.
+     * @returns The name of the tree.
+     */
+    getName() {
+        return this.name;
+    }
+    /**
+     * Returns the depth of the tree.
+     * @returns The depth of the tree.
+     */
+    getDepth() {
+        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.
+     */
+    async getSiblingPath(index, includeUncommitted) {
+        const path = [];
+        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(this.depth, path);
+    }
+    /**
+     * Commits the changes to the database.
+     * @returns Empty promise.
+     */
+    async commit() {
+        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.
+     */
+    rollback() {
+        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.
+     */
+    getLeafValue(index, includeUncommitted) {
+        return this.getLatestValueAtIndex(this.depth, index, includeUncommitted);
+    }
+    /**
+     * Clears the cache.
+     */
+    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).
+     */
+    async addLeafToCacheAndHashToRoot(leaf, index) {
+        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.
+     */
+    async getLatestValueAtIndex(level, index, includeUncommitted) {
+        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.
+     */
+    async dbGet(key) {
+        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
+    async init(prefilledSize) {
+        // prefilledSize is used only by Indexed Tree.
+        await this.writeMeta();
+    }
+    /**
+     * Initializes the tree from the database.
+     */
+    async initFromDb() {
+        // 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.
+     */
+    async writeMeta(batch) {
+        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);
+        }
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHJlZV9iYXNlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL3RyZWVfYmFzZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFDQSxPQUFPLEVBQUUsV0FBVyxFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFHN0QsT0FBTyxFQUFFLFVBQVUsRUFBRSxVQUFVLEVBQUUsTUFBTSxpQ0FBaUMsQ0FBQztBQUV6RSxNQUFNLFNBQVMsR0FBRyxHQUFHLENBQUM7QUFFdEIsTUFBTSxDQUFDLE1BQU0sY0FBYyxHQUFHLENBQUMsSUFBWSxFQUFFLEtBQWEsRUFBRSxLQUFhLEVBQUUsRUFBRSxDQUFDLEdBQUcsSUFBSSxJQUFJLEtBQUssSUFBSSxLQUFLLEVBQUUsQ0FBQztBQUMxRyxNQUFNLFVBQVUsR0FBRyxDQUFDLElBQVksRUFBRSxLQUFhLEVBQUUsSUFBWSxFQUFFLEVBQUU7SUFDL0QsTUFBTSxJQUFJLEdBQUcsTUFBTSxDQUFDLEtBQUssQ0FBQyxFQUFFLENBQUMsQ0FBQztJQUM5QixJQUFJLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxDQUFDO0lBQ2hCLElBQUksQ0FBQyxhQUFhLENBQUMsS0FBSyxFQUFFLEVBQUUsQ0FBQyxDQUFDO0lBQzlCLE9BQU8sTUFBTSxDQUFDLE1BQU0sQ0FBQyxDQUFDLElBQUksRUFBRSxVQUFVLENBQUMsSUFBSSxFQUFFLEVBQUUsQ0FBQyxDQUFDLENBQUMsQ0FBQztBQUNyRCxDQUFDLENBQUM7QUFDRixNQUFNLENBQUMsTUFBTSxVQUFVLEdBQUcsQ0FBQyxJQUFZLEVBQUUsRUFBRTtJQUN6QyxNQUFNLElBQUksR0FBRyxJQUFJLENBQUMsUUFBUSxDQUFDLENBQUMsRUFBRSxFQUFFLENBQUMsQ0FBQztJQUNsQyxNQUFNLEtBQUssR0FBRyxJQUFJLENBQUMsWUFBWSxDQUFDLEVBQUUsQ0FBQyxDQUFDO0lBQ3BDLE1BQU0sSUFBSSxHQUFHLFVBQVUsQ0FBQyxJQUFJLENBQUMsUUFBUSxDQUFDLEVBQUUsQ0FBQyxD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

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@aztec/merkle-tree",
+  "version": "0.1.0-alpha10",
+  "exports": "./dest/index.js",
+  "type": "module",
+  "dependencies": {
+    "@aztec/circuits.js": "0.1.0-alpha10",
+    "@aztec/foundation": "0.1.0-alpha10",
+    "levelup": "^5.1.1",
+    "memdown": "^6.1.1",
+    "sha256": "^0.2.0",
+    "tslib": "^2.4.0"
+  }
+}

package/package.local.json

@@ -0,0 +1,3 @@
+{
+  "files": ["dest", "src", "!*.test.*", "!dest/test", "!src/test"]
+}

package/src/hasher.ts

@@ -0,0 +1,9 @@
+/**
+ * Defines hasher interface used by Merkle trees.
+ */
+export interface Hasher {
+  compress(lhs: Uint8Array, rhs: Uint8Array): Buffer;
+  compressInputs(inputs: Buffer[]): Buffer;
+  hashToField(data: Uint8Array): Buffer;
+  hashToTree(leaves: Buffer[]): Promise<Buffer[]>;
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from './hasher.js';
+export * from './interfaces/append_only_tree.js';
+export * from './interfaces/indexed_tree.js';
+export * from './interfaces/merkle_tree.js';
+export * from './interfaces/update_only_tree.js';
+export * from './pedersen.js';
+export * from './sibling_path/sibling_path.js';
+export * from './sparse_tree/sparse_tree.js';
+export * from './standard_indexed_tree/standard_indexed_tree.js';
+export * from './standard_tree/standard_tree.js';
+export { INITIAL_LEAF } from './tree_base.js';
+export { newTree } from './new_tree.js';
+export { loadTree } from './load_tree.js';

package/src/interfaces/append_only_tree.ts

@@ -0,0 +1,12 @@
+import { MerkleTree } from './merkle_tree.js';
+
+/**
+ * A Merkle tree that supports only appending leaves and not updating existing leaves.
+ */
+export interface AppendOnlyTree extends MerkleTree {
+  /**
+   * Appends a set of leaf values to the tree.
+   * @param leaves - The set of leaves to be appended.
+   */
+  appendLeaves(leaves: Buffer[]): Promise<void>;
+}

package/src/interfaces/indexed_tree.ts

@@ -0,0 +1,78 @@
+import { LowLeafWitnessData, SiblingPath } from '../index.js';
+import { AppendOnlyTree } from './append_only_tree.js';
+
+/**
+ * A leaf of a tree.
+ */
+export interface LeafData {
+  /**
+   * A value of the leaf.
+   */
+  value: bigint;
+  /**
+   * An index of the next leaf.
+   */
+  nextIndex: bigint;
+  /**
+   * A value of the next leaf.
+   */
+  nextValue: bigint;
+}
+
+/**
+ * Indexed merkle tree.
+ */
+export interface IndexedTree extends AppendOnlyTree {
+  /**
+   * 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.
+   * @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`.
+   */
+  findIndexOfPreviousValue(
+    newValue: bigint,
+    includeUncommitted: boolean,
+  ): {
+    /**
+     * The index of the found leaf.
+     */
+    index: number;
+    /**
+     * A flag indicating if the corresponding leaf's value is equal to `newValue`.
+     */
+    alreadyPresent: boolean;
+  };
+
+  /**
+   * Gets the latest LeafData copy.
+   * @param index - Index of the leaf of which to obtain the LeafData copy.
+   * @param includeUncommitted - If true, the uncommitted changes are included in the search.
+   * @returns A copy of the leaf data at the given index or undefined if the leaf was not found.
+   */
+  getLatestLeafDataCopy(index: number, includeUncommitted: boolean): LeafData | undefined;
+
+  /**
+   * Exposes the underlying tree's update leaf method.
+   * @param leaf - The hash to set at the leaf.
+   * @param index - The index of the element.
+   */
+  // TODO: remove once the batch insertion functionality is moved to StandardIndexedTree from circuit_block_builder.ts
+  updateLeaf(leaf: LeafData, index: bigint): Promise<void>;
+
+  /**
+   * Batch insert multiple leaves into the tree.
+   * @param leaves - Leaves to insert into the tree.
+   * @param treeHeight - Height of the tree.
+   * @param subtreeHeight - Height of the subtree.
+   * @param includeUncommitted - If true, the uncommitted changes are included in the search.
+   */
+  batchInsert<TreeHeight extends number, SubtreeHeight extends number, SubtreeSiblingPathHeight extends number>(
+    leaves: Buffer[],
+    treeHeight: TreeHeight,
+    subtreeHeight: SubtreeHeight,
+    includeUncommitted: boolean,
+  ): Promise<
+    | [LowLeafWitnessData<TreeHeight>[], SiblingPath<SubtreeSiblingPathHeight>]
+    | [undefined, SiblingPath<SubtreeSiblingPathHeight>]
+  >;
+}

package/src/interfaces/merkle_tree.ts

@@ -0,0 +1,52 @@
+import { SiblingPath } from '../sibling_path/sibling_path.js';
+
+/**
+ * Defines the interface for a source of sibling paths.
+ */
+export interface SiblingPathSource {
+  /**
+   * Returns the sibling path for a requested leaf index.
+   * @param index - The index of the leaf for which a sibling path is required.
+   * @param includeUncommitted - Set to true to include uncommitted updates in the sibling path.
+   */
+  getSiblingPath<N extends number>(index: bigint, includeUncommitted: boolean): Promise<SiblingPath<N>>;
+}
+
+/**
+ * Defines the interface for a Merkle tree.
+ */
+export interface MerkleTree extends SiblingPathSource {
+  /**
+   * Returns the current root of the tree.
+   * @param includeUncommitted - Set to true to include uncommitted updates in the calculated root.
+   */
+  getRoot(includeUncommitted: boolean): Buffer;
+
+  /**
+   * Returns the number of leaves in the tree.
+   * @param includeUncommitted - Set to true to include uncommitted updates in the returned value.
+   */
+  getNumLeaves(includeUncommitted: boolean): bigint;
+
+  /**
+   * Commit pending updates to the tree.
+   */
+  commit(): Promise<void>;
+
+  /**
+   * Returns the depth of the tree.
+   */
+  getDepth(): number;
+
+  /**
+   * Rollback pending update to the tree.
+   */
+  rollback(): Promise<void>;
+
+  /**
+   * Returns the value of a leaf at the specified index.
+   * @param index - The index of the leaf value to be returned.
+   * @param includeUncommitted - Set to true to include uncommitted updates in the data set.
+   */
+  getLeafValue(index: bigint, includeUncommitted: boolean): Promise<Buffer | undefined>;
+}

package/src/interfaces/update_only_tree.ts

@@ -0,0 +1,15 @@
+import { LeafData } from '../index.js';
+import { MerkleTree } from './merkle_tree.js';
+
+/**
+ * A Merkle tree that supports updates at arbitrary indices but not appending.
+ */
+export interface UpdateOnlyTree extends MerkleTree {
+  /**
+   * Updates a leaf at a given index in the tree.
+   * @param leaf - The leaf value to be updated.
+   * @param index - The leaf to be updated.
+   */
+  // TODO: Make this strictly a Buffer
+  updateLeaf(leaf: Buffer | LeafData, index: bigint): Promise<void>;
+}

package/src/load_tree.ts

@@ -0,0 +1,24 @@
+import { LevelUp } from 'levelup';
+import { Hasher } from './hasher.js';
+import { TreeBase, decodeMeta } from './tree_base.js';
+
+/**
+ * Creates a new tree and sets its root, depth and size based on the meta data which are associated with the name.
+ * @param c - The class of the tree to be instantiated.
+ * @param db - A database used to store the Merkle tree data.
+ * @param hasher - A hasher used to compute hash paths.
+ * @param name - Name of the tree.
+ * @returns The newly created tree.
+ */
+export async function loadTree<T extends TreeBase>(
+  c: new (...args: any[]) => T,
+  db: LevelUp,
+  hasher: Hasher,
+  name: string,
+): Promise<T> {
+  const meta: Buffer = await db.get(name);
+  const { root, depth, size } = decodeMeta(meta);
+  const tree = new c(db, hasher, name, depth, size, root);
+  await tree.initFromDb();
+  return tree;
+}

package/src/new_tree.ts

@@ -0,0 +1,26 @@
+import { LevelUp } from 'levelup';
+import { Hasher } from './hasher.js';
+import { TreeBase } from './tree_base.js';
+
+/**
+ * Creates a new tree.
+ * @param c - The class of the tree to be instantiated.
+ * @param db - A database used to store the Merkle tree data.
+ * @param hasher - A hasher used to compute hash paths.
+ * @param name - Name of the tree.
+ * @param depth - Depth of the tree.
+ * @param prefilledSize - A number of leaves that are prefilled with values.
+ * @returns The newly created tree.
+ */
+export async function newTree<T extends TreeBase>(
+  c: new (...args: any[]) => T,
+  db: LevelUp,
+  hasher: Hasher,
+  name: string,
+  depth: number,
+  prefilledSize = 0,
+): Promise<T> {
+  const tree = new c(db, hasher, name, depth, 0n, undefined);
+  await tree.init(prefilledSize);
+  return tree;
+}

package/src/pedersen.ts

@@ -0,0 +1,58 @@
+import { IWasmModule } from '@aztec/foundation/wasm';
+import {
+  pedersenCompress,
+  pedersenGetHash,
+  pedersenGetHashTree,
+  pedersenHashInputs,
+} from '@aztec/circuits.js/barretenberg';
+import { Hasher } from './hasher.js';
+
+/**
+ * A helper class encapsulating Pedersen hash functionality.
+ */
+export class Pedersen implements Hasher {
+  constructor(private wasm: IWasmModule) {}
+
+  /**
+   * 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 {
+    return pedersenCompress(this.wasm, lhs, rhs);
+  }
+
+  /**
+   * Compresses an array of buffers.
+   * @param inputs - The array of buffers to compress.
+   * @returns The resulting 32-byte hash.
+   */
+  public compressInputs(inputs: Buffer[]): Buffer {
+    return pedersenHashInputs(this.wasm, inputs);
+  }
+
+  /**
+   * Get a 32-byte pedersen hash from a buffer.
+   * @param data - The data buffer.
+   * @returns The resulting hash buffer.
+   */
+  public hashToField(data: Uint8Array): Buffer {
+    return pedersenGetHash(this.wasm, Buffer.from(data));
+  }
+
+  /**
+   * Given a buffer containing 32 byte pedersen leaves, return a new buffer containing the leaves and all pairs of
+   * nodes that define a merkle tree.
+   *
+   * E.g.
+   * Input:  [1][2][3][4]
+   * Output: [1][2][3][4][compress(1,2)][compress(3,4)][compress(5,6)].
+   *
+   * @param leaves - The 32 byte pedersen leaves.
+   * @returns A tree represented by an array.
+   */
+  public hashToTree(leaves: Buffer[]): Promise<Buffer[]> {
+    return Promise.resolve(pedersenGetHashTree(this.wasm, leaves));
+  }
+}

package/src/sibling_path/sibling_path.ts

@@ -0,0 +1,139 @@
+import {
+  Tuple,
+  assertLength,
+  deserializeArrayFromVector,
+  serializeBufferArrayToVector,
+} from '@aztec/foundation/serialize';
+import { Pedersen } from '../pedersen.js';
+import { Fr } from '@aztec/foundation/fields';
+
+/**
+ * Contains functionality to compute and serialize/deserialize a sibling path.
+ * E.g. Sibling path for a leaf at index 3 in a tree of depth 3 consists of:
+ *      d0:                                            [ root ]
+ *      d1:                      [ ]                                               [*]
+ *      d2:         [*]                      [ ]                       [ ]                     [ ]
+ *      d3:   [ ]         [ ]          [*]         [ ]           [ ]         [ ]          [ ]        [ ].
+ *
+ *      And the elements would be ordered as: [ leaf_at_index_2, node_at_level_2_index_0, node_at_level_1_index_1 ].
+ */
+export class SiblingPath<N extends number> {
+  private data: Tuple<Buffer, N>;
+
+  /**
+   * Returns sibling path hashed up from the a element.
+   * @param size - The number of elements in a given path.
+   * @param zeroElement - Value of the zero element.
+   * @param pedersen - Implementation of a hasher interface using the Pedersen hash.
+   * @returns A sibling path hashed up from a zero element.
+   */
+  public static ZERO<N extends number>(size: N, zeroElement: Buffer, pedersen: Pedersen): SiblingPath<N> {
+    const bufs: Buffer[] = [];
+    let current = zeroElement;
+    for (let i = 0; i < size; ++i) {
+      bufs.push(current);
+      current = pedersen.compress(current, current);
+    }
+    return new SiblingPath(size, bufs);
+  }
+
+  /**
+   * Constructor.
+   * @param pathSize - The size of the sibling path.
+   * @param path - The sibling path data.
+   */
+  constructor(
+    /**
+     * Size of the sibling path (number of fields it contains).
+     */
+    public pathSize: N,
+    /**
+     * The sibling path data.
+     */
+    path: Buffer[],
+  ) {
+    this.data = assertLength(path, pathSize);
+  }
+
+  /**
+   * Serializes this SiblingPath object to a buffer.
+   * @returns The buffer representation of this object.
+   */
+  public toBuffer(): Buffer {
+    return serializeBufferArrayToVector(this.data);
+  }
+
+  /**
+   * Returns the path buffer underlying the sibling path.
+   * @returns The Buffer array representation of this object.
+   */
+  public toBufferArray(): Buffer[] {
+    return this.data;
+  }
+
+  /**
+   * Convert the Sibling Path object into an array of field elements.
+   * @returns The field array representation of this object.
+   */
+  public toFieldArray(): Fr[] {
+    return this.data.map(buf => Fr.fromBuffer(buf));
+  }
+
+  /**
+   * Deserializes a SiblingPath from a buffer.
+   * @param buf - A buffer containing the buffer representation of SiblingPath.
+   * @param offset - An offset to start deserializing from.
+   * @returns A SiblingPath object.
+   */
+  static fromBuffer<N extends number>(buf: Buffer, offset = 0): SiblingPath<N> {
+    const { elem } = SiblingPath.deserialize<N>(buf, offset);
+    return elem;
+  }
+
+  /**
+   * Deserializes a SiblingPath object from a slice of a part of a buffer and returns the amount of bytes advanced.
+   * @param buf - A buffer representation of the sibling path.
+   * @param offset - An offset to start deserializing from.
+   * @returns The deserialized sibling path and the number of bytes advanced.
+   */
+  static deserialize<N extends number>(buf: Buffer, offset = 0) {
+    const deserializePath = (buf: Buffer, offset: number) => ({
+      elem: buf.slice(offset, offset + 32),
+      adv: 32,
+    });
+    const { elem, adv } = deserializeArrayFromVector(deserializePath, buf, offset);
+    const size = elem.length;
+    return { elem: new SiblingPath<N>(size as N, elem), adv };
+  }
+
+  /**
+   * Serializes this SiblingPath object to a hex string representation.
+   * @returns A hex string representation of the sibling path.
+   */
+  public toString(): string {
+    return this.toBuffer().toString('hex');
+  }
+
+  /**
+   * Deserializes a SiblingPath object from a hex string representation.
+   * @param repr - A hex string representation of the sibling path.
+   * @returns A SiblingPath object.
+   */
+  public static fromString<N extends number>(repr: string): SiblingPath<N> {
+    return SiblingPath.fromBuffer<N>(Buffer.from(repr, 'hex'));
+  }
+
+  /**
+   * Generate a subtree path from the current sibling path.
+   * @param subtreeHeight - The size of the subtree that we are getting the path for.
+   * @returns A new sibling path that is the for the requested subtree.
+   */
+  public getSubtreeSiblingPath<SubtreeHeight extends number, SubtreeSiblingPathHeight extends number>(
+    subtreeHeight: SubtreeHeight,
+  ): SiblingPath<SubtreeSiblingPathHeight> {
+    // Drop the size of the subtree from the path, and return the rest.
+    const subtreeData = this.data.slice(subtreeHeight);
+    const subtreePathSize = (this.pathSize - subtreeHeight) as SubtreeSiblingPathHeight;
+    return new SiblingPath(subtreePathSize, subtreeData);
+  }
+}