@aztec/foundation 0.0.1-commit.4d79d1f2d → 0.0.1-commit.4d9804df

package/src/promise/running-promise.ts

@@ -22,16 +22,17 @@ export function makeLoggingErrorHandler(
  * at a specified polling interval. It allows starting, stopping, and checking the status of the
  * internally managed promise. The class also supports interrupting the polling process when stopped.
  */
-export class RunningPromise {
+export class RunningPromise<T = void> {
   private running = false;
   private runningPromise = Promise.resolve();
   private interruptibleSleep = new InterruptibleSleep();
   private requested: PromiseWithResolvers<void> | undefined = undefined;
+  private requestedArg: T | undefined = undefined;
 
   public static readonly EXIT: typeof EXIT = EXIT;
 
   constructor(
-    private fn: () => void | Promise<void>,
+    private fn: (arg?: T) => void | Promise<void>,
     private logger = createLogger('running-promise'),
     private pollingIntervalMS = 10000,
     private handleError: ErrorHandler = makeLoggingErrorHandler(logger),
@@ -51,7 +52,7 @@ export class RunningPromise {
       while (this.running) {
         const hasRequested = this.requested !== undefined;
         try {
-          await this.fn();
+          await this.fn(this.requestedArg);
         } catch (err) {
           const code = await this.handleError(err);
           if (code === RunningPromise.EXIT) {
@@ -64,6 +65,7 @@ export class RunningPromise {
         if (hasRequested) {
           this.requested!.resolve();
           this.requested = undefined;
+          this.requestedArg = undefined;
         }
 
         // If no immediate run was requested, sleep for the polling interval.
@@ -101,15 +103,16 @@ export class RunningPromise {
    * Triggers an immediate run of the function, bypassing the polling interval.
    * If the function is currently running, it will be allowed to continue and then called again immediately.
    */
-  public async trigger() {
+  public async trigger(arg?: T): Promise<void> {
     if (!this.running) {
-      return this.fn();
+      return this.fn(arg);
     }
 
     let requested = this.requested;
     if (!requested) {
       requested = promiseWithResolvers<void>();
       this.requested = requested;
+      this.requestedArg = arg;
       this.interruptibleSleep.interrupt();
     }
     await requested!.promise;

package/src/queue/batch_queue.ts

@@ -105,6 +105,7 @@ export class BatchQueue<T, K extends string | number> {
       return Promise.resolve();
     }
 
+    this.flushCurrentBatch();
     this.container.end();
     return runningPromise;
   }

package/src/retry/index.ts

@@ -1,7 +1,7 @@
 import { TimeoutError } from '../error/index.js';
 import { type Logger, createLogger } from '../log/index.js';
 import { sleep } from '../sleep/index.js';
-import { Timer } from '../timer/index.js';
+import { type DateProvider, Timer } from '../timer/index.js';
 
 /** An error that indicates that the operation should not be retried. */
 export class NoRetryError extends Error {}
@@ -72,6 +72,34 @@ export async function retry<Result>(
   }
 }
 
+/**
+ * Timeout specification accepted by {@link retryUntil}. Either a plain number of seconds, an explicit
+ * `{ timeout }` in seconds, or an absolute `{ deadline }` with an optional {@link DateProvider} used to
+ * read the current time. A deadline is converted to the remaining seconds at call time; a deadline that
+ * has already passed yields a zero remaining budget, matching the immediate-timeout semantics of a
+ * non-positive numeric timeout.
+ */
+export type RetryUntilTimeout = number | { timeout: number } | { deadline: Date; dateProvider?: DateProvider };
+
+/**
+ * Resolves a {@link RetryUntilTimeout} to a numeric timeout in seconds for the legacy timer-based loop.
+ * A numeric/`{ timeout }` value passes through unchanged (0 means never time out, negative times out on the
+ * first interval). A `{ deadline }` is the remaining seconds until the deadline; when the deadline is already
+ * at or past `now` it resolves to a negative value so the loop times out immediately instead of being read as
+ * the never-timeout sentinel 0.
+ */
+function resolveRetryUntilTimeoutSeconds(timeout: RetryUntilTimeout): number {
+  if (typeof timeout === 'number') {
+    return timeout;
+  }
+  if ('deadline' in timeout) {
+    const now = timeout.dateProvider?.now() ?? Date.now();
+    const remainingSeconds = (timeout.deadline.getTime() - now) / 1000;
+    return remainingSeconds > 0 ? remainingSeconds : -1;
+  }
+  return timeout.timeout;
+}
+
 /**
  * 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.
@@ -79,16 +107,20 @@ export async function retry<Result>(
  *
  * @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 timeout - The maximum time to keep retrying before throwing a timeout error. Accepts a number of
+ * seconds (0 = never time out), an explicit `{ timeout }` in seconds, or an absolute `{ deadline }` with an
+ * optional `dateProvider`. A deadline already in the past times out on the first interval, the same as a
+ * zero/negative numeric timeout. 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: () => (T | undefined) | Promise<T | undefined>,
   name = '',
-  timeout = 0,
+  timeout: RetryUntilTimeout = 0,
   interval = 1,
 ) {
+  const timeoutSeconds = resolveRetryUntilTimeoutSeconds(timeout);
   const timer = new Timer();
   while (true) {
     const result = await fn();
@@ -98,12 +130,42 @@ export async function retryUntil<T>(
 
     await sleep(interval * 1000);
 
-    if (timeout && timer.s() > timeout) {
+    if (timeoutSeconds && timer.s() > timeoutSeconds) {
       throw new TimeoutError(name ? `Timeout awaiting ${name}` : 'Timeout');
     }
   }
 }
 
+/**
+ * Retry an asynchronous function until it returns a truthy value or the maximum number of retries is exceeded.
+ * The function is retried periodically with a fixed interval between attempts.
+ *
+ * @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 error messages.
+ * @param maxRetries - The maximum number of retry attempts before throwing an error.
+ * @param retryInterval - 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 retries are exhausted.
+ */
+export async function retryTimes<T>(
+  fn: () => (T | undefined) | Promise<T | undefined>,
+  name = '',
+  maxRetries: number,
+  retryInterval = 1,
+) {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const result = await fn();
+    if (result) {
+      return result;
+    }
+
+    if (attempt < maxRetries) {
+      await sleep(retryInterval * 1000);
+    }
+  }
+
+  throw new Error(name ? `Retries exhausted awaiting ${name}` : 'Retries exhausted');
+}
+
 /**
  * Convenience wrapper around retryUntil with fast polling for tests.
  * Uses 10s timeout and 100ms polling interval by default.

package/src/schemas/api.ts

@@ -2,32 +2,19 @@ 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;
+// Forces usage of schemas that accept nulls for optional parameters.
+type ZodParameterTypeFor<T> = undefined extends T ? ZodNullableOptional<z.ZodType<T, any>> : z.ZodType<T, any>;
+
+type ZodReturnTypeFor<T> = z.ZodType<T, any>;
+
+type ZodMapParameterTypes<T extends readonly unknown[]> = {
+  [K in keyof T]-?: ZodParameterTypeFor<T[K]>;
+};
 
 /** 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>>
+    ? z.ZodFunction<z.ZodTuple<ZodMapParameterTypes<Args>, null>, ZodReturnTypeFor<Ret>>
     : never;
 };
 
@@ -37,11 +24,24 @@ export type ApiSchema = {
 };
 
 /** Return whether an API schema defines a valid function schema for a given method name. */
-export function schemaHasMethod(schema: ApiSchema, methodName: string) {
+export function schemaHasMethod<T extends ApiSchema>(
+  schema: T,
+  methodName: string,
+): methodName is Extract<keyof T, string> {
   return (
     typeof methodName === 'string' &&
     Object.hasOwn(schema, methodName) &&
-    typeof schema[methodName].parameters === 'function' &&
-    typeof schema[methodName].returnType === 'function'
+    schema[methodName].def.input !== undefined &&
+    schema[methodName].def.output !== undefined
   );
 }
+
+/** Returns the parameter tuple schema for an API method schema. */
+export function getSchemaParameters<T extends z.ZodFunction<z.ZodTuple<any, any>, z.ZodTypeAny>>(schema: T) {
+  return schema.def.input;
+}
+
+/** Returns the return value schema for an API method schema. */
+export function getSchemaReturnType<T extends z.ZodFunction<z.ZodTuple<any, any>, z.ZodTypeAny>>(schema: T) {
+  return schema.def.output;
+}

package/src/schemas/parse.ts

@@ -4,16 +4,19 @@ 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);
+  return schemas.length === 0
+    ? z.tuple([]).parse(args)
+    : z.tuple(schemas as [z.ZodTypeAny, ...z.ZodTypeAny[]]).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.
+ * @dev Zod doesn't like tuples 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;
+export function parseWithOptionals<T extends z.ZodTuple<any, any>>(args: any[], schema: T): Promise<z.output<T>> {
+  const items = schema.def.items;
+  const missingCount = items.length - args.length;
+  const optionalCount = items.filter(isOptional).length;
   const toParse =
     missingCount > 0 && missingCount <= optionalCount ? args.concat(times(missingCount, () => undefined)) : args;
   return schema.parseAsync(toParse);
@@ -24,6 +27,6 @@ function isOptional(schema: z.ZodTypeAny) {
     return schema.isOptional();
   } catch {
     // See https://github.com/colinhacks/zod/issues/1911
-    return schema._def.typeName === 'ZodOptional';
+    return schema.def.type === 'optional';
   }
 }

package/src/schemas/schemas.ts

@@ -44,15 +44,15 @@ export const schemas = {
   ]),
 
   /** Coerces any input to bigint. */
-  BigInt: z.union([z.bigint(), z.number(), z.string()]).pipe(z.coerce.bigint()),
+  BigInt: z.union([z.bigint(), z.number(), z.string()]).pipe(z.coerce.bigint<string | number | bigint>()),
 
   /** Coerces any input to integer number. */
-  Integer: z.union([z.bigint(), z.number(), z.string()]).pipe(z.coerce.number().int()),
+  Integer: z.union([z.bigint(), z.number(), z.string()]).pipe(z.coerce.number<string | number | bigint>().int()),
 
   /** Coerces input to UInt32. */
   UInt32: z.union([z.bigint(), z.number(), z.string()]).pipe(
     z.coerce
-      .number()
+      .number<string | number | bigint>()
       .int()
       .min(0)
       .max(2 ** 32 - 1),
@@ -61,7 +61,7 @@ export const schemas = {
   /** Coerces input to UInt64. */
   UInt64: z.union([z.bigint(), z.number(), z.string()]).pipe(
     z.coerce
-      .bigint()
+      .bigint<string | number | bigint>()
       .min(0n)
       .max(2n ** 64n - 1n),
   ),

package/src/schemas/types.ts

@@ -1,6 +1,6 @@
 import type { ZodType } from 'zod';
 
-export type ZodFor<T> = ZodType<T, any, any>;
+export type ZodFor<T> = ZodType<T, any>;
 
 /**
  * Creates a schema validator that enforces all properties of type T are present in the schema.
@@ -26,7 +26,7 @@ export type ZodFor<T> = ZodType<T, any, any>;
  * ```
  */
 export function zodFor<T>() {
-  return (schema => schema) as <S extends ZodType<any, any, any>>(
+  return (schema => schema) as <S extends ZodType<any, any>>(
     schema: keyof T extends keyof S['_output']
       ? keyof S['_output'] extends keyof T
         ? S

package/src/schemas/utils.ts

@@ -1,16 +1,4 @@
-import {
-  OK,
-  type ParseInput,
-  type ParseReturnType,
-  ZodFirstPartyTypeKind,
-  type ZodObject,
-  ZodOptional,
-  ZodParsedType,
-  type ZodRawShape,
-  type ZodType,
-  type ZodTypeAny,
-  z,
-} from 'zod';
+import { type ZodObject, type ZodRawShape, type ZodType, type ZodTypeAny, z } from 'zod';
 
 import { pick } from '../collection/object.js';
 import { isHex, withoutHexPrefix } from '../string/index.js';
@@ -41,24 +29,7 @@ export const bufferSchema: ZodFor<Buffer> = z.union([
   z.instanceof(Buffer),
 ]);
 
-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;
-  }
-}
+export type ZodNullableOptional<T extends ZodTypeAny> = ZodType<z.output<T> | undefined, z.input<T> | null | undefined>;
 
 /**
  * Declares a parameter as optional. Use this over z.optional in order to accept nulls as undefineds.
@@ -66,7 +37,7 @@ export class ZodNullableOptional<T extends ZodTypeAny> extends ZodOptional<T> {
  * need to convert nulls to undefineds as we parse.
  */
 export function optional<T extends ZodTypeAny>(schema: T) {
-  return ZodNullableOptional.create(schema);
+  return schema.nullish().transform(value => value ?? undefined);
 }
 
 type ToJsonIs<T, TRet> = T extends { toJSON(): TRet } ? T : never;
@@ -83,7 +54,6 @@ export function hexSchemaFor<TClass extends { fromString(str: string): any } | {
   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();
@@ -101,11 +71,7 @@ export function hexSchemaFor<TClass extends { fromString(str: string): any } | {
 export function bufferSchemaFor<TClass extends { fromBuffer(buf: Buffer): any }>(
   klazz: TClass,
   refinement?: (buf: Buffer) => boolean,
-): ZodType<
-  TClass extends { fromBuffer(buf: Buffer): infer TInstance } ? ToJsonIs<TInstance, Buffer> : never,
-  any,
-  string
-> {
+): ZodType<TClass extends { fromBuffer(buf: Buffer): infer TInstance } ? ToJsonIs<TInstance, Buffer> : never, string> {
   return bufferSchema.refine(refinement ?? (() => true), 'Not a valid buffer').transform(klazz.fromBuffer.bind(klazz));
 }
 

package/src/serialize/buffer_reader.ts

@@ -1,3 +1,4 @@
+import { toBigIntBE } from '../bigint-buffer/index.js';
 import type { Tuple } from './types.js';
 
 /**
@@ -130,6 +131,20 @@ export class BufferReader {
     return result;
   }
 
+  /**
+   * Reads a 256-bit signed integer (two's complement) from the buffer at the current index position.
+   * Updates the index position by 32 bytes after reading the number.
+   *
+   * @returns The read 256 bit signed value as a bigint.
+   */
+  public readInt256(): bigint {
+    this.#rangeCheck(32);
+    const unsigned = toBigIntBE(this.buffer.subarray(this.index, this.index + 32));
+    this.index += 32;
+    const signBit = 1n << 255n;
+    return unsigned >= signBit ? unsigned - (1n << 256n) : unsigned;
+  }
+
   /** Alias for readUInt256 */
   public readBigInt(): bigint {
     return this.readUInt256();