@aztec/foundation 4.0.0-nightly.20250907 → 4.0.0-nightly.20260108

package/src/{fields → curves/grumpkin}/point.ts

@@ -1,10 +1,10 @@
-import { toBigIntBE } from '../bigint-buffer/index.js';
-import { poseidon2Hash } from '../crypto/poseidon/index.js';
-import { randomBoolean } from '../crypto/random/index.js';
-import { hexSchemaFor } from '../schemas/utils.js';
-import { BufferReader, FieldReader, serializeToBuffer } from '../serialize/index.js';
-import { bufferToHex, hexToBuffer } from '../string/index.js';
-import { Fr } from './fields.js';
+import { toBigIntBE } from '../../bigint-buffer/index.js';
+import { poseidon2Hash } from '../../crypto/poseidon/index.js';
+import { randomBoolean } from '../../crypto/random/index.js';
+import { hexSchemaFor } from '../../schemas/utils.js';
+import { BufferReader, FieldReader, serializeToBuffer } from '../../serialize/index.js';
+import { bufferToHex, hexToBuffer } from '../../string/index.js';
+import { Fr } from '../bn254/field.js';
 
 /**
  * Represents a Point on an elliptic curve with x and y coordinates.
@@ -42,9 +42,28 @@ export class Point {
   }
 
   static get schema() {
+    // Serialization from hex string.
     return hexSchemaFor(Point);
   }
 
+  /**
+   * Creates a Point from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * Handles buffers, existing instances, or objects with x, y, and isInfinite fields.
+   * @param obj - Plain object, buffer, or Point instance
+   * @returns A Point instance
+   */
+  static fromPlainObject(obj: any): Point {
+    if (obj instanceof Point) {
+      return obj;
+    }
+    if (obj instanceof Buffer || Buffer.isBuffer(obj)) {
+      return Point.fromBuffer(obj);
+    }
+    return new Point(Fr.fromPlainObject(obj.x), Fr.fromPlainObject(obj.y), obj.isInfinite ?? false);
+  }
+
   /**
    * Generate a random Point instance.
    *

package/src/eth-address/index.ts

@@ -2,7 +2,7 @@ import { inspect } from 'util';
 
 import { keccak256String } from '../crypto/keccak/index.js';
 import { randomBytes } from '../crypto/random/index.js';
-import { Fr } from '../fields/index.js';
+import { Fr } from '../curves/bn254/index.js';
 import { hexSchemaFor } from '../schemas/utils.js';
 import { BufferReader, FieldReader } from '../serialize/index.js';
 import { TypeRegistry } from '../serialize/type_registry.js';
@@ -41,6 +41,24 @@ export class EthAddress {
     return new EthAddress(Buffer.from(address.replace(/^0x/i, ''), 'hex'));
   }
 
+  /**
+   * Creates an EthAddress from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * Handles buffers (20 or 32 bytes), strings, or existing instances.
+   * @param obj - Plain object, buffer, string, or EthAddress instance
+   * @returns An EthAddress instance
+   */
+  public static fromPlainObject(obj: any): EthAddress {
+    if (obj instanceof EthAddress) {
+      return obj;
+    }
+    if (obj instanceof Buffer || Buffer.isBuffer(obj)) {
+      return obj.length === 20 ? new EthAddress(obj) : EthAddress.fromField(new Fr(obj));
+    }
+    return EthAddress.fromString(obj);
+  }
+
   /**
    * Create a random EthAddress instance with 20 random bytes.
    * This method generates a new Ethereum address with a randomly generated set of 20 bytes.
@@ -117,14 +135,14 @@ export class EthAddress {
    * @param address - The Ethereum address as a hex-encoded string.
    * @returns The Ethereum address in its checksum format.
    */
-  public static toChecksumAddress(address: string) {
+  public static toChecksumAddress(address: string): `0x${string}` {
     if (!EthAddress.isAddress(address)) {
       throw new Error('Invalid address string.');
     }
 
     address = address.toLowerCase().replace(/^0x/i, '');
     const addressHash = keccak256String(address);
-    let checksumAddress = '0x';
+    let checksumAddress: `0x${string}` = '0x';
 
     for (let i = 0; i < address.length; i++) {
       // If ith character is 9 to f then make it uppercase.
@@ -240,8 +258,15 @@ export class EthAddress {
   }
 
   static get schema() {
+    // Serialization from hex string.
     return hexSchemaFor(EthAddress, EthAddress.isAddress);
   }
+
+  static areEqual(a: EthAddress | string, b: EthAddress | string) {
+    const addrA = typeof a === 'string' ? EthAddress.fromString(a) : a;
+    const addrB = typeof b === 'string' ? EthAddress.fromString(b) : b;
+    return addrA.equals(addrB);
+  }
 }
 
 // For deserializing JSON.

package/src/eth-signature/eth_signature.ts

@@ -78,7 +78,7 @@ export class Signature {
   }
 
   static random(): Signature {
-    return new Signature(Buffer32.random(), Buffer32.random(), Math.floor(Math.random() * 2));
+    return new Signature(Buffer32.random(), Buffer32.random(), 1);
   }
 
   static empty(): Signature {
@@ -94,9 +94,7 @@ export class Signature {
   }
 
   toBuffer(): Buffer {
-    const buffer = serializeToBuffer([this.r, this.s, this.v]);
-    this.size = buffer.length;
-    return buffer;
+    return serializeToBuffer([this.r, this.s, this.v]);
   }
 
   getSize(): number {

package/src/iterator/filter.ts

@@ -0,0 +1,11 @@
+/** Wraps an async iterable iterator such that it filters values based on a predicate. */
+export async function* filter<T>(
+  iterator: AsyncIterableIterator<T>,
+  predicate: (item: T) => boolean | Promise<boolean>,
+): AsyncIterableIterator<T> {
+  for await (const item of iterator) {
+    if (await predicate(item)) {
+      yield item;
+    }
+  }
+}

package/src/iterator/index.ts

@@ -0,0 +1 @@
+export { filter } from './filter.js';

package/src/json-rpc/client/safe_json_rpc_client.ts

@@ -178,6 +178,15 @@ export function createSafeJsonRpcClient<T extends object>(
         }
       }
     } catch (err) {
+      // Re-throw ComponentsVersionsError immediately without converting to JSON-RPC error
+      // This ensures version mismatch errors are surfaced to the user instead of being hidden
+      if (err && typeof err === 'object' && 'name' in err && err.name === 'ComponentsVersionsError') {
+        // Reject all pending requests with the version error
+        for (let i = 0; i < rpcCalls.length; i++) {
+          rpcCalls[i].deferred.reject(err);
+        }
+        return; // Return early, the promises are already rejected
+      }
       log.warn(`Failed to fetch from the remote server`, err);
       for (let i = 0; i < rpcCalls.length; i++) {
         const { request, deferred } = rpcCalls[i];

package/src/log/log_fn.ts

@@ -1,5 +1,5 @@
 /** Structured log data to include with the message. */
-export type LogData = Record<string, string | number | bigint | boolean | { toString(): string } | undefined>;
+export type LogData = Record<string, string | number | bigint | boolean | { toString(): string } | undefined | null>;
 
 /** A callable logger instance. */
 export type LogFn = (msg: string, data?: unknown) => void;

package/src/log/pino-logger.ts

@@ -111,7 +111,6 @@ const redactedPaths = [
   // bot keys
   'l1PrivateKey',
   'senderPrivateKey',
-  'recipientEncryptionSecret',
   // blob sink
   'l1ConsensusHostApiKeys',
   // sensitive options used in the CLI

package/src/profiler/index.ts

@@ -0,0 +1 @@
+export * from './profiler.js';

package/src/profiler/profiler.ts

@@ -0,0 +1,125 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { performance } from 'node:perf_hooks';
+
+interface Span {
+  label: string;
+  start: number;
+  dur: number;
+  count: number;
+  children: Span[];
+  parent: Span | undefined;
+}
+
+interface ProfileData {
+  spans: SerializedSpan[];
+  timestamp: string;
+  totalTime: number;
+}
+
+interface SerializedSpan {
+  label: string;
+  dur: number;
+  count: number;
+  children: SerializedSpan[];
+}
+
+const als = new AsyncLocalStorage<Span>();
+const roots: Span[] = [];
+
+function reset(): void {
+  roots.length = 0;
+}
+
+// Strip out circular references (parent) and unused fields (start) for JSON serialization
+function serializeSpans(spans: Span[]): SerializedSpan[] {
+  return spans.map(span => ({
+    label: span.label,
+    dur: span.dur,
+    count: span.count,
+    children: serializeSpans(span.children),
+  }));
+}
+
+let i = 0;
+function save(): void {
+  if (roots.length === 0) {
+    return;
+  }
+
+  // Find max single execution time across all spans (dur/count since dur is accumulated)
+  const findMaxSingleDuration = (spans: Span[]): number => {
+    let max = 0;
+    for (const span of spans) {
+      const singleDur = span.dur / span.count;
+      max = Math.max(max, singleDur);
+      if (span.children.length > 0) {
+        max = Math.max(max, findMaxSingleDuration(span.children));
+      }
+    }
+    return max;
+  };
+
+  const profileData: ProfileData = {
+    spans: serializeSpans(roots),
+    timestamp: new Date().toISOString(),
+    totalTime: findMaxSingleDuration(roots),
+  };
+
+  const profilePath = path.join(process.cwd(), `profile-${i++}.json`);
+  process.stdout.write(`Writing profile data to ${profilePath}\n`);
+  fs.writeFileSync(profilePath, JSON.stringify(profileData, null, 2));
+}
+
+// Hook into Jest to save after each test
+if (typeof afterEach === 'function') {
+  afterEach(() => {
+    save();
+    reset();
+  });
+}
+
+// Also save on process exit for non-Jest environments
+process.on('exit', () => {
+  save();
+});
+
+// Wrapper for async functions to maintain context properly
+async function runAsync<ReturnType>(label: string, fn: () => Promise<ReturnType>): Promise<ReturnType> {
+  const parent = als.getStore();
+
+  // Check if we already have a span with this label in the current context
+  let existingSpan: Span | undefined;
+  if (parent) {
+    existingSpan = parent.children.find(c => c.label === label);
+  } else {
+    existingSpan = roots.find(r => r.label === label);
+  }
+
+  let span: Span;
+  if (existingSpan) {
+    // Reuse existing span and increment count
+    span = existingSpan;
+    span.count++;
+  } else {
+    // Create new span
+    span = { label, start: performance.now(), dur: 0, count: 1, children: [], parent };
+    if (parent) {
+      parent.children.push(span);
+    } else {
+      roots.push(span);
+    }
+  }
+
+  const startTime = performance.now();
+  const result: ReturnType = await als.run(span, fn);
+  const elapsed = performance.now() - startTime;
+
+  // Add to total duration (for averaging)
+  span.dur += elapsed;
+
+  return result;
+}
+
+export const profiler = { reset, runAsync };

package/src/schemas/schemas.ts

@@ -1,14 +1,22 @@
 import { z } from 'zod';
 
+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 = {
+  /** Accepts a number, bigint, or string as an EpochNumber. */
+  EpochNumber: EpochNumberSchema,
+
+  /** Accepts a number, bigint, or string as a SlotNumber. */
+  SlotNumber: SlotNumberSchema,
+
   /** Accepts a hex string. */
   EthAddress: EthAddress.schema,
 
@@ -50,19 +58,19 @@ 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),
 
   /** Accepts a base64 string or an object `{ type: 'Buffer', data: [byte, byte...] }` as a buffer. */
-  Buffer: z.union([
-    bufferSchema,
-    z
-      .object({
-        type: z.literal('Buffer'),
-        data: z.array(z.number().int().min(0).max(255)),
-      })
-      .transform(({ data }) => Buffer.from(data)),
-  ]),
+  Buffer: bufferSchema,
 
   /** Accepts a hex string as a buffer. */
   BufferHex: z
@@ -74,9 +82,12 @@ 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,
 };
 
 // These are needed to avoid errors such as: "The inferred type of 'YourClassSchema' cannot be named without a reference to..."
-export type { EthAddress, Fq, Fr, Point };
+export type { EpochNumber, EthAddress, Fq, Fr, Point, SlotNumber };

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/schemas/utils.ts

@@ -21,13 +21,25 @@ export const hexSchema = z.string().refine(isHex, 'Not a valid hex string').tran
 // Copied from zod internals, which was copied from https://stackoverflow.com/questions/7860392/determine-if-string-is-in-base64-using-javascript
 const base64Regex = /^([0-9a-zA-Z+/]{4})*(([0-9a-zA-Z+/]{2}==)|([0-9a-zA-Z+/]{3}=))?$/;
 
-/** Schema for a buffer represented as a base64 string. */
-export const bufferSchema = z
-  .string()
-  // We only test the str for base64 if it's shorter than 1024 bytes, otherwise we've run into maximum
-  // stack size exceeded errors when trying to validate excessively long strings (such as contract bytecode).
-  .refine(str => str.length > 1024 || base64Regex.test(str), 'Not a valid base64 string')
-  .transform(data => Buffer.from(data, 'base64'));
+/** Schema for a buffer represented as a base64 string or a Buffer object. */
+export const bufferSchema: ZodFor<Buffer> = z.union([
+  // Serialization from base64 string.
+  z
+    .string()
+    // We only test the str for base64 if it's shorter than 1024 bytes, otherwise we've run into maximum
+    // stack size exceeded errors when trying to validate excessively long strings (such as contract bytecode).
+    .refine(str => str.length > 1024 || base64Regex.test(str), 'Not a valid base64 string')
+    .transform(data => Buffer.from(data, 'base64')),
+  // Serialization from Buffer-annotated object.
+  z
+    .object({
+      type: z.literal('Buffer'),
+      data: z.array(z.number().int().min(0).max(255)),
+    })
+    .transform(({ data }) => Buffer.from(data)),
+  // Serialization from Buffer
+  z.instanceof(Buffer),
+]);
 
 export class ZodNullableOptional<T extends ZodTypeAny> extends ZodOptional<T> {
   _isNullableOptional = true;
@@ -88,12 +100,13 @@ export function hexSchemaFor<TClass extends { fromString(str: string): any } | {
  */
 export function bufferSchemaFor<TClass extends { fromBuffer(buf: Buffer): any }>(
   klazz: TClass,
+  refinement?: (buf: Buffer) => boolean,
 ): ZodType<
   TClass extends { fromBuffer(buf: Buffer): infer TInstance } ? ToJsonIs<TInstance, Buffer> : never,
   any,
   string
 > {
-  return bufferSchema.transform(klazz.fromBuffer.bind(klazz));
+  return bufferSchema.refine(refinement ?? (() => true), 'Not a valid buffer').transform(klazz.fromBuffer.bind(klazz));
 }
 
 /** Creates a schema for a js Map type that matches the serialization used in jsonStringify. */

package/src/serialize/buffer_reader.ts

@@ -130,6 +130,11 @@ export class BufferReader {
     return result;
   }
 
+  /** Alias for readUInt256 */
+  public readBigInt(): bigint {
+    return this.readUInt256();
+  }
+
   /**
    * Reads a 16-bit unsigned integer from the buffer at the current index position.
    * Updates the index position by 2 bytes after reading the number.

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';
 
 /**

package/src/sleep/index.ts

@@ -73,3 +73,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/string/index.ts

@@ -1,3 +1,6 @@
+/** Parameterized hex string type for specific byte lengths */
+export type Hex<TByteLength extends number> = `0x${string}` & { readonly _length: TByteLength };
+
 export function hasHexPrefix(str: string): str is `0x${string}` {
   return str.startsWith('0x');
 }
@@ -39,5 +42,25 @@ export function isoDate(date?: Date) {
 }
 
 export function urlJoin(...args: string[]): string {
-  return args.map(arg => arg.replace(/\/+$/, '').replace(/^\/+/, '')).join('/');
+  const processed = [];
+  for (const arg of args) {
+    if (arg.length === 0) {
+      continue;
+    }
+
+    let start = 0;
+    let end = arg.length - 1;
+
+    while (start <= end && arg[start] === '/') {
+      start++;
+    }
+    while (end >= start && arg[end] === '/') {
+      end--;
+    }
+
+    if (start < end) {
+      processed.push(arg.slice(start, end + 1));
+    }
+  }
+  return processed.join('/');
 }

package/src/testing/files/index.ts

@@ -63,7 +63,7 @@ export function updateProtocolCircuitSampleInputs(circuitName: string, value: st
   logger(`Updated test data in ${targetFile} for ${circuitName}`);
 }
 
-function getPathToFile(targetFileFromRepoRoot: string) {
+export function getPathToFile(targetFileFromRepoRoot: string) {
   const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../../../../');
   if (!existsSync(join(repoRoot, 'CODEOWNERS'))) {
     throw new Error(`Path to repo root is incorrect (got ${repoRoot})`);

package/src/testing/formatting.ts

@@ -0,0 +1,3 @@
+export function toInlineStrArray(arr: { toString: () => string }[]): string {
+  return `[${arr.map(f => f.toString()).join(',')}]`;
+}

package/src/testing/index.ts

@@ -1,3 +1,4 @@
+export * from './formatting.js';
 export * from './snapshot_serializer.js';
 export * from './port_allocator.js';
 export * from './test_data.js';

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. */

package/src/trees/balanced_merkle_tree.ts

@@ -0,0 +1,84 @@
+import { pedersenHash as pedersenHashArray } from '@aztec/foundation/crypto/pedersen';
+import { poseidon2Hash } from '@aztec/foundation/crypto/poseidon';
+import { sha256Trunc } from '@aztec/foundation/crypto/sha256';
+
+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>;
+
+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);
+
+/**
+ * Computes the Merkle root with the provided leaves **synchronously**.
+ * This method uses a synchronous hash function (defaults to `sha256Trunc`).
+ *
+ * @throws If the number of leaves is not a power of two.
+ */
+export function computeBalancedMerkleTreeRoot(leaves: Buffer[], hasher = shaMerkleHash): Buffer {
+  const height = getTreeHeight(leaves);
+  let nodes = leaves.slice();
+
+  for (let i = 0; i < height; ++i) {
+    let j = 0;
+    for (; j < nodes.length / 2; ++j) {
+      const l = nodes[j * 2];
+      const r = nodes[j * 2 + 1];
+      nodes[j] = hasher(l, r);
+    }
+    nodes = nodes.slice(0, j);
+  }
+
+  return nodes[0];
+}
+
+/**
+ * Computes the Merkle root with the provided leaves **asynchronously**.
+ * This method uses an asynchronous hash function (defaults to `pedersenHash`).
+ *
+ * @throws If the number of leaves is not a power of two.
+ */
+export async function computeBalancedMerkleTreeRootAsync(
+  leaves: Buffer[],
+  hasher = poseidonMerkleHash,
+): Promise<Buffer> {
+  const height = getTreeHeight(leaves);
+  let nodes = leaves.slice();
+
+  for (let i = 0; i < height; ++i) {
+    let j = 0;
+    for (; j < nodes.length / 2; ++j) {
+      const l = nodes[j * 2];
+      const r = nodes[j * 2 + 1];
+      nodes[j] = await hasher(l, r);
+    }
+    nodes = nodes.slice(0, j);
+  }
+
+  return nodes[0];
+}
+
+function getTreeHeight(leaves: Buffer[]) {
+  if (leaves.length === 0) {
+    throw new Error('Cannot compute a Merkle root with no leaves');
+  }
+
+  const height = Math.log2(leaves.length);
+  if (!Number.isInteger(height)) {
+    throw new Error('Cannot compute a Merkle root with a non-power-of-two number of leaves');
+  }
+
+  return height;
+}

package/src/trees/index.ts

@@ -1,3 +1,4 @@
+export * from './balanced_merkle_tree.js';
 export * from './unbalanced_merkle_tree.js';
 export * from './unbalanced_tree_store.js';
 export * from './merkle_tree_calculator.js';