@aztec-labs/foundation 6.0.0-nightly.20260829

package/src/sleep/index.ts

@@ -0,0 +1,90 @@
+import { InterruptError } from '../error/index.js';
+
+/**
+ * InterruptibleSleep is a utility class that allows you to create an interruptible sleep function.
+ * The sleep function can be interrupted at any time by calling the `interrupt` method, which can
+ * also specify whether the sleep should throw an error or just return. This is useful when you need
+ * to terminate long-running processes or perform cleanup tasks in response to external events.
+ *
+ * @example
+ * const sleeper = new InterruptibleSleep();
+ *
+ * async function longRunningTask() \{
+ *   try \{
+ *     await sleeper.sleep(3000);
+ *     console.log('Task completed after 3 seconds');
+ *   \} catch (e) \{
+ *     console.log('Task was interrupted');
+ *   \}
+ * \}
+ *
+ * setTimeout(() =\> sleeper.interrupt(true), 1500); // Interrupt the sleep after 1.5 seconds
+ */
+export class InterruptibleSleep {
+  private interrupts: Array<(shouldThrow: boolean) => void> = [];
+  private timeoutIds: NodeJS.Timeout[] = [];
+
+  /**
+   * Sleep for a specified amount of time in milliseconds.
+   * The sleep function will pause the execution of the current async function
+   * for the given time period, allowing other tasks to run before resuming.
+   *
+   * @param ms - The number of milliseconds to sleep.
+   * @returns A Promise that resolves after the specified time has passed.
+   */
+  public async sleep(ms: number): Promise<void> {
+    let interruptResolve: (shouldThrow: boolean) => void;
+    const interruptPromise = new Promise<boolean>(resolve => {
+      interruptResolve = resolve;
+      this.interrupts.push(resolve);
+    });
+
+    let timeoutId: NodeJS.Timeout;
+    const timeoutPromise = new Promise<boolean>(resolve => {
+      timeoutId = setTimeout(() => resolve(false), ms);
+      this.timeoutIds.push(timeoutId);
+    });
+    const shouldThrow = await Promise.race([interruptPromise, timeoutPromise]);
+
+    clearTimeout(timeoutId!);
+    this.timeoutIds = this.timeoutIds.filter(id => id !== timeoutId);
+    this.interrupts = this.interrupts.filter(res => res !== interruptResolve);
+
+    if (shouldThrow) {
+      throw new InterruptError('Interrupted.');
+    }
+  }
+
+  /**
+   * Interrupts the current sleep operation and optionally throws an error if specified.
+   * By default, when interrupted, the sleep operation will resolve without throwing.
+   * If 'sleepShouldThrow' is set to true, the sleep operation will throw an InterruptError instead.
+   *
+   * @param sleepShouldThrow - A boolean value indicating whether the sleep operation should throw an error when interrupted. Default is false.
+   */
+  public interrupt(sleepShouldThrow = false): void {
+    this.interrupts.forEach(resolve => resolve(sleepShouldThrow));
+    this.interrupts = [];
+    this.timeoutIds.forEach(id => clearTimeout(id));
+    this.timeoutIds = [];
+  }
+}
+
+/**
+ * Puts the current execution context to sleep for a specified duration.
+ * This simulates a blocking sleep operation by using an asynchronous function and a Promise that resolves after the given duration.
+ * The sleep function can be interrupted by the 'interrupt' method of the InterruptibleSleep class.
+ *
+ * @param ms - The duration in milliseconds for which the sleep operation should last.
+ * @param returnValue - The return value of the promise.
+ * @returns A Promise that resolves after the specified duration, allowing the use of 'await' to pause execution.
+ */
+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

@@ -0,0 +1,80 @@
+/** 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');
+}
+
+export function withoutHexPrefix(str: string): string {
+  return hasHexPrefix(str) ? str.slice(2) : str;
+}
+
+export function withHexPrefix(str: string): `0x${string}` {
+  return hasHexPrefix(str) ? str : `0x${str}`;
+}
+
+export function isHex(str: string): boolean {
+  return /^(0x)?[0-9a-fA-F]*$/.test(str);
+}
+
+export function hexToBuffer(str: string): Buffer {
+  return Buffer.from(withoutHexPrefix(str), 'hex');
+}
+
+export function bufferToHex(buffer: Buffer): `0x${string}` {
+  return `0x${buffer.toString('hex')}`;
+}
+
+export function pluralize(str: string, count: number | bigint, plural?: string): string {
+  return count === 1 || count === 1n ? str : (plural ?? `${str}s`);
+}
+
+export function count(count: number | bigint, str: string, plural?: string): string {
+  return `${count} ${pluralize(str, count, plural)}`;
+}
+
+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(/\..+$/, '');
+}
+
+export function urlJoin(...args: string[]): string {
+  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

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+
+import { createConsoleLogger } from '../../log/console.js';
+import { fileURLToPath } from '../../url/index.js';
+import { isGenerateTestDataEnabled } from '../test_data.js';
+
+/** Writes the contents specified to the target file if test data generation is enabled. */
+export function writeTestData(targetFileFromRepoRoot: string, contents: string | Buffer, raw: boolean = false) {
+  if (!isGenerateTestDataEnabled()) {
+    return;
+  }
+  const targetFile = getPathToFile(targetFileFromRepoRoot);
+  const toWrite = raw ? contents : typeof contents === 'string' ? contents : contents.toString('hex');
+  writeFileSync(targetFile, toWrite);
+  const logger = createConsoleLogger('aztec:testing:test_data');
+  logger(`Wrote test data to ${targetFile}`);
+}
+
+export function readTestData(repoPath: string): Buffer {
+  const targetFile = getPathToFile(repoPath);
+  return readFileSync(targetFile);
+}
+
+/**
+ * Looks for a variable assignment in the target file and updates the value, only if test data generation is enabled.
+ * Note that a magic inline comment would be a cleaner approach, like `/* TEST-DATA-START *\/` and `/* TEST-DATA-END *\/`,
+ * but running nargo fmt on it panics since the comment would be erased, so we roll with this for now.
+ * @remarks Requires AZTEC_GENERATE_TEST_DATA=1 to be set
+ */
+export function updateInlineTestData(targetFileFromRepoRoot: string, itemName: string, value: string) {
+  if (!isGenerateTestDataEnabled()) {
+    return;
+  }
+  const logger = createConsoleLogger('aztec:testing:test_data');
+  const targetFile = getPathToFile(targetFileFromRepoRoot);
+  const contents = readFileSync(targetFile, 'utf8').toString();
+  const regex = new RegExp(`(let|pub\\s+global)\\s+${itemName}(\\s*:\\s*[^=]+)?\\s*=\\s*([\\s\\S]*?);`, 'g');
+  if (!regex.exec(contents)) {
+    throw new Error(`Test data marker for ${itemName} not found in ${targetFile}`);
+  }
+
+  const updatedContents = contents.replace(
+    regex,
+    (_, declareKeyword, typeAnnotation) =>
+      `${declareKeyword} ${itemName}${(typeAnnotation || '').trimEnd()} = ${value};`,
+  );
+  writeFileSync(targetFile, updatedContents);
+  logger(`Updated test data in ${targetFile} for ${itemName} to ${value}`);
+}
+
+/**
+ * Updates the sample Prover.toml files in noir-projects/fnd/noir-protocol-circuits/crates/.
+ * @remarks Requires AZTEC_GENERATE_TEST_DATA=1 to be set. The block-root, block-merge, checkpoint,
+ * tx-merge, and root rollup samples are regenerated by the prover-client
+ * `regenerate_rollup_sample_inputs.test.ts` suite; the private-kernel and transaction-base rollup
+ * samples by the e2e 'AZTEC_GENERATE_TEST_DATA=1 FAKE_PROOFS=1 yarn test:e2e single-node/prover/server/full.test' dump.
+ */
+export function updateProtocolCircuitSampleInputs(circuitName: string, value: string) {
+  const logger = createConsoleLogger('aztec:testing:test_data');
+  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}`);
+}
+
+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})`);
+  }
+
+  return join(repoRoot, targetFileFromRepoRoot);
+}

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

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

package/src/testing/port_allocator.ts

@@ -0,0 +1,31 @@
+import net from 'net';
+
+/**
+ * Get a random port that is free to use.
+ * Returns undefined if it fails to get a port.
+ *
+ * @attribution: adapted from https://stackoverflow.com/a/71178451
+ *
+ * @returns a random port that is free to use.
+ */
+export function getRandomPort(): Promise<number | undefined> {
+  return new Promise(resolve => {
+    const server = net.createServer();
+    server.listen(0, () => {
+      const address = server.address();
+      if (address && typeof address === 'object' && 'port' in address) {
+        const port = address.port;
+        server.close(() => {
+          resolve(port);
+        });
+      } else {
+        server.close(() => {
+          resolve(undefined);
+        });
+      }
+    });
+    server.on('error', () => {
+      resolve(undefined);
+    });
+  });
+}

package/src/testing/snapshot_serializer.ts

@@ -0,0 +1,33 @@
+import type { NewPlugin } from 'pretty-format';
+import { inspect } from 'util';
+
+function makeSerializerForCustomInspect(prefix: string): NewPlugin {
+  return {
+    serialize(val: any): string {
+      return inspect(val);
+    },
+
+    test(arg: any): boolean {
+      return inspect(arg).startsWith(prefix);
+    },
+  };
+}
+
+const bufferSerializer: NewPlugin = {
+  serialize(val: any): string {
+    return `Buffer<0x${val.toString('hex')}>`;
+  },
+
+  test(arg: any): boolean {
+    return Buffer.isBuffer(arg);
+  },
+};
+
+const CUSTOM_INSPECT_SERIALIZABLE_TYPES = ['AztecAddress', 'Fr', 'Fq', 'Selector', 'EthAddress'];
+
+export function setupCustomSnapshotSerializers(expect: { addSnapshotSerializer: (serializer: NewPlugin) => void }) {
+  for (const type of CUSTOM_INSPECT_SERIALIZABLE_TYPES) {
+    expect.addSnapshotSerializer(makeSerializerForCustomInspect(type));
+  }
+  expect.addSnapshotSerializer(bufferSerializer);
+}

package/src/testing/test_data.ts

@@ -0,0 +1,36 @@
+const testData: { [key: string]: unknown[] } = {};
+
+/** Returns whether test data generation is enabled */
+export function isGenerateTestDataEnabled() {
+  return ['1', 'true'].includes(process.env.AZTEC_GENERATE_TEST_DATA ?? '') && typeof expect !== 'undefined';
+}
+
+/** Pushes test data with the given name, only if test data generation is enabled. */
+export function pushTestData<T>(itemName: string, data: T) {
+  if (!isGenerateTestDataEnabled()) {
+    return;
+  }
+
+  if (typeof expect === 'undefined') {
+    return;
+  }
+
+  const testName = expect.getState().currentTestName;
+  const fullItemName = `${testName} ${itemName}`;
+
+  if (!testData[fullItemName]) {
+    testData[fullItemName] = [];
+  }
+  testData[fullItemName].push(data);
+}
+
+/** Returns all instances of pushed test data with the given name, or empty if test data generation is not enabled. */
+export function getTestData(itemName: string): unknown[] {
+  if (!isGenerateTestDataEnabled()) {
+    return [];
+  }
+
+  const testName = expect.getState().currentTestName;
+  const fullItemName = `${testName} ${itemName}`;
+  return testData[fullItemName];
+}

package/src/timer/date.ts

@@ -0,0 +1,82 @@
+import { createLogger } from '../log/pino-logger.js';
+
+/** Returns current datetime. */
+export class DateProvider {
+  public now(): number {
+    return Date.now();
+  }
+
+  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. */
+export class TestDateProvider extends DateProvider {
+  private offset = 0;
+
+  constructor(private readonly logger = createLogger('foundation:test-date-provider')) {
+    super();
+  }
+
+  public override now(): number {
+    return Date.now() + this.offset;
+  }
+
+  public setTime(timeMs: number) {
+    this.offset = timeMs - Date.now();
+    this.logger.warn(`Time set to ${new Date(timeMs).toISOString()}`, { offset: this.offset, timeMs });
+  }
+
+  /** Resets the time back to real time (offset = 0). */
+  public reset() {
+    this.offset = 0;
+    this.logger.warn('Time reset to real time');
+  }
+
+  /** Advances the time by the given number of seconds. */
+  public advanceTime(seconds: number) {
+    this.offset += seconds * 1000;
+  }
+}
+
+/**
+ * A date provider for tests that only advances time via explicit advanceTime() calls.
+ * Unlike TestDateProvider, this does NOT track real time progression - time is completely
+ * frozen until explicitly advanced. This eliminates flakiness from tests taking
+ * varying amounts of real time to execute.
+ */
+export class ManualDateProvider extends DateProvider {
+  private currentTimeMs: number;
+
+  /**
+   * @param initialTimeMs - Initial time in milliseconds. Defaults to a round timestamp for easy visualization.
+   */
+  constructor(initialTimeMs: number = Date.UTC(2025, 0, 1, 0, 0, 0)) {
+    super();
+    this.currentTimeMs = initialTimeMs;
+  }
+
+  public override now(): number {
+    return this.currentTimeMs;
+  }
+
+  /** Sets the current time to the given timestamp in milliseconds. */
+  public setTime(timeMs: number) {
+    this.currentTimeMs = timeMs;
+  }
+
+  /** Advances the time by the given number of seconds. */
+  public advanceTime(seconds: number) {
+    this.currentTimeMs += seconds * 1000;
+  }
+
+  /** Advances the time by the given number of milliseconds. */
+  public advanceTimeMs(ms: number) {
+    this.currentTimeMs += ms;
+  }
+}

package/src/timer/elapsed.ts

@@ -0,0 +1,23 @@
+import { Timer } from './timer.js';
+
+/**
+ * Measures the elapsed execution time of a function call or promise once it is awaited.
+ * @param fn - Function or promise.
+ * @returns The number of ms and the result.
+ */
+export async function elapsed<T>(fn: Promise<T> | (() => T | Promise<T>)): Promise<[number, T]> {
+  const timer = new Timer();
+  const result = await (typeof fn === 'function' ? fn() : fn);
+  return [timer.ms(), result];
+}
+
+/**
+ * Measures the elapsed execution time of a synchronous function call once it is awaited.
+ * @param fn - Function.
+ * @returns The number of ms and the result.
+ */
+export function elapsedSync<T>(fn: () => T): [number, T] {
+  const timer = new Timer();
+  const result = fn();
+  return [timer.ms(), result];
+}

package/src/timer/index.ts

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

package/src/timer/timeout.ts

@@ -0,0 +1,136 @@
+import { TimeoutError } from '../error/index.js';
+import { promiseWithResolvers } from '../promise/utils.js';
+
+/**
+ * TimeoutTask class creates an instance for managing and executing a given asynchronous function with a specified timeout duration.
+ * The task will be automatically interrupted if it exceeds the given timeout duration, and will throw a custom error message.
+ * Additional information such as execution time can be retrieved using getTime method after the task has been executed.
+ *
+ * @typeparam T - The return type of the asynchronous function to be executed.
+ */
+export class TimeoutTask<T> {
+  private totalTime = 0;
+  private timeoutPromise: Promise<never> | undefined;
+
+  constructor(
+    private fn: (signal: AbortSignal) => Promise<T>,
+    private timeout: number,
+    private errorFn: () => Error,
+    private onAbort?: () => void,
+  ) {}
+
+  /**
+   * Executes the given function with a specified timeout.
+   * If the function takes longer than the timeout, it will be interrupted and an error will be thrown.
+   * The total execution time of the function will be stored in the totalTime property.
+   *
+   * @returns The result of the executed function if completed within the timeout.
+   * @throws An error with a message indicating the function was interrupted due to exceeding the specified timeout.
+   */
+  public async exec() {
+    const signal = AbortSignal.timeout(this.timeout);
+    this.timeoutPromise = new Promise<never>((_, reject) => {
+      signal!.addEventListener(
+        'abort',
+        () => {
+          this.onAbort?.();
+          reject(this.errorFn());
+        },
+        { once: true },
+      );
+    });
+
+    const start = Date.now();
+    const result = await Promise.race<T>([this.fn(signal), this.timeoutPromise]);
+    this.totalTime = Date.now() - start;
+    return result;
+  }
+
+  /**
+   * Returns the interrupt promise associated with the TimeoutTask instance.
+   * The interrupt promise is used internally to reject the task when a timeout occurs.
+   * This method can be helpful when debugging or tracking the state of the task.
+   *
+   * @returns The interrupt promise associated with the task.
+   */
+  public getInterruptPromise() {
+    return this.timeoutPromise;
+  }
+
+  /**
+   * Get the total time spent on the most recent execution of the wrapped function.
+   * This method provides the duration from the start to the end of the function execution, whether it completed or timed out.
+   *
+   * @returns The total time in milliseconds spent on the most recent function execution.
+   */
+  public getTime() {
+    return this.totalTime;
+  }
+}
+
+/**
+ * Executes a function with a timeout.
+ * @param fn - The function to execute, accepts AbortSignal and returns a Promise.
+ * @param timeout - The maximum time in milliseconds to allow the function to run.
+ * @param errorOrFnName - Optional function name or a function that returns an Error to throw if the timeout is reached.
+ * @param onAbort - Optional callback to execute when the task is aborted.
+ *
+ * @returns A Promise that resolves with the result of the function fn if it completes within the timeout
+ *
+ * */
+export async function executeTimeout<T>(
+  fn: (signal: AbortSignal) => Promise<T>,
+  timeout: number,
+  errorOrFnName?: string | (() => Error),
+  onAbort?: () => void,
+) {
+  const errorFn =
+    typeof errorOrFnName === 'function'
+      ? errorOrFnName
+      : () => new TimeoutError(`Timeout running ${errorOrFnName ?? 'function'} after ${timeout}ms.`);
+  const task = new TimeoutTask(fn, timeout, errorFn, onAbort);
+  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>();
+
+  const timer = setTimeout(() => {
+    promise.reject(new TimeoutError(errorMessage ?? `Operation timed out after ${timeoutMs}ms`));
+  }, timeoutMs);
+
+  const cleanup = () => clearTimeout(timer);
+  return promise.promise.finally(cleanup);
+}

package/src/timer/timer.ts

@@ -0,0 +1,48 @@
+/**
+ * Timer class to measure time intervals in milliseconds and seconds.
+ * Upon instantiation, it stores the current timestamp as the starting point.
+ * The 'ms()' method returns the elapsed time in milliseconds,
+ * while the 's()' method returns the elapsed time in seconds.
+ *
+ * @example
+ * const timer = new Timer();
+ * setTimeout(() =\> \{
+ *   console.log(`Elapsed time: ${timer.ms()} ms`);
+ * \}, 1000);
+ */
+export class Timer {
+  private start: number;
+
+  constructor() {
+    this.start = performance ? performance.now() : Date.now();
+  }
+
+  /**
+   * Return microseconds.
+   */
+  public us() {
+    return this.ms() * 1000;
+  }
+
+  /**
+   * Returns the elapsed time in milliseconds since the Timer instance was created.
+   * Provides a simple and convenient way to measure the time duration between two events
+   * or monitor performance of specific code sections.
+   *
+   * @returns The elapsed time in milliseconds.
+   */
+  public ms() {
+    return (performance ? performance.now() : Date.now()) - this.start;
+  }
+
+  /**
+   * Returns the time elapsed since the Timer instance was created, in seconds.
+   * The value is calculated by subtracting the initial start time from the current time
+   * and dividing the result by 1000 to convert milliseconds to seconds.
+   *
+   * @returns The elapsed time in seconds.
+   */
+  public s() {
+    return this.ms() / 1000;
+  }
+}