@aztec/foundation 0.23.0 → 0.26.1

package/src/fields/point.ts

@@ -0,0 +1,145 @@
+import { BufferReader, FieldReader } from '../serialize/index.js';
+import { Fr } from './fields.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(Fr.ZERO, Fr.ZERO);
+  static SIZE_IN_BYTES = Fr.SIZE_IN_BYTES * 2;
+
+  /** Used to differentiate this class from AztecAddress */
+  public readonly kind = 'point';
+
+  constructor(
+    /**
+     * The point's x coordinate
+     */
+    public readonly x: Fr,
+    /**
+     * The point's y coordinate
+     */
+    public readonly y: Fr,
+  ) {}
+
+  /**
+   * 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(Fr.random(), Fr.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(Fr.fromBuffer(reader.readBytes(32)), Fr.fromBuffer(reader.readBytes(32)));
+  }
+
+  /**
+   * 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'));
+  }
+
+  /**
+   * Returns the contents of the point as an array of 2 fields.
+   * @returns The point as an array of 2 fields
+   */
+  toFields() {
+    return [this.x, this.y];
+  }
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+    return new this(reader.readField(), reader.readField());
+  }
+
+  /**
+   * Returns the contents of the point as BigInts.
+   * @returns The point as BigInts
+   */
+  toBigInts() {
+    return {
+      x: this.x.toBigInt(),
+      y: this.y.toBigInt(),
+    };
+  }
+
+  /**
+   * Converts the Point instance to a Buffer representation 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);
+  }
+
+  isZero() {
+    return this.x.isZero() && this.y.isZero();
+  }
+}
+
+/**
+ * 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 { createDebugLogger } from '../log/index.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 = createDebugLogger('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 successfully enqueued.
+   * The fn itself is execute asynchronously 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.error('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 executed.
+   */
+  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,118 @@
+import { createDebugLogger } from '../log/index.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 = createDebugLogger('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.
+   * @returns A boolean indicating whether the item was successfully added to the queue.
+   */
+  public put(item: T): boolean {
+    if (this.flushing) {
+      this.log.warn('Discarding item because queue is flushing');
+      return false;
+    } else if (this.waiting.length) {
+      this.waiting.shift()!(item);
+      return true;
+    } else {
+      this.items.push(item);
+      return true;
+    }
+  }
+
+  /**
+   * 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 and 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 and 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.error('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);
+  }
+}

package/src/fifo/serial_queue.ts

@@ -0,0 +1,81 @@
+import { MemoryFifo } from './memory_fifo.js';
+
+/**
+ * A more specialized fifo queue that enqueues functions to execute. Enqueued functions are executed in serial.
+ */
+export class SerialQueue {
+  private readonly queue = new MemoryFifo<() => Promise<void>>();
+  private runningPromise!: Promise<void>;
+
+  /**
+   * Initializes the execution of enqueued functions in the serial queue.
+   * Functions are executed in the order they were added to the queue, with each function
+   * waiting for the completion of the previous one before starting its execution.
+   * This method should be called once to start processing the queue.
+   */
+  public start() {
+    this.runningPromise = this.queue.process(fn => fn());
+  }
+
+  /**
+   * Returns the current number of enqueued functions in the serial queue.
+   * This provides a way to check the size of the queue and monitor its progress.
+   *
+   * @returns The length of the serial queue as a number.
+   */
+  public length() {
+    return this.queue.length();
+  }
+
+  /**
+   * Cancels the processing of the remaining functions in the serial queue and resolves the running promise.
+   * Any enqueued functions that have not yet been executed will be discarded. The queue can still accept new
+   * functions after cancellation, but the previously enqueued functions will not be re-processed.
+   *
+   * @returns The running promise which resolves when the current executing function (if any) completes.
+   */
+  public cancel() {
+    this.queue.cancel();
+    return this.runningPromise;
+  }
+
+  /**
+   * Signals the SerialQueue that it should finish processing its current task and stop accepting new tasks.
+   * The returned Promise resolves when all enqueued tasks have completed execution.
+   *
+   * @returns A Promise that resolves when the queue is completely emptied and no new tasks are allowed.
+   */
+  public end() {
+    this.queue.end();
+    return this.runningPromise;
+  }
+
+  /**
+   * Enqueues fn for execution on the serial queue.
+   * Returns the result of the function after execution.
+   * @param fn - The function to enqueue.
+   * @returns A resolution promise. Rejects if the function does, or if the function could not be enqueued.
+   */
+  public put<T>(fn: () => Promise<T>): Promise<T> {
+    return new Promise((resolve, reject) => {
+      const accepted = this.queue.put(async () => {
+        try {
+          const res = await fn();
+          resolve(res);
+        } catch (e) {
+          reject(e);
+        }
+      });
+      if (!accepted) {
+        reject(new Error('Could not enqueue function'));
+      }
+    });
+  }
+
+  /**
+   * Awaiting this ensures the queue is empty before resuming.
+   */
+  public async syncPoint() {
+    await this.put(async () => {});
+  }
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+// Reexport all folders at the root for packages targeting CommonJS
+export * as abi from './abi/index.js';
+export * as asyncMap from './async-map/index.js';
+export * as aztecAddress from './aztec-address/index.js';
+export * as bigintBuffer from './bigint-buffer/index.js';
+export * as collection from './collection/index.js';
+export * as committable from './committable/index.js';
+export * as crypto from './crypto/index.js';
+export * as errors from './errors/index.js';
+export * as ethAddress from './eth-address/index.js';
+export * as fields from './fields/index.js';
+export * as fifo from './fifo/index.js';
+export * as jsonRpc from './json-rpc/index.js';
+export * as jsonRpcClient from './json-rpc/client/index.js';
+export * as jsonRpcServer from './json-rpc/server/index.js';
+export * as log from './log/index.js';
+export * as mutex from './mutex/index.js';
+export * as retry from './retry/index.js';
+export * as runningPromise from './running-promise/index.js';
+export * as serialize from './serialize/index.js';
+export * as sleep from './sleep/index.js';
+export * as timer from './timer/index.js';
+export * as transport from './transport/index.js';
+export * as trees from './trees/index.js';
+export * as types from './types/index.js';
+export * as url from './url/index.js';
+export * as wasm from './wasm/index.js';
+export * as worker from './worker/index.js';
+export * as testing from './testing/index.js';

package/src/json-rpc/README.md

@@ -0,0 +1,55 @@
+# json-rpc
+
+json-rpc
+
+```
+-- src
+    -- client
+      Code to use by a client wishing to use a json-rpc server
+      Includes syntax sugar for making requests with normal method syntax
+    -- server
+      Code for easily turning a class into an exposed RPC with one endpoint per method
+```
+
+Each createJsonRpcClient and JsonRpcServer call needs a map of classes that will be translated in input and output values.
+By default, Buffer is handled, but other user-made classes need to define toString() and static fromString() like so:
+
+```
+   class PublicKey {
+     toString() {
+       return '...';
+     }
+     static fromString(str) {
+       return new PublicKey(...);
+     }
+   }
+```
+
+## Usage
+
+In Dapp:
+
+```
+const wallet = createJsonRpcClient<WalletImplementation>('wallet-server.com', /*register classes*/ {PublicKey, TxRequest});
+const response = await wallet.signTxRequest(accountPubKey, txRequest);
+```
+
+The client will send `[{ name: 'PublicKey', value: accountPubKey.toString() }, { name: 'TxRequest', txRequest.toString() }]` to the server.
+
+In wallet:
+
+```
+const publicClient = createJsonRpcClient<PublicClient>('public-client.com',  /*register classes*/ ...);
+const keyStore = createJsonRpcClient<KeyStore>('key-store.com',  /*register classes*/ ...);
+```
+
+Different clients for different services.
+
+-- server
+Running a wallet server:
+
+```
+const wallet = new WalletImplementation();
+const server = new JsonRpcServer(wallet,  /*register classes*/ ...);
+server.start(8080);
+```