@aztec/foundation 0.0.1-commit.b6e433891 → 0.0.1-commit.b8a057fa

package/src/serialize/buffer_sink.ts

@@ -0,0 +1,350 @@
+/**
+ * A value that can be appended to a {@link BufferSink}. Mirrors `Bufferable`, but the object arm allows the
+ * optional-sink overload of `toBuffer` so a legacy `toBuffer(): Buffer` and a migrated `toBuffer(sink?)` both fit.
+ */
+export type Sinkable =
+  | boolean
+  | Buffer
+  | Uint8Array
+  | number
+  | bigint
+  | string
+  | { toBuffer(sink?: BufferSink): Buffer | void }
+  | Sinkable[];
+
+const DEFAULT_INITIAL_CAPACITY = 1024;
+const MASK_64 = (1n << 64n) - 1n;
+
+/**
+ * A growable, append-only binary sink backed by a single `ArrayBuffer`.
+ *
+ * It exists to replace the recursive `toBuffer()` chain — which allocates a `Buffer` at every node and
+ * `Buffer.concat`s at every level — with one buffer that the whole object graph streams into and that is sliced
+ * exactly once at the root. Encodings are big-endian, matching `serializeToBuffer` byte-for-byte.
+ *
+ * The migration contract is the optional-sink `toBuffer`:
+ *
+ * ```ts
+ * toBuffer(): Buffer;
+ * toBuffer(sink: BufferSink): void;
+ * toBuffer(sink?: BufferSink): Buffer | void {
+ *   if (!sink) return BufferSink.serialize(this); // own a sink, fill it, slice once
+ *   serializeToSink(sink, this.a, this.b, this.c); // stream into the caller's sink
+ * }
+ * ```
+ *
+ * When a sink is passed it writes and returns `undefined`; otherwise it returns its own buffer. Nodes that have
+ * not been migrated keep their plain `toBuffer(): Buffer` and are folded in via the return-value fallback in
+ * {@link serializeToSink}, so the tree stays valid at every step of an incremental migration.
+ *
+ * Performance note: bigints are written via `DataView.setBigUint64` limbs ({@link writeBigInt},
+ * {@link writeField}), NOT a per-byte shift loop. The limb form is ~16x faster than the legacy hex round-trip
+ * on field-heavy structures, and faster than the legacy path at every width — a naive per-byte shift loop is
+ * actually the slowest option, since each byte allocates a fresh BigInt. See the spike benchmark.
+ */
+export class BufferSink {
+  private buffer: Uint8Array;
+  private view: DataView;
+  private offset = 0;
+
+  constructor(initialCapacity: number = DEFAULT_INITIAL_CAPACITY) {
+    const ab = new ArrayBuffer(initialCapacity);
+    this.buffer = new Uint8Array(ab);
+    this.view = new DataView(ab);
+  }
+
+  /** Number of bytes written so far. */
+  public get length(): number {
+    return this.offset;
+  }
+
+  /**
+   * Serialize a migrated value into a fresh sink and return the single resulting buffer. This is the no-sink
+   * branch of every migrated `toBuffer`: one allocation, one slice, only at the root.
+   *
+   * @param obj - The value to serialize via its sink-aware `toBuffer`.
+   * @param initialCapacity - Optional size hint (e.g. from `getSize()`) to skip reallocations on hot paths.
+   */
+  public static serialize(obj: { toBuffer(sink: BufferSink): void }, initialCapacity?: number): Buffer {
+    const sink = new BufferSink(initialCapacity);
+    obj.toBuffer(sink);
+    return sink.toBuffer();
+  }
+
+  private ensure(extra: number): void {
+    const required = this.offset + extra;
+    if (required <= this.buffer.length) {
+      return;
+    }
+    let next = this.buffer.length * 2;
+    while (next < required) {
+      next *= 2;
+    }
+    const grown = new Uint8Array(next);
+    grown.set(this.buffer.subarray(0, this.offset));
+    this.buffer = grown;
+    this.view = new DataView(grown.buffer);
+  }
+
+  /** Append a single byte (0/1) for a boolean, matching `boolToBuffer`. */
+  public writeBool(value: boolean): void {
+    this.ensure(1);
+    this.buffer[this.offset++] = value ? 1 : 0;
+  }
+
+  /** Append an unsigned 8-bit integer. */
+  public writeUInt8(value: number): void {
+    this.ensure(1);
+    this.buffer[this.offset++] = value & 0xff;
+  }
+
+  /** Append a big-endian unsigned 16-bit integer. */
+  public writeUInt16(value: number): void {
+    this.ensure(2);
+    this.view.setUint16(this.offset, value, false);
+    this.offset += 2;
+  }
+
+  /** Append a big-endian unsigned 32-bit integer, matching `numToUInt32BE`. */
+  public writeNumber(value: number): void {
+    this.ensure(4);
+    this.view.setUint32(this.offset, value, false);
+    this.offset += 4;
+  }
+
+  /** Append a big-endian unsigned 64-bit integer, matching `bigintToUInt64BE`. */
+  public writeUInt64(value: bigint): void {
+    this.ensure(8);
+    this.view.setBigUint64(this.offset, value, false);
+    this.offset += 8;
+  }
+
+  /**
+   * Append a non-negative bigint as a big-endian unsigned integer of `width` bytes (default 32), matching
+   * `serializeBigInt` / `toBufferBE`. Every width is written limb-wise via `setBigUint64` rather than the
+   * legacy per-byte BigInt shift loop — that loop allocated a fresh BigInt per byte and benchmarked as the
+   * *slowest* option (slower even than the legacy hex round-trip); the limb form is faster at every width.
+   *
+   * The bulk of the value is written as 64-bit big-endian limbs from the least-significant tail upward, and
+   * a final `width % 8` (at most 7) high bytes that don't fill a whole limb are written individually. The
+   * common widths (8/16/32) are exact multiples of 8, so they take the pure-limb path with no remainder.
+   * `width === 32` keeps its own straight-line four-limb form (shared with {@link writeField}) since it is
+   * the `Fr`/`Fq`/Chonk-proof hot path and the unrolled body is marginally faster than the loop.
+   *
+   * @param value - The non-negative bigint to serialize.
+   * @param width - Output width in bytes.
+   */
+  public writeBigInt(value: bigint, width = 32): void {
+    if (value < 0n) {
+      throw new Error(`Cannot serialize negative bigint ${value}`);
+    }
+    this.ensure(width);
+    const o = this.offset;
+    if (width === 32) {
+      let x = value;
+      this.view.setBigUint64(o + 24, x & MASK_64, false);
+      x >>= 64n;
+      this.view.setBigUint64(o + 16, x & MASK_64, false);
+      x >>= 64n;
+      this.view.setBigUint64(o + 8, x & MASK_64, false);
+      x >>= 64n;
+      this.view.setBigUint64(o, x & MASK_64, false);
+      x >>= 64n;
+      if (x !== 0n) {
+        throw new Error(`BigInt ${value} does not fit into 32 bytes`);
+      }
+      this.offset += 32;
+      return;
+    }
+    let x = value;
+    let pos = o + width;
+    while (pos - 8 >= o) {
+      pos -= 8;
+      this.view.setBigUint64(pos, x & MASK_64, false);
+      x >>= 64n;
+    }
+    for (let i = pos - 1; i >= o; i--) {
+      this.buffer[i] = Number(x & 0xffn);
+      x >>= 8n;
+    }
+    if (x !== 0n) {
+      throw new Error(`BigInt ${value} does not fit into ${width} bytes`);
+    }
+    this.offset += width;
+  }
+
+  /**
+   * Append a 32-byte (256-bit) big-endian non-negative bigint. Specialized form of {@link writeBigInt}
+   * with no width parameter and no width-branch, so V8 can inline the four `setBigUint64` limb writes
+   * without the wider branchy form's instability. This is the Fr/Fq leaf hot path; prefer it over
+   * `writeBigInt(value, 32)` in callers that always serialize 32-byte fields.
+   */
+  public writeField(value: bigint): void {
+    if (value < 0n) {
+      throw new Error(`Cannot serialize negative bigint ${value}`);
+    }
+    this.ensure(32);
+    const o = this.offset;
+    let x = value;
+    this.view.setBigUint64(o + 24, x & MASK_64, false);
+    x >>= 64n;
+    this.view.setBigUint64(o + 16, x & MASK_64, false);
+    x >>= 64n;
+    this.view.setBigUint64(o + 8, x & MASK_64, false);
+    x >>= 64n;
+    this.view.setBigUint64(o, x & MASK_64, false);
+    if (x >> 64n !== 0n) {
+      throw new Error(`BigInt ${value} does not fit into 32 bytes`);
+    }
+    this.offset = o + 32;
+  }
+
+  /**
+   * Append an array of field elements (or any objects exposing `toBigInt(): bigint`) as a contiguous
+   * sequence of 32-byte big-endian limbs. Iterates inline — no per-element `toBuffer` dispatch and no
+   * per-element function-call indirection through the generic sinkable dispatcher. Use this in classes
+   * that hold large flat field arrays (e.g. the 1632-element ChonkProof field list).
+   */
+  public writeFields(fields: ReadonlyArray<{ toBigInt(): bigint }>): void {
+    this.ensure(32 * fields.length);
+    for (let i = 0, n = fields.length; i < n; i++) {
+      const value = fields[i].toBigInt();
+      if (value < 0n) {
+        throw new Error(`Cannot serialize negative bigint ${value}`);
+      }
+      const o = this.offset;
+      let x = value;
+      this.view.setBigUint64(o + 24, x & MASK_64, false);
+      x >>= 64n;
+      this.view.setBigUint64(o + 16, x & MASK_64, false);
+      x >>= 64n;
+      this.view.setBigUint64(o + 8, x & MASK_64, false);
+      x >>= 64n;
+      this.view.setBigUint64(o, x & MASK_64, false);
+      if (x >> 64n !== 0n) {
+        throw new Error(`BigInt ${value} does not fit into 32 bytes`);
+      }
+      this.offset = o + 32;
+    }
+  }
+
+  /** Append raw bytes verbatim (no length prefix), matching how a `Buffer`/`Uint8Array` is serialized inline. */
+  public writeBytes(bytes: Uint8Array): void {
+    this.ensure(bytes.length);
+    this.buffer.set(bytes, this.offset);
+    this.offset += bytes.length;
+  }
+
+  /** Append a string as a 4-byte big-endian length prefix followed by its UTF-8 bytes, matching the string case. */
+  public writeString(value: string): void {
+    const bytes = Buffer.from(value);
+    this.writeNumber(bytes.length);
+    this.writeBytes(bytes);
+  }
+
+  /**
+   * Reset the write cursor without releasing the backing buffer. Lets the same sink be reused across many
+   * serializations without reallocating — the per-call cost drops to the bytes written (no `new ArrayBuffer`).
+   * Any `Buffer` previously returned by {@link toBuffer} is a fresh copy and remains valid; any view from
+   * {@link asUint8Array} aliases the buffer and is invalidated.
+   */
+  public reset(): void {
+    this.offset = 0;
+  }
+
+  /** Copy the written region into a freshly allocated `Buffer`. The single allocation of the whole serialization. */
+  public toBuffer(): Buffer {
+    return Buffer.from(this.buffer.subarray(0, this.offset));
+  }
+
+  /** A zero-copy view of the written region. Valid only until the next write (which may reallocate). */
+  public asUint8Array(): Uint8Array {
+    return this.buffer.subarray(0, this.offset);
+  }
+}
+
+/**
+ * Streaming counterpart to `serializeToBufferArray`: walk a list of {@link Sinkable}s and append each to the sink.
+ * Dispatch matches `serializeToBufferArray` byte-for-byte. An object is serialized via `obj.toBuffer(sink)`; a
+ * migrated node writes into the sink and returns `undefined`, while a not-yet-migrated node ignores the argument
+ * and returns its `Buffer`, which we copy in. That return-value fallback is what makes the migration incremental.
+ *
+ * Dispatch is hot-pathed for the common case of objects exposing `toBuffer` (Fr/Fq and every other migrated leaf),
+ * and arrays recurse via an inner-array helper to avoid the per-call rest-args allocation that a spread-recurse
+ * would force on large flat arrays like the 1632-element ChonkProof field list.
+ *
+ * @param sink - The destination sink.
+ * @param objs - The values to serialize, in order.
+ */
+export function serializeToSink(sink: BufferSink, ...objs: Sinkable[]): void {
+  serializeArrayToSinkInner(sink, objs);
+}
+
+function serializeArrayToSinkInner(sink: BufferSink, objs: Sinkable[]): void {
+  for (let i = 0, n = objs.length; i < n; i++) {
+    serializeOneToSink(sink, objs[i]);
+  }
+}
+
+function serializeOneToSink(sink: BufferSink, obj: Sinkable): void {
+  if (typeof obj === 'object' && obj !== null) {
+    // Hot path: migrated nodes (anything implementing toBuffer, including Fr/Fq via BaseField). This branch
+    // is taken for the vast majority of recursive serialization, so it is checked before the typeof primitives.
+    if ((obj as any).toBuffer !== undefined) {
+      const ret = (obj as { toBuffer(sink: BufferSink): Buffer | void }).toBuffer(sink);
+      if (ret !== undefined) {
+        sink.writeBytes(ret);
+      }
+      return;
+    }
+    if (Array.isArray(obj)) {
+      serializeArrayToSinkInner(sink, obj);
+      return;
+    }
+    if (Buffer.isBuffer(obj) || obj instanceof Uint8Array) {
+      sink.writeBytes(obj);
+      return;
+    }
+    throw new Error(`Cannot serialize input to sink: ${typeof obj} ${(obj as any).constructor?.name}`);
+  }
+  if (typeof obj === 'boolean') {
+    sink.writeBool(obj);
+  } else if (typeof obj === 'bigint') {
+    sink.writeBigInt(obj);
+  } else if (typeof obj === 'number') {
+    sink.writeNumber(obj);
+  } else if (typeof obj === 'string') {
+    sink.writeString(obj);
+  } else {
+    throw new Error(`Cannot serialize input to sink: ${typeof obj}`);
+  }
+}
+
+/**
+ * Streaming counterpart to `serializeArrayOfBufferableToVector`: write a length prefix (1 or 4 bytes) giving the
+ * number of serialized elements, then each element. Byte-identical to the buffer version.
+ *
+ * @param sink - The destination sink.
+ * @param objs - The vector elements.
+ * @param prefixLength - Width of the count prefix in bytes (1 or 4).
+ */
+export function serializeArrayToSink(sink: BufferSink, objs: Sinkable[], prefixLength = 4): void {
+  const count = countSinkables(objs);
+  if (prefixLength === 1) {
+    sink.writeUInt8(count);
+  } else if (prefixLength === 4) {
+    sink.writeNumber(count);
+  } else {
+    throw new Error(`Unsupported prefix length. Got ${prefixLength}, expected 1 or 4`);
+  }
+  serializeArrayToSinkInner(sink, objs);
+}
+
+/** Count how many top-level buffers `serializeToBufferArray` would emit, flattening nested arrays as it does. */
+function countSinkables(objs: Sinkable[]): number {
+  let count = 0;
+  for (const obj of objs) {
+    count += Array.isArray(obj) ? countSinkables(obj) : 1;
+  }
+  return count;
+}

package/src/serialize/index.ts

@@ -1,5 +1,6 @@
 export * from './free_funcs.js';
 export * from './buffer_reader.js';
+export * from './buffer_sink.js';
 export * from './field_reader.js';
 export * from './types.js';
 export * from './serialize.js';

package/src/string/index.ts

@@ -58,7 +58,7 @@ export function urlJoin(...args: string[]): string {
       end--;
     }
 
-    if (start < end) {
+    if (start <= end) {
       processed.push(arg.slice(start, end + 1));
     }
   }

package/src/testing/files/index.ts

@@ -52,8 +52,7 @@ export function updateInlineTestData(targetFileFromRepoRoot: string, itemName: s
 /**
  * Updates the sample Prover.toml files in noir-projects/noir-protocol-circuits/crates/.
  * @remarks Requires AZTEC_GENERATE_TEST_DATA=1 to be set
- * To re-gen, run 'AZTEC_GENERATE_TEST_DATA=1 FAKE_PROOFS=1 yarn test:e2e full.test'
- * To re-gen public base only, run 'AZTEC_GENERATE_TEST_DATA=1 yarn workspace @aztec/prover-client test orchestrator_public_functions'
+ * To re-gen, run 'AZTEC_GENERATE_TEST_DATA=1 FAKE_PROOFS=1 yarn test:e2e e2e_prover/full.test'
  */
 export function updateProtocolCircuitSampleInputs(circuitName: string, value: string) {
   const logger = createConsoleLogger('aztec:testing:test_data');

package/src/timer/index.ts

@@ -1,4 +1,4 @@
 export * from './date.js';
 export { elapsed, elapsedSync } from './elapsed.js';
-export { TimeoutTask, executeTimeout, timeoutPromise } from './timeout.js';
+export { TimeoutTask, execWithSignal, executeTimeout, timeoutPromise } from './timeout.js';
 export { Timer } from './timer.js';

package/src/timer/timeout.ts

@@ -92,6 +92,37 @@ export async function executeTimeout<T>(
   return await task.exec();
 }
 
+function defaultSignalError(signal: AbortSignal) {
+  if (signal.reason instanceof Error) {
+    return signal.reason;
+  }
+
+  return new Error(signal.reason ? String(signal.reason) : 'Operation aborted');
+}
+
+/** Executes a function until it completes or the given signal aborts. */
+export async function execWithSignal<T>(
+  fn: (signal: AbortSignal) => Promise<T>,
+  signal: AbortSignal,
+  errorFn: (signal: AbortSignal) => Error = defaultSignalError,
+) {
+  if (signal.aborted) {
+    throw errorFn(signal);
+  }
+
+  const abortPromise = promiseWithResolvers<never>();
+  const abortListener = () => abortPromise.reject(errorFn(signal));
+  signal.addEventListener('abort', abortListener, { once: true });
+
+  try {
+    return await Promise.race<T>([fn(signal), abortPromise.promise]);
+  } finally {
+    if (abortListener) {
+      signal.removeEventListener('abort', abortListener);
+    }
+  }
+}
+
 /** Returns a promise that rejects after the given timeout */
 export function timeoutPromise(timeoutMs: number, errorMessage?: string) {
   const promise = promiseWithResolvers<never>();

package/src/transport/dispatch/create_dispatch_proxy.ts

@@ -2,7 +2,17 @@ import { EventEmitter } from 'events';
 
 import { type TransferDescriptor, isTransferDescriptor } from '../interface/transferable.js';
 import type { TransportClient } from '../transport_client.js';
-import type { DispatchMsg } from './create_dispatch_fn.js';
+
+/**
+ * Represents a message object for dispatching function calls.
+ * Contains the function name ('fn') and an array of arguments ('args') required to call the target method.
+ */
+export interface DispatchMsg {
+  /** Name of the target method to be called. */
+  fn: string;
+  /** An array of arguments to be passed to the target method. */
+  args: any[];
+}
 
 /**
  * FilterOutAttributes type filters out all non-method properties of an object, leaving only the attributes

package/src/transport/index.ts

@@ -1,4 +1,3 @@
-export * from './dispatch/create_dispatch_fn.js';
 export * from './dispatch/create_dispatch_proxy.js';
 export * from './dispatch/messages.js';
 export * from './interface/connector.js';

package/src/trees/balanced_merkle_tree_root.ts

@@ -1,10 +1,7 @@
-import { poseidonMerkleHash, shaMerkleHash } from './hasher.js';
+import { 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`).
@@ -36,7 +33,7 @@ export function computeBalancedMerkleTreeRoot(leaves: Buffer[], hasher = shaMerk
  */
 export async function computeBalancedMerkleTreeRootAsync(
   leaves: Buffer[],
-  hasher = poseidonMerkleHash,
+  hasher: (left: Buffer, right: Buffer) => Promise<Buffer<ArrayBuffer>>,
 ): Promise<Buffer> {
   const height = getTreeHeight(leaves);
   let nodes = leaves.slice();

package/src/trees/hasher.ts

@@ -1,4 +1,4 @@
-import { poseidon2Hash } from '../crypto/poseidon/index.js';
+import { poseidon2HashWithSeparator } from '../crypto/poseidon/index.js';
 import { sha256Trunc } from '../crypto/sha256/index.js';
 
 /**
@@ -44,5 +44,8 @@ export interface AsyncHasher {
 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>;
+/** Creates a poseidon2 merkle hasher with the given domain separator. */
+export const makePoseidonMerkleHash =
+  (separator: number): AsyncHasher['hash'] =>
+  async (left: Buffer, right: Buffer) =>
+    (await poseidon2HashWithSeparator([left, right], separator)).toBuffer() as Buffer<ArrayBuffer>;

package/src/trees/indexed_merkle_tree_calculator.ts

@@ -40,7 +40,11 @@ export class IndexedMerkleTreeCalculator<T extends IndexedTreeLeafPreimage, N ex
     }
     const sorted = values
       .map((v, i) => ({ value: v, index: i }))
-      .sort((a, b) => Number(toBigIntBE(b.value) - toBigIntBE(a.value)));
+      .sort((a, b): -1 | 0 | 1 => {
+        const aBigInt = toBigIntBE(a.value);
+        const bBigInt = toBigIntBE(b.value);
+        return aBigInt < bBigInt ? 1 : aBigInt > bBigInt ? -1 : 0;
+      });
     const indexedLeaves = sorted.map((item, i) => ({
       leaf: this.factory.fromBuffer(
         Buffer.concat([

package/src/trees/membership_witness.ts

@@ -38,14 +38,6 @@ 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,8 +1,7 @@
-import { poseidon2Hash } from '@aztec/foundation/crypto/poseidon';
-
-import type { AsyncHasher } from './hasher.js';
 import { MerkleTree } from './merkle_tree.js';
 
+type MerkleHashFn = (left: Buffer, right: Buffer) => Promise<Buffer<ArrayBuffer>>;
+
 /**
  * Merkle tree calculator.
  */
@@ -10,17 +9,12 @@ export class MerkleTreeCalculator {
   private constructor(
     private height: number,
     private zeroHashes: Buffer[],
-    private hasher: AsyncHasher['hash'],
+    private hasher: MerkleHashFn,
   ) {
     this.hasher = hasher;
   }
 
-  static async create(
-    height: number,
-    zeroLeaf: Buffer = Buffer.alloc(32),
-    hasher = async (left: Buffer, right: Buffer) =>
-      (await poseidon2Hash([left, right])).toBuffer() as Buffer<ArrayBuffer>,
-  ) {
+  static async create(height: number, zeroLeaf: Buffer = Buffer.alloc(32), hasher: MerkleHashFn) {
     const zeroHashes = [zeroLeaf];
     for (let i = 0; i < height; i++) {
       zeroHashes.push((await hasher(zeroHashes[i], zeroHashes[i])) as Buffer<ArrayBuffer>);

package/src/trees/sibling_path.ts

@@ -1,5 +1,6 @@
+import { z } from 'zod';
+
 import { makeTuple } from '../array/array.js';
-import { poseidon2Hash } from '../crypto/poseidon/index.js';
 import { Fr } from '../curves/bn254/index.js';
 import { schemas } from '../schemas/index.js';
 import {
@@ -43,10 +44,14 @@ export class SiblingPath<N extends number> {
   }
 
   static schemaFor<N extends number>(size: N) {
-    return schemas.Buffer.transform(b => SiblingPath.fromBuffer(b) as SiblingPath<N>).refine(
-      path => path.pathSize === size,
-      path => ({ message: `Expected sibling path size ${size} but got ${path.pathSize}` }),
-    );
+    return schemas.Buffer.transform(b => SiblingPath.fromBuffer(b) as SiblingPath<N>).superRefine((path, ctx) => {
+      if (path.pathSize !== size) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Expected sibling path size ${size} but got ${path.pathSize}`,
+        });
+      }
+    });
   }
 
   toJSON() {
@@ -172,7 +177,7 @@ export async function computeRootFromSiblingPath(
   leaf: Buffer,
   siblingPath: Buffer[],
   index: number,
-  hasher = async (left: Buffer, right: Buffer) => (await poseidon2Hash([left, right])).toBuffer(),
+  hasher: (left: Buffer, right: Buffer) => Promise<Buffer>,
 ) {
   let result = leaf;
   for (const sibling of siblingPath) {

package/src/trees/unbalanced_merkle_tree_root.ts

@@ -1,12 +1,9 @@
 import { computeBalancedMerkleTreeRoot, computeBalancedMerkleTreeRootAsync } from './balanced_merkle_tree_root.js';
-import { poseidonMerkleHash, shaMerkleHash } from './hasher.js';
+import { 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);
 
 /**
@@ -67,7 +64,7 @@ export function computeUnbalancedMerkleTreeRoot(
 
 export async function computeUnbalancedMerkleTreeRootAsync(
   leaves: Buffer[],
-  hasher = poseidonMerkleHash,
+  hasher: (left: Uint8Array, right: Uint8Array) => Promise<Buffer<ArrayBuffer>>,
   emptyRoot = Buffer.alloc(32),
 ): Promise<Buffer> {
   if (!leaves.length) {

package/src/types/index.ts

@@ -29,11 +29,58 @@ export function isErrorClass<T extends Error>(value: unknown, errorClass: new (.
   return value instanceof errorClass || (value instanceof Error && value.name === errorClass.name);
 }
 
+const MAX_ERR_DEPTH = 10;
+
+/** Returns the first error in the cause chain matching the given error class. */
+export function getErrorCause<T extends Error>(err: unknown, errorClass: new (...args: any[]) => T): T | undefined {
+  let current = err;
+  for (let i = 0; current !== undefined && current !== null && i < MAX_ERR_DEPTH; i++) {
+    if (isErrorClass(current, errorClass)) {
+      return current;
+    }
+
+    if (typeof current === 'object' && Object.hasOwn(current, 'cause')) {
+      current = (current as { cause: unknown }).cause;
+    } else {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
 /** Resolves a record-like type. Lifted from viem. */
 export type Prettify<T> = {
   [K in keyof T]: T[K];
 } & {};
 
+/** Returns a type T based on a flag: T if true, undefined if false, optional otherwise. */
+export type DefineIfFlag<Opts, Key extends keyof Opts, T> = Opts extends {
+  [K in Key]: true;
+}
+  ? T
+  : Opts extends { [K in Key]: false }
+    ? never
+    : Opts extends { [K in Key]?: boolean }
+      ? T | undefined
+      : never;
+
+/** Returns a type with fields conditionally required based on a flag */
+export type PickIfFlag<
+  OptsSchema,
+  Opts extends OptsSchema,
+  Key extends keyof OptsSchema,
+  Field extends object,
+> = Opts extends { [K in Key]: true }
+  ? Field
+  : Opts extends { [K in Key]: false }
+    ? {}
+    : Opts extends { [K in Key]?: boolean }
+      ? Partial<Field>
+      : {};
+
+/** Picks only the defined (non-undefined) properties of a type. */
+export type PickDefined<T> = Prettify<Pick<T, { [K in keyof T]: T[K] extends undefined ? never : K }[keyof T]>>;
+
 /**
  * Type-safe Event Emitter type
  * @example