@aztec/foundation 0.0.1-commit.993d240 → 0.0.1-commit.9a89641

package/src/config/network_name.ts

@@ -1,6 +1,6 @@
 export type NetworkNames =
   | 'local'
-  | 'staging-public'
+  | 'staging'
   | 'testnet'
   | 'mainnet'
   | 'next-net'
@@ -11,7 +11,7 @@ export function getActiveNetworkName(name?: string): NetworkNames {
   const network = name || process.env.NETWORK;
   if (!network || network === '' || network === 'local') {
     return 'local';
-  } else if (network === 'staging-public') {
+  } else if (network === 'staging') {
     return network;
   } else if (network === 'testnet' || network === 'alpha-testnet') {
     return 'testnet';

package/src/crypto/bls/bn254_keystore.ts

@@ -1,7 +1,8 @@
 import { randomBytes } from '@aztec/foundation/crypto/random';
 
-import { createCipheriv, createDecipheriv, createHash, pbkdf2Sync, randomUUID } from 'crypto';
+import { createCipheriv, createDecipheriv, createHash, pbkdf2, pbkdf2Sync, randomUUID } from 'crypto';
 import { readFileSync } from 'fs';
+import { promisify } from 'util';
 import { z } from 'zod';
 
 /**
@@ -100,24 +101,15 @@ export interface Bn254KeystoreInterface {
   version: number;
 }
 
-/**
- * Creates a BN254 keystore object for a BN254 BLS private key.
- *
- * Uses PBKDF2 with SHA-256 for key derivation and AES-128-CTR for encryption,
- * following the EIP-2335 specification format.
- *
- * @param password - Password for encrypting the private key
- * @param privateKeyHex - Private key as 0x-prefixed hex string (32 bytes)
- * @param pubkeyHex - Public key as hex string (compressed or uncompressed)
- * @param derivationPath - BIP-44 style derivation path (e.g., "m/12381/3600/0/0/0")
- * @returns BN254 keystore object ready to be serialized to JSON
- * @throws Error if private key is not 32-byte hex
- */
-export function createBn254Keystore(
-  password: string,
+const pbkdf2Async = promisify(pbkdf2);
+
+function createBn254KeystoreFromDerivedKey(
   privateKeyHex: string,
   pubkeyHex: string,
   derivationPath: string,
+  salt: Buffer,
+  iv: Buffer,
+  dk: Buffer,
 ): Bn254Keystore {
   const ensureHex = (hex: string) => hex.replace(/^0x/i, '');
   const privHex = ensureHex(privateKeyHex);
@@ -125,11 +117,7 @@ export function createBn254Keystore(
     throw new Error('BLS private key must be 32-byte hex');
   }
 
-  const salt = randomBytes(32);
-  const iv = randomBytes(16);
-  const dk = pbkdf2Sync(Buffer.from(password.normalize('NFKD'), 'utf8'), salt, 262144, 32, 'sha256');
   const cipherKey = dk.subarray(0, 16);
-
   const cipher = createCipheriv('aes-128-ctr', cipherKey, iv);
   const plaintext = Buffer.from(privHex, 'hex');
   const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
@@ -166,6 +154,31 @@ export function createBn254Keystore(
   };
 }
 
+/**
+ * Creates a BN254 keystore object for a BN254 BLS private key.
+ *
+ * Uses PBKDF2 with SHA-256 for key derivation and AES-128-CTR for encryption,
+ * following the EIP-2335 specification format.
+ *
+ * @param password - Password for encrypting the private key
+ * @param privateKeyHex - Private key as 0x-prefixed hex string (32 bytes)
+ * @param pubkeyHex - Public key as hex string (compressed or uncompressed)
+ * @param derivationPath - BIP-44 style derivation path (e.g., "m/12381/3600/0/0/0")
+ * @returns BN254 keystore object ready to be serialized to JSON
+ * @throws Error if private key is not 32-byte hex
+ */
+export async function createBn254Keystore(
+  password: string,
+  privateKeyHex: string,
+  pubkeyHex: string,
+  derivationPath: string,
+): Promise<Bn254Keystore> {
+  const salt = randomBytes(32);
+  const iv = randomBytes(16);
+  const dk = await pbkdf2Async(Buffer.from(password.normalize('NFKD'), 'utf8'), salt, 262144, 32, 'sha256');
+  return createBn254KeystoreFromDerivedKey(privateKeyHex, pubkeyHex, derivationPath, salt, iv, dk);
+}
+
 /**
  * Loads and validates a BN254 keystore file.
  *

package/src/crypto/keys/index.ts

@@ -1,10 +1,26 @@
-import { BarretenbergSync } from '@aztec/bb.js';
+import { BarretenbergSync, CircuitKind } from '@aztec/bb.js';
 
 import { Fr } from '../../curves/bn254/field.js';
 
-export async function vkAsFieldsMegaHonk(input: Buffer): Promise<Fr[]> {
+export async function vkAsFields(input: Buffer, kind: CircuitKind): Promise<Fr[]> {
   await BarretenbergSync.initSingleton();
   const api = BarretenbergSync.getSingleton();
-  const response = api.megaVkAsFields({ verificationKey: input });
-  return response.fields.map(field => Fr.fromBuffer(Buffer.from(field)));
+  switch (kind) {
+    case CircuitKind.App: {
+      const response = api.megaAppVkAsFields({ verificationKey: input });
+      return response.fields.map(field => Fr.fromBuffer(Buffer.from(field)));
+    }
+    case CircuitKind.Kernel: {
+      const response = api.megaKernelVkAsFields({ verificationKey: input });
+      return response.fields.map(field => Fr.fromBuffer(Buffer.from(field)));
+    }
+    case CircuitKind.HidingKernel: {
+      const response = api.megaZKVkAsFields({ verificationKey: input });
+      return response.fields.map(field => Fr.fromBuffer(Buffer.from(field)));
+    }
+    default: {
+      const _exhaustive: never = kind;
+      throw new Error(`vkAsFields: unhandled CircuitKind ${_exhaustive}`);
+    }
+  }
 }

package/src/fifo/fifo_frame_reader.ts

@@ -1,5 +1,6 @@
 import EventEmitter from 'node:events';
 import * as fs from 'node:fs';
+import * as net from 'node:net';
 import type { Readable } from 'node:stream';
 
 /**
@@ -36,8 +37,22 @@ export class FifoFrameReader extends EventEmitter<FifoFrameReaderEvents> {
   }
 
   /** Open a FIFO at the given path and start reading frames. */
-  start(fifoPath: string, highWaterMark = 64 * 1024): void {
-    this.startFromStream(fs.createReadStream(fifoPath, { highWaterMark }));
+  start(fifoPath: string): void {
+    // Read the FIFO through a libuv pipe handle (net.Socket) rather than fs.createReadStream.
+    // An fs read stream services the pipe with a blocking threadpool read that destroy() cannot
+    // cancel: if a writer never closes, that read stays parked and keeps the host process alive
+    // (manifesting as Jest "did not exit"). Opening O_NONBLOCK and wrapping the fd in a pipe
+    // handle makes reads epoll-based, so stop()'s destroy() releases the handle immediately,
+    // regardless of whether the writer is still attached.
+    const fd = fs.openSync(fifoPath, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+    let socket: net.Socket;
+    try {
+      socket = new net.Socket({ fd, readable: true, writable: false });
+    } catch (err) {
+      fs.closeSync(fd);
+      throw err;
+    }
+    this.startFromStream(socket);
   }
 
   /** Start reading frames from an existing readable stream. */

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

@@ -14,8 +14,9 @@ const DEFAULT_BATCH_WINDOW_MS = 0;
 // the maximum size of a batched request
 const DEFAULT_MAX_BATCH_SIZE = 100;
 
-// 10 mb
-const DEFAULT_MAX_REQUESTY_BODY_SIZE = 10 * 1024 * 1024;
+// 1 mb, matching the JSON-RPC server's default maxBodySizeBytes so the client never assembles a batch the
+// server rejects for exceeding the body limit
+const DEFAULT_MAX_REQUESTY_BODY_SIZE = 1 * 1024 * 1024;
 
 export type SafeJsonRpcClientOptions = {
   namespaceMethods?: string | false;

package/src/json-rpc/server/safe_json_rpc_server.ts

@@ -224,7 +224,11 @@ export class SafeJsonRpcServer {
           result = await this.proxy.call(method, params);
         }
 
-        return { jsonrpc, id, result };
+        // Coerce an undefined return value to null so the response always carries a `result` key.
+        // JSON.stringify drops undefined-valued keys, which would otherwise produce a JSON-RPC
+        // response with neither `result` nor `error` — a spec violation that leaves callers unable
+        // to distinguish "not found" from a malformed response.
+        return { jsonrpc, id, result: result ?? null };
       } catch (err: any) {
         if (err && err instanceof ZodError) {
           const message = err.issues.map(e => `${e.message} (${e.path.join('.')})`).join('. ') || 'Validation error';

package/src/log/aws-logger-config.ts

@@ -0,0 +1,32 @@
+import type { pino } from 'pino';
+
+function getSeverity(label: string): { severityText: string; severityNumber: number } {
+  switch (label) {
+    case 'trace':
+      return { severityText: 'TRACE', severityNumber: 1 };
+    case 'debug':
+      return { severityText: 'DEBUG', severityNumber: 5 };
+    case 'verbose':
+      return { severityText: 'VERBOSE', severityNumber: 7 };
+    case 'info':
+      return { severityText: 'INFO', severityNumber: 9 };
+    case 'warn':
+      return { severityText: 'WARN', severityNumber: 13 };
+    case 'error':
+      return { severityText: 'ERROR', severityNumber: 17 };
+    case 'fatal':
+      return { severityText: 'FATAL', severityNumber: 21 };
+    default:
+      return { severityText: 'UNSPECIFIED', severityNumber: 0 };
+  }
+}
+
+/** Pino configuration that adds OpenTelemetry severity fields understood by CloudWatch Logs. */
+export const AWSCloudLoggerConfig = {
+  messageKey: 'msg',
+  formatters: {
+    level(label: string, level: number): object {
+      return { level, ...getSeverity(label) };
+    },
+  },
+} satisfies pino.LoggerOptions;

package/src/log/pino-logger.ts

@@ -7,6 +7,7 @@ import { inspect } from 'util';
 import { compactArray } from '../collection/array.js';
 import type { EnvVar } from '../config/index.js';
 import { parseBooleanEnv } from '../config/parse-env.js';
+import { AWSCloudLoggerConfig } from './aws-logger-config.js';
 import { convertBigintsToStrings } from './bigint-utils.js';
 import { GoogleCloudLoggerConfig } from './gcloud-logger-config.js';
 import { getLogLevelFromFilters, parseLogLevelEnvVar } from './log-filters.js';
@@ -134,8 +135,17 @@ export const [logLevel, logFilters] = parseLogLevelEnvVar(process.env.LOG_LEVEL,
 // Define custom logging levels for pino.
 const customLevels = { verbose: 25 };
 
-// Global pino options, tweaked for google cloud if running there.
+// Global pino options, tweaked for the active cloud logging backend.
 const useGcloudLogging = parseBooleanEnv(process.env['USE_GCLOUD_LOGGING' satisfies EnvVar]);
+const useAwsLogging = parseBooleanEnv(process.env['USE_AWS_LOGGING' satisfies EnvVar]);
+const loggingConfig = useGcloudLogging
+  ? GoogleCloudLoggerConfig
+  : useAwsLogging
+    ? AWSCloudLoggerConfig
+    : {
+        formatters: {},
+        messageKey: 'msg',
+      };
 
 const redactedPaths = [
   'validatorPrivateKeys',
@@ -156,7 +166,7 @@ const redactedPaths = [
 
 const pinoOpts: pino.LoggerOptions<keyof typeof customLevels> = {
   customLevels,
-  messageKey: 'msg',
+  messageKey: loggingConfig.messageKey,
   useOnlyCustomLevels: false,
   level: logLevel,
   redact: {
@@ -170,8 +180,8 @@ const pinoOpts: pino.LoggerOptions<keyof typeof customLevels> = {
   },
   formatters: {
     log: obj => convertBigintsToStrings(obj) as Record<string, unknown>,
+    ...loggingConfig.formatters,
   },
-  ...(useGcloudLogging ? GoogleCloudLoggerConfig : {}),
 };
 
 export const levels = {
@@ -241,7 +251,7 @@ const pinoPrettyBaseOpts = {
   destination: 2,
   sync: true,
   colorize: useColor,
-  ignore: 'module,actor,instanceId,pid,hostname,trace_id,span_id,trace_flags,severity',
+  ignore: 'module,actor,instanceId,pid,hostname,trace_id,span_id,trace_flags,severity,severityText,severityNumber',
   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,

package/src/promise/running-promise.ts

@@ -22,16 +22,17 @@ export function makeLoggingErrorHandler(
  * at a specified polling interval. It allows starting, stopping, and checking the status of the
  * internally managed promise. The class also supports interrupting the polling process when stopped.
  */
-export class RunningPromise {
+export class RunningPromise<T = void> {
   private running = false;
   private runningPromise = Promise.resolve();
   private interruptibleSleep = new InterruptibleSleep();
   private requested: PromiseWithResolvers<void> | undefined = undefined;
+  private requestedArg: T | undefined = undefined;
 
   public static readonly EXIT: typeof EXIT = EXIT;
 
   constructor(
-    private fn: () => void | Promise<void>,
+    private fn: (arg?: T) => void | Promise<void>,
     private logger = createLogger('running-promise'),
     private pollingIntervalMS = 10000,
     private handleError: ErrorHandler = makeLoggingErrorHandler(logger),
@@ -51,7 +52,7 @@ export class RunningPromise {
       while (this.running) {
         const hasRequested = this.requested !== undefined;
         try {
-          await this.fn();
+          await this.fn(this.requestedArg);
         } catch (err) {
           const code = await this.handleError(err);
           if (code === RunningPromise.EXIT) {
@@ -64,6 +65,7 @@ export class RunningPromise {
         if (hasRequested) {
           this.requested!.resolve();
           this.requested = undefined;
+          this.requestedArg = undefined;
         }
 
         // If no immediate run was requested, sleep for the polling interval.
@@ -101,15 +103,16 @@ export class RunningPromise {
    * Triggers an immediate run of the function, bypassing the polling interval.
    * If the function is currently running, it will be allowed to continue and then called again immediately.
    */
-  public async trigger() {
+  public async trigger(arg?: T): Promise<void> {
     if (!this.running) {
-      return this.fn();
+      return this.fn(arg);
     }
 
     let requested = this.requested;
     if (!requested) {
       requested = promiseWithResolvers<void>();
       this.requested = requested;
+      this.requestedArg = arg;
       this.interruptibleSleep.interrupt();
     }
     await requested!.promise;

package/src/retry/index.ts

@@ -1,7 +1,7 @@
 import { TimeoutError } from '../error/index.js';
 import { type Logger, createLogger } from '../log/index.js';
 import { sleep } from '../sleep/index.js';
-import { Timer } from '../timer/index.js';
+import { type DateProvider, Timer } from '../timer/index.js';
 
 /** An error that indicates that the operation should not be retried. */
 export class NoRetryError extends Error {}
@@ -72,6 +72,34 @@ export async function retry<Result>(
   }
 }
 
+/**
+ * Timeout specification accepted by {@link retryUntil}. Either a plain number of seconds, an explicit
+ * `{ timeout }` in seconds, or an absolute `{ deadline }` with an optional {@link DateProvider} used to
+ * read the current time. A deadline is converted to the remaining seconds at call time; a deadline that
+ * has already passed yields a zero remaining budget, matching the immediate-timeout semantics of a
+ * non-positive numeric timeout.
+ */
+export type RetryUntilTimeout = number | { timeout: number } | { deadline: Date; dateProvider?: DateProvider };
+
+/**
+ * Resolves a {@link RetryUntilTimeout} to a numeric timeout in seconds for the legacy timer-based loop.
+ * A numeric/`{ timeout }` value passes through unchanged (0 means never time out, negative times out on the
+ * first interval). A `{ deadline }` is the remaining seconds until the deadline; when the deadline is already
+ * at or past `now` it resolves to a negative value so the loop times out immediately instead of being read as
+ * the never-timeout sentinel 0.
+ */
+function resolveRetryUntilTimeoutSeconds(timeout: RetryUntilTimeout): number {
+  if (typeof timeout === 'number') {
+    return timeout;
+  }
+  if ('deadline' in timeout) {
+    const now = timeout.dateProvider?.now() ?? Date.now();
+    const remainingSeconds = (timeout.deadline.getTime() - now) / 1000;
+    return remainingSeconds > 0 ? remainingSeconds : -1;
+  }
+  return timeout.timeout;
+}
+
 /**
  * Retry an asynchronous function until it returns a truthy value or the specified timeout is exceeded.
  * The function is retried periodically with a fixed interval between attempts. The operation can be named for better error messages.
@@ -79,16 +107,20 @@ export async function retry<Result>(
  *
  * @param fn - The asynchronous function to be retried, which should return a truthy value upon success or undefined otherwise.
  * @param name - The optional name of the operation, used for generating timeout error message.
- * @param timeout - The optional maximum time, in seconds, to keep retrying before throwing a timeout error. Defaults to 0 (never timeout).
+ * @param timeout - The maximum time to keep retrying before throwing a timeout error. Accepts a number of
+ * seconds (0 = never time out), an explicit `{ timeout }` in seconds, or an absolute `{ deadline }` with an
+ * optional `dateProvider`. A deadline already in the past times out on the first interval, the same as a
+ * zero/negative numeric timeout. Defaults to 0 (never timeout).
  * @param interval - The optional interval, in seconds, between retry attempts. Defaults to 1 second.
  * @returns A Promise that resolves with the successful (truthy) result of the provided function, or rejects if timeout is exceeded.
  */
 export async function retryUntil<T>(
   fn: () => (T | undefined) | Promise<T | undefined>,
   name = '',
-  timeout = 0,
+  timeout: RetryUntilTimeout = 0,
   interval = 1,
 ) {
+  const timeoutSeconds = resolveRetryUntilTimeoutSeconds(timeout);
   const timer = new Timer();
   while (true) {
     const result = await fn();
@@ -98,7 +130,7 @@ export async function retryUntil<T>(
 
     await sleep(interval * 1000);
 
-    if (timeout && timer.s() > timeout) {
+    if (timeoutSeconds && timer.s() > timeoutSeconds) {
       throw new TimeoutError(name ? `Timeout awaiting ${name}` : 'Timeout');
     }
   }

package/src/serialize/buffer_reader.ts

@@ -255,6 +255,11 @@ export class BufferReader {
     if (maxSize !== undefined && size > maxSize) {
       throw new Error(`Vector size ${size} exceeds maximum allowed ${maxSize}`);
     }
+    // Every element consumes at least one byte, so a size beyond the bytes left is unsatisfiable. Reject it
+    // up front rather than relying on each item deserializer to bounds-check as the loop runs out of input.
+    if (size > this.remainingBytes()) {
+      throw new Error(`Vector size ${size} exceeds remaining buffer length ${this.remainingBytes()}`);
+    }
     const result = new Array<T>(size);
     for (let i = 0; i < size; i++) {
       result[i] = itemDeserializer.fromBuffer(this);

package/src/serialize/serialize.ts

@@ -23,56 +23,6 @@ export function serializeArrayOfBufferableToVector(objs: Bufferable[], prefixLen
   return Buffer.concat([lengthBuf, ...arr]);
 }
 
-/**
- * Helper function for deserializeArrayFromVector.
- */
-type DeserializeFn<T> = (
-  buf: Buffer,
-  offset: number,
-) => {
-  /**
-   * The deserialized type.
-   */
-  elem: T;
-  /**
-   * How many bytes to advance by.
-   */
-  adv: number;
-};
-
-/**
- * Deserializes an array from a vector on an element-by-element basis.
- * @param deserialize - A function used to deserialize each element of the vector.
- * @param vector - The vector to deserialize.
- * @param offset - The position in the vector to start deserializing from.
- * @returns Deserialized array and how many bytes we advanced by.
- */
-export function deserializeArrayFromVector<T>(
-  deserialize: DeserializeFn<T>,
-  vector: Buffer,
-  offset = 0,
-): {
-  /**
-   * The deserialized array.
-   */
-  elem: T[];
-  /**
-   * How many bytes we advanced by.
-   */
-  adv: number;
-} {
-  let pos = offset;
-  const size = vector.readUInt32BE(pos);
-  pos += 4;
-  const arr = new Array<T>(size);
-  for (let i = 0; i < size; ++i) {
-    const { elem, adv } = deserialize(vector, pos);
-    pos += adv;
-    arr[i] = elem;
-  }
-  return { elem: arr, adv: pos - offset };
-}
-
 /**
  * Cast a uint8 array to a number.
  * @param array - The uint8 array.

package/src/string/index.ts

@@ -37,6 +37,20 @@ export function truncate(str: string, length: number = 64): string {
   return str.length > length ? str.slice(0, length) + '...' : str;
 }
 
+/** Formats a duration in seconds into a compact human-readable string (e.g. `45s`, `12m`, `2h 5m`). */
+export function formatSeconds(seconds: number): string {
+  if (seconds < 60) {
+    return `${Math.round(seconds)}s`;
+  }
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) {
+    return `${minutes}m`;
+  }
+  const hours = Math.floor(minutes / 60);
+  const remMinutes = minutes % 60;
+  return remMinutes > 0 ? `${hours}h ${remMinutes}m` : `${hours}h`;
+}
+
 export function isoDate(date?: Date) {
   return (date ?? new Date()).toISOString().replace(/[-:T]/g, '').replace(/\..+$/, '');
 }

package/src/testing/files/index.ts

@@ -50,14 +50,13 @@ export function updateInlineTestData(targetFileFromRepoRoot: string, itemName: s
 }
 
 /**
- * Updates the sample Prover.toml files in noir-projects/noir-protocol-circuits/crates/.
+ * Updates the sample Prover.toml files in noir-projects/fnd/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');
-  const targetFileFromRepoRoot = `noir-projects/noir-protocol-circuits/crates/${circuitName}/Prover.toml`;
+  const targetFileFromRepoRoot = `noir-projects/fnd/noir-protocol-circuits/crates/${circuitName}/Prover.toml`;
   const targetFile = getPathToFile(targetFileFromRepoRoot);
   writeFileSync(targetFile, value);
   logger(`Updated test data in ${targetFile} for ${circuitName}`);

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

@@ -3,15 +3,18 @@ import { z } from 'zod';
 import { makeTuple } from '../array/array.js';
 import { Fr } from '../curves/bn254/index.js';
 import { schemas } from '../schemas/index.js';
-import {
-  type Tuple,
-  assertLength,
-  deserializeArrayFromVector,
-  serializeArrayOfBufferableToVector,
-} from '../serialize/index.js';
+import { BufferReader, type Tuple, assertLength, serializeArrayOfBufferableToVector } from '../serialize/index.js';
 import { bufferToHex, hexToBuffer } from '../string/index.js';
 import type { Hasher } from './hasher.js';
 
+/**
+ * Upper bound on the elements a serialized sibling path may declare. The deepest protocol tree is 42 levels,
+ * and the stacked path proving L2-to-L1 message inclusion spans four unbalanced trees, so this leaves room to
+ * spare while keeping a malformed length prefix from driving a large allocation. `stdlib` asserts that it stays
+ * above every protocol tree height, which this package cannot check itself without depending on `@aztec/constants`.
+ */
+export const MAX_SIBLING_PATH_LENGTH = 128;
+
 /**
  * Contains functionality to compute and serialize/deserialize a sibling path.
  * E.g. Sibling path for a leaf at index 3 in a tree of depth 3 consists of:
@@ -118,26 +121,12 @@ export class SiblingPath<N extends number> {
    * @param buf - A buffer containing the buffer representation of SiblingPath.
    * @param offset - An offset to start deserializing from.
    * @returns A SiblingPath object.
+   * @throws If the length prefix exceeds MAX_SIBLING_PATH_LENGTH or the buffer holds fewer elements than it declares.
    */
   static fromBuffer<N extends number>(buf: Buffer, offset = 0): SiblingPath<N> {
-    const { elem } = SiblingPath.deserialize<N>(buf, offset);
-    return elem;
-  }
-
-  /**
-   * Deserializes a SiblingPath object from a slice of a part of a buffer and returns the amount of bytes advanced.
-   * @param buf - A buffer representation of the sibling path.
-   * @param offset - An offset to start deserializing from.
-   * @returns The deserialized sibling path and the number of bytes advanced.
-   */
-  static deserialize<N extends number>(buf: Buffer, offset = 0) {
-    const deserializePath = (buf: Buffer, offset: number) => ({
-      elem: buf.slice(offset, offset + 32),
-      adv: 32,
-    });
-    const { elem, adv } = deserializeArrayFromVector(deserializePath, buf, offset);
-    const size = elem.length;
-    return { elem: new SiblingPath<N>(size as N, elem), adv };
+    const reader = new BufferReader(buf, offset);
+    const path = reader.readVector({ fromBuffer: r => r.readBytes(Fr.SIZE_IN_BYTES) }, MAX_SIBLING_PATH_LENGTH);
+    return new SiblingPath<N>(path.length as N, path);
   }
 
   /**

package/src/types/index.ts

@@ -29,13 +29,43 @@ 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 IfFlag<
+export type PickIfFlag<
   OptsSchema,
   Opts extends OptsSchema,
   Key extends keyof OptsSchema,
@@ -48,6 +78,9 @@ export type IfFlag<
       ? 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