@aztec/foundation 0.0.0-test.0

package/src/queue/serial_queue.ts

@@ -0,0 +1,86 @@
+import { FifoMemoryQueue } from './fifo_memory_queue.js';
+
+/**
+ * A more specialized fifo queue that enqueues functions to execute. Enqueued functions are executed in serial.
+ */
+export class SerialQueue {
+  private readonly queue = new FifoMemoryQueue<() => Promise<void>>();
+  private runningPromise!: Promise<void>;
+  private started = false;
+
+  /**
+   * Initializes the execution of enqueued functions in the serial queue.
+   * Functions are executed in the order they were added to the queue, with each function
+   * waiting for the completion of the previous one before starting its execution.
+   * This method should be called once to start processing the queue.
+   */
+  public start() {
+    if (this.started) {
+      return;
+    }
+    this.runningPromise = this.queue.process(fn => fn());
+    this.started = true;
+  }
+
+  /**
+   * Returns the current number of enqueued functions in the serial queue.
+   * This provides a way to check the size of the queue and monitor its progress.
+   *
+   * @returns The length of the serial queue as a number.
+   */
+  public length() {
+    return this.queue.length();
+  }
+
+  /**
+   * Cancels the processing of the remaining functions in the serial queue and resolves the running promise.
+   * Any enqueued functions that have not yet been executed will be discarded. The queue can still accept new
+   * functions after cancellation, but the previously enqueued functions will not be re-processed.
+   *
+   * @returns The running promise which resolves when the current executing function (if any) completes.
+   */
+  public cancel() {
+    this.queue.cancel();
+    return this.runningPromise;
+  }
+
+  /**
+   * Signals the SerialQueue that it should finish processing its current task and stop accepting new tasks.
+   * The returned Promise resolves when all enqueued tasks have completed execution.
+   *
+   * @returns A Promise that resolves when the queue is completely emptied and no new tasks are allowed.
+   */
+  public end() {
+    this.queue.end();
+    return this.runningPromise;
+  }
+
+  /**
+   * Enqueues fn for execution on the serial queue.
+   * Returns the result of the function after execution.
+   * @param fn - The function to enqueue.
+   * @returns A resolution promise. Rejects if the function does, or if the function could not be enqueued.
+   */
+  public put<T>(fn: () => T | Promise<T>): Promise<Awaited<T>> {
+    return new Promise((resolve, reject) => {
+      const accepted = this.queue.put(async () => {
+        try {
+          const res = await fn();
+          resolve(res);
+        } catch (e) {
+          reject(e);
+        }
+      });
+      if (!accepted) {
+        reject(new Error('Could not enqueue function'));
+      }
+    });
+  }
+
+  /**
+   * Awaiting this ensures the queue is empty before resuming.
+   */
+  public async syncPoint() {
+    await this.put(async () => {});
+  }
+}

package/src/retry/index.ts

@@ -0,0 +1,100 @@
+import { TimeoutError } from '../error/index.js';
+import { createLogger } from '../log/index.js';
+import { sleep } from '../sleep/index.js';
+import { Timer } from '../timer/index.js';
+
+/** An error that indicates that the operation should not be retried. */
+export class NoRetryError extends Error {}
+
+/**
+ * Generates a backoff sequence for retrying operations with an increasing delay.
+ * The backoff sequence follows this pattern: 1, 1, 1, 2, 4, 8, 16, 32, 64, ...
+ * This generator can be used in combination with the `retry` function to perform
+ * retries with exponential backoff and capped at 64 seconds between attempts.
+ *
+ * @returns A generator that yields the next backoff value in seconds as an integer.
+ */
+export function* backoffGenerator() {
+  const v = [1, 1, 1, 2, 4, 8, 16, 32, 64];
+  let i = 0;
+  while (true) {
+    yield v[Math.min(i++, v.length - 1)];
+  }
+}
+
+/**
+ * Generates a backoff sequence based on the array of retry intervals to use with the `retry` function.
+ * @param retries - Intervals to retry (in seconds).
+ * @returns A generator sequence.
+ */
+export function* makeBackoff(retries: number[]) {
+  for (const retry of retries) {
+    yield retry;
+  }
+}
+
+/**
+ * Retry a given asynchronous function with a specific backoff strategy, until it succeeds or backoff generator ends.
+ * It logs the error and retry interval in case an error is caught. The function can be named for better log output.
+ *
+ * @param fn - The asynchronous function to be retried.
+ * @param name - The optional name of the operation, used for logging purposes.
+ * @param backoff - The optional backoff generator providing the intervals in seconds between retries. Defaults to a predefined series.
+ * @param log - Logger to use for logging.
+ * @param failSilently - Do not log errors while retrying.
+ * @returns A Promise that resolves with the successful result of the provided function, or rejects if backoff generator ends.
+ * @throws If `NoRetryError` is thrown by the `fn`, it is rethrown.
+ */
+export async function retry<Result>(
+  fn: () => Promise<Result>,
+  name = 'Operation',
+  backoff = backoffGenerator(),
+  log = createLogger('foundation:retry'),
+  failSilently = false,
+) {
+  while (true) {
+    try {
+      return await fn();
+    } catch (err: any) {
+      if (err instanceof NoRetryError) {
+        // A special error that indicates that the operation should not be retried. Rethrow it.
+        throw err;
+      }
+      const s = backoff.next().value;
+      if (s === undefined) {
+        throw err;
+      }
+      log.verbose(`${name} failed. Will retry in ${s}s...`);
+      !failSilently && log.error(`Error while retrying ${name}`, err);
+      await sleep(s * 1000);
+      continue;
+    }
+  }
+}
+
+/**
+ * Retry an asynchronous function until it returns a truthy value or the specified timeout is exceeded.
+ * The function is retried periodically with a fixed interval between attempts. The operation can be named for better error messages.
+ * Will never timeout if the value is 0.
+ *
+ * @param fn - The asynchronous function to be retried, which should return a truthy value upon success or undefined otherwise.
+ * @param name - The optional name of the operation, used for generating timeout error message.
+ * @param timeout - The optional maximum time, in seconds, to keep retrying before throwing a timeout error. Defaults to 0 (never timeout).
+ * @param interval - The optional interval, in seconds, between retry attempts. Defaults to 1 second.
+ * @returns A Promise that resolves with the successful (truthy) result of the provided function, or rejects if timeout is exceeded.
+ */
+export async function retryUntil<T>(fn: () => Promise<T | undefined>, name = '', timeout = 0, interval = 1) {
+  const timer = new Timer();
+  while (true) {
+    const result = await fn();
+    if (result) {
+      return result;
+    }
+
+    await sleep(interval * 1000);
+
+    if (timeout && timer.s() > timeout) {
+      throw new TimeoutError(name ? `Timeout awaiting ${name}` : 'Timeout');
+    }
+  }
+}

package/src/running-promise/index.ts

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

package/src/schemas/api.ts

@@ -0,0 +1,47 @@
+import type { z } from 'zod';
+
+import type { ZodNullableOptional } from './utils.js';
+
+// Forces usage of ZodNullableOptional in parameters schemas so we properly accept nulls for optional parameters.
+type ZodParameterTypeFor<T> = undefined extends T
+  ? ZodNullableOptional<z.ZodType<T, z.ZodTypeDef, any>>
+  : z.ZodType<T, z.ZodTypeDef, any>;
+
+type ZodReturnTypeFor<T> = z.ZodType<T, z.ZodTypeDef, any>;
+
+// This monstruosity is used for mapping function arguments to their schema representation.
+// The complexity is required to satisfy ZodTuple which requires a fixed length tuple and
+// has a very annoying type of [] | [ZodTypeAny, ...ZodTypeAny], and most types fail to match
+// the second option. While a purely recursive approach works, it fails when trying to deal
+// with optional arguments (ie optional items in the tuple), and ts does not really like them
+// during a recursion and fails with infinite stack depth.
+// This type appears to satisfy everyone. Everyone but me.
+type ZodMapParameterTypes<T> = T extends []
+  ? []
+  : T extends [item: infer Head, ...infer Rest]
+  ? [ZodParameterTypeFor<Head>, ...{ [K in keyof Rest]: ZodParameterTypeFor<Rest[K]> }]
+  : T extends [item?: infer Head, ...infer Rest]
+  ? [ZodNullableOptional<ZodParameterTypeFor<Head>>, ...{ [K in keyof Rest]: ZodParameterTypeFor<Rest[K]> }]
+  : never;
+
+/** Maps all functions in an interface to their schema representation. */
+export type ApiSchemaFor<T> = {
+  [K in keyof T]: T[K] extends (...args: infer Args) => Promise<infer Ret>
+    ? z.ZodFunction<z.ZodTuple<ZodMapParameterTypes<Args>, z.ZodUnknown>, ZodReturnTypeFor<Ret>>
+    : never;
+};
+
+/** Generic Api schema not bounded to a specific implementation. */
+export type ApiSchema = {
+  [key: string]: z.ZodFunction<z.ZodTuple<any, any>, z.ZodTypeAny>;
+};
+
+/** Return whether an API schema defines a valid function schema for a given method name. */
+export function schemaHasMethod(schema: ApiSchema, methodName: string) {
+  return (
+    typeof methodName === 'string' &&
+    Object.hasOwn(schema, methodName) &&
+    typeof schema[methodName].parameters === 'function' &&
+    typeof schema[methodName].returnType === 'function'
+  );
+}

package/src/schemas/index.ts

@@ -0,0 +1,5 @@
+export * from './api.js';
+export * from './parse.js';
+export * from './utils.js';
+export * from './types.js';
+export * from './schemas.js';

package/src/schemas/parse.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+
+import { times } from '../collection/array.js';
+
+/** Parses the given arguments using a tuple from the provided schemas. */
+export function parse<T extends [] | [z.ZodTypeAny, ...z.ZodTypeAny[]]>(args: IArguments, ...schemas: T) {
+  return z.tuple(schemas).parse(args);
+}
+
+/**
+ * Parses the given arguments against a tuple, allowing empty for optional items.
+ * @dev Zod doesn't like tuplues with optional items. See https://github.com/colinhacks/zod/discussions/949.
+ */
+export function parseWithOptionals<T extends z.AnyZodTuple>(args: any[], schema: T): Promise<T['_output']> {
+  const missingCount = schema.items.length - args.length;
+  const optionalCount = schema.items.filter(isOptional).length;
+  const toParse =
+    missingCount > 0 && missingCount <= optionalCount ? args.concat(times(missingCount, () => undefined)) : args;
+  return schema.parseAsync(toParse);
+}
+
+function isOptional(schema: z.ZodTypeAny) {
+  try {
+    return schema.isOptional();
+  } catch (err) {
+    // See https://github.com/colinhacks/zod/issues/1911
+    return schema._def.typeName === 'ZodOptional';
+  }
+}

package/src/schemas/schemas.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+
+import { Buffer32 } from '../buffer/buffer32.js';
+import { EthAddress } from '../eth-address/index.js';
+import { Fq, Fr } from '../fields/fields.js';
+import { Point } from '../fields/point.js';
+import { isHex, withoutHexPrefix } from '../string/index.js';
+import { bufferSchema, hexSchema } from './utils.js';
+
+export const schemas = {
+  /** Accepts a hex string. */
+  EthAddress: EthAddress.schema,
+
+  /** Accepts a hex string. */
+  Fr: Fr.schema,
+
+  /** Accepts a hex string. */
+  Fq: Fq.schema,
+
+  /** Point. Serialized as a hex string. */
+  Point: Point.schema,
+
+  /** Coerces any input to bigint. */
+  BigInt: z.union([z.bigint(), z.number(), z.string()]).pipe(z.coerce.bigint()),
+
+  /** Coerces any input to integer number. */
+  Integer: z.union([z.bigint(), z.number(), z.string()]).pipe(z.coerce.number().int()),
+
+  /** Coerces input to UInt32. */
+  UInt32: z.union([z.bigint(), z.number(), z.string()]).pipe(
+    z.coerce
+      .number()
+      .int()
+      .min(0)
+      .max(2 ** 32 - 1),
+  ),
+
+  /** Accepts a hex string as a Buffer32 type. */
+  Buffer32: z.string().refine(isHex, 'Not a valid hex string').transform(Buffer32.fromString),
+
+  /** Accepts a base64 string or an object `{ type: 'Buffer', data: [byte, byte...] }` as a buffer. */
+  Buffer: z.union([
+    bufferSchema,
+    z
+      .object({
+        type: z.literal('Buffer'),
+        data: z.array(z.number().int().min(0).max(255)),
+      })
+      .transform(({ data }) => Buffer.from(data)),
+  ]),
+
+  /** Accepts a hex string as a buffer. */
+  BufferHex: z
+    .string()
+    .refine(isHex, 'Not a valid hex string')
+    .transform(withoutHexPrefix)
+    .transform(data => Buffer.from(data, 'hex')),
+
+  /** Hex string with an optional 0x prefix which gets removed as part of the parsing. */
+  HexString: hexSchema,
+};
+
+// These are needed to avoid errors such as: "The inferred type of 'YourClassSchema' cannot be named without a reference to..."
+export type { EthAddress, Point, Fr, Fq };

package/src/schemas/types.ts

@@ -0,0 +1,3 @@
+import type { ZodType } from 'zod';
+
+export type ZodFor<T> = ZodType<T, any, any>;

package/src/schemas/utils.ts

@@ -0,0 +1,112 @@
+import {
+  OK,
+  type ParseInput,
+  type ParseReturnType,
+  ZodFirstPartyTypeKind,
+  type ZodObject,
+  ZodOptional,
+  ZodParsedType,
+  type ZodRawShape,
+  type ZodType,
+  type ZodTypeAny,
+  z,
+} from 'zod';
+
+import { pick } from '../collection/object.js';
+import { isHex, withoutHexPrefix } from '../string/index.js';
+import type { ZodFor } from './types.js';
+
+export const hexSchema = z.string().refine(isHex, 'Not a valid hex string').transform(withoutHexPrefix);
+
+// Copied from zod internals, which was copied from https://stackoverflow.com/questions/7860392/determine-if-string-is-in-base64-using-javascript
+const base64Regex = /^([0-9a-zA-Z+/]{4})*(([0-9a-zA-Z+/]{2}==)|([0-9a-zA-Z+/]{3}=))?$/;
+
+/** Schema for a buffer represented as a base64 string. */
+export const bufferSchema = z
+  .string()
+  // We only test the str for base64 if it's shorter than 1024 bytes, otherwise we've run into maximum
+  // stack size exceeded errors when trying to validate excessively long strings (such as contract bytecode).
+  .refine(str => str.length > 1024 || base64Regex.test(str), 'Not a valid base64 string')
+  .transform(data => Buffer.from(data, 'base64'));
+
+export class ZodNullableOptional<T extends ZodTypeAny> extends ZodOptional<T> {
+  _isNullableOptional = true;
+
+  override _parse(input: ParseInput): ParseReturnType<this['_output']> {
+    const parsedType = this._getType(input);
+    if (parsedType === ZodParsedType.undefined || parsedType === ZodParsedType.null) {
+      return OK(undefined);
+    }
+    return this._def.innerType._parse(input);
+  }
+
+  static override create<T extends ZodTypeAny>(type: T): ZodNullableOptional<T> {
+    return new ZodNullableOptional({
+      innerType: type,
+      typeName: ZodFirstPartyTypeKind.ZodOptional,
+    }) as any;
+  }
+}
+
+/**
+ * Declares a parameter as optional. Use this over z.optional in order to accept nulls as undefineds.
+ * This is required as JSON does not have an undefined type, and null is used to represent it, so we
+ * need to convert nulls to undefineds as we parse.
+ */
+export function optional<T extends ZodTypeAny>(schema: T) {
+  return ZodNullableOptional.create(schema);
+}
+
+type ToJsonIs<T, TRet> = T extends { toJSON(): TRet } ? T : never;
+
+/**
+ * Creates a schema that accepts a hex string and uses it to hydrate an instance.
+ * @param klazz - Class that implements either fromString or fromBuffer.
+ * @returns A schema for the class.
+ */
+export function hexSchemaFor<TClass extends { fromString(str: string): any } | { fromBuffer(buf: Buffer): any }>(
+  klazz: TClass,
+  refinement?: (input: string) => boolean,
+): ZodType<
+  TClass extends { fromString(str: string): infer TInstance } | { fromBuffer(buf: Buffer): infer TInstance }
+    ? ToJsonIs<TInstance, string>
+    : never,
+  any,
+  string
+> {
+  const stringSchema = refinement ? z.string().refine(refinement, `Not a valid instance`) : z.string();
+  const hexSchema = stringSchema.refine(isHex, 'Not a valid hex string');
+  return 'fromString' in klazz
+    ? hexSchema.transform(klazz.fromString.bind(klazz))
+    : hexSchema.transform(str => Buffer.from(withoutHexPrefix(str), 'hex')).transform(klazz.fromBuffer.bind(klazz));
+}
+
+/**
+ * Creates a schema that accepts a base64 string and uses it to hydrate an instance.
+ * @param klazz - Class that implements fromBuffer.
+ * @returns A schema for the class.
+ */
+export function bufferSchemaFor<TClass extends { fromBuffer(buf: Buffer): any }>(
+  klazz: TClass,
+): ZodType<
+  TClass extends { fromBuffer(buf: Buffer): infer TInstance } ? ToJsonIs<TInstance, Buffer> : never,
+  any,
+  string
+> {
+  return bufferSchema.transform(klazz.fromBuffer.bind(klazz));
+}
+
+/** Creates a schema for a js Map type that matches the serialization used in jsonStringify. */
+export function mapSchema<TKey, TValue>(key: ZodFor<TKey>, value: ZodFor<TValue>): ZodFor<Map<TKey, TValue>> {
+  return z.array(z.tuple([key, value])).transform(entries => new Map(entries));
+}
+
+/** Creates a schema for a js Set type that matches the serialization used in jsonStringify. */
+export function setSchema<T>(value: ZodFor<T>): ZodFor<Set<T>> {
+  return z.array(value).transform(entries => new Set(entries));
+}
+
+/** Given an already parsed and validated object, extracts the keys defined in the given schema. Does not validate again. */
+export function pickFromSchema<T extends object, S extends ZodObject<ZodRawShape>>(obj: T, schema: S) {
+  return pick(obj, ...Object.keys(schema.shape));
+}