@aztec/foundation 0.0.0-test.0

package/src/fields/point.ts

@@ -0,0 +1,300 @@
+import { toBigIntBE } from '../bigint-buffer/index.js';
+import { poseidon2Hash } from '../crypto/poseidon/index.js';
+import { randomBoolean } from '../crypto/random/index.js';
+import { hexSchemaFor } from '../schemas/utils.js';
+import { BufferReader, FieldReader, serializeToBuffer } from '../serialize/index.js';
+import { bufferToHex, hexToBuffer } from '../string/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.
+ * TODO(#7386): Clean up this class.
+ */
+export class Point {
+  static ZERO = new Point(Fr.ZERO, Fr.ZERO, false);
+  static SIZE_IN_BYTES = Fr.SIZE_IN_BYTES * 2;
+  static COMPRESSED_SIZE_IN_BYTES = Fr.SIZE_IN_BYTES;
+
+  /** 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,
+    /**
+     * Whether the point is at infinity
+     */
+    public readonly isInfinite: boolean,
+  ) {
+    // TODO(#7386): check if on curve
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  static get schema() {
+    return hexSchemaFor(Point);
+  }
+
+  /**
+   * Generate a random Point instance.
+   *
+   * @returns A randomly generated Point instance.
+   */
+  static async random() {
+    while (true) {
+      try {
+        return await Point.fromXAndSign(Fr.random(), randomBoolean());
+      } catch (e: any) {
+        if (!(e instanceof NotOnCurveError)) {
+          throw e;
+        }
+        // The random point is not on the curve - we try again
+        continue;
+      }
+    }
+  }
+
+  /**
+   * 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), Fr.fromBuffer(reader), false);
+  }
+
+  /**
+   * Create a Point instance from a compressed buffer.
+   * The input 'buffer' should have exactly 33 bytes representing the x coordinate and the sign of the y coordinate.
+   *
+   * @param buffer - The buffer containing the x coordinate and the sign of the y coordinate.
+   * @returns A Point instance.
+   */
+  static fromCompressedBuffer(buffer: Buffer | BufferReader): Promise<Point> {
+    const reader = BufferReader.asReader(buffer);
+    const value = toBigIntBE(reader.readBytes(Point.COMPRESSED_SIZE_IN_BYTES));
+
+    const x = new Fr(value & ((1n << 255n) - 1n));
+    const sign = (value & (1n << 255n)) !== 0n;
+
+    return this.fromXAndSign(x, sign);
+  }
+
+  /**
+   * Create a Point instance from a hex-encoded string.
+   * The input 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 str - The hex-encoded string representing the Point coordinates.
+   * @returns A Point instance.
+   */
+  static fromString(str: string) {
+    return this.fromBuffer(hexToBuffer(str));
+  }
+
+  /**
+   * 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, new Fr(this.isInfinite)];
+  }
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+    return new this(reader.readField(), reader.readField(), reader.readBoolean());
+  }
+
+  /**
+   * Uses the x coordinate and isPositive flag (+/-) to reconstruct the point.
+   * @dev The y coordinate can be derived from the x coordinate and the "sign" flag by solving the grumpkin curve
+   * equation for y.
+   * @param x - The x coordinate of the point
+   * @param sign - The "sign" of the y coordinate - note that this is not a sign as is known in integer arithmetic.
+   * Instead it is a boolean flag that determines whether the y coordinate is <= (Fr.MODULUS - 1) / 2
+   * @returns The point as an array of 2 fields
+   */
+  static async fromXAndSign(x: Fr, sign: boolean) {
+    const y = await Point.YFromX(x);
+    if (y == null) {
+      throw new NotOnCurveError(x);
+    }
+
+    const yPositiveBigInt = y.toBigInt() <= (Fr.MODULUS - 1n) / 2n ? y.toBigInt() : Fr.MODULUS - y.toBigInt();
+    const yNegativeBigInt = Fr.MODULUS - yPositiveBigInt;
+
+    // Choose the positive or negative root based on isPositive
+    const finalY = sign ? new Fr(yPositiveBigInt) : new Fr(yNegativeBigInt);
+
+    // Create and return the new Point
+    return new this(x, finalY, false);
+  }
+
+  /**
+   * @returns
+   */
+  static YFromX(x: Fr): Promise<Fr | null> {
+    // Calculate y^2 = x^3 - 17 (i.e. the Grumpkin curve equation)
+    const ySquared = x.square().mul(x).sub(new Fr(17));
+
+    // y is then simply the square root. Note however that not all square roots exist in the field: if sqrt returns null
+    // then there is no point in the curve with this x coordinate.
+    return ySquared.sqrt();
+  }
+
+  /**
+   * Returns the x coordinate and the sign of the y coordinate.
+   * @dev The y sign can be determined by checking if the y coordinate is greater than half of the modulus.
+   * @returns The x coordinate and the sign of the y coordinate.
+   */
+  toXAndSign(): [Fr, boolean] {
+    return [this.x, this.y.toBigInt() <= (Fr.MODULUS - 1n) / 2n];
+  }
+
+  /**
+   * Returns the contents of the point as BigInts.
+   * @returns The point as BigInts
+   */
+  toBigInts() {
+    return {
+      x: this.x.toBigInt(),
+      y: this.y.toBigInt(),
+      isInfinite: this.isInfinite ? 1n : 0n,
+    };
+  }
+
+  /**
+   * Converts the Point instance to a Buffer representation of the coordinates.
+   * @returns A Buffer representation of the Point instance.
+   * @dev Note that toBuffer does not include the isInfinite flag and other serialization methods do (e.g. toFields).
+   * This is because currently when we work with point as bytes we don't want to populate the extra bytes for
+   * isInfinite flag because:
+   * 1. Our Grumpkin BB API currently does not handle point at infinity,
+   * 2. we use toBuffer when serializing notes and events and there we only work with public keys and point at infinity
+   *   is not considered a valid public key and the extra byte would raise DA cost.
+   */
+  toBuffer() {
+    if (this.isInfinite) {
+      throw new Error('Cannot serialize infinite point without isInfinite flag');
+    }
+    const buf = serializeToBuffer([this.x, this.y]);
+    if (buf.length !== Point.SIZE_IN_BYTES) {
+      throw new Error(`Invalid buffer length for Point: ${buf.length}`);
+    }
+    return buf;
+  }
+
+  /**
+   * Converts the Point instance to a compressed Buffer representation of the coordinates.
+   * @returns A Buffer representation of the Point instance
+   */
+  toCompressedBuffer() {
+    const [x, sign] = this.toXAndSign();
+    // Here we leverage that Fr fits into 254 bits (log2(Fr.MODULUS) < 254) and given that we serialize Fr to 32 bytes
+    // and we use big-endian the 2 most significant bits are never populated. Hence we can use one of the bits as
+    // a sign bit.
+    const compressedValue = x.toBigInt() + (sign ? 2n ** 255n : 0n);
+    const buf = serializeToBuffer(compressedValue);
+    if (buf.length !== Point.COMPRESSED_SIZE_IN_BYTES) {
+      throw new Error(`Invalid buffer length for compressed Point: ${buf.length}`);
+    }
+    return buf;
+  }
+
+  /**
+   * 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 bufferToHex(this.toBuffer());
+  }
+
+  /**
+   * 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)}`;
+  }
+
+  toNoirStruct() {
+    /* eslint-disable camelcase */
+    return { x: this.x, y: this.y, is_infinite: this.isInfinite };
+    /* eslint-enable camelcase */
+  }
+
+  // Used for IvpkM, OvpkM, NpkM and TpkM. TODO(#8124): Consider removing this method.
+  toWrappedNoirStruct() {
+    /* eslint-disable camelcase */
+    return { inner: this.toNoirStruct() };
+    /* eslint-enable camelcase */
+  }
+
+  /**
+   * 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();
+  }
+
+  hash() {
+    return poseidon2Hash(this.toFields());
+  }
+
+  /**
+   * Check if this is point at infinity.
+   * Check this is consistent with how bb is encoding the point at infinity
+   */
+  public get inf() {
+    return this.isInfinite;
+  }
+
+  isOnGrumpkin() {
+    // TODO: Check this against how bb handles curve check and infinity point check
+    if (this.inf) {
+      return true;
+    }
+
+    // The Grumpkin equation is y^2 = x^3 - 17. We could use `YFromX` and then compare to `this.y`, but this would
+    // involve computing the square root of y, of which there are two possible valid values. This method is also faster.
+    const lhs = this.y.square();
+    const rhs = this.x.mul(this.x).mul(this.x).sub(new Fr(17));
+    return lhs.equals(rhs);
+  }
+}
+
+export class NotOnCurveError extends Error {
+  constructor(x: Fr) {
+    super('The given x-coordinate is not on the Grumpkin curve: ' + x.toString());
+    this.name = 'NotOnCurveError';
+  }
+}

package/src/fs/index.ts

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

package/src/fs/run_in_dir.ts

@@ -0,0 +1,33 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+
+import { createLogger } from '../log/pino-logger.js';
+
+// Create a random directory underneath a 'base' directory
+// Calls a provided method, ensures the random directory is cleaned up afterwards unless the operation fails
+export async function runInDirectory<T>(
+  workingDirBase: string,
+  fn: (dir: string) => Promise<T>,
+  skipCleanup: boolean | undefined,
+  logger = createLogger('foundation:run-in-directory'),
+): Promise<T> {
+  // Create random directory to be used for temp files
+  const workingDirectory = await fs.mkdtemp(path.join(workingDirBase, 'tmp-'));
+
+  await fs.access(workingDirectory);
+
+  try {
+    return await fn(workingDirectory);
+  } catch (err) {
+    skipCleanup = true;
+    throw err;
+  } finally {
+    if (!skipCleanup) {
+      try {
+        await fs.rm(workingDirectory, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+      } catch (err) {
+        logger.warn(`Failed to cleanup temporary directory ${workingDirectory}: ${err}`, { err });
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+// Reexport all folders at the root for packages targeting CommonJS
+export * as asyncMap from './async-map/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 './error/index.js';
+export * as ethAddress from './eth-address/index.js';
+export * as fields from './fields/index.js';
+export * as fifo from './queue/index.js';
+export * as fs from './fs/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';
+export * as config from './config/index.js';
+export * as buffer from './buffer/index.js';
+export * as ethSignature from './eth-signature/index.js';

package/src/iterable/all.ts

@@ -0,0 +1,32 @@
+import { isAsyncIterable } from './isAsyncIt.js';
+
+/**
+ * Collects all values from an (async) iterable and returns them as an array
+ * @param source - Iterable to collect all values from
+ * @returns All of the iterable's values as an array.
+ */
+function all<T>(source: Iterable<T>): T[];
+function all<T>(source: Iterable<T> | AsyncIterable<T>): Promise<T[]>;
+function all<T>(source: Iterable<T> | AsyncIterable<T>): Promise<T[]> | T[] {
+  if (isAsyncIterable(source)) {
+    return (async () => {
+      const arr = [];
+
+      for await (const entry of source) {
+        arr.push(entry);
+      }
+
+      return arr;
+    })();
+  }
+
+  const arr = [];
+
+  for (const entry of source) {
+    arr.push(entry);
+  }
+
+  return arr;
+}
+
+export { all };

package/src/iterable/filter.ts

@@ -0,0 +1,77 @@
+import { peek } from './peek.js';
+
+function isAsyncIterable<T>(thing: any): thing is AsyncIterable<T> {
+  return thing[Symbol.asyncIterator] != null;
+}
+
+/**
+ * Filters the passed (async) iterable by using the filter function.
+ * @param source - An iterable to filter.
+ * @returns A generator of the filtered values.
+ */
+function filter<T>(
+  source: Iterable<T>,
+  fn: (val: T, index: number) => Promise<boolean>,
+): AsyncGenerator<T, void, undefined>;
+function filter<T>(source: Iterable<T>, fn: (val: T, index: number) => boolean): Generator<T, void, undefined>;
+function filter<T>(
+  source: Iterable<T> | AsyncIterable<T>,
+  fn: (val: T, index: number) => boolean | Promise<boolean>,
+): AsyncGenerator<T, void, undefined>;
+function filter<T>(
+  source: Iterable<T> | AsyncIterable<T>,
+  fn: (val: T, index: number) => boolean | Promise<boolean>,
+): Generator<T, void, undefined> | AsyncGenerator<T, void, undefined> {
+  let index = 0;
+
+  if (isAsyncIterable(source)) {
+    return (async function* () {
+      for await (const entry of source) {
+        if (await fn(entry, index++)) {
+          yield entry;
+        }
+      }
+    })();
+  }
+
+  // if mapping function returns a promise we have to return an async generator
+  const peekable = peek(source);
+  const { value, done } = peekable.next();
+
+  if (done === true) {
+    return (function* () {})();
+  }
+
+  const res = fn(value, index++);
+
+  // @ts-expect-error .then is not present on O
+  if (typeof res.then === 'function') {
+    return (async function* () {
+      if (await res) {
+        yield value;
+      }
+
+      for await (const entry of peekable) {
+        if (await fn(entry, index++)) {
+          yield entry;
+        }
+      }
+    })();
+  }
+
+  const func = fn as (val: T, index: number) => boolean;
+
+  return (function* () {
+    if (res === true) {
+      yield value;
+    }
+
+    for (const entry of peekable) {
+      if (func(entry, index++)) {
+        yield entry;
+      }
+    }
+  })();
+}
+
+export { filter };

package/src/iterable/index.ts

@@ -0,0 +1,7 @@
+export * from './map.js';
+export * from './filter.js';
+export * from './sort.js';
+export * from './take.js';
+export * from './all.js';
+export * from './peek.js';
+export * from './toArray.js';

package/src/iterable/isAsyncIt.ts

@@ -0,0 +1,8 @@
+/**
+ * Utility function to type check an AsyncIterable
+ * @param thing - Input to type check
+ * @returns Type-checked input
+ */
+export function isAsyncIterable<T>(thing: any): thing is AsyncIterable<T> {
+  return thing[Symbol.asyncIterator] != null;
+}

package/src/iterable/map.ts

@@ -0,0 +1,66 @@
+import { isAsyncIterable } from './isAsyncIt.js';
+import { peek } from './peek.js';
+
+/**
+ * Takes an (async) iterable and returns one with each item mapped by the passed
+ * function.
+ * @param source - The iterable to run the map function on.
+ * @param func - The function to run over the iterable's items.
+ * @returns A generator of the mapped items.
+ */
+function map<I, O>(
+  source: Iterable<I>,
+  func: (val: I, index: number) => Promise<O>,
+): AsyncGenerator<O, void, undefined>;
+function map<I, O>(source: Iterable<I>, func: (val: I, index: number) => O): Generator<O, void, undefined>;
+function map<I, O>(
+  source: AsyncIterable<I> | Iterable<I>,
+  func: (val: I, index: number) => O | Promise<O>,
+): AsyncGenerator<O, void, undefined>;
+function map<I, O>(
+  source: AsyncIterable<I> | Iterable<I>,
+  func: (val: I, index: number) => O | Promise<O>,
+): AsyncGenerator<O, void, undefined> | Generator<O, void, undefined> {
+  let index = 0;
+
+  if (isAsyncIterable(source)) {
+    return (async function* () {
+      for await (const val of source) {
+        yield func(val, index++);
+      }
+    })();
+  }
+
+  // if mapping function returns a promise we have to return an async generator
+  const peekable = peek(source);
+  const { value, done } = peekable.next();
+
+  if (done === true) {
+    return (function* () {})();
+  }
+
+  const res = func(value, index++);
+
+  // @ts-expect-error .then is not present on O
+  if (typeof res.then === 'function') {
+    return (async function* () {
+      yield await res;
+
+      for await (const val of peekable) {
+        yield func(val, index++);
+      }
+    })();
+  }
+
+  const fn = func as (val: I, index: number) => O;
+
+  return (function* () {
+    yield res as O;
+
+    for (const val of peekable) {
+      yield fn(val, index++);
+    }
+  })();
+}
+
+export { map };

package/src/iterable/peek.ts

@@ -0,0 +1,58 @@
+export interface Peek<T> {
+  peek(): IteratorResult<T, undefined>;
+}
+
+export interface AsyncPeek<T> {
+  peek(): Promise<IteratorResult<T, undefined>>;
+}
+
+export interface Push<T> {
+  push(value: T): void;
+}
+
+export type Peekable<T> = Iterable<T> & Peek<T> & Push<T> & Iterator<T>;
+
+export type AsyncPeekable<T> = AsyncIterable<T> & AsyncPeek<T> & Push<T> & AsyncIterator<T>;
+
+/**
+ * Utility function that allows peeking into the contents of an async iterator.
+ * @param iterable - The async iterator to peek the values of.
+ */
+function peekable<T>(iterable: Iterable<T>): Peekable<T>;
+function peekable<T>(iterable: AsyncIterable<T>): AsyncPeekable<T>;
+function peekable<T>(iterable: Iterable<T> | AsyncIterable<T>): Peekable<T> | AsyncPeekable<T> {
+  const [iterator, symbol] =
+    // @ts-expect-error can't use Symbol.asyncIterator to index iterable since it might be Iterable
+    iterable[Symbol.asyncIterator] != null
+      ? // @ts-expect-error can't use Symbol.asyncIterator to index iterable since it might be Iterable
+        [iterable[Symbol.asyncIterator](), Symbol.asyncIterator]
+      : // @ts-expect-error can't use Symbol.iterator to index iterable since it might be AsyncIterable
+        [iterable[Symbol.iterator](), Symbol.iterator];
+
+  const queue: any[] = [];
+
+  // @ts-expect-error can't use symbol to index peekable
+  return {
+    peek: () => {
+      return iterator.next();
+    },
+    push: (value: any) => {
+      queue.push(value);
+    },
+    next: () => {
+      if (queue.length > 0) {
+        return {
+          done: false,
+          value: queue.shift(),
+        };
+      }
+
+      return iterator.next();
+    },
+    [symbol]() {
+      return this;
+    },
+  };
+}
+
+export { peekable as peek };

package/src/iterable/sort.ts

@@ -0,0 +1,39 @@
+import { all } from './all.js';
+import { isAsyncIterable } from './isAsyncIt.js';
+
+export interface CompareFunction<T> {
+  (a: T, b: T): number;
+}
+
+/**
+ * Collects all values from an async iterator, sorts them
+ * using the passed function and yields them.
+ * @param source - Iterable to sort.
+ * @param sorter - Sorting function.
+ * @returns A generator of the sorted values.
+ */
+function sort<T>(source: Iterable<T>, sorter: CompareFunction<T>): Generator<T, void, undefined>;
+function sort<T>(
+  source: Iterable<T> | AsyncIterable<T>,
+  sorter: CompareFunction<T>,
+): AsyncGenerator<T, void, undefined>;
+function sort<T>(
+  source: Iterable<T> | AsyncIterable<T>,
+  sorter: CompareFunction<T>,
+): AsyncGenerator<T, void, undefined> | Generator<T, void, undefined> {
+  if (isAsyncIterable(source)) {
+    return (async function* () {
+      const arr = await all(source);
+
+      yield* arr.sort(sorter);
+    })();
+  }
+
+  return (function* () {
+    const arr = all(source);
+
+    yield* arr.sort(sorter);
+  })();
+}
+
+export { sort };