@aztec/foundation 0.1.0-alpha10

package/src/crypto/random/index.ts

@@ -0,0 +1,38 @@
+import isNode from 'detect-node';
+import nodeCrypto from 'crypto';
+
+// limit of Crypto.getRandomValues()
+// https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues
+const MAX_BYTES = 65536;
+
+const getWebCrypto = () => {
+  if (typeof window !== 'undefined' && window.crypto) return window.crypto;
+  if (typeof self !== 'undefined' && self.crypto) return self.crypto;
+  return undefined;
+};
+
+export const randomBytes = (len: number) => {
+  if (isNode) {
+    return nodeCrypto.randomBytes(len) as Buffer;
+  }
+
+  const crypto = getWebCrypto();
+  if (!crypto) {
+    throw new Error('randomBytes UnsupportedEnvironment');
+  }
+
+  const buf = Buffer.allocUnsafe(len);
+  if (len > MAX_BYTES) {
+    // this is the max bytes crypto.getRandomValues
+    // can do at once see https://developer.mozilla.org/en-US/docs/Web/API/window.crypto.getRandomValues
+    for (let generated = 0; generated < len; generated += MAX_BYTES) {
+      // buffer.slice automatically checks if the end is past the end of
+      // the buffer so we don't have to here
+      crypto.getRandomValues(buf.slice(generated, generated + MAX_BYTES));
+    }
+  } else {
+    crypto.getRandomValues(buf);
+  }
+
+  return buf;
+};

package/src/crypto/sha256/index.test.ts

@@ -0,0 +1,13 @@
+import { sha256 } from './index.js';
+import { randomBytes, createHash } from 'crypto';
+
+describe('sha256', () => {
+  it('should correctly hash data using hash.js', () => {
+    const data = randomBytes(67);
+
+    const expected = createHash('sha256').update(data).digest();
+
+    const result = sha256(data);
+    expect(result).toEqual(expected);
+  });
+});

package/src/crypto/sha256/index.ts

@@ -0,0 +1,15 @@
+import { default as hash } from 'hash.js';
+import { toBigIntBE, toBufferBE } from '../../bigint-buffer/index.js';
+import { Fr } from '../../fields/fields.js';
+
+export const sha256 = (data: Buffer) => Buffer.from(hash.sha256().update(data).digest());
+
+/**
+ * Squashes the output of sha256 into a field element.
+ * WARNING: if you have not thought about why you are using this, or talked to somebody who has do not use it.
+ * @param buf - Input buffer
+ * @returns Returns a sha256 output squashed into a field element.
+ */
+export const sha256ToField = (buf: Buffer): Fr => {
+  return Fr.fromBuffer(toBufferBE(toBigIntBE(sha256(buf)) % Fr.MODULUS, 32));
+};

package/src/errors/index.ts

@@ -0,0 +1,6 @@
+/**
+ * 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 {}

package/src/eth-address/eth_address.test.ts

@@ -0,0 +1,104 @@
+import { EthAddress } from './index.js';
+
+describe('address', () => {
+  it('should return correct string', () => {
+    const address = EthAddress.fromString('0xc6d9d2cd449a754c494264e1809c50e34d64562b');
+    expect(address.toChecksumString()).toBe('0xc6d9d2cD449A754c494264e1809c50e34D64562b');
+  });
+
+  it('should return correct buffer', () => {
+    const address = EthAddress.fromString('0xc6d9d2cd449a754c494264e1809c50e34d64562b');
+    expect(address.toBuffer()).toEqual(Buffer.from('c6d9d2cD449A754c494264e1809c50e34D64562b', 'hex'));
+  });
+
+  it('should return correct 32 byte buffer', () => {
+    const address = EthAddress.fromString('0xc6d9d2cd449a754c494264e1809c50e34d64562b');
+    expect(address.toBuffer32()).toEqual(
+      Buffer.from('000000000000000000000000c6d9d2cD449A754c494264e1809c50e34D64562b', 'hex'),
+    );
+  });
+
+  it('should create address from 32 byte buffer', () => {
+    const buffer = Buffer.from('000000000000000000000000c6d9d2cD449A754c494264e1809c50e34D64562b', 'hex');
+    expect(new EthAddress(buffer)).toEqual(EthAddress.fromString('0xc6d9d2cD449A754c494264e1809c50e34D64562b'));
+  });
+
+  it('should not create address from 32 byte buffer that does not start with 12 0 bytes', () => {
+    const buffer = Buffer.from('010000000000000000000000c6d9d2cD449A754c494264e1809c50e34D64562b', 'hex');
+    expect(() => new EthAddress(buffer)).toThrowError();
+  });
+
+  it('should have correct zero address', () => {
+    expect(EthAddress.ZERO.toString()).toBe('0x0000000000000000000000000000000000000000');
+  });
+
+  describe('isAddress', () => {
+    it(`should return true for valid prefixed address`, () => {
+      expect(EthAddress.isAddress('0xc6d9d2cd449a754c494264e1809c50e34d64562b')).toBe(true);
+    });
+
+    it(`should return true for valid unprefixed address`, () => {
+      expect(EthAddress.isAddress('c6d9d2cd449a754c494264e1809c50e34d64562b')).toBe(true);
+    });
+
+    it(`should return true for valid all uppercase address`, () => {
+      expect(EthAddress.isAddress('0xC6D9D2CD449A754C494264E1809C50E34D64562B')).toBe(true);
+    });
+
+    it(`should return true for correctly checksummed address`, () => {
+      expect(EthAddress.isAddress('0xE247A45c287191d435A8a5D72A7C8dc030451E9F')).toBe(true);
+    });
+
+    it(`should return false for badly checksummed address`, () => {
+      expect(EthAddress.isAddress('0xE247A45C287191d435A8a5D72A7C8dc030451E9F')).toBe(false);
+    });
+
+    it(`should return false for non hex characters`, () => {
+      expect(EthAddress.isAddress('0xg6d9d2cd449a754c494264e1809c50e34d64562b')).toBe(false);
+    });
+  });
+
+  describe('checkAddressChecksum', () => {
+    const tests = [
+      { value: '0x52908400098527886E0F7030069857D2E4169EE7', is: true },
+      { value: '0x8617E340B3D01FA5F11F306F4090FD50E238070D', is: true },
+      { value: '0xde709f2102306220921060314715629080e2fb77', is: true },
+      { value: '0x27b1fdb04752bbc536007a920d24acb045561c26', is: true },
+      { value: '0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed', is: true },
+      { value: '0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359', is: true },
+      { value: '0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB', is: true },
+      { value: '0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb', is: true },
+      { value: '0XD1220A0CF47C7B9BE7A2E6BA89F429762E7B9ADB', is: false },
+      { value: '0xd1220a0cf47c7b9be7a2e6ba89f429762e7b9adb', is: false },
+    ];
+
+    tests.forEach(test => {
+      it(`should return ${test.is} for address ${test.value}`, () => {
+        expect(EthAddress.checkAddressChecksum(test.value)).toBe(test.is);
+      });
+    });
+  });
+
+  describe('toChecksumAddress', () => {
+    const tests = [
+      {
+        value: '0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed',
+        is: '0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed',
+      },
+      {
+        value: '0xfb6916095ca1df60bb79ce92ce3ea74c37c5d359',
+        is: '0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359',
+      },
+      {
+        value: '0xdbf03b407c01e7cd3cbea99509d93f8dddc8c6fb',
+        is: '0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB',
+      },
+    ];
+
+    tests.forEach(test => {
+      it(`should return ${test.is} for address ${test.value}`, () => {
+        expect(EthAddress.toChecksumAddress(test.value)).toBe(test.is);
+      });
+    });
+  });
+});

package/src/eth-address/index.ts

@@ -0,0 +1,236 @@
+import { keccak256String, randomBytes } from '../crypto/index.js';
+import { Fr } from '../fields/index.js';
+import { BufferReader } 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 === 32) {
+      if (!buffer.slice(0, 12).equals(Buffer.alloc(12))) {
+        throw new Error('Invalid address buffer.');
+      } else {
+        this.buffer = buffer.slice(12);
+      }
+    } else 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 upppercase.
+      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.toBuffer());
+  }
+
+  /**
+   * 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 the internal Buffer representation of the Ethereum address.
+   * This method is useful when working with raw binary data or when
+   * integrating with other modules that require a Buffer as input.
+   *
+   * @returns A Buffer instance containing the 20-byte 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));
+  }
+
+  /**
+   * Deserializes from a buffer or reader, corresponding to a write in cpp.
+   * @param buffer - Buffer to read from.
+   * @returns The EthAdress.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader): EthAddress {
+    const reader = BufferReader.asReader(buffer);
+    return new EthAddress(reader.readBuffer());
+  }
+
+  /**
+   * Friendly representation for debugging purposes.
+   * @returns A hex string representing the address.
+   */
+  toFriendlyJSON() {
+    return this.toString();
+  }
+}

package/src/fields/coordinate.test.ts

@@ -0,0 +1,26 @@
+import { toBufferBE } from '../bigint-buffer/index.js';
+import { Coordinate } from './coordinate.js';
+import { Fr } from './fields.js';
+
+const MAX_256_VALUE = 2n ** 256n - 1n;
+
+describe('coordinate', () => {
+  it('stores 256 bits in fields', () => {
+    const max256Value = toBufferBE(MAX_256_VALUE, 32);
+    const coordinate = Coordinate.fromBuffer(max256Value);
+    // this returns a buffer containing the bit pattern split across 2 fields
+    expect(coordinate.toFieldsBuffer()).toEqual(
+      Buffer.concat([Buffer.alloc(1, 0), Buffer.alloc(31, 0xff), Buffer.alloc(31, 0), Buffer.alloc(1, 0xff)]),
+    );
+    // this returns the value in a single 32 byte buffer
+    expect(coordinate.toBuffer()).toEqual(max256Value);
+    // this returns the value as a big int
+    expect(coordinate.toBigInt()).toBe(MAX_256_VALUE);
+  });
+
+  it('can be constructed from a field', () => {
+    const field = Fr.random();
+    const coordinate = Coordinate.fromField(field);
+    expect(coordinate.toBuffer()).toEqual(field.toBuffer());
+  });
+});

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 serialised 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());
+  }
+
+  /**
+   * Serialises the oblect to buffer of 2 fields.
+   * @returns A buffer serialisation of the object.
+   */
+  toFieldsBuffer(): Buffer {
+    return Buffer.concat([this.fields[0].toBuffer(), this.fields[1].toBuffer()]);
+  }
+
+  /**
+   * Serialises the coordinate to a single 32 byte buffer.
+   * @returns A buffer serialisation 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)]);
+  }
+}