@aztec/foundation 0.0.1-commit.b655e406 → 0.0.1-commit.c2595eba

package/src/log/pino-logger.ts

@@ -1,19 +1,62 @@
-import { createColors, isColorSupported } from 'colorette';
+import { type Color, createColors, isColorSupported } from 'colorette';
 import isNode from 'detect-node';
 import { pino, symbols } from 'pino';
 import type { Writable } from 'stream';
 import { inspect } from 'util';
 
 import { compactArray } from '../collection/array.js';
-import { type EnvVar, parseBooleanEnv } from '../config/index.js';
+import type { EnvVar } from '../config/index.js';
+import { parseBooleanEnv } from '../config/parse-env.js';
 import { GoogleCloudLoggerConfig } from './gcloud-logger-config.js';
 import { getLogLevelFromFilters, parseEnv } from './log-filters.js';
 import type { LogLevel } from './log-levels.js';
 import type { LogData, LogFn } from './log_fn.js';
 
-export function createLogger(module: string): Logger {
-  module = logNameHandlers.reduce((moduleName, handler) => handler(moduleName), module.replace(/^aztec:/, ''));
-  const pinoLogger = logger.child({ module }, { level: getLogLevelFromFilters(logFilters, module) });
+/** Optional bindings to pass to createLogger for additional context. */
+export type LoggerBindings = {
+  /** Actor label shown in logs (e.g., 'MAIN', 'prover-node'). */
+  actor?: string;
+  /** Instance identifier for distinguishing multiple instances of the same component. */
+  instanceId?: string;
+};
+
+// Allow global hooks for providing default bindings.
+// Used by withLoggerBindings in pino-logger-server to propagate bindings via AsyncLocalStorage.
+type LogBindingsHandler = () => LoggerBindings | undefined;
+const logBindingsHandlers: LogBindingsHandler[] = [];
+
+export function addLogBindingsHandler(handler: LogBindingsHandler): void {
+  logBindingsHandlers.push(handler);
+}
+
+export function removeLogBindingsHandler(handler: LogBindingsHandler) {
+  const index = logBindingsHandlers.indexOf(handler);
+  if (index !== -1) {
+    logBindingsHandlers.splice(index, 1);
+  }
+}
+
+function getBindingsFromHandlers(): LoggerBindings | undefined {
+  for (const handler of logBindingsHandlers) {
+    const bindings = handler();
+    if (bindings) {
+      return bindings;
+    }
+  }
+  return undefined;
+}
+
+export function createLogger(module: string, bindings?: LoggerBindings): Logger {
+  module = module.replace(/^aztec:/, '');
+
+  const resolvedBindings = { ...getBindingsFromHandlers(), ...bindings };
+  const actor = resolvedBindings?.actor;
+  const instanceId = resolvedBindings?.instanceId;
+
+  const pinoLogger = logger.child(
+    { module, ...(actor && { actor }), ...(instanceId && { instanceId }) },
+    { level: getLogLevelFromFilters(logFilters, module) },
+  );
 
   // We check manually for isLevelEnabled to avoid calling processLogData unnecessarily.
   // Note that isLevelEnabled is missing from the browser version of pino.
@@ -43,11 +86,24 @@ export function createLogger(module: string): Logger {
     isLevelEnabled: (level: LogLevel) => isLevelEnabled(pinoLogger, level),
     /** Module name for the logger. */
     module,
-    /** Creates another logger by extending this logger module name. */
-    createChild: (childModule: string) => createLogger(`${module}:${childModule}`),
+    /** Creates another logger by extending this logger module name and preserving bindings. */
+    createChild: (childModule: string) => createLogger(`${module}:${childModule}`, { actor, instanceId }),
+    /** Returns the bindings (actor, instanceId) for this logger. */
+    getBindings: () => ({ actor, instanceId }),
   };
 }
 
+/**
+ * Returns a logger for the given module. If loggerOrBindings is already a Logger, returns it directly.
+ * Otherwise, creates a new logger with the given module name and bindings.
+ */
+export function resolveLogger(module: string, loggerOrBindings?: Logger | LoggerBindings): Logger {
+  if (loggerOrBindings && 'info' in loggerOrBindings) {
+    return loggerOrBindings as Logger;
+  }
+  return createLogger(module, loggerOrBindings);
+}
+
 // Allow global hooks for processing log data.
 // Used for injecting OTEL trace_id in telemetry client.
 type LogDataHandler = (data: LogData) => LogData;
@@ -61,31 +117,6 @@ function processLogData(data: LogData): LogData {
   return logDataHandlers.reduce((accum, handler) => handler(accum), data);
 }
 
-// Allow global hooks for tweaking module names.
-// Used in tests to add a uid to modules, so we can differentiate multiple nodes in the same process.
-type LogNameHandler = (module: string) => string;
-const logNameHandlers: LogNameHandler[] = [];
-
-export function addLogNameHandler(handler: LogNameHandler): void {
-  logNameHandlers.push(handler);
-}
-
-export function removeLogNameHandler(handler: LogNameHandler) {
-  const index = logNameHandlers.indexOf(handler);
-  if (index !== -1) {
-    logNameHandlers.splice(index, 1);
-  }
-}
-
-/** Creates all loggers within the given callback with the suffix appended to the module name. */
-export async function withLogNameSuffix<T>(suffix: string, callback: () => Promise<T>): Promise<T> {
-  const logNameHandler = (module: string) => `${module}:${suffix}`;
-  addLogNameHandler(logNameHandler);
-  const result = await callback();
-  removeLogNameHandler(logNameHandler);
-  return result;
-}
-
 // Patch isLevelEnabled missing from pino/browser.
 function isLevelEnabled(logger: pino.Logger<'verbose', boolean>, level: LogLevel): boolean {
   return typeof logger.isLevelEnabled === 'function'
@@ -145,22 +176,90 @@ export const levels = {
 // Transport options for pretty logging to stderr via pino-pretty.
 const colorEnv = process.env['FORCE_COLOR' satisfies EnvVar];
 const useColor = colorEnv === undefined ? isColorSupported : parseBooleanEnv(colorEnv);
-const { bold, reset } = createColors({ useColor });
-export const pinoPrettyOpts = {
+const { bold, reset, cyan, magenta, yellow, blue, green, magentaBright, yellowBright, blueBright, greenBright } =
+  createColors({ useColor });
+
+// Per-actor coloring: each unique actor gets a different color for easier visual distinction.
+// Disabled when LOG_NO_COLOR_PER_ACTOR is set to a truthy value.
+const useColorPerActor = useColor && !parseBooleanEnv(process.env['LOG_NO_COLOR_PER_ACTOR' satisfies EnvVar]);
+const actorColors: Color[] = [yellow, magenta, blue, green, magentaBright, yellowBright, blueBright, greenBright];
+const actorColorMap = new Map<string, Color>();
+let nextColorIndex = 0;
+
+/** Returns the color function assigned to a given actor, assigning a new one if needed. */
+export function getActorColor(actor: string): Color {
+  let color = actorColorMap.get(actor);
+  if (!color) {
+    color = actorColors[nextColorIndex % actorColors.length];
+    actorColorMap.set(actor, color);
+    nextColorIndex++;
+  }
+  return color;
+}
+
+/** Resets the actor-to-color mapping. Useful for testing. */
+export function resetActorColors(): void {
+  actorColorMap.clear();
+  nextColorIndex = 0;
+}
+
+// String template for messageFormat (used in worker threads and when per-actor coloring is disabled).
+const messageFormatString = `${bold('{module}')}{if actor} ${cyan('{actor}')}{end}{if instanceId} ${reset(cyan('{instanceId}'))}{end} ${reset('{msg}')}`;
+
+// Function for messageFormat when per-actor coloring is enabled (can only be used in-process, not worker threads).
+type LogObject = { actor?: string; module?: string; instanceId?: string; msg?: string };
+
+/** Formats a log message with per-actor coloring. Actor, module, and instanceId share the same color. */
+export function formatLogMessage(log: LogObject, messageKey: string): string {
+  const actor = log.actor;
+  const module = log.module ?? '';
+  const instanceId = log.instanceId;
+  const msg = log[messageKey as keyof LogObject] ?? '';
+
+  // Use actor color for actor, module, and instanceId when actor is present
+  const color = actor ? getActorColor(actor) : cyan;
+
+  let result = bold(color(module));
+  if (actor) {
+    result += ' ' + color(actor);
+  }
+  if (instanceId) {
+    result += ' ' + reset(color(instanceId));
+  }
+  result += ' ' + reset(String(msg));
+  return result;
+}
+
+// Base options for pino-pretty (shared between transport and direct use).
+const pinoPrettyBaseOpts = {
   destination: 2,
   sync: true,
   colorize: useColor,
-  ignore: 'module,pid,hostname,trace_id,span_id,trace_flags,severity',
-  messageFormat: `${bold('{module}')} ${reset('{msg}')}`,
+  ignore: 'module,actor,instanceId,pid,hostname,trace_id,span_id,trace_flags,severity',
   customLevels: 'fatal:60,error:50,warn:40,info:30,verbose:25,debug:20,trace:10',
   customColors: 'fatal:bgRed,error:red,warn:yellow,info:green,verbose:magenta,debug:blue,trace:gray',
   minimumLevel: 'trace' as const,
   singleLine: !parseBooleanEnv(process.env['LOG_MULTILINE' satisfies EnvVar]),
 };
 
+/**
+ * Pino-pretty options for direct use (e.g., jest/setup.mjs).
+ * Includes function-based messageFormat for per-actor coloring when enabled.
+ */
+export const pinoPrettyOpts = {
+  ...pinoPrettyBaseOpts,
+  messageFormat: useColorPerActor ? formatLogMessage : messageFormatString,
+};
+
+// Transport options use string template only (functions can't be serialized to worker threads).
+const prettyTransportOpts = {
+  ...pinoPrettyBaseOpts,
+  messageFormat: messageFormatString,
+};
+
 const prettyTransport: pino.TransportTargetOptions = {
   target: 'pino-pretty',
-  options: pinoPrettyOpts,
+  options: prettyTransportOpts,
   level: 'trace',
 };
 
@@ -261,6 +360,8 @@ export type Logger = { [K in LogLevel]: LogFn } & { /** Error log function */ er
   isLevelEnabled: (level: LogLevel) => boolean;
   module: string;
   createChild: (childModule: string) => Logger;
+  /** Returns the bindings (actor, instanceId) for this logger. */
+  getBindings: () => LoggerBindings;
 };
 
 /**

package/src/queue/semaphore.ts

@@ -1,5 +1,10 @@
 import { FifoMemoryQueue } from './fifo_memory_queue.js';
 
+export interface ISemaphore {
+  acquire(): Promise<void>;
+  release(): void;
+}
+
 /**
  * Allows the acquiring of up to `size` tokens before calls to acquire block, waiting for a call to release().
  */

package/src/retry/index.ts

@@ -103,3 +103,21 @@ export async function retryUntil<T>(
     }
   }
 }
+
+/**
+ * Convenience wrapper around retryUntil with fast polling for tests.
+ * Uses 10s timeout and 100ms polling interval by default.
+ *
+ * @param fn - The function to retry until it returns a truthy value.
+ * @param name - Description of what we're waiting for (for error messages).
+ * @param timeout - Optional timeout in seconds. Defaults to 10s.
+ * @param interval - Optional interval in seconds. Defaults to 0.1s (100ms).
+ */
+export function retryFastUntil<T>(
+  fn: () => (T | undefined) | Promise<T | undefined>,
+  name = '',
+  timeout = 10,
+  interval = 0.1,
+) {
+  return retryUntil(fn, name, timeout, interval);
+}

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

@@ -224,15 +224,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 +351,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 +364,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';
 
 /**

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/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/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_root.ts

@@ -0,0 +1,68 @@
+import { poseidonMerkleHash, shaMerkleHash } from './hasher.js';
+
+export const computeBalancedShaRoot = (leaves: Buffer[]) => computeBalancedMerkleTreeRoot(leaves);
+
+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 `poseidon2Hash`).
+ *
+ * @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/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,5 +1,4 @@
-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';
@@ -9,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));
   }