@aztec/foundation 0.23.0 → 0.24.0

package/src/serialize/field_reader.ts

@@ -0,0 +1,143 @@
+import { Fq, Fr } from '../fields/fields.js';
+import { Tuple } from './types.js';
+
+/**
+ * The FieldReader class provides a utility for reading various data types from a field array.
+ *
+ * Usage:
+ * Create a new instance of FieldReader with an array of fields and an optional offset.
+ * Use the provided methods to read desired data types from the field array.
+ * The reading methods automatically advance the internal index.
+ */
+export class FieldReader {
+  private index: number;
+  private length: number;
+  constructor(private fields: Fr[], offset = 0) {
+    this.index = offset;
+    this.length = fields.length;
+    if (offset >= this.length) {
+      throw new Error('Offset out of bounds.');
+    }
+  }
+
+  /**
+   * Creates a FieldReader instance from either a field array or an existing FieldReader.
+   *
+   * @param fields - A field array or FieldReader to initialize the FieldReader.
+   * @returns An instance of FieldReader.
+   */
+  public static asReader(fields: Fr[] | FieldReader): FieldReader {
+    if (fields instanceof FieldReader) {
+      return fields;
+    }
+
+    return new FieldReader(fields);
+  }
+
+  /**
+   * Reads a single field from the array.
+   *
+   * @returns A field.
+   */
+  public readField(): Fr {
+    if (this.index === this.length) {
+      throw new Error('Not enough fields to be consumed.');
+    }
+    return this.fields[this.index++];
+  }
+
+  /**
+   * Reads a Fq from the array.
+   *
+   * @returns An Fq.
+   */
+  public readFq(): Fq {
+    return Fq.fromHighLow(this.readField(), this.readField());
+  }
+
+  /**
+   * Reads and returns the next boolean value from the field array.
+   * Advances the internal index by 1, treating the field at the current index as a boolean value.
+   * Returns true if the field is non-zero, false otherwise.
+   * Throw if the value is not 0 or 1.
+   *
+   * @returns A boolean value representing the field at the current index.
+   */
+  public readBoolean(): boolean {
+    const field = this.readField();
+    const value = field.toBigInt();
+    if (value > 1n) {
+      throw new Error('Field is not a boolean.');
+    }
+    return value == 1n;
+  }
+
+  /**
+   * Reads a 32-bit unsigned integer from the field array at the current index position.
+   * Updates the index position by 1 after reading the number.
+   * Throw if the value is greater than 2 ** 32.
+   *
+   * @returns The read 32-bit unsigned integer value.
+   */
+  public readU32(): number {
+    const field = this.readField();
+    const value = field.toBigInt();
+    if (value >= 1n << 32n) {
+      throw new Error('Field is not a u32.');
+    }
+    return Number(value);
+  }
+
+  /**
+   * Read an array of a fixed size field array.
+   *
+   * @param size - The fixed number of fields in the array.
+   * @returns An array of fields.
+   */
+  public readFieldArray<N extends number>(size: N): Tuple<Fr, N> {
+    const result: Fr[] = [];
+    for (let i = 0; i < size; ++i) {
+      result.push(this.readField());
+    }
+    return result as Tuple<Fr, N>;
+  }
+
+  /**
+   * Read an array of a fixed size with elements of type T from the field array.
+   * The 'itemDeserializer' object should have a 'fromFields' method that takes a FieldReader instance as input,
+   * and returns an instance of the desired deserialized data type T.
+   * This method will call the 'fromFields' method for each element in the array and return the resulting array.
+   *
+   * @param size - The fixed number of elements in the array.
+   * @param itemDeserializer - An object with a 'fromFields' method to deserialize individual elements of type T.
+   * @returns An array of instances of type T.
+   */
+  public readArray<T, N extends number>(
+    size: N,
+    itemDeserializer: {
+      /**
+       * A function for deserializing data from a FieldReader instance.
+       */
+      fromFields: (reader: FieldReader) => T;
+    },
+  ): Tuple<T, N> {
+    const result = Array.from({ length: size }, () => itemDeserializer.fromFields(this));
+    return result as Tuple<T, N>;
+  }
+
+  /**
+   * Reads a serialized object from a field array and returns the deserialized object using the given deserializer.
+   *
+   * @typeparam T - The type of the deserialized object.
+   * @param deserializer - An object with a 'fromFields' method that takes a FieldReader instance and returns an instance of the deserialized object.
+   * @returns The deserialized object of type T.
+   */
+  public readObject<T>(deserializer: {
+    /**
+     * A method that takes a FieldReader instance and returns an instance of the deserialized data type.
+     */
+    fromFields: (reader: FieldReader) => T;
+  }): T {
+    return deserializer.fromFields(this);
+  }
+}

package/src/serialize/free_funcs.ts

@@ -0,0 +1,147 @@
+import { Fr } from '../fields/fields.js';
+
+/**
+ * Convert a boolean value to its corresponding byte representation in a Buffer of size 1.
+ * The function takes a boolean value and writes it into a new buffer as either 1 (true) or 0 (false).
+ * This method is useful for converting a boolean value into a binary format that can be stored or transmitted easily.
+ *
+ * @param b - The boolean value to be converted.
+ * @returns A Buffer containing the byte representation of the input boolean value.
+ */
+export function boolToByte(b: boolean) {
+  const buf = Buffer.alloc(1);
+  buf.writeUInt8(b ? 1 : 0);
+  return buf;
+}
+
+/**
+ * @param n - The input number to be converted to a big-endian unsigned 16-bit integer Buffer.
+ * @param bufferSize - Optional, the size of the output Buffer (default is 2).
+ * @returns A Buffer containing the big-endian unsigned 16-bit integer representation of the input number.
+ */
+export function numToUInt16BE(n: number, bufferSize = 2) {
+  const buf = Buffer.alloc(bufferSize);
+  buf.writeUInt16BE(n, bufferSize - 2);
+  return buf;
+}
+
+/**
+ * Convert a number into a 4-byte little-endian unsigned integer buffer.
+ * The input number is serialized as an unsigned 32-bit integer in little-endian byte order,
+ * and returned as a Buffer of specified size (defaults to 4).
+ * If the provided bufferSize is greater than 4, the additional bytes will be padded with zeros.
+ *
+ * @param n - The number to be converted into a little-endian unsigned integer buffer.
+ * @param bufferSize - Optional, the size of the output buffer (default value is 4).
+ * @returns A Buffer containing the serialized little-endian unsigned integer representation of the input number.
+ */
+export function numToUInt32LE(n: number, bufferSize = 4) {
+  const buf = Buffer.alloc(bufferSize);
+  buf.writeUInt32LE(n, bufferSize - 4);
+  return buf;
+}
+
+/**
+ * Convert a number to a big-endian unsigned 32-bit integer Buffer.
+ * This function takes a number and an optional buffer size as input and creates a Buffer with the specified size (defaults to 4) containing the big-endian representation of the input number as an unsigned 32-bit integer. Note that the bufferSize should be greater than or equal to 4, otherwise the output Buffer might truncate the serialized value.
+ *
+ * @param n - The input number to be converted to a big-endian unsigned 32-bit integer Buffer.
+ * @param bufferSize - Optional, the size of the output Buffer (default is 4).
+ * @returns A Buffer containing the big-endian unsigned 32-bit integer representation of the input number.
+ */
+export function numToUInt32BE(n: number, bufferSize = 4) {
+  const buf = Buffer.alloc(bufferSize);
+  buf.writeUInt32BE(n, bufferSize - 4);
+  return buf;
+}
+
+/**
+ * Serialize a number into a big-endian signed 32-bit integer Buffer with the specified buffer size.
+ * This function converts the input number into its binary representation and stores it in a Buffer
+ * with the provided buffer size. By default, the buffer size is set to 4 bytes which represents a 32-bit integer.
+ * The function will use the last 4 bytes of the buffer to store the serialized number. If the input number
+ * is outside the range of a 32-bit signed integer, the resulting serialization may be incorrect due to truncation.
+ *
+ * @param n - The number to be serialized as a signed 32-bit integer.
+ * @param bufferSize - Optional, the size of the output Buffer (default is 4 bytes).
+ * @returns A Buffer containing the serialized big-endian signed 32-bit integer.
+ */
+export function numToInt32BE(n: number, bufferSize = 4) {
+  const buf = Buffer.alloc(bufferSize);
+  buf.writeInt32BE(n, bufferSize - 4);
+  return buf;
+}
+
+/**
+ * Convert a number to an 8-bit unsigned integer and return it as a Buffer of length 1.
+ * The input number is written as an 8-bit unsigned integer into the buffer. This function
+ * is useful for converting small numeric values to a standardized binary format that can be
+ * easily stored or transmitted.
+ *
+ * @param n - The number to be converted to an 8-bit unsigned integer.
+ * @returns A Buffer containing the 8-bit unsigned integer representation of the input number.
+ */
+export function numToUInt8(n: number) {
+  const bufferSize = 1;
+  const buf = Buffer.alloc(bufferSize);
+  buf.writeUInt8(n, 0);
+  return buf;
+}
+
+/**
+ * Adds a 4-byte byte-length prefix to a buffer.
+ * @param buf - The input Buffer to be prefixed
+ * @returns A Buffer with 4-byte byte-length prefix.
+ */
+export function prefixBufferWithLength(buf: Buffer) {
+  const lengthBuf = Buffer.alloc(4);
+  lengthBuf.writeUInt32BE(buf.length, 0);
+  return Buffer.concat([lengthBuf, buf]);
+}
+
+/**
+ * Parse a buffer as a big integer.
+ */
+export function toBigInt(buf: Buffer): bigint {
+  const hex = buf.toString('hex');
+  if (hex.length === 0) {
+    return BigInt(0);
+  }
+  return BigInt(`0x${hex}`);
+}
+
+/**
+ * Stores full 256 bits of information in 2 fields.
+ * @param buf - 32 bytes of data
+ * @returns 2 field elements
+ */
+export function to2Fields(buf: Buffer): [Fr, Fr] {
+  if (buf.length !== 32) {
+    throw new Error('Buffer must be 32 bytes');
+  }
+
+  // Split the hash into two fields, a high and a low
+  const buf1 = Buffer.concat([Buffer.alloc(16), buf.subarray(0, 16)]);
+  const buf2 = Buffer.concat([Buffer.alloc(16), buf.subarray(16, 32)]);
+
+  return [Fr.fromBuffer(buf1), Fr.fromBuffer(buf2)];
+}
+
+/**
+ * Reconstructs the original 32 bytes of data from 2 field elements.
+ * @param field1 - First field element
+ * @param field2 - Second field element
+ * @returns 32 bytes of data as a Buffer
+ */
+export function from2Fields(field1: Fr, field2: Fr): Buffer {
+  // Convert the field elements back to buffers
+  const buf1 = field1.toBuffer();
+  const buf2 = field2.toBuffer();
+
+  // Remove the padding (first 16 bytes) from each buffer
+  const originalPart1 = buf1.slice(16, 32);
+  const originalPart2 = buf2.slice(16, 32);
+
+  // Concatenate the two parts to form the original buffer
+  return Buffer.concat([originalPart1, originalPart2]);
+}

package/src/serialize/index.ts

@@ -0,0 +1,5 @@
+export * from './free_funcs.js';
+export * from './buffer_reader.js';
+export * from './field_reader.js';
+export * from './types.js';
+export * from './serialize.js';

package/src/serialize/serialize.ts

@@ -0,0 +1,303 @@
+import { toBigIntBE, toBufferBE } from '../bigint-buffer/index.js';
+import { Fr } from '../fields/fields.js';
+import { numToUInt32BE } from './free_funcs.js';
+
+/**
+ * For serializing an array of fixed length buffers.
+ * TODO move to foundation pkg.
+ * @param arr - Array of buffers.
+ * @returns The serialized buffers.
+ */
+export function serializeBufferArrayToVector(arr: Buffer[]): Buffer {
+  const lengthBuf = Buffer.alloc(4);
+  lengthBuf.writeUInt32BE(arr.length, 0);
+  return Buffer.concat([lengthBuf, ...arr]);
+}
+
+/**
+ * Helper function for deserializeArrayFromVector.
+ */
+type DeserializeFn<T> = (
+  buf: Buffer,
+  offset: number,
+) => {
+  /**
+   * The deserialized type.
+   */
+  elem: T;
+  /**
+   * How many bytes to advance by.
+   */
+  adv: number;
+};
+
+/**
+ * Deserializes an array from a vector on an element-by-element basis.
+ * @param deserialize - A function used to deserialize each element of the vector.
+ * @param vector - The vector to deserialize.
+ * @param offset - The position in the vector to start deserializing from.
+ * @returns Deserialized array and how many bytes we advanced by.
+ *
+ * TODO: move to foundation pkg.
+ */
+export function deserializeArrayFromVector<T>(
+  deserialize: DeserializeFn<T>,
+  vector: Buffer,
+  offset = 0,
+): {
+  /**
+   * The deserialized array.
+   */
+  elem: T[];
+  /**
+   * How many bytes we advanced by.
+   */
+  adv: number;
+} {
+  let pos = offset;
+  const size = vector.readUInt32BE(pos);
+  pos += 4;
+  const arr = new Array<T>(size);
+  for (let i = 0; i < size; ++i) {
+    const { elem, adv } = deserialize(vector, pos);
+    pos += adv;
+    arr[i] = elem;
+  }
+  return { elem: arr, adv: pos - offset };
+}
+
+/**
+ * Cast a uint8 array to a number.
+ * @param array - The uint8 array.
+ * @returns The number.
+ */
+export function uint8ArrayToNum(array: Uint8Array): number {
+  const buf = Buffer.from(array);
+  return buf.readUint32LE();
+}
+
+/**
+ * Serializes a boolean to a buffer.
+ * @param value - Value to serialize.
+ * @returns The serialized boolean.
+ */
+export function boolToBuffer(value: boolean, bufferSize = 1): Buffer {
+  const buf = Buffer.alloc(bufferSize);
+  buf.writeUInt8(value ? 1 : 0, bufferSize - 1);
+  return buf;
+}
+
+/**
+ * Deserialize the 256-bit number at address `offset`.
+ * @param buf - The buffer.
+ * @param offset - The address.
+ * @returns The deserialized 256-bit field.
+ */
+export function deserializeField(buf: Buffer, offset = 0) {
+  const adv = 32;
+  return { elem: buf.slice(offset, offset + adv), adv };
+}
+
+/** A type that can be written to a buffer. */
+export type Bufferable =
+  | boolean
+  | Buffer
+  | number
+  | string
+  | {
+      /**
+       * Serialize to a buffer.
+       */
+      toBuffer: () => Buffer;
+    }
+  | Bufferable[];
+
+/** A type that can be converted to a Field or a Field array. */
+export type Fieldeable =
+  | Fr
+  | boolean
+  | number
+  | bigint
+  | {
+      /** Serialize to a field. */
+      toField: () => Fr;
+    }
+  | {
+      /** Serialize to an array of fields. */
+      toFields: () => Fr[];
+    }
+  | Fieldeable[];
+
+/**
+ * Serializes a list of objects contiguously.
+ * @param objs - Objects to serialize.
+ * @returns A buffer list with the concatenation of all fields.
+ */
+export function serializeToBufferArray(...objs: Bufferable[]): Buffer[] {
+  let ret: Buffer[] = [];
+  for (const obj of objs) {
+    if (Array.isArray(obj)) {
+      ret = [...ret, ...serializeToBufferArray(...obj)];
+    } else if (Buffer.isBuffer(obj)) {
+      ret.push(obj);
+    } else if (typeof obj === 'boolean') {
+      ret.push(boolToBuffer(obj));
+    } else if (typeof obj === 'number') {
+      // Note: barretenberg assumes everything is big-endian
+      ret.push(numToUInt32BE(obj)); // TODO: Are we always passing numbers as UInt32?
+    } else if (typeof obj === 'string') {
+      ret.push(numToUInt32BE(obj.length));
+      ret.push(Buffer.from(obj));
+    } else {
+      ret.push(obj.toBuffer());
+    }
+  }
+  return ret;
+}
+
+/**
+ * Serializes a list of objects contiguously.
+ * @param objs - Objects to serialize.
+ * @returns An array of fields with the concatenation of all fields.
+ */
+export function serializeToFields(...objs: Fieldeable[]): Fr[] {
+  let ret: Fr[] = [];
+  for (const obj of objs) {
+    if (Array.isArray(obj)) {
+      ret = [...ret, ...serializeToFields(...obj)];
+    } else if (obj instanceof Fr) {
+      ret.push(obj);
+    } else if (typeof obj === 'boolean' || typeof obj === 'number' || typeof obj === 'bigint') {
+      ret.push(new Fr(obj));
+    } else if ('toFields' in obj) {
+      ret = [...ret, ...obj.toFields()];
+    } else {
+      ret.push(obj.toField());
+    }
+  }
+  return ret;
+}
+
+/**
+ * Serializes a list of objects contiguously.
+ * @param objs - Objects to serialize.
+ * @returns A single buffer with the concatenation of all fields.
+ */
+export function serializeToBuffer(...objs: Bufferable[]): Buffer {
+  return Buffer.concat(serializeToBufferArray(...objs));
+}
+
+/**
+ * Returns a user-friendly JSON representation of an object, showing buffers as hex strings.
+ * @param obj - Object to json-stringify.
+ * @returns A JSON string.
+ */
+export function toFriendlyJSON(obj: object): string {
+  return JSON.stringify(
+    obj,
+    (key, value) => {
+      if (value !== null && typeof value === 'object' && value.type === 'Buffer' && Array.isArray(value.data)) {
+        return '0x' + Buffer.from(value.data).toString('hex');
+      } else if (typeof value === 'bigint') {
+        return value.toString();
+      } else if (
+        value &&
+        (
+          value as {
+            /**
+             * Signature of the target serialization function.
+             */
+            toFriendlyJSON: () => string;
+          }
+        ).toFriendlyJSON
+      ) {
+        return value.toFriendlyJSON();
+      } else {
+        return value;
+      }
+    },
+    2,
+  );
+}
+
+/**
+ * Serialize a BigInt value into a Buffer of specified width.
+ * The function converts the input BigInt into its big-endian representation and stores it in a Buffer of the given width.
+ * If the width is not provided, a default value of 32 bytes will be used. It is important to provide an appropriate width
+ * to avoid truncation or incorrect serialization of large BigInt values.
+ *
+ * @param n - The BigInt value to be serialized.
+ * @param width - The width (in bytes) of the output Buffer, optional with default value 32.
+ * @returns A Buffer containing the serialized BigInt value in big-endian format.
+ */
+export function serializeBigInt(n: bigint, width = 32) {
+  return toBufferBE(n, width);
+}
+
+/**
+ * Deserialize a big integer from a buffer, given an offset and width.
+ * Reads the specified number of bytes from the buffer starting at the offset, converts it to a big integer, and returns the deserialized result along with the number of bytes read (advanced).
+ *
+ * @param buf - The buffer containing the big integer to be deserialized.
+ * @param offset - The position in the buffer where the big integer starts. Defaults to 0.
+ * @param width - The number of bytes to read from the buffer for the big integer. Defaults to 32.
+ * @returns An object containing the deserialized big integer value ('elem') and the number of bytes advanced ('adv').
+ */
+export function deserializeBigInt(buf: Buffer, offset = 0, width = 32) {
+  return { elem: toBigIntBE(buf.subarray(offset, offset + width)), adv: width };
+}
+
+/**
+ * Serializes a Date object into a Buffer containing its timestamp as a big integer value.
+ * The resulting Buffer has a fixed width of 8 bytes, representing a 64-bit big-endian integer.
+ * This function is useful for converting date values into a binary format that can be stored or transmitted easily.
+ *
+ * @param date - The Date object to be serialized.
+ * @returns A Buffer containing the serialized timestamp of the input Date object.
+ */
+export function serializeDate(date: Date) {
+  return serializeBigInt(BigInt(date.getTime()), 8);
+}
+
+/**
+ * Deserialize a boolean value from a given buffer at the specified offset.
+ * Reads a single byte at the provided offset in the buffer and returns
+ * the deserialized boolean value along with the number of bytes read (adv).
+ *
+ * @param buf - The buffer containing the serialized boolean value.
+ * @param offset - The position in the buffer to start reading the boolean value.
+ * @returns An object containing the deserialized boolean value (elem) and the number of bytes read (adv).
+ */
+export function deserializeBool(buf: Buffer, offset = 0) {
+  const adv = 1;
+  return { elem: buf.readUInt8(offset), adv };
+}
+
+/**
+ * Deserialize a 4-byte unsigned integer from a buffer, starting at the specified offset.
+ * The deserialization reads 4 bytes from the given buffer and converts it into a number.
+ * Returns an object containing the deserialized unsigned integer and the number of bytes advanced (4).
+ *
+ * @param buf - The buffer containing the serialized unsigned integer.
+ * @param offset - The starting position in the buffer to deserialize from (default is 0).
+ * @returns An object with the deserialized unsigned integer as 'elem' and the number of bytes advanced ('adv') as 4.
+ */
+export function deserializeUInt32(buf: Buffer, offset = 0) {
+  const adv = 4;
+  return { elem: buf.readUInt32BE(offset), adv };
+}
+
+/**
+ * Deserialize a signed 32-bit integer from a buffer at the given offset.
+ * The input 'buf' should be a Buffer containing binary data, and 'offset' should be the position in the buffer
+ * where the signed 32-bit integer starts. Returns an object with both the deserialized integer (elem) and the
+ * number of bytes advanced in the buffer (adv, always equal to 4).
+ *
+ * @param buf - The buffer containing the binary data.
+ * @param offset - Optional, the position in the buffer where the signed 32-bit integer starts (default is 0).
+ * @returns An object with the deserialized integer as 'elem' and the number of bytes advanced as 'adv'.
+ */
+export function deserializeInt32(buf: Buffer, offset = 0) {
+  const adv = 4;
+  return { elem: buf.readInt32BE(offset), adv };
+}

package/src/serialize/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Represents a fixed-length array.
+ */
+export type Tuple<T, N extends number> = N extends N ? (number extends N ? T[] : _Tuple<T, N, []>) : never;
+/**
+ * Recursive type helper for constructing a fixed-length tuple of a given type.
+ * This is utilized internally by Tuple to create the final fixed-length tuple.
+ */
+type _Tuple<T, N extends number, R extends unknown[]> = R['length'] extends N ? R : _Tuple<T, N, [T, ...R]>;
+
+/**
+ * Check an array size, and cast it to a tuple.
+ * @param array - The array.
+ * @param n - The size.
+ * @returns The case tuple, or throws Error.
+ */
+export function assertLength<T, N extends number>(array: T[], n: N): Tuple<T, N> {
+  if (array.length !== n) {
+    throw new Error(`Wrong 'fixed array' size. Expected ${n}, got ${array.length}.`);
+  }
+  return array as Tuple<T, N>;
+}
+/**
+ * Annoying, mapping a tuple does not preserve length.
+ * This is a helper to preserve length during a map operation.
+ * @typeparam T - The original array type.
+ */
+type MapTuple<T extends any[], F extends (item: any) => any> = {
+  [K in keyof T]: T[K] extends infer U ? (F extends (item: U) => infer V ? V : never) : never;
+};
+
+/**
+ * Annoyingly, mapping a tuple does not preserve length.
+ * This is a helper to preserve length during a map operation.
+ * @see https://github.com/microsoft/TypeScript/issues/29841.
+ * @param array - A tuple array.
+ */
+export function mapTuple<T extends any[], F extends (item: any) => any>(tuple: T, fn: F): MapTuple<T, F> {
+  return tuple.map(fn) as MapTuple<T, F>;
+}