@aztec/foundation 0.1.0-alpha10

package/src/fields/fields.ts

@@ -0,0 +1,234 @@
+import { randomBytes } from 'crypto';
+import { BufferReader } from '../serialize/buffer_reader.js';
+import { toBigIntBE, toBufferBE, toHex } from '../bigint-buffer/index.js';
+
+/**
+ * Fr represents a field of integers modulo the prime number MODULUS.
+ * It provides utility functions to work with elements in this field, such as conversions between different representations and checks for equality and zero values. The elements can be serialized to and deserialized from byte buffers or strings.
+ * Some use cases include working with cryptographic operations and finite fields.
+ */
+export class Fr {
+  static ZERO = new Fr(0n);
+  static MODULUS = 0x30644e72e131a029b85045b68181585d2833e84879b9709143e1f593f0000001n;
+  static MAX_VALUE = Fr.MODULUS - 1n;
+  static SIZE_IN_BYTES = 32;
+
+  /**
+   * The numeric value of the field element as a bigint.
+   */
+  public readonly value;
+
+  constructor(value: bigint | number) {
+    this.value = BigInt(value);
+    // if (value > Fr.MAX_VALUE) {
+    //   throw new Error(`Fr out of range ${value}.`);
+    // }
+  }
+
+  /**
+   * Generates a random Fr or Fq instance with a value modulo the respective class' MODULUS.
+   * This method uses randomBytes to generate a random 32-byte buffer, converts it to a bigint
+   * and takes the modulus of the result with the class' MODULUS constant.
+   *
+   * @returns A new Fr or Fq instance with a random value.
+   */
+  static random() {
+    const r = toBigIntBE(randomBytes(Fr.SIZE_IN_BYTES)) % Fr.MODULUS;
+    return new Fr(r);
+  }
+
+  /**
+   * Returns a new zero-value field.
+   * @returns A new zero-value field.
+   */
+  static zero() {
+    return new Fr(0n);
+  }
+
+  /**
+   * Create an instance of the corresponding class (Fr or Fq) from a Buffer or a BufferReader.
+   * Reads 'SIZE_IN_BYTES' bytes from the given Buffer or BufferReader and constructs an instance with the decoded value.
+   * If the input is a Buffer, it is internally converted to a BufferReader before reading.
+   * Throws an error if the input length is invalid or the decoded value is out of range.
+   *
+   * @param buffer - The Buffer or BufferReader containing the bytes representing the value.
+   * @returns An instance of the corresponding class (Fr or Fq) with the decoded value.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new Fr(toBigIntBE(reader.readBytes(Fr.SIZE_IN_BYTES)));
+  }
+
+  /**
+   * Create a Fr instance from a hex-encoded string.
+   * The input 'address' can be either prefixed with '0x' or not, and should have exactly 64 hex characters.
+   * Throws an error if the input length is invalid or the address value is out of range.
+   *
+   * @param address - The hex-encoded string representing the field element.
+   * @returns A Fr instance.
+   */
+  static fromString(address: string) {
+    return Fr.fromBuffer(Buffer.from(address.replace(/^0x/i, ''), 'hex'));
+  }
+
+  /**
+   * Converts the value of the instance to a buffer with a specified length.
+   * The method uses the provided value and size in bytes to create a buffer representation
+   * of the numeric value. This can be useful for serialization and communication purposes.
+   *
+   * @returns A buffer representing the instance's value.
+   */
+  toBuffer() {
+    return toBufferBE(this.value, Fr.SIZE_IN_BYTES);
+  }
+
+  /**
+   * Converts the value of the Fr or Fq class instance to a hexadecimal string.
+   * The resulting string is prefixed with '0x' and represents the bigint value
+   * in base 16.
+   *
+   * @param padTo32 - Whether to pad the string to 32 bytes.
+   * @returns A hex-encoded string representing the value of the class instance.
+   */
+  toString(padTo32 = false): `0x${string}` {
+    return toHex(this.value, padTo32);
+  }
+
+  /**
+   * Returns a shortened string representation of the Fr value, formatted with '0x' prefix and ellipsis in the middle.
+   * The resulting string has first 10 characters (including '0x') and last 4 characters of the full hexadecimal value.
+   *
+   * @returns A shorter, human-readable string representation of the Fr value.
+   */
+  toShortString() {
+    const str = this.toString();
+    return `${str.slice(0, 10)}...${str.slice(-4)}`;
+  }
+
+  /**
+   * Checks if the provided Fr instance is equal to the current instance.
+   * Two instances are considered equal if their 'value' properties are the same.
+   *
+   * @param rhs - The Fr instance to compare with the current instance.
+   * @returns A boolean indicating whether the two instances are equal.
+   */
+  equals(rhs: Fr) {
+    return this.value === rhs.value;
+  }
+
+  /**
+   * Check if the instance value is zero.
+   * The method returns true if the value of the instance is 0n (zero in BigInt representation),
+   * otherwise, it returns false.
+   *
+   * @returns A boolean indicating whether the instance value is zero or not.
+   */
+  isZero() {
+    return this.value === 0n;
+  }
+
+  /**
+   * Converts the current value of the Fq or Fr instance to a friendly JSON representation.
+   * The output will be a hexadecimal string prefixed with '0x'.
+   *
+   * @returns A '0x' prefixed hexadecimal string representing the current value.
+   */
+  toFriendlyJSON() {
+    return this.toString();
+  }
+}
+
+/**
+ * Fq represents a field element in a prime finite field with modulus defined by the constant MODULUS.
+ * It provides methods for creating, manipulating, and comparing field elements, as well as converting
+ * them to/from different data types like Buffers and hex strings. Field elements are used in various
+ * cryptographic protocols and operations, such as elliptic curve cryptography.
+ *
+ * @example
+ * const fqElem = new Fq(BigInt("123456789"));
+ * const randomFqElem = Fq.random();
+ * const fromBufferFqElem = Fq.fromBuffer(buffer);
+ */
+export class Fq {
+  static MODULUS = 0x30644e72e131a029b85045b68181585d97816a916871ca8d3c208c16d87cfd47n;
+  static MAX_VALUE = Fr.MODULUS - 1n;
+  static SIZE_IN_BYTES = 32;
+
+  constructor(
+    /**
+     * The element's value as a bigint in the finite field.
+     */
+    public readonly value: bigint,
+  ) {
+    if (value > Fq.MAX_VALUE) {
+      throw new Error(`Fr out of range ${value}.`);
+    }
+  }
+
+  /**
+   * Generates a random Fr or Fq instance with a value within the range of their respective modulus.
+   * The random value is generated from a byte array of length equal to SIZE_IN_BYTES, then truncated
+   * to the appropriate modulus before creating the new Fr or Fq instance.
+   *
+   * @returns A new Fr or Fq instance with a randomly generated value.
+   */
+  static random() {
+    const r = toBigIntBE(randomBytes(64)) % Fq.MODULUS;
+    return new this(r);
+  }
+
+  /**
+   * Create an instance of the calling class (Fr or Fq) from a given buffer or BufferReader.
+   * Reads SIZE_IN_BYTES from the provided buffer and converts it to a bigint, then creates a new instance
+   * with that value. Throws an error if the value is out of range for the calling class.
+   *
+   * @param buffer - The input buffer or BufferReader containing the bytes representing the value.
+   * @returns An instance of the calling class (Fr or Fq) initialized with the bigint value.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new this(toBigIntBE(reader.readBytes(this.SIZE_IN_BYTES)));
+  }
+
+  /**
+   * Converts the bigint value of the instance to a Buffer representation.
+   * The output buffer has a fixed size, determined by the 'SIZE_IN_BYTES' constant.
+   *
+   * @returns A Buffer containing the byte representation of the instance's value.
+   */
+  toBuffer() {
+    return toBufferBE(this.value, Fq.SIZE_IN_BYTES);
+  }
+
+  /**
+   * Converts the Fq value to a hexadecimal string representation.
+   * The resulting string is prefixed with '0x' and contains the exact number of hex characters required
+   * to represent the numeric value of this instance.
+   *
+   * @returns A hexadecimal string representing the Fq value.
+   */
+  toString() {
+    return toHex(this.value);
+  }
+
+  /**
+   * Check if the value of the current instance is zero.
+   * This function compares the internal 'value' property with 0n (BigInt representation of zero).
+   * Returns true if the value is zero, otherwise returns false.
+   *
+   * @returns A boolean indicating whether the value is zero or not.
+   */
+  isZero() {
+    return this.value === 0n;
+  }
+
+  /**
+   * Converts the value of the Fr or Fq instance to a friendly JSON format.
+   * The output is a hexadecimal string representation of the value with '0x' prefix.
+   *
+   * @returns A string representing the value in the JSON format.
+   */
+  toFriendlyJSON() {
+    return this.toString();
+  }
+}

package/src/fields/index.ts

@@ -0,0 +1,3 @@
+export * from './fields.js';
+export * from './point.js';
+export * from './coordinate.js';

package/src/fields/point.ts

@@ -0,0 +1,143 @@
+import { BufferReader } from '../serialize/buffer_reader.js';
+import { Coordinate } from './coordinate.js';
+
+/**
+ * Represents a Point on an elliptic curve with x and y coordinates.
+ * The Point class provides methods for creating instances from different input types,
+ * converting instances to various output formats, and checking the equality of points.
+ */
+export class Point {
+  static ZERO = new Point(Coordinate.ZERO, Coordinate.ZERO);
+
+  /** Used to differentiate this class from AztecAddress */
+  public readonly kind = 'point';
+
+  constructor(
+    /**
+     * The point's x coordinate
+     */
+    public readonly x: Coordinate,
+    /**
+     * The point's y coordinate
+     */
+    public readonly y: Coordinate,
+  ) {}
+
+  /**
+   * Generate a random Point instance.
+   *
+   * @returns A randomly generated Point instance.
+   */
+  static random() {
+    // TODO is this a random point on the curve?
+    return new Point(Coordinate.random(), Coordinate.random());
+  }
+
+  /**
+   * Create a Point instance from a given buffer or BufferReader.
+   * The input 'buffer' should have exactly 64 bytes representing the x and y coordinates.
+   *
+   * @param buffer - The buffer or BufferReader containing the x and y coordinates of the point.
+   * @returns A Point instance.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new this(Coordinate.fromBuffer(reader.readBytes(32)), Coordinate.fromBuffer(reader.readBytes(32)));
+  }
+
+  /**
+   * Creates a point instance from its x and y coordinates.
+   * @param x - X coordinate.
+   * @param y - Y coordinate.
+   * @returns A Point instance.
+   */
+  static fromCoordinates(x: Coordinate, y: Coordinate) {
+    return new this(x, y);
+  }
+
+  /**
+   * Create a Point instance from a hex-encoded string.
+   * The input 'address' should be prefixed with '0x' or not, and have exactly 128 hex characters representing the x and y coordinates.
+   * Throws an error if the input length is invalid or coordinate values are out of range.
+   *
+   * @param address - The hex-encoded string representing the Point coordinates.
+   * @returns A Point instance.
+   */
+  static fromString(address: string) {
+    return this.fromBuffer(Buffer.from(address.replace(/^0x/i, ''), 'hex'));
+  }
+
+  /**
+   * Convert the Point instance to a Buffer representation of fields
+   * The output buffer's length will be (128 bytes).
+   * This method is useful for serialization and deserialization of the Point object.
+   *
+   * @returns A Buffer representation of the Point instance.
+   */
+  toFieldsBuffer() {
+    return Buffer.concat([this.x.toFieldsBuffer(), this.y.toFieldsBuffer()]);
+  }
+
+  /**
+   * Returns the contents of the point as an array of 4 fields.
+   * @returns The point as an array of 4 fields
+   */
+  toFields() {
+    return this.x.toFields().concat(this.y.toFields());
+  }
+
+  /**
+   * Converts the Point instance to a Buffer representaion of the coordinates.
+   * The outputs buffer length will be 64, the length of both coordinates not represented as fields.
+   * @returns A Buffer representation of the Point instance.
+   */
+  toBuffer() {
+    return Buffer.concat([this.x.toBuffer(), this.y.toBuffer()]);
+  }
+
+  /**
+   * Convert the Point instance to a hexadecimal string representation.
+   * The output string is prefixed with '0x' and consists of exactly 128 hex characters,
+   * representing the concatenated x and y coordinates of the point.
+   *
+   * @returns A hex-encoded string representing the Point instance.
+   */
+  toString() {
+    return '0x' + this.toBuffer().toString('hex');
+  }
+
+  /**
+   * Generate a short string representation of the Point instance.
+   * The returned string includes the first 10 and last 4 characters of the full string representation,
+   * with '...' in between to indicate truncation. This is useful for displaying or logging purposes
+   * when the full string representation may be too long.
+   *
+   * @returns A truncated string representation of the Point instance.
+   */
+  toShortString() {
+    const str = this.toString();
+    return `${str.slice(0, 10)}...${str.slice(-4)}`;
+  }
+
+  /**
+   * Check if two Point instances are equal by comparing their buffer values.
+   * Returns true if the buffer values are the same, and false otherwise.
+   *
+   * @param rhs - The Point instance to compare with the current instance.
+   * @returns A boolean indicating whether the two Point instances are equal.
+   */
+  equals(rhs: Point) {
+    return this.x.equals(rhs.x) && this.y.equals(rhs.y);
+  }
+}
+
+/**
+ * Does this object look like a point?
+ * @param obj - Object to test if it is a point.
+ * @returns Whether it looks like a point.
+ */
+export function isPoint(obj: object): obj is Point {
+  if (!obj) return false;
+  const point = obj as Point;
+  return point.kind === 'point' && point.x !== undefined && point.y !== undefined;
+}

package/src/fifo/bounded_serial_queue.ts

@@ -0,0 +1,100 @@
+import { createLogger } from '../log/console.js';
+import { Semaphore } from './semaphore.js';
+import { SerialQueue } from './serial_queue.js';
+
+/**
+ * Leverages the unbounded SerialQueue and Semaphore to create a SerialQueue that will block when putting an item
+ * if the queue size = maxQueueSize.
+ */
+export class BoundedSerialQueue {
+  private readonly queue = new SerialQueue();
+  private semaphore: Semaphore;
+
+  constructor(maxQueueSize: number, private log = createLogger('aztec:foundation:bounded_serial_queue')) {
+    this.semaphore = new Semaphore(maxQueueSize);
+  }
+
+  /**
+   * Initializes the underlying SerialQueue instance, allowing items to be processed from the queue.
+   * The start method should be called before using the BoundedSerialQueue to ensure proper functionality.
+   */
+  public start() {
+    this.queue.start();
+  }
+
+  /**
+   * Returns the current number of items in the queue.
+   * This is useful for monitoring the size of BoundedSerialQueue and understanding its utilization.
+   *
+   * @returns The length of the queue as an integer value.
+   */
+  public length() {
+    return this.queue.length();
+  }
+
+  /**
+   * Cancels the current operation in the SerialQueue, if any, and clears the queue.
+   * Any pending tasks in the queue will not be executed, and the queue will be emptied.
+   * This method is useful for cleaning up resources and stopping ongoing processes when they are no longer needed.
+   * @returns A promise, resolved once cancelled.
+   */
+  public cancel() {
+    return this.queue.cancel();
+  }
+
+  /**
+   * Ends the queue processing gracefully, preventing new items from being added.
+   * The currently executing item, if any, will complete and remaining queued items
+   * will be processed in order. Once all items have been processed, the queue becomes
+   * permanently unusable.
+   *
+   * @returns A promise that resolves when all items in the queue have been processed.
+   */
+  public end() {
+    return this.queue.end();
+  }
+
+  /**
+   * The caller will block until fn is succesfully enqueued.
+   * The fn itself is execute asyncronously and its result discarded.
+   * TODO(AD) do we need this if we have exec()?
+   * @param fn - The function to call once unblocked.
+   */
+  public async put(fn: () => Promise<void>): Promise<void> {
+    await this.semaphore.acquire();
+    this.queue
+      .put(async () => {
+        try {
+          await fn();
+        } finally {
+          this.semaphore.release();
+        }
+      })
+      .catch(err => {
+        this.log('BoundedSerialQueue handler exception:', err);
+      });
+  }
+
+  /**
+   * The caller will block until fn is successfully executed, and it's result returned.
+   * @param fn - The function.
+   * @returns A promise that resolves with the result once exceuted.
+   */
+  public async exec<T>(fn: () => Promise<T>): Promise<T> {
+    await this.semaphore.acquire();
+    return this.queue.put(async () => {
+      try {
+        return await fn();
+      } finally {
+        this.semaphore.release();
+      }
+    });
+  }
+
+  /**
+   * Awaiting this ensures the queue is empty before resuming.
+   */
+  public async syncPoint() {
+    await this.queue.syncPoint();
+  }
+}

package/src/fifo/index.ts

@@ -0,0 +1,4 @@
+export * from './memory_fifo.js';
+export * from './serial_queue.js';
+export * from './bounded_serial_queue.js';
+export * from './semaphore.js';

package/src/fifo/memory_fifo.ts

@@ -0,0 +1,114 @@
+import { createLogger } from '../log/console.js';
+
+/**
+ * A simple fifo queue. It can grow unbounded. It can have multiple producers and consumers.
+ * Putting an item onto the queue always succeeds, unless either end() or cancel() has been called in which case
+ * the item being pushed is simply discarded.
+ */
+export class MemoryFifo<T> {
+  private waiting: ((item: T | null) => void)[] = [];
+  private items: T[] = [];
+  private flushing = false;
+
+  constructor(private log = createLogger('aztec:foundation:memory_fifo')) {}
+
+  /**
+   * Returns the current number of items in the queue.
+   * The length represents the size of the queue at the time of invocation and may change as new items are added or consumed.
+   *
+   * @returns The number of items in the queue.
+   */
+  public length() {
+    return this.items.length;
+  }
+
+  /**
+   * Returns next item within the queue, or blocks until and item has been put into the queue.
+   * If given a timeout, the promise will reject if no item is received after `timeout` seconds.
+   * If the queue is flushing, `null` is returned.
+   * @param timeout - The timeout in seconds.
+   * @returns A result promise.
+   */
+  public get(timeout?: number): Promise<T | null> {
+    if (this.items.length) {
+      return Promise.resolve(this.items.shift()!);
+    }
+
+    if (this.items.length === 0 && this.flushing) {
+      return Promise.resolve(null);
+    }
+
+    return new Promise<T | null>((resolve, reject) => {
+      this.waiting.push(resolve);
+
+      if (timeout) {
+        setTimeout(() => {
+          const index = this.waiting.findIndex(r => r === resolve);
+          if (index > -1) {
+            this.waiting.splice(index, 1);
+            const err = new Error('Timeout getting item from queue.');
+            reject(err);
+          }
+        }, timeout * 1000);
+      }
+    });
+  }
+
+  /**
+   * Put an item onto back of the queue.
+   * @param item - The item to enqueue.
+   */
+  public put(item: T) {
+    if (this.flushing) {
+      return;
+    } else if (this.waiting.length) {
+      this.waiting.shift()!(item);
+    } else {
+      this.items.push(item);
+    }
+  }
+
+  /**
+   * Once ended, no further items are added to queue. Consumers will consume remaining items within the queue.
+   * The queue is not reusable after calling `end()`.
+   * Any consumers waiting for an item receive null.
+   */
+  public end() {
+    this.flushing = true;
+    this.waiting.forEach(resolve => resolve(null));
+  }
+
+  /**
+   * Once cancelled, all items are discarded from the queue, and no further items are added to the queue.
+   * The queue is not reusable after calling `cancel()`.
+   * Any consumers waiting for an item receive null.
+   */
+  public cancel() {
+    this.flushing = true;
+    this.items = [];
+    this.waiting.forEach(resolve => resolve(null));
+  }
+
+  /**
+   * Process items from the queue using a provided handler function.
+   * The function iterates over items in the queue, invoking the handler for each item until the queue is empty or flushing.
+   * If the handler throws an error, it will be caught and logged as 'Queue handler exception:', but the iteration will continue.
+   * The process function returns a promise that resolves when there are no more items in the queue or the queue is flushing.
+   *
+   * @param handler - A function that takes an item of type T and returns a Promise<void> after processing the item.
+   * @returns A Promise<void> that resolves when the queue is finished processing.
+   */
+  public async process(handler: (item: T) => Promise<void>) {
+    try {
+      while (true) {
+        const item = await this.get();
+        if (item === null) {
+          break;
+        }
+        await handler(item);
+      }
+    } catch (err) {
+      this.log('Queue handler exception:', err);
+    }
+  }
+}

package/src/fifo/semaphore.ts

@@ -0,0 +1,33 @@
+import { MemoryFifo } from './memory_fifo.js';
+
+/**
+ * Allows the acquiring of up to `size` tokens before calls to acquire block, waiting for a call to release().
+ */
+export class Semaphore {
+  private readonly queue = new MemoryFifo<boolean>();
+
+  constructor(size: number) {
+    new Array(size).fill(true).map(() => this.queue.put(true));
+  }
+
+  /**
+   * Acquires a token from the Semaphore, allowing access to a limited resource.
+   * If no tokens are available, the call will block and wait until a token is released.
+   * Use in conjunction with the release() method to manage access to resources with limited capacity.
+   *
+   * @returns A Promise that resolves when a token is acquired.
+   */
+  public async acquire() {
+    await this.queue.get();
+  }
+
+  /**
+   * Releases a token back into the semaphore, allowing another acquire call to proceed.
+   * If there are any pending calls to acquire(), one of them will be unblocked and allowed to proceed.
+   * This method should only be called by the holder of the acquired token to ensure proper functionality
+   * and avoid unexpected behavior.
+   */
+  public release() {
+    this.queue.put(true);
+  }
+}