@aztec/foundation 0.15.0 → 0.16.0

package/src/fields/fields.ts

@@ -1,256 +1,256 @@
-import { AztecAddress } from '../aztec-address/index.js';
-import { toBigIntBE, toBufferBE, toHex } from '../bigint-buffer/index.js';
+import { toBigIntBE, toBufferBE } from '../bigint-buffer/index.js';
 import { randomBytes } from '../crypto/index.js';
 import { BufferReader } from '../serialize/buffer_reader.js';
 
+const ZERO_BUFFER = Buffer.alloc(32);
+
+/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
+
 /**
- * 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.
+ * Represents a field derived from BaseField.
  */
-export class Fr {
-  static ZERO = new Fr(0n);
-  static MODULUS = 0x30644e72e131a029b85045b68181585d2833e84879b9709143e1f593f0000001n;
-  static MAX_VALUE = Fr.MODULUS - 1n;
-  static SIZE_IN_BYTES = 32;
-
+type DerivedField<T extends BaseField> = {
+  new (value: any): T;
   /**
-   * The numeric value of the field element as a bigint.
+   * All derived fields will specify a MODULUS.
    */
-  public readonly value: bigint;
-
-  constructor(value: boolean | bigint | number | Fr | AztecAddress) {
-    const isFr = (value: boolean | bigint | number | Fr | AztecAddress): value is Fr | AztecAddress =>
-      !!(value as Fr).toBigInt;
-    this.value = isFr(value) ? value.toBigInt() : BigInt(value);
-    if (this.value > Fr.MAX_VALUE) {
-      throw new Error(`Fr out of range ${value}.`);
-    }
-  }
+  MODULUS: bigint;
+};
 
-  /**
-   * 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);
-  }
+/**
+ * Base field class.
+ * Conversions from Buffer to BigInt and vice-versa are not cheap.
+ * We allow construction with either form and lazily convert to other as needed.
+ * We only check we are within the field modulus when initializing with bigint.
+ * If NODE_ENV === 'test', we will always initialize both types to check the modulus.
+ * This is also necessary in test environment as a lot of tests just use deep equality to check equality.
+ * WARNING: This could lead to a bugs in production that don't reveal in tests, but it's low risk.
+ */
+abstract class BaseField {
+  static SIZE_IN_BYTES = 32;
+  private asBuffer?: Buffer;
+  private asBigInt?: bigint;
 
   /**
-   * Returns a new zero-value field.
-   * @returns A new zero-value field.
-   */
-  static zero() {
-    return new Fr(0n);
+   * Return bigint representation.
+   * @deprecated Just to get things compiling. Use toBigInt().
+   * */
+  get value(): bigint {
+    return this.toBigInt();
   }
 
-  /**
-   * 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)));
-  }
+  protected constructor(value: number | bigint | boolean | BaseField | Buffer) {
+    if (value instanceof Buffer) {
+      this.asBuffer =
+        value.length === 32 ? value : Buffer.concat([Buffer.alloc(BaseField.SIZE_IN_BYTES - value.length), value]);
+    } else if (typeof value === 'bigint' || typeof value === 'number' || typeof value === 'boolean') {
+      this.asBigInt = BigInt(value);
+      if (this.asBigInt >= this.modulus()) {
+        throw new Error('Value >= to field modulus.');
+      }
+    } else if (value instanceof BaseField) {
+      this.asBuffer = value.asBuffer;
+      this.asBigInt = value.asBigInt;
+    } else {
+      throw new Error(`Type '${typeof value}' with value '${value}' passed to BaseField ctor.`);
+    }
 
-  /**
-   * 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'));
+    // Loads of our tests are just doing deep equality rather than calling e.g. toBigInt() first.
+    // This ensures the deep equality passes regardless of the internal representation.
+    // It also ensures the value range is checked even when initializing as a buffer.
+    if (process.env.NODE_ENV === 'test') {
+      this.toBuffer();
+      this.toBigInt();
+    }
   }
 
+  protected abstract modulus(): bigint;
+
   /**
-   * 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.
+   * We return a copy of the Buffer to ensure this remains immutable.
    */
-  toBuffer() {
-    return toBufferBE(this.value, Fr.SIZE_IN_BYTES);
+  toBuffer(): Buffer {
+    if (!this.asBuffer) {
+      this.asBuffer = toBufferBE(this.asBigInt!, 32);
+    }
+    return Buffer.from(this.asBuffer);
   }
 
-  /**
-   * 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);
+  toString(): `0x${string}` {
+    return `0x${this.toBuffer().toString('hex')}`;
   }
 
-  /**
-   * Retrieves the underlying bigint.
-   * This method mostly exists to match user expectations, as value is already public.
-   * @returns The underlying bigint.
-   */
-  public toBigInt(): bigint {
-    return this.value;
+  toBigInt(): bigint {
+    if (this.asBigInt === undefined) {
+      this.asBigInt = toBigIntBE(this.asBuffer!);
+      if (this.asBigInt >= this.modulus()) {
+        throw new Error('Value >= to field modulus.');
+      }
+    }
+    return this.asBigInt;
   }
 
-  /**
-   * 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() {
+  toShortString(): string {
     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;
+  equals(rhs: BaseField): boolean {
+    return this.toBuffer().equals(rhs.toBuffer());
   }
 
-  /**
-   * 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;
+  isZero(): boolean {
+    return this.toBuffer().equals(ZERO_BUFFER);
   }
 
-  /**
-   * 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();
+  toFriendlyJSON(): string {
+    return `0x${this.toBigInt().toString()}`;
   }
 
-  /** Returns self. */
   toField() {
     return this;
   }
 }
 
 /**
- * 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);
+ * Constructs a field from a Buffer of BufferReader.
+ * It maybe not read the full 32 bytes if the Buffer is shorter, but it will padded in BaseField constructor.
  */
-export class Fq {
-  static MODULUS = 0x30644e72e131a029b85045b68181585d97816a916871ca8d3c208c16d87cfd47n;
-  static MAX_VALUE = Fr.MODULUS - 1n;
-  static SIZE_IN_BYTES = 32;
+function fromBuffer<T extends BaseField>(buffer: Buffer | BufferReader, f: DerivedField<T>) {
+  const reader = BufferReader.asReader(buffer);
+  return new f(reader.readBytes(BaseField.SIZE_IN_BYTES));
+}
 
-  constructor(
-    /**
-     * The element's value as a bigint in the finite field.
-     */
-    public readonly value: bigint,
-  ) {
-    if (value > Fq.MAX_VALUE) {
-      throw new Error(`Fq out of range ${value}.`);
-    }
+/**
+ * Constructs a field from a Buffer, but reduces it first.
+ * This requires a conversion to a bigint first so the initial underlying representation will be a bigint.
+ */
+function fromBufferReduce<T extends BaseField>(buffer: Buffer, f: DerivedField<T>) {
+  return new f(toBigIntBE(buffer) % f.MODULUS);
+}
+
+/**
+ * To ensure a field is uniformly random, it's important to reduce a 512 bit value.
+ * If you reduced a 256 bit number, there would a be a high skew in the lower range of the field.
+ */
+function random<T extends BaseField>(f: DerivedField<T>): T {
+  return fromBufferReduce(randomBytes(64), f);
+}
+
+/**
+ * Constructs a field from a 0x prefixed hex string.
+ */
+function fromString<T extends BaseField>(buf: string, f: DerivedField<T>) {
+  const buffer = Buffer.from(buf.replace(/^0x/i, ''), 'hex');
+  return new f(buffer);
+}
+
+/**
+ * Branding to ensure fields are not interchangeable types.
+ */
+export interface Fr {
+  /** Brand. */
+  _branding: 'Fr';
+}
+
+/**
+ * Fr field class.
+ */
+export class Fr extends BaseField {
+  static ZERO = new Fr(0n);
+  static MODULUS = 0x30644e72e131a029b85045b68181585d2833e84879b9709143e1f593f0000001n;
+
+  constructor(value: number | bigint | boolean | Fr | Buffer) {
+    super(value);
+  }
+
+  protected modulus() {
+    return Fr.MODULUS;
   }
 
-  /**
-   * 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);
+    return random(Fr);
+  }
+
+  static zero() {
+    return Fr.ZERO;
   }
 
-  /**
-   * 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)));
+    return fromBuffer(buffer, Fr);
   }
 
-  /**
-   * 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);
+  static fromBufferReduce(buffer: Buffer) {
+    return fromBufferReduce(buffer, Fr);
   }
 
-  /**
-   * 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);
+  static fromString(buf: string) {
+    return fromString(buf, Fr);
   }
+}
 
-  /**
-   * 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;
+/**
+ * Branding to ensure fields are not interchangeable types.
+ */
+export interface Fq {
+  /** Brand. */
+  _branding: 'Fq';
+}
+
+/**
+ * Fq field class.
+ */
+export class Fq extends BaseField {
+  static ZERO = new Fq(0n);
+  static MODULUS = 0x30644e72e131a029b85045b68181585d97816a916871ca8d3c208c16d87cfd47n;
+  private static HIGH_SHIFT = BigInt((BaseField.SIZE_IN_BYTES / 2) * 8);
+  private static LOW_MASK = (1n << Fq.HIGH_SHIFT) - 1n;
+
+  get low(): Fr {
+    return new Fr(this.toBigInt() & Fq.LOW_MASK);
   }
 
-  /**
-   * 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();
+  get high(): Fr {
+    return new Fr(this.toBigInt() >> Fq.HIGH_SHIFT);
   }
 
-  /** Returns self. */
-  toField() {
-    return this;
+  constructor(value: number | bigint | boolean | Fq | Buffer) {
+    super(value);
+  }
+
+  protected modulus() {
+    return Fq.MODULUS;
+  }
+
+  static random() {
+    return random(Fq);
+  }
+
+  static zero() {
+    return Fq.ZERO;
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    return fromBuffer(buffer, Fq);
+  }
+
+  static fromBufferReduce(buffer: Buffer) {
+    return fromBufferReduce(buffer, Fq);
+  }
+
+  static fromString(buf: string) {
+    return fromString(buf, Fq);
+  }
+
+  static fromHighLow(high: Fr, low: Fr): Fq {
+    return new Fq((high.toBigInt() << Fq.HIGH_SHIFT) + low.toBigInt());
   }
 }
+
+/**
+ * GrumpkinScalar is an Fq.
+ * @remarks Called GrumpkinScalar because it is used to represent elements in Grumpkin's scalar field as defined in
+ *          the Aztec Yellow Paper.
+ */
+export type GrumpkinScalar = Fq;
+export const GrumpkinScalar = Fq;

package/src/fields/index.ts

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

package/src/fields/point.ts

@@ -72,8 +72,8 @@ export class Point {
    */
   toBigInts() {
     return {
-      x: this.x.value,
-      y: this.y.value,
+      x: this.x.toBigInt(),
+      y: this.y.toBigInt(),
     };
   }
 
@@ -120,6 +120,10 @@ export class Point {
   equals(rhs: Point) {
     return this.x.equals(rhs.x) && this.y.equals(rhs.y);
   }
+
+  isZero() {
+    return this.x.isZero() && this.y.isZero();
+  }
 }
 
 /**
@@ -128,7 +132,9 @@ export class Point {
  * @returns Whether it looks like a point.
  */
 export function isPoint(obj: object): obj is Point {
-  if (!obj) return false;
+  if (!obj) {
+    return false;
+  }
   const point = obj as Point;
   return point.kind === 'point' && point.x !== undefined && point.y !== undefined;
 }

package/src/json-rpc/class_converter.ts

@@ -1,4 +1,4 @@
-import { assert, hasOwnProperty } from './js_utils.js';
+import { assert } from './js_utils.js';
 
 /**
  * Represents a class compatible with our class conversion system.
@@ -133,7 +133,7 @@ export class ClassConverter {
   register(type: string, class_: IOClass, encoding: ClassEncoding) {
     assert(type !== 'Buffer', "'Buffer' handling is hardcoded. Cannot use as name.");
     assert(
-      hasOwnProperty(class_.prototype, 'toString') || hasOwnProperty(class_.prototype, 'toJSON'),
+      class_.prototype['toString'] || class_.prototype['toJSON'],
       `Class ${type} must define a toString() OR toJSON() method.`,
     );
     assert(
@@ -197,9 +197,13 @@ export class ClassConverter {
    */
   private lookupObject(classObj: any) {
     const nameResult = this.toName.get(classObj.constructor);
-    if (nameResult) return { type: nameResult[0], encoding: nameResult[1] };
+    if (nameResult) {
+      return { type: nameResult[0], encoding: nameResult[1] };
+    }
     const classResult = this.toClass.get(classObj.constructor.name);
-    if (classResult) return { type: classObj.constructor.name, encoding: classResult[1] };
+    if (classResult) {
+      return { type: classObj.constructor.name, encoding: classResult[1] };
+    }
     throw new Error(`Could not find class ${classObj.constructor.name} in lookup.`);
   }
 }

package/src/json-rpc/client/json_rpc_client.ts

@@ -123,7 +123,9 @@ export function createJsonRpcClient<T extends object>(
     {},
     {
       get: (target, rpcMethod: string) => {
-        if (['then', 'catch'].includes(rpcMethod)) return Reflect.get(target, rpcMethod);
+        if (['then', 'catch'].includes(rpcMethod)) {
+          return Reflect.get(target, rpcMethod);
+        }
         return (...params: any[]) => {
           debug(format(`JsonRpcClient.constructor`, 'proxy', rpcMethod, '<-', params));
           return request(rpcMethod, params);

package/src/log/console.ts

@@ -1,5 +1,5 @@
 /* eslint-disable no-console */
-import { LogFn } from './index.js';
+import { LogFn } from './log_fn.js';
 
 /**
  * ConsoleLogger is a utility class that provides customizable console logging functionality.

package/src/log/debug.ts

@@ -1,6 +1,6 @@
 import debug from 'debug';
 
-import { LogFn } from './index.js';
+import { LogFn } from './log_fn.js';
 
 let preLogHook: ((...args: any[]) => void) | undefined;
 let postLogHook: ((...args: any[]) => void) | undefined;

package/src/log/index.ts

@@ -1,10 +1,5 @@
-/** Structured log data to include with the message. */
-export type LogData = Record<string, string | number | bigint | boolean>;
-
-/** A callable logger instance. */
-export type LogFn = (msg: string, data?: LogData) => void;
-
 export * from './console.js';
 export * from './debug.js';
 export * from './logger.js';
 export * from './log_history.js';
+export * from './log_fn.js';

package/src/log/log_fn.ts

@@ -0,0 +1,5 @@
+/** Structured log data to include with the message. */
+export type LogData = Record<string, string | number | bigint | boolean>;
+
+/** A callable logger instance. */
+export type LogFn = (msg: string, data?: LogData) => void;

package/src/log/logger.ts

@@ -2,7 +2,7 @@ import debug from 'debug';
 import isNode from 'detect-node';
 import { isatty } from 'tty';
 
-import { LogData, LogFn } from './index.js';
+import { LogData, LogFn } from './log_fn.js';
 
 // Matches a subset of Winston log levels
 const LogLevels = ['silent', 'error', 'warn', 'info', 'verbose', 'debug'] as const;
@@ -39,7 +39,9 @@ export type DebugLogger = LogFn & Logger;
  */
 export function createDebugLogger(name: string): DebugLogger {
   const debugLogger = debug(name);
-  if (currentLevel === 'debug') debugLogger.enabled = true;
+  if (currentLevel === 'debug') {
+    debugLogger.enabled = true;
+  }
 
   const logger = {
     silent: () => {},
@@ -78,7 +80,9 @@ function logWithDebug(debug: debug.Debugger, level: LogLevel, msg: string, data?
 
   msg = data ? `${msg} ${fmtLogData(data)}` : msg;
   if (debug.enabled) {
-    if (level !== 'debug') msg = `${level.toUpperCase()} ${msg}`;
+    if (level !== 'debug') {
+      msg = `${level.toUpperCase()} ${msg}`;
+    }
     debug(msg);
   } else if (LogLevels.indexOf(level) <= LogLevels.indexOf(currentLevel)) {
     printLog(`${getPrefix(debug, level)} ${msg}`);
@@ -94,7 +98,9 @@ function logWithDebug(debug: debug.Debugger, level: LogLevel, msg: string, data?
 function getPrefix(debugLogger: debug.Debugger, level: LogLevel) {
   const levelLabel = currentLevel !== level ? ` ${level.toUpperCase()}` : '';
   const prefix = `${debugLogger.namespace.replace(/^aztec:/, '')}${levelLabel}`;
-  if (!isNode || !isatty(process.stderr.fd)) return prefix;
+  if (!isNode || !isatty(process.stderr.fd)) {
+    return prefix;
+  }
   const colorIndex = debug.selectColor(debugLogger.namespace) as number;
   const colorCode = '\u001B[3' + (colorIndex < 8 ? colorIndex : '8;5;' + colorIndex);
   return `  ${colorCode};1m${prefix}\u001B[0m`;

package/src/serialize/buffer_reader.ts

@@ -1,4 +1,3 @@
-import { Fq, Fr } from '../fields/fields.js';
 import { Tuple } from './types.js';
 
 /**
@@ -83,27 +82,6 @@ export class BufferReader {
     return Buffer.from(this.buffer.subarray(this.index - n, this.index));
   }
 
-  /**
-   * Reads a Fr (finite field) element from the buffer using the 'fromBuffer' method of the Fr class.
-   * The Fr class should provide a 'fromBuffer' method that takes a BufferReader instance as input.
-   *
-   * @returns An instance of the Fr class representing the finite field element.
-   */
-  public readFr(): Fr {
-    return Fr.fromBuffer(this);
-  }
-
-  /**
-   * Reads the next Fq element from the buffer using the Fq.fromBuffer method.
-   * The Fq element represents a finite field in elliptic curve cryptography and is used for calculations.
-   * Advances the internal buffer index by the number of bytes read.
-   *
-   * @returns An Fq instance representing the finite field element.
-   */
-  public readFq(): Fq {
-    return Fq.fromBuffer(this);
-  }
-
   /**
    * 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.