@aztec/foundation 0.22.0 → 0.24.0

package/src/eth-address/index.ts

@@ -0,0 +1,234 @@
+import { keccak256String } from '../crypto/keccak/index.js';
+import { randomBytes } from '../crypto/random/index.js';
+import { Fr } from '../fields/index.js';
+import { BufferReader, FieldReader } from '../serialize/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'));
+  }
+
+  /**
+   * 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) {
+    if (!EthAddress.isAddress(address)) {
+      throw new Error('Invalid address string.');
+    }
+
+    address = address.toLowerCase().replace(/^0x/i, '');
+    const addressHash = keccak256String(address);
+    let checksumAddress = '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 `0x${this.buffer.toString('hex')}` as `0x${string}`;
+  }
+
+  /**
+   * 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.
+   */
+  // TODO(#3938): nuke this
+  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));
+  }
+
+  /**
+   * Friendly representation for debugging purposes.
+   * @returns A hex string representing the address.
+   */
+  toFriendlyJSON() {
+    return this.toString();
+  }
+}

package/src/fields/coordinate.ts

@@ -0,0 +1,104 @@
+import { toBigIntBE } from '../bigint-buffer/index.js';
+import { Tuple } from '../serialize/types.js';
+import { Fr } from './fields.js';
+
+/**
+ * Class to wrap a single point coordinate.
+ * This class handles the complexities of representing point coordinates as 32 byte buffers as well as fields.
+ * The coordinate value is split across 2 fields to ensure that the max size of a field is not breached.
+ * This is achieved by placing the most significant byte of the lower field into the least significant byte of the higher field.
+ * Calls to 'toBuffer' or 'toBigInt' undo this change and simply return the original 32 byte value.
+ * Calls to 'toFieldsBuffer' will return a 64 bytes buffer containing the serialized fields.
+ */
+export class Coordinate {
+  static ZERO = new Coordinate([Fr.ZERO, Fr.ZERO]);
+
+  constructor(
+    /**
+     * The fields of the coordinate value. Least significant limb at index 0.
+     */
+    public fields: Tuple<Fr, 2>,
+  ) {}
+
+  /**
+   * Converts the coordinate data into a tuple of fields
+   * @returns A tuple of the coordinate fields
+   */
+  toFields(): Tuple<Fr, 2> {
+    return this.fields;
+  }
+
+  /**
+   * Generates a random coordinate value
+   * @returns The random coordinate
+   */
+  static random(): Coordinate {
+    return this.fromField(Fr.random());
+  }
+
+  /**
+   * serializes the object to buffer of 2 fields.
+   * @returns A buffer serialization of the object.
+   */
+  toFieldsBuffer(): Buffer {
+    return Buffer.concat([this.fields[0].toBuffer(), this.fields[1].toBuffer()]);
+  }
+
+  /**
+   * serializes the coordinate to a single 32 byte buffer.
+   * @returns A buffer serialization of the object.
+   */
+  toBuffer(): Buffer {
+    const buf0 = this.fields[0].toBuffer();
+    const buf1 = this.fields[1].toBuffer();
+    buf0[0] = buf1[31];
+    return buf0;
+  }
+
+  /**
+   * Returns true if this coordinate is equal to the one provided
+   * @param other - The coordinate against which to compare
+   * @returns True if the coordinates are the same, false otherwise
+   */
+  equals(other: Coordinate): boolean {
+    return this.toBigInt() === other.toBigInt();
+  }
+
+  /**
+   * Returns the coordinate's value as a bigint
+   * @returns The coordinate value as a bigint
+   */
+  toBigInt(): bigint {
+    return toBigIntBE(this.toBuffer());
+  }
+
+  /**
+   * Creates a coordinate object from a 32 byte coordinate value
+   * @param coordinate - A buffer containing the 32 byte coordinate value
+   * @returns The new coordinate object
+   */
+  static fromBuffer(coordinate: Buffer) {
+    if (coordinate.length != 32) {
+      throw new Error(`Invalid size of coordinate buffer`);
+    }
+    const buf0 = Buffer.alloc(32);
+    coordinate.copy(buf0, 0, 0, 32);
+    const buf1 = Buffer.alloc(32);
+    buf1[31] = buf0[0];
+    buf0[0] = 0;
+    return new Coordinate([Fr.fromBuffer(buf0), Fr.fromBuffer(buf1)]);
+  }
+
+  /**
+   * Creates a coordinate object from a field
+   * @param coordinate - The field containing the coordinate
+   * @returns The new coordinate object
+   */
+  static fromField(coordinate: Fr) {
+    const buf0 = coordinate.toBuffer();
+    const buf1 = Buffer.alloc(32);
+    buf1[31] = buf0[0];
+    buf0[0] = 0;
+    return new Coordinate([Fr.fromBuffer(buf0), Fr.fromBuffer(buf1)]);
+  }
+}

package/src/fields/fields.ts

@@ -0,0 +1,328 @@
+import { toBigIntBE, toBufferBE } from '../bigint-buffer/index.js';
+import { randomBytes } from '../crypto/random/index.js';
+import { BufferReader } from '../serialize/buffer_reader.js';
+
+const ZERO_BUFFER = Buffer.alloc(32);
+
+/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
+
+/**
+ * Represents a field derived from BaseField.
+ */
+type DerivedField<T extends BaseField> = {
+  new (value: any): T;
+  /**
+   * All derived fields will specify a MODULUS.
+   */
+  MODULUS: bigint;
+};
+
+/**
+ * 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;
+
+  /**
+   * Return bigint representation.
+   * @deprecated Just to get things compiling. Use toBigInt().
+   * */
+  get value(): bigint {
+    return this.toBigInt();
+  }
+
+  protected constructor(value: number | bigint | boolean | BaseField | Buffer) {
+    if (value instanceof Buffer) {
+      if (value.length > BaseField.SIZE_IN_BYTES) {
+        throw new Error(`Value length ${value.length} exceeds ${BaseField.SIZE_IN_BYTES}`);
+      }
+      this.asBuffer =
+        value.length === BaseField.SIZE_IN_BYTES
+          ? 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 0x${this.asBigInt.toString(16)} is greater or equal 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.`);
+    }
+
+    // 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;
+
+  /**
+   * We return a copy of the Buffer to ensure this remains immutable.
+   */
+  toBuffer(): Buffer {
+    if (!this.asBuffer) {
+      this.asBuffer = toBufferBE(this.asBigInt!, 32);
+    }
+    return Buffer.from(this.asBuffer);
+  }
+
+  toString(): `0x${string}` {
+    return `0x${this.toBuffer().toString('hex')}`;
+  }
+
+  toBigInt(): bigint {
+    if (this.asBigInt === undefined) {
+      this.asBigInt = toBigIntBE(this.asBuffer!);
+      if (this.asBigInt >= this.modulus()) {
+        throw new Error(`Value 0x${this.asBigInt.toString(16)} is greater or equal to field modulus.`);
+      }
+    }
+    return this.asBigInt;
+  }
+
+  toBool(): boolean {
+    return Boolean(this.toBigInt());
+  }
+
+  toNumber(): number {
+    const value = this.toBigInt();
+    if (value > Number.MAX_SAFE_INTEGER) {
+      throw new Error(`Value ${value.toString(16)} greater than than max safe integer`);
+    }
+    return Number(value);
+  }
+
+  toShortString(): string {
+    const str = this.toString();
+    return `${str.slice(0, 10)}...${str.slice(-4)}`;
+  }
+
+  equals(rhs: BaseField): boolean {
+    return this.toBuffer().equals(rhs.toBuffer());
+  }
+
+  lt(rhs: BaseField): boolean {
+    return this.toBigInt() < rhs.toBigInt();
+  }
+
+  isZero(): boolean {
+    return this.toBuffer().equals(ZERO_BUFFER);
+  }
+
+  toFriendlyJSON(): string {
+    return this.toString();
+  }
+
+  toField() {
+    return this;
+  }
+}
+
+/**
+ * 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.
+ */
+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));
+}
+
+/**
+ * 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;
+  }
+
+  static random() {
+    return random(Fr);
+  }
+
+  static zero() {
+    return Fr.ZERO;
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    return fromBuffer(buffer, Fr);
+  }
+
+  static fromBufferReduce(buffer: Buffer) {
+    return fromBufferReduce(buffer, Fr);
+  }
+
+  static fromString(buf: string) {
+    return fromString(buf, Fr);
+  }
+
+  /** Arithmetic */
+
+  add(rhs: Fr) {
+    return new Fr((this.toBigInt() + rhs.toBigInt()) % Fr.MODULUS);
+  }
+
+  sub(rhs: Fr) {
+    const result = this.toBigInt() - rhs.toBigInt();
+    return new Fr(result < 0 ? result + Fr.MODULUS : result);
+  }
+
+  mul(rhs: Fr) {
+    return new Fr((this.toBigInt() * rhs.toBigInt()) % Fr.MODULUS);
+  }
+
+  div(rhs: Fr) {
+    if (rhs.isZero()) {
+      throw new Error('Division by zero');
+    }
+
+    const bInv = modInverse(rhs.toBigInt());
+    return this.mul(bInv);
+  }
+}
+
+/**
+ * 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);
+  }
+
+  get high(): Fr {
+    return new Fr(this.toBigInt() >> Fq.HIGH_SHIFT);
+  }
+
+  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());
+  }
+}
+
+// Beware: Performance bottleneck below
+
+/**
+ * Find the modular inverse of a given element, for BN254 Fr.
+ */
+function modInverse(b: bigint) {
+  const [gcd, x, _] = extendedEuclidean(b, Fr.MODULUS);
+  if (gcd != 1n) {
+    throw Error('Inverse does not exist');
+  }
+  // Add modulus if -ve to ensure positive
+  return new Fr(x > 0 ? x : x + Fr.MODULUS);
+}
+
+/**
+ * The extended Euclidean algorithm can be used to find the multiplicative inverse of a field element
+ * This is used to perform field division.
+ */
+function extendedEuclidean(a: bigint, modulus: bigint): [bigint, bigint, bigint] {
+  if (a == 0n) {
+    return [modulus, 0n, 1n];
+  } else {
+    const [gcd, x, y] = extendedEuclidean(modulus % a, a);
+    return [gcd, y - (modulus / a) * x, x];
+  }
+}
+
+/**
+ * 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

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