@aztec/foundation 0.22.0 → 0.24.0

package/src/abi/encoder.ts

@@ -0,0 +1,143 @@
+import { Fr } from '../fields/index.js';
+import { ABIType, FunctionAbi } from './abi.js';
+import { isAddressStruct, isFunctionSelectorStruct, isWrappedFieldStruct } from './utils.js';
+
+/**
+ * Encodes arguments for a function call.
+ * Missing support for integer and string.
+ */
+class ArgumentEncoder {
+  private flattened: Fr[] = [];
+
+  constructor(private abi: FunctionAbi, private args: any[]) {}
+
+  static typeSize(abiType: ABIType): number {
+    switch (abiType.kind) {
+      case 'field':
+      case 'boolean':
+      case 'integer':
+        return 1;
+      case 'string':
+        return abiType.length;
+      case 'array':
+        return abiType.length * ArgumentEncoder.typeSize(abiType.type);
+      case 'struct':
+        return abiType.fields.reduce((acc, field) => acc + ArgumentEncoder.typeSize(field.type), 0);
+      default: {
+        const exhaustiveCheck: never = abiType;
+        throw new Error(`Unhandled abi type: ${exhaustiveCheck}`);
+      }
+    }
+  }
+
+  /**
+   * Encodes a single argument from the given type to field.
+   * @param abiType - The abi type of the argument.
+   * @param arg - The value to encode.
+   * @param name - Name.
+   */
+  private encodeArgument(abiType: ABIType, arg: any, name?: string) {
+    if (arg === undefined || arg == null) {
+      throw new Error(`Undefined argument ${name ?? 'unnamed'} of type ${abiType.kind}`);
+    }
+    switch (abiType.kind) {
+      case 'field':
+        if (typeof arg === 'number') {
+          this.flattened.push(new Fr(BigInt(arg)));
+        } else if (typeof arg === 'bigint') {
+          this.flattened.push(new Fr(arg));
+        } else if (typeof arg === 'boolean') {
+          this.flattened.push(new Fr(arg ? 1n : 0n));
+        } else if (typeof arg === 'object') {
+          if (Buffer.isBuffer(arg)) {
+            this.flattened.push(Fr.fromBuffer(arg));
+          } else if (typeof arg.toField === 'function') {
+            this.flattened.push(arg.toField());
+          } else {
+            throw new Error(`Argument for ${name} cannot be serialized to a field`);
+          }
+        } else {
+          throw new Error(`Invalid argument "${arg}" of type ${abiType.kind}`);
+        }
+        break;
+      case 'boolean':
+        this.flattened.push(new Fr(arg ? 1n : 0n));
+        break;
+      case 'array':
+        for (let i = 0; i < abiType.length; i += 1) {
+          this.encodeArgument(abiType.type, arg[i], `${name}[${i}]`);
+        }
+        break;
+      case 'string':
+        for (let i = 0; i < abiType.length; i += 1) {
+          // If the string is shorter than the defined length, pad it with 0s.
+          const toInsert = i < arg.length ? BigInt((arg as string).charCodeAt(i)) : 0n;
+          this.flattened.push(new Fr(toInsert));
+        }
+        break;
+      case 'struct': {
+        // If the abi expects a struct like { address: Field } and the supplied arg does not have
+        // an address field in it, we try to encode it as if it were a field directly.
+        const isAddress = isAddressStruct(abiType);
+        if (isAddress && typeof arg.address === 'undefined' && typeof arg.inner === 'undefined') {
+          this.encodeArgument({ kind: 'field' }, arg, `${name}.inner`);
+          break;
+        }
+        // Or if the supplied argument does have an address field in it, like a CompleteAddress,
+        // we encode it directly as a field.
+        if (isAddress && typeof arg.address !== 'undefined') {
+          this.encodeArgument({ kind: 'field' }, arg.address, `${name}.address`);
+          break;
+        }
+        if (isFunctionSelectorStruct(abiType)) {
+          this.encodeArgument({ kind: 'integer', sign: 'unsigned', width: 32 }, arg.value ?? arg, `${name}.inner`);
+          break;
+        }
+        if (isWrappedFieldStruct(abiType)) {
+          this.encodeArgument({ kind: 'field' }, arg.inner ?? arg, `${name}.inner`);
+          break;
+        }
+        for (const field of abiType.fields) {
+          this.encodeArgument(field.type, arg[field.name], `${name}.${field.name}`);
+        }
+        break;
+      }
+      case 'integer':
+        this.flattened.push(new Fr(arg));
+        break;
+      default:
+        throw new Error(`Unsupported type: ${abiType}`);
+    }
+  }
+
+  /**
+   * Encodes all the arguments for the given function ABI.
+   * @returns The encoded arguments.
+   */
+  public encode() {
+    for (let i = 0; i < this.abi.parameters.length; i += 1) {
+      const parameterAbi = this.abi.parameters[i];
+      this.encodeArgument(parameterAbi.type, this.args[i], parameterAbi.name);
+    }
+    return this.flattened;
+  }
+}
+
+/**
+ * Encodes all the arguments for a function call.
+ * @param abi - The function ABI entry.
+ * @param args - The arguments to encode.
+ * @returns The encoded arguments.
+ */
+export function encodeArguments(abi: FunctionAbi, args: any[]) {
+  return new ArgumentEncoder(abi, args).encode();
+}
+
+/**
+ * Returns the size of the arguments for a function ABI.
+ * @param abi - The function ABI entry.
+ * @returns The size of the arguments.
+ */
+export function countArgumentsSize(abi: FunctionAbi) {
+  return abi.parameters.reduce((acc, parameter) => acc + ArgumentEncoder.typeSize(parameter.type), 0);
+}

package/src/abi/index.ts

@@ -0,0 +1,6 @@
+export * from './abi.js';
+export * from './buffer.js';
+export * from './encoder.js';
+export * from './decoder.js';
+export * from './selector.js';
+export * from './utils.js';

package/src/abi/selector.ts

@@ -0,0 +1,243 @@
+import { randomBytes } from 'crypto';
+
+import { fromHex, toBigIntBE, toBufferBE } from '../bigint-buffer/index.js';
+import { keccak } from '../crypto/keccak/index.js';
+import { Fr } from '../fields/index.js';
+import { BufferReader, FieldReader } from '../serialize/index.js';
+import { type ABIParameter } from './abi.js';
+import { decodeFunctionSignature } from './decoder.js';
+
+/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
+
+/** A selector is the first 4 bytes of the hash of a signature. */
+abstract class Selector {
+  /** The size of the selector in bytes. */
+  public static SIZE = 4;
+
+  constructor(/** Value of the selector */ public value: number) {
+    if (value > 2 ** (Selector.SIZE * 8) - 1) {
+      throw new Error(`Selector must fit in ${Selector.SIZE} bytes (got value ${value}).`);
+    }
+  }
+
+  /**
+   * Checks if the selector is empty (all bytes are 0).
+   * @returns True if the selector is empty (all bytes are 0).
+   */
+  public isEmpty(): boolean {
+    return this.value === 0;
+  }
+
+  /**
+   * Serialize as a buffer.
+   * @param bufferSize - The buffer size.
+   * @returns The buffer.
+   */
+  toBuffer(bufferSize = Selector.SIZE): Buffer {
+    return toBufferBE(BigInt(this.value), bufferSize);
+  }
+
+  /**
+   * Serialize as a hex string.
+   * @returns The string.
+   */
+  toString(): string {
+    return this.toBuffer().toString('hex');
+  }
+
+  /**
+   * Checks if this selector is equal to another.
+   * @param other - The other selector.
+   * @returns True if the selectors are equal.
+   */
+  equals(other: Selector): boolean {
+    return this.value === other.value;
+  }
+
+  /**
+   * Returns a new field with the same contents as this EthAddress.
+   *
+   * @returns An Fr instance.
+   */
+  public toField() {
+    return new Fr(BigInt(this.value));
+  }
+}
+
+/** Function selector branding */
+export interface FunctionSelector {
+  /** Brand. */
+  _branding: 'FunctionSelector';
+}
+
+/** A function selector is the first 4 bytes of the hash of a function signature. */
+export class FunctionSelector extends Selector {
+  /**
+   * Checks if this function selector is equal to another.
+   * @returns True if the function selectors are equal.
+   */
+  equals(otherName: string, otherParams: ABIParameter[]): boolean;
+  equals(other: FunctionSelector): boolean;
+  equals(other: FunctionSelector | string, otherParams?: ABIParameter[]): boolean {
+    if (typeof other === 'string') {
+      return this.equals(FunctionSelector.fromNameAndParameters(other, otherParams!));
+    }
+    return this.value === other.value;
+  }
+
+  /**
+   * Deserializes from a buffer or reader, corresponding to a write in cpp.
+   * @param buffer - Buffer  or BufferReader to read from.
+   * @returns The Selector.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    const value = Number(toBigIntBE(reader.readBytes(Selector.SIZE)));
+    return new FunctionSelector(value);
+  }
+
+  /**
+   * Converts a field to selector.
+   * @param fr - The field to convert.
+   * @returns The selector.
+   */
+  static fromField(fr: Fr) {
+    return new FunctionSelector(Number(fr.toBigInt()));
+  }
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+    return FunctionSelector.fromField(reader.readField());
+  }
+
+  /**
+   * Creates a selector from a signature.
+   * @param signature - Signature to generate the selector for (e.g. "transfer(field,field)").
+   * @returns selector.
+   */
+  static fromSignature(signature: string) {
+    // throw if signature contains whitespace
+    if (/\s/.test(signature)) {
+      throw new Error('Signature cannot contain whitespace');
+    }
+    return FunctionSelector.fromBuffer(keccak(Buffer.from(signature)).subarray(0, Selector.SIZE));
+  }
+
+  /**
+   * Create a Selector instance from a hex-encoded string.
+   * The input 'address' should be prefixed with '0x' or not, and have exactly 64 hex characters.
+   * Throws an error if the input length is invalid or address value is out of range.
+   *
+   * @param selector - The hex-encoded string representing the Selector.
+   * @returns An Selector instance.
+   */
+  static fromString(selector: string) {
+    const buf = fromHex(selector);
+    if (buf.length !== Selector.SIZE) {
+      throw new Error(`Invalid Selector length ${buf.length} (expected ${Selector.SIZE}).`);
+    }
+    return FunctionSelector.fromBuffer(buf);
+  }
+
+  /**
+   * Creates an empty selector.
+   * @returns An empty selector.
+   */
+  static empty() {
+    return new FunctionSelector(0);
+  }
+
+  /**
+   * Creates a function selector for a given function name and parameters.
+   * @param name - The name of the function.
+   * @param parameters - An array of ABIParameter objects, each containing the type information of a function parameter.
+   * @returns A Buffer containing the 4-byte selector.
+   */
+  static fromNameAndParameters(args: { name: string; parameters: ABIParameter[] }): FunctionSelector;
+  static fromNameAndParameters(name: string, parameters: ABIParameter[]): FunctionSelector;
+  static fromNameAndParameters(
+    nameOrArgs: string | { name: string; parameters: ABIParameter[] },
+    maybeParameters?: ABIParameter[],
+  ): FunctionSelector {
+    const { name, parameters } =
+      typeof nameOrArgs === 'string' ? { name: nameOrArgs, parameters: maybeParameters! } : nameOrArgs;
+    const signature = decodeFunctionSignature(name, parameters);
+    const selector = this.fromSignature(signature);
+    // If using the debug logger here it kill the typing in the `server_world_state_synchronizer` and jest tests.
+    // console.log(`selector for ${signature} is ${selector}`);
+    return selector;
+  }
+
+  /**
+   * Creates a random instance.
+   */
+  static random() {
+    return FunctionSelector.fromBuffer(randomBytes(Selector.SIZE));
+  }
+}
+
+/** Event selector branding */
+export interface EventSelector {
+  /** Brand. */
+  _branding: 'EventSelector';
+}
+
+/** An event selector is the first 4 bytes of the hash of an event signature. */
+export class EventSelector extends Selector {
+  /**
+   * Deserializes from a buffer or reader, corresponding to a write in cpp.
+   * @param buffer - Buffer  or BufferReader to read from.
+   * @returns The Selector.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    const value = Number(toBigIntBE(reader.readBytes(Selector.SIZE)));
+    return new EventSelector(value);
+  }
+
+  /**
+   * Converts a field to selector.
+   * @param fr - The field to convert.
+   * @returns The selector.
+   */
+  static fromField(fr: Fr) {
+    return new EventSelector(Number(fr.toBigInt()));
+  }
+
+  /**
+   * Creates a selector from a signature.
+   * @param signature - Signature to generate the selector for (e.g. "transfer(field,field)").
+   * @returns selector.
+   */
+  static fromSignature(signature: string) {
+    // throw if signature contains whitespace
+    if (/\s/.test(signature)) {
+      throw new Error('Signature cannot contain whitespace');
+    }
+    return EventSelector.fromBuffer(keccak(Buffer.from(signature)).subarray(0, Selector.SIZE));
+  }
+
+  /**
+   * Create a Selector instance from a hex-encoded string.
+   * The input 'address' should be prefixed with '0x' or not, and have exactly 64 hex characters.
+   * Throws an error if the input length is invalid or address value is out of range.
+   *
+   * @param selector - The hex-encoded string representing the Selector.
+   * @returns An Selector instance.
+   */
+  static fromString(selector: string) {
+    const buf = fromHex(selector);
+    if (buf.length !== Selector.SIZE) {
+      throw new Error(`Invalid Selector length ${buf.length} (expected ${Selector.SIZE}).`);
+    }
+    return EventSelector.fromBuffer(buf);
+  }
+
+  /**
+   * Creates an empty selector.
+   * @returns An empty selector.
+   */
+  static empty() {
+    return new EventSelector(0);
+  }
+}

package/src/abi/utils.ts

@@ -0,0 +1,50 @@
+import { type ABIType } from './abi.js';
+
+/**
+ * Returns whether the ABI type is an Aztec or Ethereum Address defined in Aztec.nr.
+ * @param abiType - Type to check.
+ * @returns Boolean.
+ */
+export function isAddressStruct(abiType: ABIType) {
+  return isEthAddressStruct(abiType) || isAztecAddressStruct(abiType);
+}
+
+/**
+ * Returns whether the ABI type is an Ethereum Address defined in Aztec.nr.
+ * @param abiType - Type to check.
+ * @returns Boolean.
+ */
+export function isEthAddressStruct(abiType: ABIType) {
+  return abiType.kind === 'struct' && abiType.path.endsWith('types::address::EthAddress');
+}
+
+/**
+ * Returns whether the ABI type is an Aztec Address defined in Aztec.nr.
+ * @param abiType - Type to check.
+ * @returns Boolean.
+ */
+export function isAztecAddressStruct(abiType: ABIType) {
+  return abiType.kind === 'struct' && abiType.path.endsWith('types::address::AztecAddress');
+}
+
+/**
+ * Returns whether the ABI type is an Function Selector defined in Aztec.nr.
+ * @param abiType - Type to check.
+ * @returns Boolean.
+ */
+export function isFunctionSelectorStruct(abiType: ABIType) {
+  return abiType.kind === 'struct' && abiType.path.endsWith('types::abis::function_selector::FunctionSelector');
+}
+
+/**
+ * Returns whether the ABI type is a struct with a single `inner` field.
+ * @param abiType - Type to check.
+ */
+export function isWrappedFieldStruct(abiType: ABIType) {
+  return (
+    abiType.kind === 'struct' &&
+    abiType.fields.length === 1 &&
+    abiType.fields[0].name === 'inner' &&
+    abiType.fields[0].type.kind === 'field'
+  );
+}

package/src/array/array.ts

@@ -0,0 +1,86 @@
+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}`);
+    }
+  }
+}

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,36 @@
+import { Fr } from '../fields/index.js';
+import { 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);
+  }
+
+  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);
+  }
+}

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');
+}