@aztec-labs/foundation 6.0.0-nightly.20260829

package/src/curves/grumpkin/point.ts

@@ -0,0 +1,300 @@
+import { toBigIntBE } from '../../bigint-buffer/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 '../bn254/field.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 INFINITY = new Point(Fr.ZERO, Fr.ZERO);
+  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';
+
+  /** Whether the point is at infinity */
+  public readonly isInfinite: boolean;
+
+  constructor(
+    /**
+     * The point's x coordinate
+     */
+    public readonly x: Fr,
+    /**
+     * The point's y coordinate
+     */
+    public readonly y: Fr,
+  ) {
+    // TODO(#7386): check if on curve
+    // NOTE: now there is no isInfinite in the struct, empty == inf, so an empty class would pass an on-curve check. This may be fine depending on the usage.
+    this.isInfinite = x.isZero() && y.isZero();
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  static get schema() {
+    // Serialization from hex string.
+    return hexSchemaFor(Point);
+  }
+
+  /**
+   * Creates a Point from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * Handles buffers, existing instances, or objects with x, y, and isInfinite fields.
+   * @param obj - Plain object, buffer, or Point instance
+   * @returns A Point instance
+   */
+  static fromPlainObject(obj: any): Point {
+    if (obj instanceof Point) {
+      return obj;
+    }
+    if (obj instanceof Buffer || Buffer.isBuffer(obj)) {
+      return Point.fromBuffer(obj);
+    }
+    return new this(Fr.fromPlainObject(obj.x), Fr.fromPlainObject(obj.y));
+  }
+
+  /**
+   * Generate a random Point instance that is on the curve.
+   *
+   * @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));
+  }
+
+  /**
+   * 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];
+  }
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+    const [x, y] = [reader.readField(), reader.readField()];
+    return new this(x, y);
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * @param x - The x coordinate of the point
+   * @returns y^2 such that y^2 = x^3 - 17
+   */
+  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(),
+    };
+  }
+
+  /**
+   * 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. The point at infinity is serialized as (0, 0).
+   */
+  toBuffer() {
+    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() {
+    return { x: this.x, y: this.y };
+  }
+
+  // Used for IvpkM. TODO(#8124): Consider removing this method.
+  toWrappedNoirStruct() {
+    return { inner: this.toNoirStruct() };
+  }
+
+  /**
+   * 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();
+  }
+
+  /**
+   * @param x - The x coordinate of the point
+   * @param y - The y coordinate of the point
+   * @returns Whether the point exists on Grumpkin
+   */
+  isOnCurve() {
+    if (this.isInfinite) {
+      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/decorators/index.ts

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

package/src/decorators/memoize.ts

@@ -0,0 +1,11 @@
+export function memoize<This extends object, Result>(fn: () => Result, context: ClassMethodDecoratorContext) {
+  return function (this: This) {
+    const key = `__${String(context.name)}_value`;
+    const thisWithKey = this as { [key: string]: Result };
+    if (!(key in this)) {
+      const result = fn.call(this);
+      thisWithKey[key] = result;
+    }
+    return thisWithKey[key];
+  };
+}

package/src/error/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Represents an error thrown when an operation is interrupted unexpectedly.
+ * This custom error class extends the built-in Error class in JavaScript and
+ * can be used to handle cases where a process or task is terminated before completion.
+ */
+export class InterruptError extends Error {
+  public override readonly name = 'InterruptError';
+}
+
+/**
+ * An error thrown when an action times out.
+ */
+export class TimeoutError extends Error {
+  public override readonly name = 'TimeoutError';
+}
+
+/**
+ * Represents an error thrown when an operation is aborted.
+ */
+export class AbortError extends Error {
+  public override readonly name = 'AbortError';
+}

package/src/eth-address/index.ts

@@ -0,0 +1,269 @@
+import { inspect } from 'util';
+
+import { keccak256String } from '../crypto/keccak/index.js';
+import { randomBytes } from '../crypto/random/index.js';
+import { Fr } from '../curves/bn254/index.js';
+import { hexSchemaFor } from '../schemas/utils.js';
+import { BufferReader, FieldReader } from '../serialize/index.js';
+import { bufferToHex } from '../string/index.js';
+
+/**
+ * Represents an Ethereum address as a 20-byte buffer and provides various utility methods
+ * for converting between different representations, generating random addresses, validating
+ * checksums, and comparing addresses. EthAddress can be instantiated using a buffer or string,
+ * and can be serialized/deserialized from a buffer or BufferReader.
+ */
+export class EthAddress {
+  /** The size of an Ethereum address in bytes. */
+  public static SIZE_IN_BYTES = 20;
+  /** Represents a zero Ethereum address with 20 bytes filled with zeros. */
+  public static ZERO = new EthAddress(Buffer.alloc(EthAddress.SIZE_IN_BYTES));
+
+  constructor(private buffer: Buffer) {
+    if (buffer.length !== EthAddress.SIZE_IN_BYTES) {
+      throw new Error(`Expect buffer size to be ${EthAddress.SIZE_IN_BYTES}. Got ${buffer.length}.`);
+    }
+  }
+
+  /**
+   * Creates an EthAddress instance from a valid Ethereum address string.
+   * The input 'address' can be either in checksum format or lowercase, and it can be prefixed with '0x'.
+   * Throws an error if the input is not a valid Ethereum address.
+   *
+   * @param address - The string representing the Ethereum address.
+   * @returns An EthAddress instance.
+   */
+  public static fromString(address: string) {
+    if (!EthAddress.isAddress(address)) {
+      throw new Error(`Invalid address string: ${address}`);
+    }
+    return new EthAddress(Buffer.from(address.replace(/^0x/i, ''), 'hex'));
+  }
+
+  /**
+   * Creates an EthAddress from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * Handles buffers (20 or 32 bytes), strings, or existing instances.
+   * @param obj - Plain object, buffer, string, or EthAddress instance
+   * @returns An EthAddress instance
+   */
+  public static fromPlainObject(obj: any): EthAddress {
+    if (obj instanceof EthAddress) {
+      return obj;
+    }
+    if (obj instanceof Buffer || Buffer.isBuffer(obj)) {
+      return obj.length === 20 ? new EthAddress(obj) : EthAddress.fromField(new Fr(obj));
+    }
+    return EthAddress.fromString(obj);
+  }
+
+  /**
+   * Create a random EthAddress instance with 20 random bytes.
+   * This method generates a new Ethereum address with a randomly generated set of 20 bytes.
+   * It is useful for generating test addresses or unique identifiers.
+   *
+   * @returns A randomly generated EthAddress instance.
+   */
+  public static random() {
+    return new EthAddress(randomBytes(20));
+  }
+
+  /**
+   * Determines if the given string represents a valid Ethereum address.
+   * A valid address should meet the following criteria:
+   * 1. Contains exactly 40 hex characters (excluding an optional '0x' prefix).
+   * 2. Is either all lowercase, all uppercase, or has a valid checksum based on EIP-55.
+   *
+   * @param address - The string to be checked for validity as an Ethereum address.
+   * @returns True if the input string represents a valid Ethereum address, false otherwise.
+   */
+  public static isAddress(address: string) {
+    if (!/^(0x)?[0-9a-f]{40}$/i.test(address)) {
+      // Does not have the basic requirements of an address.
+      return false;
+    } else if (/^(0x|0X)?[0-9a-f]{40}$/.test(address) || /^(0x|0X)?[0-9A-F]{40}$/.test(address)) {
+      // It's ALL lowercase or ALL uppercase.
+      return true;
+    } else {
+      return EthAddress.checkAddressChecksum(address);
+    }
+  }
+
+  /**
+   * Checks if the EthAddress instance represents a zero address.
+   * A zero address consists of 20 bytes filled with zeros and is considered an invalid address.
+   *
+   * @returns A boolean indicating whether the EthAddress instance is a zero address or not.
+   */
+  public isZero() {
+    return this.equals(EthAddress.ZERO);
+  }
+
+  /**
+   * Checks if the given Ethereum address has a valid checksum.
+   * The input 'address' should be prefixed with '0x' or not, and have exactly 40 hex characters.
+   * Returns true if the address has a valid checksum, false otherwise.
+   *
+   * @param address - The hex-encoded string representing the Ethereum address.
+   * @returns A boolean value indicating whether the address has a valid checksum.
+   */
+  public static checkAddressChecksum(address: string) {
+    address = address.replace(/^0x/i, '');
+    const addressHash = keccak256String(address.toLowerCase());
+
+    for (let i = 0; i < 40; i++) {
+      // The nth letter should be uppercase if the nth digit of casemap is 1.
+      if (
+        (parseInt(addressHash[i], 16) > 7 && address[i].toUpperCase() !== address[i]) ||
+        (parseInt(addressHash[i], 16) <= 7 && address[i].toLowerCase() !== address[i])
+      ) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Converts an Ethereum address to its checksum format.
+   * The input 'address' should be prefixed with '0x' or not, and have exactly 40 hex characters.
+   * The checksum format is created by capitalizing certain characters in the hex string
+   * based on the hash of the lowercase address.
+   * Throws an error if the input address is invalid.
+   *
+   * @param address - The Ethereum address as a hex-encoded string.
+   * @returns The Ethereum address in its checksum format.
+   */
+  public static toChecksumAddress(address: string): `0x${string}` {
+    if (!EthAddress.isAddress(address)) {
+      throw new Error('Invalid address string.');
+    }
+
+    address = address.toLowerCase().replace(/^0x/i, '');
+    const addressHash = keccak256String(address);
+    let checksumAddress: `0x${string}` = '0x';
+
+    for (let i = 0; i < address.length; i++) {
+      // If ith character is 9 to f then make it uppercase.
+      if (parseInt(addressHash[i], 16) > 7) {
+        checksumAddress += address[i].toUpperCase();
+      } else {
+        checksumAddress += address[i];
+      }
+    }
+    return checksumAddress;
+  }
+
+  /**
+   * Checks whether the given EthAddress instance is equal to the current instance.
+   * Equality is determined by comparing the underlying byte buffers of both instances.
+   *
+   * @param rhs - The EthAddress instance to compare with the current instance.
+   * @returns A boolean value indicating whether the two instances are equal (true) or not (false).
+   */
+  public equals(rhs: EthAddress) {
+    return this.buffer.equals(rhs.buffer);
+  }
+
+  /**
+   * Converts the Ethereum address to a hex-encoded string.
+   * The resulting string is prefixed with '0x' and has exactly 40 hex characters.
+   * This method can be used to represent the EthAddress instance in the widely used hexadecimal format.
+   *
+   * @returns A hex-encoded string representation of the Ethereum address.
+   */
+  public toString() {
+    return bufferToHex(this.buffer);
+  }
+
+  [inspect.custom]() {
+    return `EthAddress<${this.toString()}>`;
+  }
+
+  /**
+   * Returns the Ethereum address as a checksummed string.
+   * The output string will have characters in the correct upper or lowercase form, according to EIP-55.
+   * This provides a way to verify if an address is typed correctly, by checking the character casing.
+   *
+   * @returns A checksummed Ethereum address string.
+   */
+  public toChecksumString() {
+    return EthAddress.toChecksumAddress(this.buffer.toString('hex'));
+  }
+
+  /**
+   * Returns a 20-byte buffer representation of the Ethereum address.
+   * @returns A 20-byte Buffer containing the Ethereum address.
+   */
+  public toBuffer() {
+    return this.buffer;
+  }
+
+  /**
+   * Returns a 32-byte buffer representation of the Ethereum address, with the original 20-byte address
+   * occupying the last 20 bytes and the first 12 bytes being zero-filled.
+   * This format is commonly used in smart contracts when handling addresses as 32-byte values.
+   *
+   * @returns A 32-byte Buffer containing the padded Ethereum address.
+   */
+  public toBuffer32() {
+    const buffer = Buffer.alloc(32);
+    this.buffer.copy(buffer, 12);
+    return buffer;
+  }
+
+  /**
+   * Returns a new field with the same contents as this EthAddress.
+   *
+   * @returns An Fr instance.
+   */
+  public toField() {
+    return Fr.fromBuffer(this.toBuffer32());
+  }
+
+  /**
+   * Converts a field to a eth address.
+   * @param fr - The field to convert.
+   * @returns The eth address.
+   */
+  static fromField(fr: Fr): EthAddress {
+    return new EthAddress(fr.toBuffer().slice(-EthAddress.SIZE_IN_BYTES));
+  }
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+    return EthAddress.fromField(reader.readField());
+  }
+
+  /**
+   * Deserializes from a buffer or reader, corresponding to a write in cpp.
+   * @param buffer - Buffer to read from.
+   * @returns The EthAddress.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader): EthAddress {
+    const reader = BufferReader.asReader(buffer);
+    return new EthAddress(reader.readBytes(EthAddress.SIZE_IN_BYTES));
+  }
+
+  /** Converts a number into an address. Useful for testing. */
+  static fromNumber(num: bigint | number): EthAddress {
+    const buffer = Buffer.alloc(EthAddress.SIZE_IN_BYTES);
+    buffer.writeBigUInt64BE(BigInt(num), EthAddress.SIZE_IN_BYTES - 8);
+    return new EthAddress(buffer);
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  static get schema() {
+    // Serialization from hex string.
+    return hexSchemaFor(EthAddress, EthAddress.isAddress);
+  }
+
+  static areEqual(a: EthAddress | string, b: EthAddress | string) {
+    const addrA = typeof a === 'string' ? EthAddress.fromString(a) : a;
+    const addrB = typeof b === 'string' ? EthAddress.fromString(b) : b;
+    return addrA.equals(addrB);
+  }
+}