@aztec/foundation 0.0.1-commit.9593d84 → 0.0.1-commit.967fc6998

package/src/schemas/schemas.ts

@@ -4,10 +4,10 @@ import { EpochNumber, EpochNumberSchema } from '../branded-types/epoch.js';
 import { SlotNumber, SlotNumberSchema } from '../branded-types/slot.js';
 import { Buffer32 } from '../buffer/buffer32.js';
 import { SecretValue } from '../config/secret_value.js';
+import { Fq, Fr } from '../curves/bn254/field.js';
+import { Point } from '../curves/grumpkin/point.js';
 import { EthAddress } from '../eth-address/index.js';
-import { Fq, Fr } from '../fields/fields.js';
-import { Point } from '../fields/point.js';
-import { isHex, withoutHexPrefix } from '../string/index.js';
+import { isHex, withHexPrefix, withoutHexPrefix } from '../string/index.js';
 import { bufferSchema, hexSchema } from './utils.js';
 
 export const schemas = {
@@ -58,6 +58,14 @@ export const schemas = {
       .max(2 ** 32 - 1),
   ),
 
+  /** Coerces input to UInt64. */
+  UInt64: z.union([z.bigint(), z.number(), z.string()]).pipe(
+    z.coerce
+      .bigint()
+      .min(0n)
+      .max(2n ** 64n - 1n),
+  ),
+
   /** Accepts a hex string as a Buffer32 type. */
   Buffer32: z.string().refine(isHex, 'Not a valid hex string').transform(Buffer32.fromString),
 
@@ -74,6 +82,9 @@ export const schemas = {
   /** Hex string with an optional 0x prefix which gets removed as part of the parsing. */
   HexString: hexSchema,
 
+  /** Hex string with an optional 0x prefix which gets enforced as part of the parsing. */
+  HexStringWith0x: z.string().refine(isHex, 'Not a valid hex string').transform(withHexPrefix),
+
   /** A secret config value */
   SecretValue: SecretValue.schema,
 };

package/src/schemas/types.ts

@@ -1,3 +1,36 @@
 import type { ZodType } from 'zod';
 
 export type ZodFor<T> = ZodType<T, any, any>;
+
+/**
+ * Creates a schema validator that enforces all properties of type T are present in the schema.
+ * This provides compile-time safety to ensure schemas don't miss optional properties.
+ *
+ * @example
+ * ```ts
+ * interface MyConfig {
+ *   foo: string;
+ *   bar?: number;
+ * }
+ *
+ * // ✅ This will work - all keys present
+ * const schema1 = zodFor<MyConfig>()(z.object({
+ *   foo: z.string(),
+ *   bar: z.number().optional(),
+ * }));
+ *
+ * // ❌ This will error - 'bar' is missing
+ * const schema2 = zodFor<MyConfig>()(z.object({
+ *   foo: z.string(),
+ * }));
+ * ```
+ */
+export function zodFor<T>() {
+  return (schema => schema) as <S extends ZodType<any, any, any>>(
+    schema: keyof T extends keyof S['_output']
+      ? keyof S['_output'] extends keyof T
+        ? S
+        : S & { __error__: 'Schema has extra keys not in type'; __extra__: Exclude<keyof S['_output'], keyof T> }
+      : S & { __error__: 'Schema is missing keys from type'; __missing__: Exclude<keyof T, keyof S['_output']> },
+  ) => S;
+}

package/src/serialize/buffer_reader.ts

@@ -1,3 +1,4 @@
+import { toBigIntBE } from '../bigint-buffer/index.js';
 import type { Tuple } from './types.js';
 
 /**
@@ -130,6 +131,20 @@ export class BufferReader {
     return result;
   }
 
+  /**
+   * Reads a 256-bit signed integer (two's complement) from the buffer at the current index position.
+   * Updates the index position by 32 bytes after reading the number.
+   *
+   * @returns The read 256 bit signed value as a bigint.
+   */
+  public readInt256(): bigint {
+    this.#rangeCheck(32);
+    const unsigned = toBigIntBE(this.buffer.subarray(this.index, this.index + 32));
+    this.index += 32;
+    const signBit = 1n << 255n;
+    return unsigned >= signBit ? unsigned - (1n << 256n) : unsigned;
+  }
+
   /** Alias for readUInt256 */
   public readBigInt(): bigint {
     return this.readUInt256();
@@ -224,15 +239,22 @@ export class BufferReader {
    * deserializing each one using the 'fromBuffer' method of 'itemDeserializer'.
    *
    * @param itemDeserializer - Object with 'fromBuffer' method to deserialize vector elements.
+   * @param maxSize - Optional maximum allowed size for the vector. If the size exceeds this, an error is thrown.
    * @returns An array of deserialized elements of type T.
    */
-  public readVector<T>(itemDeserializer: {
-    /**
-     * A method to deserialize data from a buffer.
-     */
-    fromBuffer: (reader: BufferReader) => T;
-  }): T[] {
+  public readVector<T>(
+    itemDeserializer: {
+      /**
+       * A method to deserialize data from a buffer.
+       */
+      fromBuffer: (reader: BufferReader) => T;
+    },
+    maxSize?: number,
+  ): T[] {
     const size = this.readNumber();
+    if (maxSize !== undefined && size > maxSize) {
+      throw new Error(`Vector size ${size} exceeds maximum allowed ${maxSize}`);
+    }
     const result = new Array<T>(size);
     for (let i = 0; i < size; i++) {
       result[i] = itemDeserializer.fromBuffer(this);
@@ -344,10 +366,11 @@ export class BufferReader {
    * The method first reads the size of the string, then reads the corresponding
    * number of bytes from the buffer and converts them to a string.
    *
+   * @param maxSize - Optional maximum allowed size for the string buffer. If the size exceeds this, an error is thrown.
    * @returns The read string from the buffer.
    */
-  public readString(): string {
-    return this.readBuffer().toString();
+  public readString(maxSize?: number): string {
+    return this.readBuffer(maxSize).toString();
   }
 
   /**
@@ -356,10 +379,14 @@ export class BufferReader {
    * a Buffer with that size containing the bytes. Useful for reading variable-length
    * binary data encoded as (size, data) format.
    *
+   * @param maxSize - Optional maximum allowed size for the buffer. If the size exceeds this, an error is thrown.
    * @returns A Buffer containing the read bytes.
    */
-  public readBuffer(): Buffer {
+  public readBuffer(maxSize?: number): Buffer {
     const size = this.readNumber();
+    if (maxSize !== undefined && size > maxSize) {
+      throw new Error(`Buffer size ${size} exceeds maximum allowed ${maxSize}`);
+    }
     this.#rangeCheck(size);
     return this.readBytes(size);
   }

package/src/serialize/field_reader.ts

@@ -1,4 +1,4 @@
-import { Fq, type Fr } from '../fields/fields.js';
+import { Fq, type Fr } from '../curves/bn254/field.js';
 import type { Tuple } from './types.js';
 
 /**

package/src/serialize/free_funcs.ts

@@ -1,5 +1,5 @@
 import { toBufferBE } from '../bigint-buffer/index.js';
-import { Fr } from '../fields/fields.js';
+import { Fr } from '../curves/bn254/field.js';
 import type { Tuple } from './types.js';
 
 /**

package/src/serialize/serialize.ts

@@ -1,5 +1,5 @@
 import { toBigIntBE, toBufferBE } from '../bigint-buffer/index.js';
-import { Fr } from '../fields/fields.js';
+import { Fr } from '../curves/bn254/field.js';
 import { numToUInt32BE } from './free_funcs.js';
 
 /**
@@ -269,6 +269,22 @@ export function serializeBigInt(n: bigint, width = 32) {
   return toBufferBE(n, width);
 }
 
+/**
+ * Serialize a signed BigInt value into a Buffer of specified width using two's complement.
+ * @param n - The signed BigInt value to be serialized.
+ * @param width - The width (in bytes) of the output Buffer, optional with default value 32.
+ * @returns A Buffer containing the serialized signed BigInt value in big-endian format.
+ */
+export function serializeSignedBigInt(n: bigint, width = 32) {
+  const widthBits = BigInt(width * 8);
+  const max = 1n << (widthBits - 1n);
+  if (n < -max || n >= max) {
+    throw new Error(`Signed BigInt ${n.toString()} does not fit into ${width} bytes`);
+  }
+  const unsigned = n < 0n ? (1n << widthBits) + n : n;
+  return toBufferBE(unsigned, width);
+}
+
 /**
  * Deserialize a big integer from a buffer, given an offset and width.
  * Reads the specified number of bytes from the buffer starting at the offset, converts it to a big integer, and returns the deserialized result along with the number of bytes read (advanced).
@@ -282,6 +298,22 @@ export function deserializeBigInt(buf: Buffer, offset = 0, width = 32) {
   return { elem: toBigIntBE(buf.subarray(offset, offset + width)), adv: width };
 }
 
+/**
+ * Deserialize a signed BigInt from a buffer (two's complement).
+ * @param buf - The buffer containing the signed big integer to be deserialized.
+ * @param offset - The position in the buffer where the integer starts. Defaults to 0.
+ * @param width - The number of bytes to read from the buffer for the integer. Defaults to 32.
+ * @returns An object containing the deserialized signed bigint value ('elem') and bytes advanced ('adv').
+ */
+export function deserializeSignedBigInt(buf: Buffer, offset = 0, width = 32) {
+  const { elem, adv } = deserializeBigInt(buf, offset, width);
+  const widthBits = BigInt(width * 8);
+  const signBit = 1n << (widthBits - 1n);
+  const fullRange = 1n << widthBits;
+  const signed = elem >= signBit ? elem - fullRange : elem;
+  return { elem: signed, adv };
+}
+
 /**
  * Serializes a Date object into a Buffer containing its timestamp as a big integer value.
  * The resulting Buffer has a fixed width of 8 bytes, representing a 64-bit big-endian integer.

package/src/sleep/index.ts

@@ -22,6 +22,7 @@ import { InterruptError } from '../error/index.js';
  */
 export class InterruptibleSleep {
   private interrupts: Array<(shouldThrow: boolean) => void> = [];
+  private timeoutIds: NodeJS.Timeout[] = [];
 
   /**
    * Sleep for a specified amount of time in milliseconds.
@@ -38,9 +39,15 @@ export class InterruptibleSleep {
       this.interrupts.push(resolve);
     });
 
-    const timeoutPromise = new Promise<boolean>(resolve => setTimeout(() => resolve(false), ms));
+    let timeoutId: NodeJS.Timeout;
+    const timeoutPromise = new Promise<boolean>(resolve => {
+      timeoutId = setTimeout(() => resolve(false), ms);
+      this.timeoutIds.push(timeoutId);
+    });
     const shouldThrow = await Promise.race([interruptPromise, timeoutPromise]);
 
+    clearTimeout(timeoutId!);
+    this.timeoutIds = this.timeoutIds.filter(id => id !== timeoutId);
     this.interrupts = this.interrupts.filter(res => res !== interruptResolve);
 
     if (shouldThrow) {
@@ -58,6 +65,8 @@ export class InterruptibleSleep {
   public interrupt(sleepShouldThrow = false): void {
     this.interrupts.forEach(resolve => resolve(sleepShouldThrow));
     this.interrupts = [];
+    this.timeoutIds.forEach(id => clearTimeout(id));
+    this.timeoutIds = [];
   }
 }
 
@@ -73,3 +82,9 @@ export class InterruptibleSleep {
 export function sleep<T>(ms: number, returnValue?: T): Promise<T> {
   return new Promise(resolve => setTimeout(() => resolve(returnValue as T), ms));
 }
+
+/** Sleeps until the target date */
+export function sleepUntil<T>(target: Date, now: Date, returnValue?: T): Promise<T> {
+  const ms = target.getTime() - now.getTime();
+  return sleep(ms, returnValue);
+}

package/src/timer/date.ts

@@ -9,6 +9,10 @@ export class DateProvider {
   public nowInSeconds(): number {
     return Math.floor(this.now() / 1000);
   }
+
+  public nowAsDate(): Date {
+    return new Date(this.now());
+  }
 }
 
 /** Returns current datetime and allows to override it. */
@@ -27,4 +31,52 @@ export class TestDateProvider extends DateProvider {
     this.offset = timeMs - Date.now();
     this.logger.warn(`Time set to ${new Date(timeMs).toISOString()}`, { offset: this.offset, timeMs });
   }
+
+  /** Resets the time back to real time (offset = 0). */
+  public reset() {
+    this.offset = 0;
+    this.logger.warn('Time reset to real time');
+  }
+
+  /** Advances the time by the given number of seconds. */
+  public advanceTime(seconds: number) {
+    this.offset += seconds * 1000;
+  }
+}
+
+/**
+ * A date provider for tests that only advances time via explicit advanceTime() calls.
+ * Unlike TestDateProvider, this does NOT track real time progression - time is completely
+ * frozen until explicitly advanced. This eliminates flakiness from tests taking
+ * varying amounts of real time to execute.
+ */
+export class ManualDateProvider extends DateProvider {
+  private currentTimeMs: number;
+
+  /**
+   * @param initialTimeMs - Initial time in milliseconds. Defaults to a round timestamp for easy visualization.
+   */
+  constructor(initialTimeMs: number = Date.UTC(2025, 0, 1, 0, 0, 0)) {
+    super();
+    this.currentTimeMs = initialTimeMs;
+  }
+
+  public override now(): number {
+    return this.currentTimeMs;
+  }
+
+  /** Sets the current time to the given timestamp in milliseconds. */
+  public setTime(timeMs: number) {
+    this.currentTimeMs = timeMs;
+  }
+
+  /** Advances the time by the given number of seconds. */
+  public advanceTime(seconds: number) {
+    this.currentTimeMs += seconds * 1000;
+  }
+
+  /** Advances the time by the given number of milliseconds. */
+  public advanceTimeMs(ms: number) {
+    this.currentTimeMs += ms;
+  }
 }

package/src/transport/transport_client.ts

@@ -91,7 +91,7 @@ export class TransportClient<Payload> extends EventEmitter {
     }
     const msgId = this.msgId++;
     const msg = { msgId, payload };
-    log.debug(format(`->`, msg));
+    log.trace(format(`->`, msg));
     return new Promise<any>((resolve, reject) => {
       this.pendingRequests.push({ resolve, reject, msgId });
       this.socket!.send(msg, transfer).catch(reject);
@@ -111,7 +111,7 @@ export class TransportClient<Payload> extends EventEmitter {
       this.close();
       return;
     }
-    log.debug(format(`<-`, msg));
+    log.trace(format(`<-`, msg));
     if (isEventMessage(msg)) {
       this.emit('event_msg', msg.payload);
       return;

package/src/trees/{balanced_merkle_tree.ts → balanced_merkle_tree_root.ts}

@@ -1,21 +1,7 @@
-import { pedersenHash as pedersenHashArray, poseidon2Hash, sha256Trunc } from '@aztec/foundation/crypto';
-
-import type { AsyncHasher, Hasher } from './hasher.js';
-
-export const shaMerkleHash: Hasher['hash'] = (left: Buffer, right: Buffer) =>
-  sha256Trunc(Buffer.concat([left, right])) as Buffer<ArrayBuffer>;
-
-export const pedersenMerkleHash: AsyncHasher['hash'] = async (left: Buffer, right: Buffer) =>
-  (await pedersenHashArray([left, right])).toBuffer() as Buffer<ArrayBuffer>;
-
-export const poseidonMerkleHash: AsyncHasher['hash'] = async (left: Buffer, right: Buffer) =>
-  (await poseidon2Hash([left, right])).toBuffer() as Buffer<ArrayBuffer>;
+import { poseidonMerkleHash, shaMerkleHash } from './hasher.js';
 
 export const computeBalancedShaRoot = (leaves: Buffer[]) => computeBalancedMerkleTreeRoot(leaves);
 
-export const computeBalancedPedersenRoot = async (leaves: Buffer[]) =>
-  await computeBalancedMerkleTreeRootAsync(leaves, pedersenMerkleHash);
-
 export const computeBalancedPoseidonRoot = async (leaves: Buffer[]) =>
   await computeBalancedMerkleTreeRootAsync(leaves, poseidonMerkleHash);
 
@@ -44,7 +30,7 @@ export function computeBalancedMerkleTreeRoot(leaves: Buffer[], hasher = shaMerk
 
 /**
  * Computes the Merkle root with the provided leaves **asynchronously**.
- * This method uses an asynchronous hash function (defaults to `pedersenHash`).
+ * This method uses an asynchronous hash function (defaults to `poseidon2Hash`).
  *
  * @throws If the number of leaves is not a power of two.
  */

package/src/trees/hasher.ts

@@ -1,3 +1,6 @@
+import { poseidon2Hash } from '../crypto/poseidon/index.js';
+import { sha256Trunc } from '../crypto/sha256/index.js';
+
 /**
  * Defines hasher interface used by Merkle trees.
  */
@@ -37,3 +40,9 @@ export interface AsyncHasher {
    */
   hashInputs(inputs: Buffer[]): Promise<Buffer<ArrayBuffer>>;
 }
+
+export const shaMerkleHash: Hasher['hash'] = (left: Buffer, right: Buffer) =>
+  sha256Trunc(Buffer.concat([left, right])) as Buffer<ArrayBuffer>;
+
+export const poseidonMerkleHash: AsyncHasher['hash'] = async (left: Buffer, right: Buffer) =>
+  (await poseidon2Hash([left, right])).toBuffer() as Buffer<ArrayBuffer>;

package/src/trees/index.ts

@@ -1,6 +1,4 @@
-export * from './balanced_merkle_tree.js';
-export * from './unbalanced_merkle_tree.js';
-export * from './unbalanced_tree_store.js';
+export * from './balanced_merkle_tree_root.js';
 export * from './merkle_tree_calculator.js';
 export * from './merkle_tree.js';
 export * from './indexed_merkle_tree_calculator.js';
@@ -10,3 +8,5 @@ export * from './membership_witness.js';
 export * from './hasher.js';
 export * from './indexed_tree_leaf.js';
 export * from './unbalanced_merkle_tree_calculator.js';
+export * from './unbalanced_merkle_tree_root.js';
+export * from './unbalanced_tree_store.js';

package/src/trees/indexed_merkle_tree.ts

@@ -1,4 +1,4 @@
-import { Fr } from '../fields/index.js';
+import { Fr } from '../curves/bn254/index.js';
 import { assertLength } from '../serialize/index.js';
 import type { IndexedTreeLeafPreimage } from './indexed_tree_leaf.js';
 import { MembershipWitness } from './membership_witness.js';

package/src/trees/membership_witness.ts

@@ -1,6 +1,6 @@
 import { assertMemberLength } from '../array/array.js';
 import { toBigIntBE, toBufferBE } from '../bigint-buffer/index.js';
-import { Fr } from '../fields/fields.js';
+import { Fr } from '../curves/bn254/field.js';
 import { schemas } from '../schemas/schemas.js';
 import { BufferReader, type Tuple, serializeToBuffer } from '../serialize/index.js';
 import type { SiblingPath } from './sibling_path.js';
@@ -38,6 +38,14 @@ export class MembershipWitness<N extends number> {
     return [new Fr(this.leafIndex), ...this.siblingPath];
   }
 
+  /**
+   * Returns a representation of the membership witness as expected by intrinsic Noir deserialization.
+   */
+  public toNoirRepresentation(): (string | string[])[] {
+    // TODO(#12874): remove the stupid as string conversion by modifying ForeignCallOutput type in acvm.js
+    return [new Fr(this.leafIndex).toString() as string, this.siblingPath.map(fr => fr.toString()) as string[]];
+  }
+
   static schemaFor<N extends number>(size: N) {
     return schemas.Buffer.transform(b => MembershipWitness.fromBuffer(b, size));
   }

package/src/trees/merkle_tree_calculator.ts

@@ -1,4 +1,4 @@
-import { pedersenHash } from '@aztec/foundation/crypto';
+import { poseidon2Hash } from '@aztec/foundation/crypto/poseidon';
 
 import type { AsyncHasher } from './hasher.js';
 import { MerkleTree } from './merkle_tree.js';
@@ -19,7 +19,7 @@ export class MerkleTreeCalculator {
     height: number,
     zeroLeaf: Buffer = Buffer.alloc(32),
     hasher = async (left: Buffer, right: Buffer) =>
-      (await pedersenHash([left, right])).toBuffer() as Buffer<ArrayBuffer>,
+      (await poseidon2Hash([left, right])).toBuffer() as Buffer<ArrayBuffer>,
   ) {
     const zeroHashes = [zeroLeaf];
     for (let i = 0; i < height; i++) {

package/src/trees/sibling_path.ts

@@ -1,6 +1,6 @@
 import { makeTuple } from '../array/array.js';
-import { pedersenHash } from '../crypto/index.js';
-import { Fr } from '../fields/index.js';
+import { poseidon2Hash } from '../crypto/poseidon/index.js';
+import { Fr } from '../curves/bn254/index.js';
 import { schemas } from '../schemas/index.js';
 import {
   type Tuple,
@@ -172,7 +172,7 @@ export async function computeRootFromSiblingPath(
   leaf: Buffer,
   siblingPath: Buffer[],
   index: number,
-  hasher = async (left: Buffer, right: Buffer) => (await pedersenHash([left, right])).toBuffer(),
+  hasher = async (left: Buffer, right: Buffer) => (await poseidon2Hash([left, right])).toBuffer(),
 ) {
   let result = leaf;
   for (const sibling of siblingPath) {

package/src/trees/unbalanced_merkle_tree_calculator.ts

@@ -1,18 +1,7 @@
-import { shaMerkleHash } from './balanced_merkle_tree.js';
-import type { Hasher } from './hasher.js';
+import { type Hasher, shaMerkleHash } from './hasher.js';
 import { SiblingPath } from './sibling_path.js';
 import { type TreeNodeLocation, UnbalancedTreeStore } from './unbalanced_tree_store.js';
 
-export function computeCompressedUnbalancedMerkleTreeRoot(
-  leaves: Buffer[],
-  valueToCompress = Buffer.alloc(32),
-  emptyRoot = Buffer.alloc(32),
-  hasher?: Hasher['hash'],
-): Buffer {
-  const calculator = UnbalancedMerkleTreeCalculator.create(leaves, valueToCompress, emptyRoot, hasher);
-  return calculator.getRoot();
-}
-
 interface TreeNode {
   value: Buffer;
   leafIndex?: number;

package/src/trees/{unbalanced_merkle_tree.ts → unbalanced_merkle_tree_root.ts}

@@ -1,15 +1,14 @@
-import {
-  computeBalancedMerkleTreeRoot,
-  computeBalancedMerkleTreeRootAsync,
-  poseidonMerkleHash,
-  shaMerkleHash,
-} from './balanced_merkle_tree.js';
+import { computeBalancedMerkleTreeRoot, computeBalancedMerkleTreeRootAsync } from './balanced_merkle_tree_root.js';
+import { poseidonMerkleHash, shaMerkleHash } from './hasher.js';
+import { UnbalancedMerkleTreeCalculator } from './unbalanced_merkle_tree_calculator.js';
 
 export const computeUnbalancedShaRoot = (leaves: Buffer[]) => computeUnbalancedMerkleTreeRoot(leaves, shaMerkleHash);
 
 export const computeUnbalancedPoseidonRoot = async (leaves: Buffer[]) =>
   await computeUnbalancedMerkleTreeRootAsync(leaves, poseidonMerkleHash);
 
+export const computeWonkyShaRoot = (leaves: Buffer[]) => computeWonkyMerkleTreeRoot(leaves);
+
 /**
  * Computes the Merkle root of an unbalanced tree.
  *
@@ -101,59 +100,16 @@ export async function computeUnbalancedMerkleTreeRootAsync(
   return root!;
 }
 
-/// Get the depth of the maximum balanced tree that can be created with the given number of leaves. The subtree will be
-/// the left most subtree of the wonky tree with a total of `numLeaves` leaves.
-///
-/// Note: All the leaves may not be used to form the tree. For example, if there are 5 leaves, the maximum depth is 2,
-/// only 4 leaves are used to form a balanced tree.
-function getMaxBalancedSubtreeDepth(numLeaves: number) {
-  return Math.floor(Math.log2(numLeaves));
-}
-
-/// Get the maximum depth of an unbalanced tree that can be created with the given number of leaves.
-function getMaxUnbalancedTreeDepth(numLeaves: number) {
-  return Math.ceil(Math.log2(numLeaves));
-}
-
-function findPosition(
-  rootLevel: number,
-  leafLevel: number,
-  numLeaves: number,
-  indexOffset: number,
-  targetIndex: number,
-): { level: number; indexAtLevel: number } {
-  if (numLeaves <= 1) {
-    // Single leaf.
-    return { level: rootLevel, indexAtLevel: indexOffset };
-  }
-
-  // The largest balanced tree that can be created with the given number of leaves.
-  const maxBalancedTreeDepth = getMaxBalancedSubtreeDepth(numLeaves);
-  const numBalancedLeaves = 2 ** maxBalancedTreeDepth;
-  const numRemainingLeaves = numLeaves - numBalancedLeaves;
-
-  if (targetIndex < numBalancedLeaves) {
-    // Target is in the balanced tree.
-
-    // - If numRemainingLeaves is 0: this balanced tree is grown from the current root.
-    // - If numRemainingLeaves is not 0: the remaining leaves will form another tree, which will become the right child of the root.
-    //   And the balanced tree will be the left child of the root.
-    //   There will be an extra level between the root of the balanced tree and the current root.
-    const extraLevel = numRemainingLeaves ? 1 : 0;
-
-    return { level: rootLevel + maxBalancedTreeDepth + extraLevel, indexAtLevel: indexOffset + targetIndex };
-  } else {
-    // Target is in the right branch.
-    const rightBranchMaxLevel = getMaxUnbalancedTreeDepth(numRemainingLeaves);
-    const shiftedUp = leafLevel - rootLevel - rightBranchMaxLevel - 1;
-    const nextLeafLevel = leafLevel - shiftedUp;
-    const newIndexOffset = (indexOffset + numBalancedLeaves) >> shiftedUp;
-    const shiftedTargetIndex = targetIndex - numBalancedLeaves;
-    return findPosition(rootLevel + 1, nextLeafLevel, numRemainingLeaves, newIndexOffset, shiftedTargetIndex);
-  }
-}
-
-export function findLeafLevelAndIndex(numLeaves: number, leafIndex: number) {
-  const maxLevel = getMaxUnbalancedTreeDepth(numLeaves);
-  return findPosition(0, maxLevel, numLeaves, 0, leafIndex);
+// A **wonky** tree is a "compressed" unbalanced Merkle tree.
+// It is constructed in the same way as an unbalanced tree: by first creating the largest possible left subtree, with
+// the remaining leaves forming a right subtree that follows the same process recursively.
+// During construction, leaves equal to `valueToCompress` are skipped (compressed) and do not contribute to the tree.
+export function computeWonkyMerkleTreeRoot(
+  leaves: Buffer[],
+  valueToCompress = Buffer.alloc(32),
+  emptyRoot = Buffer.alloc(32),
+  hasher = shaMerkleHash,
+): Buffer {
+  const calculator = UnbalancedMerkleTreeCalculator.create(leaves, valueToCompress, emptyRoot, hasher);
+  return calculator.getRoot();
 }

package/src/trees/unbalanced_tree_store.ts

@@ -1,5 +1,3 @@
-import { findLeafLevelAndIndex } from './unbalanced_merkle_tree.js';
-
 export interface TreeNodeLocation {
   level: number;
   index: number;
@@ -104,3 +102,60 @@ export class UnbalancedTreeStore<T> {
     return `${location.level}-${location.index}`;
   }
 }
+
+/// Get the depth of the maximum balanced tree that can be created with the given number of leaves. The subtree will be
+/// the left most subtree of the unbalanced tree with a total of `numLeaves` leaves.
+///
+/// Note: All the leaves may not be used to form the tree. For example, if there are 5 leaves, the maximum depth is 2,
+/// only 4 leaves are used to form a balanced tree.
+function getMaxBalancedSubtreeDepth(numLeaves: number) {
+  return Math.floor(Math.log2(numLeaves));
+}
+
+/// Get the maximum depth of an unbalanced tree that can be created with the given number of leaves.
+function getMaxUnbalancedTreeDepth(numLeaves: number) {
+  return Math.ceil(Math.log2(numLeaves));
+}
+
+function findPosition(
+  rootLevel: number,
+  leafLevel: number,
+  numLeaves: number,
+  indexOffset: number,
+  targetIndex: number,
+): { level: number; indexAtLevel: number } {
+  if (numLeaves <= 1) {
+    // Single leaf.
+    return { level: rootLevel, indexAtLevel: indexOffset };
+  }
+
+  // The largest balanced tree that can be created with the given number of leaves.
+  const maxBalancedTreeDepth = getMaxBalancedSubtreeDepth(numLeaves);
+  const numBalancedLeaves = 2 ** maxBalancedTreeDepth;
+  const numRemainingLeaves = numLeaves - numBalancedLeaves;
+
+  if (targetIndex < numBalancedLeaves) {
+    // Target is in the balanced tree.
+
+    // - If numRemainingLeaves is 0: this balanced tree is grown from the current root.
+    // - If numRemainingLeaves is not 0: the remaining leaves will form another tree, which will become the right child of the root.
+    //   And the balanced tree will be the left child of the root.
+    //   There will be an extra level between the root of the balanced tree and the current root.
+    const extraLevel = numRemainingLeaves ? 1 : 0;
+
+    return { level: rootLevel + maxBalancedTreeDepth + extraLevel, indexAtLevel: indexOffset + targetIndex };
+  } else {
+    // Target is in the right branch.
+    const rightBranchMaxLevel = getMaxUnbalancedTreeDepth(numRemainingLeaves);
+    const shiftedUp = leafLevel - rootLevel - rightBranchMaxLevel - 1;
+    const nextLeafLevel = leafLevel - shiftedUp;
+    const newIndexOffset = (indexOffset + numBalancedLeaves) >> shiftedUp;
+    const shiftedTargetIndex = targetIndex - numBalancedLeaves;
+    return findPosition(rootLevel + 1, nextLeafLevel, numRemainingLeaves, newIndexOffset, shiftedTargetIndex);
+  }
+}
+
+export function findLeafLevelAndIndex(numLeaves: number, leafIndex: number) {
+  const maxLevel = getMaxUnbalancedTreeDepth(numLeaves);
+  return findPosition(0, maxLevel, numLeaves, 0, leafIndex);
+}