@aztec/foundation 0.23.0 → 0.24.0

package/src/mutex/index.ts

@@ -0,0 +1,83 @@
+import { MutexDatabase } from './mutex_database.js';
+
+export * from './mutex_database.js';
+
+/**
+ * Mutex class provides a mutual exclusion mechanism for critical sections of code using a named lock.
+ * The lock is acquired and released via the `lock` and `unlock` methods. Locks can be optionally pinged
+ * to keep them alive when they are held for longer durations, avoiding unintended release due to timeouts.
+ *
+ * The underlying lock state is managed in a MutexDatabase instance which can be shared across multiple Mutex instances.
+ * This allows for synchronization between different parts of an application or even across different instances of an application.
+ *
+ * @example
+ * const mutex = new Mutex(mutexDatabase, 'myLock');
+ * await mutex.lock();
+ * // Critical section here
+ * await mutex.unlock();
+ */
+export class Mutex {
+  private id = 0;
+  private pingTimeout!: NodeJS.Timeout;
+
+  constructor(
+    private readonly db: MutexDatabase,
+    private readonly name: string,
+    private readonly timeout = 5000,
+    private readonly tryLockInterval = 2000,
+    private readonly pingInterval = 2000,
+  ) {}
+
+  /**
+   * Acquire a lock on the mutex. If 'untilAcquired' is true, the method will keep trying to acquire the lock until it
+   * successfully acquires it. If 'untilAcquired' is false, the method will try to acquire the lock once and return
+   * immediately with a boolean indicating if the lock has been acquired or not.
+   *
+   * @param untilAcquired - Optional parameter, set to true by default. If true, the method will keep trying to acquire the lock until success. If false, the method will try only once and return a boolean value.
+   * @returns A Promise that resolves to true if the lock has been acquired, or false when 'untilAcquired' is false and the lock could not be immediately acquired.
+   */
+  public async lock(untilAcquired = true) {
+    while (true) {
+      if (await this.db.acquireLock(this.name, this.timeout)) {
+        const id = this.id;
+        this.pingTimeout = setTimeout(() => this.ping(id), this.pingInterval);
+        return true;
+      }
+
+      if (!untilAcquired) {
+        return false;
+      }
+      await new Promise(resolve => setTimeout(resolve, this.tryLockInterval));
+    }
+  }
+
+  /**
+   * Unlocks the mutex, allowing other instances to acquire the lock.
+   * This method also clears the internal ping timeout and increments the internal ID
+   * to ensure stale pings do not extend the lock after it has been released.
+   *
+   * @returns A promise that resolves once the lock has been released in the database.
+   */
+  public async unlock() {
+    clearTimeout(this.pingTimeout);
+    this.id++;
+    await this.db.releaseLock(this.name);
+  }
+
+  /**
+   * Periodically extends the lock's lifetime by updating the database record with a new expiration time.
+   * This method is called recursively using setTimeout. If the id passed to the ping method does not match
+   * the current lock instance's id, it means the lock has been released or acquired by another instance
+   * and the ping should not proceed further.
+   *
+   * @param id - The id of the current lock instance.
+   */
+  private async ping(id: number) {
+    if (id !== this.id) {
+      return;
+    }
+
+    await this.db.extendLock(this.name, this.timeout);
+    this.pingTimeout = setTimeout(() => this.ping(id), this.pingInterval);
+  }
+}

package/src/mutex/mutex_database.ts

@@ -0,0 +1,12 @@
+/**
+ * Represents a mutual exclusion (mutex) database interface.
+ * Provides functionality for acquiring, extending, and releasing locks on resources to ensure exclusive access and prevent conflicts in concurrent applications.
+ */
+export interface MutexDatabase {
+  // eslint-disable-next-line jsdoc/require-jsdoc
+  acquireLock(name: string, timeout: number): Promise<boolean>;
+  // eslint-disable-next-line jsdoc/require-jsdoc
+  extendLock(name: string, timeout: number): Promise<void>;
+  // eslint-disable-next-line jsdoc/require-jsdoc
+  releaseLock(name: string): Promise<void>;
+}

package/src/noir/index.ts

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

package/src/noir/noir_package_config.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+
+const noirGitDependencySchema = z.object({
+  git: z.string(),
+  tag: z.string(),
+  directory: z.string().optional(),
+});
+
+const noirLocalDependencySchema = z.object({
+  path: z.string(),
+});
+
+const noirPackageConfigSchema = z.object({
+  package: z.object({
+    name: z.string().default(''),
+    type: z.enum(['lib', 'contract', 'bin']).default('bin'),
+    entry: z.string().optional(),
+    description: z.string().optional(),
+    authors: z.array(z.string()).optional(),
+    // eslint-disable-next-line camelcase
+    compiler_version: z.string().optional(),
+    backend: z.string().optional(),
+    license: z.string().optional(),
+  }),
+  dependencies: z.record(z.union([noirGitDependencySchema, noirLocalDependencySchema])).default({}),
+});
+
+/**
+ * Noir package configuration.
+ */
+export type NoirPackageConfig = z.infer<typeof noirPackageConfigSchema>;
+
+/**
+ * A remote package dependency.
+ */
+export type NoirGitDependencyConfig = z.infer<typeof noirGitDependencySchema>;
+
+/**
+ * A local package dependency.
+ */
+export type NoirLocalDependencyConfig = z.infer<typeof noirLocalDependencySchema>;
+
+/**
+ * A package dependency.
+ */
+export type NoirDependencyConfig = NoirGitDependencyConfig | NoirLocalDependencyConfig;
+
+/**
+ * Checks that an object is a package configuration.
+ * @param config - Config to check
+ */
+export function parseNoirPackageConfig(config: any): NoirPackageConfig {
+  return noirPackageConfigSchema.parse(config);
+}

package/src/retry/index.ts

@@ -0,0 +1,99 @@
+import { createDebugLogger } from '../log/index.js';
+import { sleep } from '../sleep/index.js';
+import { Timer } from '../timer/index.js';
+
+/** An error that indicates that the operation should not be retried. */
+export class NoRetryError extends Error {}
+
+/**
+ * Generates a backoff sequence for retrying operations with an increasing delay.
+ * The backoff sequence follows this pattern: 1, 1, 1, 2, 4, 8, 16, 32, 64, ...
+ * This generator can be used in combination with the `retry` function to perform
+ * retries with exponential backoff and capped at 64 seconds between attempts.
+ *
+ * @returns A generator that yields the next backoff value in seconds as an integer.
+ */
+export function* backoffGenerator() {
+  const v = [1, 1, 1, 2, 4, 8, 16, 32, 64];
+  let i = 0;
+  while (true) {
+    yield v[Math.min(i++, v.length - 1)];
+  }
+}
+
+/**
+ * Generates a backoff sequence based on the array of retry intervals to use with the `retry` function.
+ * @param retries - Intervals to retry (in seconds).
+ * @returns A generator sequence.
+ */
+export function* makeBackoff(retries: number[]) {
+  for (const retry of retries) {
+    yield retry;
+  }
+}
+
+/**
+ * Retry a given asynchronous function with a specific backoff strategy, until it succeeds or backoff generator ends.
+ * It logs the error and retry interval in case an error is caught. The function can be named for better log output.
+ *
+ * @param fn - The asynchronous function to be retried.
+ * @param name - The optional name of the operation, used for logging purposes.
+ * @param backoff - The optional backoff generator providing the intervals in seconds between retries. Defaults to a predefined series.
+ * @param log - Logger to use for logging.
+ * @param failSilently - Do not log errors while retrying.
+ * @returns A Promise that resolves with the successful result of the provided function, or rejects if backoff generator ends.
+ * @throws If `NoRetryError` is thrown by the `fn`, it is rethrown.
+ */
+export async function retry<Result>(
+  fn: () => Promise<Result>,
+  name = 'Operation',
+  backoff = backoffGenerator(),
+  log = createDebugLogger('aztec:foundation:retry'),
+  failSilently = false,
+) {
+  while (true) {
+    try {
+      return await fn();
+    } catch (err: any) {
+      if (err instanceof NoRetryError) {
+        // A special error that indicates that the operation should not be retried. Rethrow it.
+        throw err;
+      }
+      const s = backoff.next().value;
+      if (s === undefined) {
+        throw err;
+      }
+      log(`${name} failed. Will retry in ${s}s...`);
+      !failSilently && log.error(err);
+      await sleep(s * 1000);
+      continue;
+    }
+  }
+}
+
+/**
+ * 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.
+ * Will never timeout if the value is 0.
+ *
+ * @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 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: () => Promise<T | undefined>, name = '', timeout = 0, interval = 1) {
+  const timer = new Timer();
+  while (true) {
+    const result = await fn();
+    if (result) {
+      return result;
+    }
+
+    await sleep(interval * 1000);
+
+    if (timeout && timer.s() > timeout) {
+      throw new Error(name ? `Timeout awaiting ${name}` : 'Timeout');
+    }
+  }
+}

package/src/running-promise/index.ts

@@ -0,0 +1,60 @@
+/**
+ * RunningPromise is a utility class that helps manage the execution of an asynchronous function
+ * 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 {
+  private running = false;
+  private runningPromise = Promise.resolve();
+  private interruptPromise = Promise.resolve();
+  private interruptResolve = () => {};
+  constructor(private fn: () => Promise<void>, private pollingInterval = 10000) {}
+
+  /**
+   * Starts the running promise.
+   */
+  public start() {
+    this.running = true;
+    this.interruptPromise = new Promise(resolve => (this.interruptResolve = resolve));
+
+    const poll = async () => {
+      while (this.running) {
+        await this.fn();
+        await this.interruptibleSleep(this.pollingInterval);
+      }
+    };
+    this.runningPromise = poll();
+  }
+
+  /**
+   * Stops the running promise, resolves any pending interruptible sleep,
+   * and waits for the currently executing function to complete.
+   */
+  async stop(): Promise<void> {
+    this.running = false;
+    this.interruptResolve();
+    await this.runningPromise;
+  }
+
+  /**
+   * A sleep function that can be interrupted before the specified time.
+   * The sleep duration is determined by 'timeInMs', and it can be terminated early if the 'interruptPromise' is resolved.
+   * @param timeInMs - The time in milliseconds.
+   */
+  private async interruptibleSleep(timeInMs: number) {
+    let timeout!: NodeJS.Timeout;
+    const sleepPromise = new Promise(resolve => {
+      timeout = setTimeout(resolve, timeInMs);
+    });
+    await Promise.race([sleepPromise, this.interruptPromise]);
+    clearTimeout(timeout);
+  }
+
+  /**
+   * Checks if the running promise is currently active.
+   * @returns True if the promise is running.
+   */
+  public isRunning() {
+    return this.running;
+  }
+}

package/src/serialize/buffer_reader.ts

@@ -0,0 +1,286 @@
+import { Tuple } from './types.js';
+
+/**
+ * The BufferReader class provides a utility for reading various data types from a buffer.
+ * It supports reading numbers, booleans, byte arrays, Fr and Fq field elements,
+ * vectors, arrays, objects, strings, and maps. It maintains an internal index to
+ * keep track of the current reading position in the buffer.
+ *
+ * Usage:
+ * Create a new instance of BufferReader with a buffer and an optional offset.
+ * Use the provided methods to read desired data types from the buffer.
+ * The reading methods automatically advance the internal index.
+ *
+ * @example
+ * const reader = new BufferReader(someBuffer);
+ * const num = reader.readNumber();
+ * const bool = reader.readBoolean();
+ * const byteArray = reader.readBytes(4);
+ */
+export class BufferReader {
+  private index: number;
+  constructor(private buffer: Buffer, offset = 0) {
+    this.index = offset;
+  }
+
+  /**
+   * Creates a BufferReader instance from either a Buffer or an existing BufferReader.
+   * If the input is a Buffer, it creates a new BufferReader with the given buffer.
+   * If the input is already a BufferReader, it returns the input unchanged.
+   *
+   * @param bufferOrReader - A Buffer or BufferReader to initialize the BufferReader.
+   * @returns An instance of BufferReader.
+   */
+  public static asReader(bufferOrReader: Uint8Array | Buffer | BufferReader): BufferReader {
+    if (bufferOrReader instanceof BufferReader) {
+      return bufferOrReader;
+    }
+
+    const buf = Buffer.isBuffer(bufferOrReader)
+      ? bufferOrReader
+      : Buffer.from(bufferOrReader.buffer, bufferOrReader.byteOffset, bufferOrReader.byteLength);
+
+    return new BufferReader(buf);
+  }
+
+  /**
+   * Reads a 32-bit unsigned integer from the buffer at the current index position.
+   * Updates the index position by 4 bytes after reading the number.
+   *
+   * @returns The read 32-bit unsigned integer value.
+   */
+  public readNumber(): number {
+    this.index += 4;
+    return this.buffer.readUint32BE(this.index - 4);
+  }
+
+  /**
+   * Reads `count` 32-bit unsigned integers from the buffer at the current index position.
+   * @param count - The number of 32-bit unsigned integers to read.
+   * @returns An array of 32-bit unsigned integers.
+   */
+  public readNumbers<N extends number>(count: N): Tuple<number, N> {
+    const result = Array.from({ length: count }, () => this.readNumber());
+    return result as Tuple<number, N>;
+  }
+
+  /**
+   * Reads a 16-bit unsigned integer from the buffer at the current index position.
+   * Updates the index position by 2 bytes after reading the number.
+   *
+   * @returns The read 16 bit value.
+   */
+  public readUInt16(): number {
+    this.index += 2;
+    return this.buffer.readUInt16BE(this.index - 2);
+  }
+
+  /**
+   * Reads a 8-bit unsigned integer from the buffer at the current index position.
+   * Updates the index position by 1 byte after reading the number.
+   *
+   * @returns The read 8 bit value.
+   */
+  public readUInt8(): number {
+    this.index += 1;
+    return this.buffer.readUInt8(this.index - 1);
+  }
+
+  /**
+   * Reads and returns the next boolean value from the buffer.
+   * Advances the internal index by 1, treating the byte at the current index as a boolean value.
+   * Returns true if the byte is non-zero, false otherwise.
+   *
+   * @returns A boolean value representing the byte at the current index.
+   */
+  public readBoolean(): boolean {
+    this.index += 1;
+    return Boolean(this.buffer.at(this.index - 1));
+  }
+
+  /**
+   * Reads a specified number of bytes from the buffer and returns a new Buffer containing those bytes.
+   * Advances the reader's index by the number of bytes read. Throws an error if there are not enough
+   * bytes left in the buffer to satisfy the requested number of bytes.
+   *
+   * @param n - The number of bytes to read from the buffer.
+   * @returns A new Buffer containing the read bytes.
+   */
+  public readBytes(n: number): Buffer {
+    this.index += n;
+    return Buffer.from(this.buffer.subarray(this.index - n, this.index));
+  }
+
+  /** Reads until the end of the buffer. */
+  public readToEnd(): Buffer {
+    const result = this.buffer.subarray(this.index);
+    this.index = this.buffer.length;
+    return result;
+  }
+
+  /**
+   * Reads a vector of numbers from the buffer and returns it as an array of numbers.
+   * The method utilizes the 'readVector' method, passing a deserializer that reads numbers.
+   *
+   * @returns An array of numbers representing the vector read from the buffer.
+   */
+  public readNumberVector(): number[] {
+    return this.readVector({
+      fromBuffer: (reader: BufferReader) => reader.readNumber(),
+    });
+  }
+
+  /**
+   * Reads a vector of fixed size from the buffer and deserializes its elements using the provided itemDeserializer object.
+   * The 'itemDeserializer' object should have a 'fromBuffer' method that takes a BufferReader instance and returns the deserialized element.
+   * The method first reads the size of the vector (a number) from the buffer, then iterates through its elements,
+   * deserializing each one using the 'fromBuffer' method of 'itemDeserializer'.
+   *
+   * @param itemDeserializer - Object with 'fromBuffer' method to deserialize vector elements.
+   * @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[] {
+    const size = this.readNumber();
+    const result = new Array<T>(size);
+    for (let i = 0; i < size; i++) {
+      result[i] = itemDeserializer.fromBuffer(this);
+    }
+    return result;
+  }
+
+  /**
+   * Read an array of a fixed size with elements of type T from the buffer.
+   * The 'itemDeserializer' object should have a 'fromBuffer' method that takes a BufferReader instance as input,
+   * and returns an instance of the desired deserialized data type T.
+   * This method will call the 'fromBuffer' method for each element in the array and return the resulting array.
+   *
+   * @param size - The fixed number of elements in the array.
+   * @param itemDeserializer - An object with a 'fromBuffer' method to deserialize individual elements of type T.
+   * @returns An array of instances of type T.
+   */
+  public readArray<T, N extends number>(
+    size: N,
+    itemDeserializer: {
+      /**
+       * A function for deserializing data from a BufferReader instance.
+       */
+      fromBuffer: (reader: BufferReader) => T;
+    },
+  ): Tuple<T, N> {
+    const result = Array.from({ length: size }, () => itemDeserializer.fromBuffer(this));
+    return result as Tuple<T, N>;
+  }
+
+  /**
+   * Read a variable sized Buffer array where elements are represented by length + data.
+   * The method consecutively looks for a number which is the size of the proceeding buffer,
+   * then reads the bytes until it reaches the end of the reader's internal buffer.
+   * NOTE: if `size` is not provided, this will run to the end of the reader's buffer.
+   * @param size - Size of the buffer array in bytes (full remaining buffer length if left empty).
+   * @returns An array of variable sized buffers.
+   */
+  public readBufferArray(size = -1): Buffer[] {
+    const result: Buffer[] = [];
+    const end = size >= 0 ? this.index + size : this.buffer.length;
+    while (this.index < end) {
+      const item = this.readBuffer();
+      result.push(item);
+    }
+    // Ensure that all bytes have been read.
+    if (this.index !== end) {
+      throw new Error(
+        `Reader buffer was not fully consumed. Consumed up to ${this.index} bytes. End of data: ${end} bytes.`,
+      );
+    }
+    return result;
+  }
+
+  /**
+   * Reads a serialized object from a buffer and returns the deserialized object using the given deserializer.
+   *
+   * @typeparam T - The type of the deserialized object.
+   * @param deserializer - An object with a 'fromBuffer' method that takes a BufferReader instance and returns an instance of the deserialized object.
+   * @returns The deserialized object of type T.
+   */
+  public readObject<T>(deserializer: {
+    /**
+     * A method that takes a BufferReader instance and returns an instance of the deserialized data type.
+     */
+    fromBuffer: (reader: BufferReader) => T;
+  }): T {
+    return deserializer.fromBuffer(this);
+  }
+
+  /**
+   * Returns a Buffer containing the next n bytes from the current buffer without modifying the reader's index position.
+   * If n is not provided or exceeds the remaining length of the buffer, it returns all bytes from the current position till the end of the buffer.
+   *
+   * @param n - The number of bytes to peek from the current buffer. (Optional).
+   * @returns A Buffer with the next n bytes or the remaining bytes if n is not provided or exceeds the buffer length.
+   */
+  public peekBytes(n?: number): Buffer {
+    return this.buffer.subarray(this.index, n ? this.index + n : undefined);
+  }
+
+  /**
+   * Reads a string from the buffer and returns it.
+   * 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.
+   *
+   * @returns The read string from the buffer.
+   */
+  public readString(): string {
+    return this.readBuffer().toString();
+  }
+
+  /**
+   * Reads a buffer from the current position of the reader and advances the index.
+   * The method first reads the size (number) of bytes to be read, and then returns
+   * a Buffer with that size containing the bytes. Useful for reading variable-length
+   * binary data encoded as (size, data) format.
+   *
+   * @returns A Buffer containing the read bytes.
+   */
+  public readBuffer(): Buffer {
+    const size = this.readNumber();
+    return this.readBytes(size);
+  }
+
+  /**
+   * Reads and constructs a map object from the current buffer using the provided deserializer.
+   * The method reads the number of entries in the map, followed by iterating through each key-value pair.
+   * The key is read as a string, while the value is obtained using the passed deserializer's `fromBuffer` method.
+   * The resulting map object is returned, containing all the key-value pairs read from the buffer.
+   *
+   * @param deserializer - An object with a `fromBuffer` method to deserialize the values in the map.
+   * @returns A map object with string keys and deserialized values based on the provided deserializer.
+   */
+  public readMap<T>(deserializer: {
+    /**
+     * Deserializes an element of type T from a BufferReader instance.
+     */
+    fromBuffer: (reader: BufferReader) => T;
+  }): { [key: string]: T } {
+    const numEntries = this.readNumber();
+    const map: { [key: string]: T } = {};
+    for (let i = 0; i < numEntries; i++) {
+      const key = this.readString();
+      const value = this.readObject<T>(deserializer);
+      map[key] = value;
+    }
+    return map;
+  }
+
+  /**
+   * Get the length of the reader's buffer.
+   * @returns The length of the underlying reader's buffer.
+   */
+  public getLength(): number {
+    return this.buffer.length;
+  }
+}