@aztec/foundation 0.0.0-test.1 → 0.0.1-commit.0b941701

package/src/serialize/buffer_reader.ts

@@ -19,7 +19,10 @@ import type { Tuple } from './types.js';
  */
 export class BufferReader {
   private index: number;
-  constructor(private buffer: Buffer, offset = 0) {
+  constructor(
+    private buffer: Buffer,
+    offset = 0,
+  ) {
     this.index = offset;
   }
 
@@ -70,6 +73,43 @@ export class BufferReader {
     return result as Tuple<number, N>;
   }
 
+  /**
+   * Reads a 256-bit unsigned integer from the buffer at the current index position.
+   * Updates the index position by 32 bytes after reading the number.
+   *
+   * Assumes the number is stored in big-endian format.
+   *
+   * @returns The read 256 bit value as a bigint.
+   */
+  public readUInt64(): bigint {
+    this.#rangeCheck(8);
+
+    const result = this.buffer.readBigUInt64BE(this.index);
+
+    this.index += 8;
+    return result;
+  }
+
+  /**
+   * Reads a 128-bit unsigned integer from the buffer at the current index position.
+   * Updates the index position by 16 bytes after reading the number.
+   *
+   * Assumes the number is stored in big-endian format.
+   *
+   * @returns The read 128 bit value as a bigint.
+   */
+  public readUInt128(): bigint {
+    this.#rangeCheck(16);
+
+    let result = BigInt(0);
+    for (let i = 0; i < 2; i++) {
+      result = (result << BigInt(64)) | this.buffer.readBigUInt64BE(this.index + i * 8);
+    }
+
+    this.index += 16;
+    return result;
+  }
+
   /**
    * Reads a 256-bit unsigned integer from the buffer at the current index position.
    * Updates the index position by 32 bytes after reading the number.
@@ -82,14 +122,19 @@ export class BufferReader {
     this.#rangeCheck(32);
 
     let result = BigInt(0);
-    for (let i = 0; i < 32; i++) {
-      result = (result << BigInt(8)) | BigInt(this.buffer[this.index + i]);
+    for (let i = 0; i < 4; i++) {
+      result = (result << BigInt(64)) | this.buffer.readBigUInt64BE(this.index + i * 8);
     }
 
     this.index += 32;
     return result;
   }
 
+  /** Alias for readUInt256 */
+  public readBigInt(): bigint {
+    return this.readUInt256();
+  }
+
   /**
    * Reads a 16-bit unsigned integer from the buffer at the current index position.
    * Updates the index position by 2 bytes after reading the number.
@@ -160,6 +205,18 @@ export class BufferReader {
     });
   }
 
+  /**
+   * Reads a vector of 256-bit unsigned integers from the buffer and returns it as an array of bigints.
+   * The method utilizes the 'readVector' method, passing a deserializer that reads bigints.
+   *
+   * @returns An array of bigints representing the vector read from the buffer.
+   */
+  public readUint256Vector(): bigint[] {
+    return this.readVector({
+      fromBuffer: (reader: BufferReader) => reader.readUInt256(),
+    });
+  }
+
   /**
    * Reads a vector of fixed size from the buffer and deserializes its elements using the provided itemDeserializer object.
    * The 'itemDeserializer' object should have a 'fromBuffer' method that takes a BufferReader instance and returns the deserialized element.
@@ -167,15 +224,22 @@ export class BufferReader {
    * deserializing each one using the 'fromBuffer' method of 'itemDeserializer'.
    *
    * @param itemDeserializer - Object with 'fromBuffer' method to deserialize vector elements.
+   * @param maxSize - Optional maximum allowed size for the vector. If the size exceeds this, an error is thrown.
    * @returns An array of deserialized elements of type T.
    */
-  public readVector<T>(itemDeserializer: {
-    /**
-     * A method to deserialize data from a buffer.
-     */
-    fromBuffer: (reader: BufferReader) => T;
-  }): T[] {
+  public readVector<T>(
+    itemDeserializer: {
+      /**
+       * A method to deserialize data from a buffer.
+       */
+      fromBuffer: (reader: BufferReader) => T;
+    },
+    maxSize?: number,
+  ): T[] {
     const size = this.readNumber();
+    if (maxSize !== undefined && size > maxSize) {
+      throw new Error(`Vector size ${size} exceeds maximum allowed ${maxSize}`);
+    }
     const result = new Array<T>(size);
     for (let i = 0; i < size; i++) {
       result[i] = itemDeserializer.fromBuffer(this);
@@ -287,10 +351,11 @@ export class BufferReader {
    * The method first reads the size of the string, then reads the corresponding
    * number of bytes from the buffer and converts them to a string.
    *
+   * @param maxSize - Optional maximum allowed size for the string buffer. If the size exceeds this, an error is thrown.
    * @returns The read string from the buffer.
    */
-  public readString(): string {
-    return this.readBuffer().toString();
+  public readString(maxSize?: number): string {
+    return this.readBuffer(maxSize).toString();
   }
 
   /**
@@ -299,10 +364,14 @@ export class BufferReader {
    * a Buffer with that size containing the bytes. Useful for reading variable-length
    * binary data encoded as (size, data) format.
    *
+   * @param maxSize - Optional maximum allowed size for the buffer. If the size exceeds this, an error is thrown.
    * @returns A Buffer containing the read bytes.
    */
-  public readBuffer(): Buffer {
+  public readBuffer(maxSize?: number): Buffer {
     const size = this.readNumber();
+    if (maxSize !== undefined && size > maxSize) {
+      throw new Error(`Buffer size ${size} exceeds maximum allowed ${maxSize}`);
+    }
     this.#rangeCheck(size);
     return this.readBytes(size);
   }

package/src/serialize/field_reader.ts

@@ -1,4 +1,4 @@
-import { Fq, type Fr } from '../fields/fields.js';
+import { Fq, type Fr } from '../curves/bn254/field.js';
 import type { Tuple } from './types.js';
 
 /**
@@ -11,11 +11,15 @@ import type { Tuple } from './types.js';
  */
 export class FieldReader {
   private index: number;
-  private length: number;
-  constructor(private fields: Fr[], offset = 0) {
+  private readonly length: number;
+
+  constructor(
+    private fields: Fr[],
+    offset = 0,
+  ) {
     this.index = offset;
     this.length = fields.length;
-    if (offset >= this.length) {
+    if (offset > this.length) {
       throw new Error('Offset out of bounds.');
     }
   }
@@ -43,6 +47,10 @@ export class FieldReader {
     return this.index;
   }
 
+  public remainingFields(): number {
+    return this.length - this.index;
+  }
+
   /**
    * Skips the next n fields.
    *
@@ -121,6 +129,22 @@ export class FieldReader {
     return Number(value);
   }
 
+  /**
+   * Reads a 64-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 ** 64.
+   *
+   * @returns The read 64-bit unsigned integer value as a bigint.
+   */
+  public readU64(): bigint {
+    const field = this.readField();
+    const value = field.toBigInt();
+    if (value >= 1n << 64n) {
+      throw new Error('Field is not a u64.');
+    }
+    return value;
+  }
+
   /**
    * Read an array of a fixed size field array.
    *

package/src/serialize/free_funcs.ts

@@ -1,4 +1,5 @@
-import { Fr } from '../fields/fields.js';
+import { toBufferBE } from '../bigint-buffer/index.js';
+import { Fr } from '../curves/bn254/field.js';
 import type { Tuple } from './types.js';
 
 /**
@@ -56,6 +57,30 @@ export function numToUInt32BE(n: number, bufferSize = 4) {
   return buf;
 }
 
+/**
+ * Convert a bigint to a big-endian unsigned 64-bit integer Buffer.
+ *
+ * @param n - The bigint to be converted to a big-endian unsigned 64-bit integer Buffer.
+ * @param bufferSize - Optional, the size of the output Buffer (default is 8).
+ * @returns A Buffer containing the big-endian unsigned 64-bit integer representation of the input number.
+ */
+export function bigintToUInt64BE(n: bigint, bufferSize = 8) {
+  const buf = Buffer.alloc(bufferSize);
+  buf.writeBigUInt64BE(n, bufferSize - 8);
+  return buf;
+}
+
+/**
+ * Convert a bigint to a big-endian unsigned 128-bit integer Buffer.
+ *
+ * @param n - The bigint to be converted to a big-endian unsigned 128-bit integer Buffer.
+ * @param bufferSize - Optional, the size of the output Buffer (default is 16).
+ * @returns A Buffer containing the big-endian unsigned 128-bit integer representation of the input number.
+ */
+export function bigintToUInt128BE(n: bigint, bufferSize = 16) {
+  return toBufferBE(n, bufferSize);
+}
+
 /**
  * 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
@@ -160,37 +185,6 @@ export function truncateAndPad(buf: Buffer): Buffer {
   return Buffer.concat([Buffer.alloc(1), buf.subarray(0, 31)]);
 }
 
-/**
- * Stores 248 bits of information in 1 field.
- * @param buf - 32 or 31 bytes of data
- * @returns 1 field element
- */
-export function toTruncField(buf: Buffer): Fr {
-  if (buf.length !== 32 && buf.length !== 31) {
-    throw new Error('Buffer must be 31 or 32 bytes');
-  }
-  if ((buf.length == 32 && buf[0] == 0) || buf.length == 31) {
-    return Fr.fromBuffer(buf);
-  } else {
-    // Note: safer to NOT truncate here, all inputs are expected to be truncated
-    // from Noir or L1 Contracts or Class.hash() methods
-    throw new Error(`Number ${toBigInt(buf)} does not fit in 31 byte truncated buffer`);
-  }
-}
-
-/**
- * Reconstructs the original 31 bytes of data from 1 truncated field element.
- * @param field - field element
- * @returns 31 bytes of data as a Buffer
- */
-export function fromTruncField(field: Fr): Buffer {
-  const buffer = field.toBuffer();
-  if (buffer[0] != 0) {
-    throw new Error(`Number ${field} does not fit in 31 byte truncated buffer`);
-  }
-  return buffer;
-}
-
 export function fromFieldsTuple(fields: Tuple<Fr, 2>): Buffer {
   return from2Fields(fields[0], fields[1]);
 }

package/src/serialize/serialize.ts

@@ -1,5 +1,5 @@
 import { toBigIntBE, toBufferBE } from '../bigint-buffer/index.js';
-import { Fr } from '../fields/fields.js';
+import { Fr } from '../curves/bn254/field.js';
 import { numToUInt32BE } from './free_funcs.js';
 
 /**
@@ -145,6 +145,8 @@ export type Fieldable =
     }
   | Fieldable[];
 
+export type Serializable = Bufferable & Fieldable;
+
 /**
  * Serializes a list of objects contiguously.
  * @param objs - Objects to serialize.

package/src/sleep/index.ts

@@ -73,3 +73,9 @@ export class InterruptibleSleep {
 export function sleep<T>(ms: number, returnValue?: T): Promise<T> {
   return new Promise(resolve => setTimeout(() => resolve(returnValue as T), ms));
 }
+
+/** Sleeps until the target date */
+export function sleepUntil<T>(target: Date, now: Date, returnValue?: T): Promise<T> {
+  const ms = target.getTime() - now.getTime();
+  return sleep(ms, returnValue);
+}

package/src/string/index.ts

@@ -1,3 +1,6 @@
+/** Parameterized hex string type for specific byte lengths */
+export type Hex<TByteLength extends number> = `0x${string}` & { readonly _length: TByteLength };
+
 export function hasHexPrefix(str: string): str is `0x${string}` {
   return str.startsWith('0x');
 }
@@ -6,6 +9,10 @@ export function withoutHexPrefix(str: string): string {
   return hasHexPrefix(str) ? str.slice(2) : str;
 }
 
+export function withHexPrefix(str: string): `0x${string}` {
+  return hasHexPrefix(str) ? str : `0x${str}`;
+}
+
 export function isHex(str: string): boolean {
   return /^(0x)?[0-9a-fA-F]*$/.test(str);
 }
@@ -19,7 +26,7 @@ export function bufferToHex(buffer: Buffer): `0x${string}` {
 }
 
 export function pluralize(str: string, count: number | bigint, plural?: string): string {
-  return count === 1 || count === 1n ? str : plural ?? `${str}s`;
+  return count === 1 || count === 1n ? str : (plural ?? `${str}s`);
 }
 
 export function count(count: number | bigint, str: string, plural?: string): string {
@@ -29,3 +36,31 @@ export function count(count: number | bigint, str: string, plural?: string): str
 export function truncate(str: string, length: number = 64): string {
   return str.length > length ? str.slice(0, length) + '...' : str;
 }
+
+export function isoDate(date?: Date) {
+  return (date ?? new Date()).toISOString().replace(/[-:T]/g, '').replace(/\..+$/, '');
+}
+
+export function urlJoin(...args: string[]): string {
+  const processed = [];
+  for (const arg of args) {
+    if (arg.length === 0) {
+      continue;
+    }
+
+    let start = 0;
+    let end = arg.length - 1;
+
+    while (start <= end && arg[start] === '/') {
+      start++;
+    }
+    while (end >= start && arg[end] === '/') {
+      end--;
+    }
+
+    if (start < end) {
+      processed.push(arg.slice(start, end + 1));
+    }
+  }
+  return processed.join('/');
+}

package/src/testing/files/index.ts

@@ -35,12 +35,16 @@ export function updateInlineTestData(targetFileFromRepoRoot: string, itemName: s
   const logger = createConsoleLogger('aztec:testing:test_data');
   const targetFile = getPathToFile(targetFileFromRepoRoot);
   const contents = readFileSync(targetFile, 'utf8').toString();
-  const regex = new RegExp(`let ${itemName} =[\\s\\S]*?;`, 'g');
+  const regex = new RegExp(`(let|pub\\s+global)\\s+${itemName}(\\s*:\\s*[^=]+)?\\s*=\\s*([\\s\\S]*?);`, 'g');
   if (!regex.exec(contents)) {
     throw new Error(`Test data marker for ${itemName} not found in ${targetFile}`);
   }
 
-  const updatedContents = contents.replaceAll(regex, `let ${itemName} = ${value};`);
+  const updatedContents = contents.replace(
+    regex,
+    (_, declareKeyword, typeAnnotation) =>
+      `${declareKeyword} ${itemName}${(typeAnnotation || '').trimEnd()} = ${value};`,
+  );
   writeFileSync(targetFile, updatedContents);
   logger(`Updated test data in ${targetFile} for ${itemName} to ${value}`);
 }
@@ -59,7 +63,7 @@ export function updateProtocolCircuitSampleInputs(circuitName: string, value: st
   logger(`Updated test data in ${targetFile} for ${circuitName}`);
 }
 
-function getPathToFile(targetFileFromRepoRoot: string) {
+export function getPathToFile(targetFileFromRepoRoot: string) {
   const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../../../../');
   if (!existsSync(join(repoRoot, 'CODEOWNERS'))) {
     throw new Error(`Path to repo root is incorrect (got ${repoRoot})`);

package/src/testing/formatting.ts

@@ -0,0 +1,3 @@
+export function toInlineStrArray(arr: { toString: () => string }[]): string {
+  return `[${arr.map(f => f.toString()).join(',')}]`;
+}

package/src/testing/index.ts

@@ -1,3 +1,4 @@
+export * from './formatting.js';
 export * from './snapshot_serializer.js';
 export * from './port_allocator.js';
 export * from './test_data.js';

package/src/timer/date.ts

@@ -5,15 +5,25 @@ export class DateProvider {
   public now(): number {
     return Date.now();
   }
+
+  public nowInSeconds(): number {
+    return Math.floor(this.now() / 1000);
+  }
+
+  public nowAsDate(): Date {
+    return new Date(this.now());
+  }
 }
 
 /** Returns current datetime and allows to override it. */
-export class TestDateProvider implements DateProvider {
+export class TestDateProvider extends DateProvider {
   private offset = 0;
 
-  constructor(private readonly logger = createLogger('foundation:test-date-provider')) {}
+  constructor(private readonly logger = createLogger('foundation:test-date-provider')) {
+    super();
+  }
 
-  public now(): number {
+  public override now(): number {
     return Date.now() + this.offset;
   }
 

package/src/timer/index.ts

@@ -1,4 +1,4 @@
 export * from './date.js';
 export { elapsed, elapsedSync } from './elapsed.js';
-export { TimeoutTask, executeTimeout } from './timeout.js';
+export { TimeoutTask, executeTimeout, timeoutPromise } from './timeout.js';
 export { Timer } from './timer.js';

package/src/timer/timeout.ts

@@ -1,4 +1,5 @@
 import { TimeoutError } from '../error/index.js';
+import { promiseWithResolvers } from '../promise/utils.js';
 
 /**
  * TimeoutTask class creates an instance for managing and executing a given asynchronous function with a specified timeout duration.
@@ -8,15 +9,15 @@ import { TimeoutError } from '../error/index.js';
  * @typeparam T - The return type of the asynchronous function to be executed.
  */
 export class TimeoutTask<T> {
-  private interruptPromise!: Promise<any>;
-  private interrupt = () => {};
   private totalTime = 0;
+  private timeoutPromise: Promise<never> | undefined;
 
-  constructor(private fn: () => Promise<T>, private timeout: number, errorFn: () => any) {
-    this.interruptPromise = new Promise<T>((_, reject) => {
-      this.interrupt = () => reject(errorFn());
-    });
-  }
+  constructor(
+    private fn: (signal: AbortSignal) => Promise<T>,
+    private timeout: number,
+    private errorFn: () => Error,
+    private onAbort?: () => void,
+  ) {}
 
   /**
    * Executes the given function with a specified timeout.
@@ -27,15 +28,22 @@ export class TimeoutTask<T> {
    * @throws An error with a message indicating the function was interrupted due to exceeding the specified timeout.
    */
   public async exec() {
-    const interruptTimeout = setTimeout(this.interrupt, this.timeout);
-    try {
-      const start = Date.now();
-      const result = await Promise.race<T>([this.fn(), this.interruptPromise]);
-      this.totalTime = Date.now() - start;
-      return result;
-    } finally {
-      clearTimeout(interruptTimeout);
-    }
+    const signal = AbortSignal.timeout(this.timeout);
+    this.timeoutPromise = new Promise<never>((_, reject) => {
+      signal!.addEventListener(
+        'abort',
+        () => {
+          this.onAbort?.();
+          reject(this.errorFn());
+        },
+        { once: true },
+      );
+    });
+
+    const start = Date.now();
+    const result = await Promise.race<T>([this.fn(signal), this.timeoutPromise]);
+    this.totalTime = Date.now() - start;
+    return result;
   }
 
   /**
@@ -46,7 +54,7 @@ export class TimeoutTask<T> {
    * @returns The interrupt promise associated with the task.
    */
   public getInterruptPromise() {
-    return this.interruptPromise;
+    return this.timeoutPromise;
   }
 
   /**
@@ -60,11 +68,38 @@ export class TimeoutTask<T> {
   }
 }
 
-export async function executeTimeout<T>(fn: () => Promise<T>, timeout: number, errorOrFnName?: string | (() => any)) {
+/**
+ * Executes a function with a timeout.
+ * @param fn - The function to execute, accepts AbortSignal and returns a Promise.
+ * @param timeout - The maximum time in milliseconds to allow the function to run.
+ * @param errorOrFnName - Optional function name or a function that returns an Error to throw if the timeout is reached.
+ * @param onAbort - Optional callback to execute when the task is aborted.
+ *
+ * @returns A Promise that resolves with the result of the function fn if it completes within the timeout
+ *
+ * */
+export async function executeTimeout<T>(
+  fn: (signal: AbortSignal) => Promise<T>,
+  timeout: number,
+  errorOrFnName?: string | (() => Error),
+  onAbort?: () => void,
+) {
   const errorFn =
     typeof errorOrFnName === 'function'
       ? errorOrFnName
       : () => new TimeoutError(`Timeout running ${errorOrFnName ?? 'function'} after ${timeout}ms.`);
-  const task = new TimeoutTask(fn, timeout, errorFn);
+  const task = new TimeoutTask(fn, timeout, errorFn, onAbort);
   return await task.exec();
 }
+
+/** Returns a promise that rejects after the given timeout */
+export function timeoutPromise(timeoutMs: number, errorMessage?: string) {
+  const promise = promiseWithResolvers<never>();
+
+  const timer = setTimeout(() => {
+    promise.reject(new TimeoutError(errorMessage ?? `Operation timed out after ${timeoutMs}ms`));
+  }, timeoutMs);
+
+  const cleanup = () => clearTimeout(timer);
+  return promise.promise.finally(cleanup);
+}

package/src/transport/index.ts

@@ -7,5 +7,4 @@ export * from './interface/socket.js';
 export * from './interface/transferable.js';
 export * from './transport_client.js';
 export * from './transport_server.js';
-export * from './browser/index.js';
 export * from './node/index.js';

package/src/transport/interface/connector.ts

@@ -4,6 +4,5 @@ import type { Socket } from './socket.js';
  * Opens a socket with corresponding TransportListener.
  */
 export interface Connector {
-  // eslint-disable-next-line jsdoc/require-jsdoc
   createSocket(): Promise<Socket>;
 }

package/src/transport/interface/listener.ts

@@ -7,10 +7,9 @@ import type { Socket } from './socket.js';
  * Possible implementations could include MessageChannels or WebSockets.
  */
 export interface Listener extends EventEmitter {
-  // eslint-disable-next-line jsdoc/require-jsdoc
   open(): void;
-  // eslint-disable-next-line jsdoc/require-jsdoc
+
   close(): void;
-  // eslint-disable-next-line jsdoc/require-jsdoc
+
   on(name: 'new_socket', cb: (client: Socket) => void): this;
 }

package/src/transport/interface/socket.ts

@@ -6,10 +6,9 @@
  * If `registerHandler` callback receives `undefined` that signals the other end closed.
  */
 export interface Socket {
-  // eslint-disable-next-line jsdoc/require-jsdoc
   send(msg: any, transfer?: Transferable[]): Promise<void>;
-  // eslint-disable-next-line jsdoc/require-jsdoc
+
   registerHandler(cb: (msg: any) => any): void;
-  // eslint-disable-next-line jsdoc/require-jsdoc
+
   close(): void;
 }

package/src/transport/transport_client.ts

@@ -18,9 +18,9 @@ interface PendingRequest {
    * The unique message identifier used for tracking and matching request/response pairs.
    */
   msgId: number;
-  // eslint-disable-next-line jsdoc/require-jsdoc
+
   resolve(data: any): void;
-  // eslint-disable-next-line jsdoc/require-jsdoc
+
   reject(error: Error): void;
 }
 
@@ -30,9 +30,8 @@ interface PendingRequest {
  * for efficient and concurrent communication with a corresponding TransportServer.
  */
 export interface ITransportClient<Payload> extends EventEmitter {
-  // eslint-disable-next-line jsdoc/require-jsdoc
   on(name: 'event_msg', handler: (payload: Payload) => void): this;
-  // eslint-disable-next-line jsdoc/require-jsdoc
+
   emit(name: 'event_msg', payload: Payload): boolean;
 }
 

package/src/transport/transport_server.ts

@@ -9,7 +9,10 @@ import { isTransferDescriptor } from './interface/transferable.js';
 export class TransportServer<Payload> {
   private sockets: Socket[] = [];
 
-  constructor(private listener: Listener, private msgHandlerFn: (msg: Payload) => Promise<any>) {}
+  constructor(
+    private listener: Listener,
+    private msgHandlerFn: (msg: Payload) => Promise<any>,
+  ) {}
 
   /**
    * Starts the TransportServer, allowing it to accept new connections and handle incoming messages.