@aztec/foundation 0.23.0 → 0.26.1

package/src/array/array.ts

@@ -0,0 +1,119 @@
+import { Tuple } from '../serialize/index.js';
+
+export type { FieldsOf } from '../types/index.js';
+
+/**
+ * Create an array over an integer range.
+ * @param n - The number of integers.
+ * @param offset - The starting number.
+ * @returns The array of numbers.
+ */
+export function range(n: number, offset = 0) {
+  const ret: number[] = [];
+  for (let i = 0; i < n; i++) {
+    ret.push(offset + i);
+  }
+  return ret;
+}
+
+/**
+ * Create an array over an integer range, filled with a function 'fn'.
+ * This is used over e.g. lodash because it resolved to a tuple type, needed for our fixed array type safety.
+ * @param n - The number of integers.
+ * @param fn - The generator function.
+ * @returns The array of numbers.
+ */
+export function makeTuple<T, N extends number>(length: N, fn: (i: number) => T, offset = 0) {
+  return Array.from({ length }, (v: any, i: number) => fn(i + offset)) as Tuple<T, N>;
+}
+
+/**
+ * Create an array over an integer range, filled with a function 'fn'. However, the latter half of the array are set to zeros.
+ * see `makeTuple` above.
+ * @param n - The number of integers.
+ * @param fn - The generator function.
+ * @returns The array of numbers.
+ */
+export function makeHalfFullTuple<T, N extends number>(length: N, fn: (i: number) => T, offset = 0) {
+  return Array.from({ length }, (v: any, i: number) => (i < length / 2 ? fn(i + offset) : fn(0))) as Tuple<T, N>;
+}
+
+/**
+ * Assert a member of an object is a certain length.
+ * @param obj - An object.
+ * @param member - A member string.
+ * @param length - The length.
+ */
+export function assertMemberLength<
+  F extends string,
+  T extends {
+    [f in F]: {
+      /**
+       * A property which the tested member of the object T has to have.
+       */
+      length: number;
+    };
+  },
+>(obj: T, member: F, length: number) {
+  if (obj[member].length !== length) {
+    throw new Error(`Expected ${member} to have length ${length} but was ${obj[member].length}`);
+  }
+}
+
+/**
+ * Assert all subarrays in a member of an object are a certain length.
+ * @param obj - An object.
+ * @param member - A member string.
+ * @param length - The expected length for each subarray.
+ */
+export function assertItemsLength<
+  F extends string,
+  T extends {
+    [f in F]: {
+      /**
+       * A property which the tested member of the object T has to have.
+       */
+      length: number;
+    }[];
+  },
+>(obj: T, member: F, length: number) {
+  const arrays = obj[member];
+  for (let i = 0; i < arrays.length; i++) {
+    if (arrays[i].length !== length) {
+      throw new Error(`Expected ${member}[${i}] to have length ${length} but was ${arrays[i].length}`);
+    }
+  }
+}
+
+/**
+ * Checks that the permutation is valid. Throws an error if it is not.
+ * @param original - The original array.
+ * @param permutation - The array which is allegedly a permutation of the original.
+ * @param indexes - The indices of the original array which the permutation should map to.
+ * @param isEqual - A function to compare the elements of the original and permutation arrays.
+ */
+export function assertPermutation<T>(
+  original: T[],
+  permutation: T[],
+  indexes: number[],
+  isEqual: (a: T, b: T) => boolean,
+): void {
+  if (original.length !== permutation.length || original.length !== indexes.length) {
+    throw new Error(`Invalid lengths: ${original.length}, ${permutation.length}, ${indexes.length}`);
+  }
+
+  const seenValue = new Set<number>();
+  for (let i = 0; i < indexes.length; i++) {
+    const index = indexes[i];
+    const permutedValue = permutation[i];
+    const originalValueAtIndex = original[index];
+
+    if (!isEqual(permutedValue, originalValueAtIndex)) {
+      throw new Error(`Invalid permutation at index ${index}: ${permutedValue} !== ${originalValueAtIndex}`);
+    }
+    if (seenValue.has(index)) {
+      throw new Error(`Duplicate index in permutation: ${index}`);
+    }
+    seenValue.add(index);
+  }
+}

package/src/array/index.ts

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

package/src/async-map/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Maps an array of elements by applying an asynchronous function to each element in sequence,
+ * and returns a new array with the results. The function receives each element of the array
+ * and its index as arguments, and should return a Promise that resolves to the desired value.
+ *
+ * @typeParam T - The original array element type.
+ * @typeParam U - The resulting array element type.
+ * @param arr - The array to map.
+ * @param fn - The async function to apply on each element of the array.
+ * @returns A Promise that resolves to a new array containing the mapped values.
+ */
+export async function asyncMap<T, U>(arr: T[], fn: (e: T, i: number) => Promise<U>): Promise<U[]> {
+  const results: U[] = [];
+  for (let i = 0; i < arr.length; ++i) {
+    results.push(await fn(arr[i], i));
+  }
+  return results;
+}

package/src/aztec-address/index.ts

@@ -0,0 +1,56 @@
+import { inspect } from 'util';
+
+import { Fr, fromBuffer } from '../fields/index.js';
+import { BufferReader, FieldReader } from '../serialize/index.js';
+
+/**
+ * AztecAddress represents a 32-byte address in the Aztec Protocol.
+ * It provides methods to create, manipulate, and compare addresses.
+ * The maximum value of an address is determined by the field modulus and all instances of AztecAddress.
+ * It should have a value less than or equal to this max value.
+ * This class also provides helper functions to convert addresses from strings, buffers, and other formats.
+ */
+export class AztecAddress extends Fr {
+  constructor(buffer: Buffer) {
+    if (buffer.length !== 32) {
+      throw new Error(`Invalid AztecAddress length ${buffer.length}.`);
+    }
+    super(buffer);
+  }
+
+  [inspect.custom]() {
+    return `AztecAddress<${this.toString()}>`;
+  }
+
+  static ZERO = new AztecAddress(Buffer.alloc(32));
+
+  static zero(): AztecAddress {
+    return AztecAddress.ZERO;
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    return fromBuffer(buffer, AztecAddress);
+  }
+
+  static fromField(fr: Fr) {
+    return new AztecAddress(fr.toBuffer());
+  }
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+    return AztecAddress.fromField(reader.readField());
+  }
+
+  static fromBigInt(value: bigint) {
+    return AztecAddress.fromField(new Fr(value));
+  }
+
+  static fromString(buf: string) {
+    const buffer = Buffer.from(buf.replace(/^0x/i, ''), 'hex');
+    return new AztecAddress(buffer);
+  }
+
+  static random() {
+    return new AztecAddress(super.random().toBuffer());
+  }
+}

package/src/bigint-buffer/index.ts

@@ -0,0 +1,87 @@
+/**
+ * Convert a little-endian buffer into a BigInt.
+ * @param buf - The little-endian buffer to convert.
+ * @returns A BigInt with the little-endian representation of buf.
+ */
+export function toBigIntLE(buf: Buffer): bigint {
+  const reversed = Buffer.from(buf);
+  reversed.reverse();
+  const hex = reversed.toString('hex');
+  if (hex.length === 0) {
+    return BigInt(0);
+  }
+  return BigInt(`0x${hex}`);
+}
+
+/**
+ * Convert a big-endian buffer into a BigInt.
+ * @param buf - The big-endian buffer to convert.
+ * @returns A BigInt with the big-endian representation of buf.
+ */
+export function toBigIntBE(buf: Buffer): bigint {
+  const hex = buf.toString('hex');
+  if (hex.length === 0) {
+    return BigInt(0);
+  }
+  return BigInt(`0x${hex}`);
+}
+
+/**
+ * Convert a BigInt to a little-endian buffer.
+ * @param num - The BigInt to convert.
+ * @param width - The number of bytes that the resulting buffer should be.
+ * @returns A little-endian buffer representation of num.
+ */
+export function toBufferLE(num: bigint, width: number): Buffer {
+  if (num < BigInt(0)) {
+    throw new Error(`Cannot convert negative bigint ${num.toString()} to buffer with toBufferLE.`);
+  }
+  const hex = num.toString(16);
+  const buffer = Buffer.from(hex.padStart(width * 2, '0').slice(0, width * 2), 'hex');
+  buffer.reverse();
+  return buffer;
+}
+
+/**
+ * Convert a BigInt to a big-endian buffer.
+ * @param num - The BigInt to convert.
+ * @param width - The number of bytes that the resulting buffer should be.
+ * @returns A big-endian buffer representation of num.
+ */
+export function toBufferBE(num: bigint, width: number): Buffer {
+  if (num < BigInt(0)) {
+    throw new Error(`Cannot convert negative bigint ${num.toString()} to buffer with toBufferBE.`);
+  }
+  const hex = num.toString(16);
+  const buffer = Buffer.from(hex.padStart(width * 2, '0').slice(0, width * 2), 'hex');
+  if (buffer.length > width) {
+    throw new Error(`Number ${num.toString(16)} does not fit in ${width}`);
+  }
+  return buffer;
+}
+
+/**
+ * Converts a BigInt to its hex representation.
+ * @param num - The BigInt to convert.
+ * @param padTo32 - Whether to pad the resulting string to 32 bytes.
+ * @returns An even-length 0x-prefixed string.
+ */
+export function toHex(num: bigint, padTo32 = false): `0x${string}` {
+  const str = num.toString(16);
+  const targetLen = str.length % 2 === 0 ? str.length : str.length + 1;
+  const paddedStr = str.padStart(padTo32 ? 64 : targetLen, '0');
+  return `0x${paddedStr}`;
+}
+
+/**
+ * Converts a hex string to a buffer. Throws if input is not a valid hex string.
+ * @param value - The hex string to convert. May be 0x prefixed or not.
+ * @returns A buffer.
+ */
+export function fromHex(value: string): Buffer {
+  const hexRegex = /^(0x)?[0-9a-fA-F]*$/;
+  if (!hexRegex.test(value) || value.length % 2 !== 0) {
+    throw new Error(`Invalid hex string: ${value}`);
+  }
+  return Buffer.from(value.replace(/^0x/i, ''), 'hex');
+}

package/src/collection/array.ts

@@ -0,0 +1,64 @@
+import { Tuple } from '../serialize/types.js';
+
+/**
+ * Pads an array to the target length by appending an element to its end. Throws if target length exceeds the input array length. Does not modify the input array.
+ * @param arr - Array with elements to pad.
+ * @param elem - Element to use for padding.
+ * @param length - Target length.
+ * @returns A new padded array.
+ */
+export function padArrayEnd<T, N extends number>(arr: T[], elem: T, length: N): Tuple<T, N> {
+  if (arr.length > length) {
+    throw new Error(`Array size exceeds target length`);
+  }
+  // Since typescript cannot always deduce that something is a tuple, we cast
+  return [...arr, ...Array(length - arr.length).fill(elem)] as Tuple<T, N>;
+}
+
+/**
+ * Pads an array to the target length by prepending elements at the beginning. Throws if target length exceeds the input array length. Does not modify the input array.
+ * @param arr - Array with elements to pad.
+ * @param elem - Element to use for padding.
+ * @param length - Target length.
+ * @returns A new padded array.
+ */
+export function padArrayStart<T, N extends number>(arr: T[], elem: T, length: N): Tuple<T, N> {
+  if (arr.length > length) {
+    throw new Error(`Array size exceeds target length`);
+  }
+  // Since typescript cannot always deduce that something is a tuple, we cast
+  return [...Array(length - arr.length).fill(elem), ...arr] as Tuple<T, N>;
+}
+
+/**
+ * Returns if an array is composed of empty items.
+ * @param arr - Array to check.
+ * @returns True if every item in the array isEmpty.
+ */
+export function isArrayEmpty<T>(arr: T[], isEmpty: (item: T) => boolean): boolean {
+  for (const item of arr) {
+    if (!isEmpty(item)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Returns the number of non-empty items in an array.
+ * @param arr - Array to check.
+ * @returns Number of non-empty items in an array.
+ */
+export function arrayNonEmptyLength<T>(arr: T[], isEmpty: (item: T) => boolean): number {
+  return arr.reduce((sum, item) => (isEmpty(item) ? sum : sum + 1), 0);
+}
+
+/**
+ * Executes the given function n times and returns the results in an array.
+ * @param n - How many times to repeat.
+ * @param fn - Mapper from index to value.
+ * @returns The array with the result from all executions.
+ */
+export function times<T>(n: number, fn: (i: number) => T): T[] {
+  return [...Array(n).keys()].map(i => fn(i));
+}

package/src/collection/index.ts

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

package/src/committable/committable.ts

@@ -0,0 +1,46 @@
+/**
+ * A class that allows for a value to be committed or rolled back.
+ */
+export class Committable<T> {
+  private currentValue: T;
+  private nextValue: T | undefined = undefined;
+
+  constructor(initialValue: T) {
+    this.currentValue = initialValue;
+  }
+
+  /**
+   * Commits the uncommitted value.
+   */
+  public commit() {
+    if (this.nextValue === undefined) {
+      return;
+    }
+    this.currentValue = this.nextValue;
+    this.nextValue = undefined;
+  }
+
+  /**
+   * Rolls back the uncommitted value.
+   */
+  public rollback() {
+    this.nextValue === undefined;
+  }
+
+  /**
+   * Gets the current value.
+   * @param includeUncommitted - Whether to include the uncommitted value.
+   * @returns The current value if includeUncommitted is false, otherwise the uncommitted value.
+   */
+  public get(includeUncommitted: boolean = false): T {
+    return includeUncommitted && this.nextValue ? this.nextValue : this.currentValue;
+  }
+
+  /**
+   * Sets the next value to be committed to.
+   * @param value - The new value to be set.
+   */
+  public set(value: T) {
+    this.nextValue = value;
+  }
+}

package/src/committable/index.ts

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

package/src/crypto/index.ts

@@ -0,0 +1,17 @@
+import { BarretenbergSync } from '@aztec/bb.js';
+
+export * from './keccak/index.js';
+export * from './random/index.js';
+export * from './sha256/index.js';
+export * from './pedersen/index.js';
+export * from './poseidon/index.js';
+
+/**
+ * Init the bb singleton. This constructs (if not already) the barretenberg sync api within bb.js itself.
+ * It takes about 100-200ms to initialize. It may not seem like much, but when in conjunction with many other things
+ * initializing, developers may want to pick precisely when to incur this cost.
+ * If in a test environment, we'll just do it on module load.
+ */
+export async function init() {
+  await BarretenbergSync.initSingleton();
+}

package/src/crypto/keccak/index.ts

@@ -0,0 +1,33 @@
+import { Keccak } from 'sha3';
+
+/**
+ * Computes the Keccak-256 hash of the given input buffer.
+ *
+ * @param input - The input buffer to be hashed.
+ * @returns The computed Keccak-256 hash as a Buffer.
+ */
+export function keccak(input: Buffer) {
+  const hash = new Keccak(256);
+  return hash.update(input).digest();
+}
+
+/**
+ * Computes the keccak-256 hash of a given input string and returns the result as a hexadecimal string.
+ */
+export function keccak256String(input: string) {
+  const hash = new Keccak(256);
+  hash.reset();
+  hash.update(input);
+  return hash.digest('hex');
+}
+
+/**
+ * Computes the Keccak-224 hash of the given input buffer.
+ *
+ * @param input - The input buffer to be hashed.
+ * @returns The computed Keccak-224 hash as a Buffer.
+ */
+export function keccak224(input: Buffer) {
+  const hash = new Keccak(224);
+  return hash.update(input).digest();
+}

package/src/crypto/pedersen/index.ts

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