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

package/src/log/pino-logger.ts

@@ -5,7 +5,8 @@ import type { Writable } from 'stream';
 import { inspect } from 'util';
 
 import { compactArray } from '../collection/array.js';
-import { type EnvVar, parseBooleanEnv } from '../config/index.js';
+import type { EnvVar } from '../config/index.js';
+import { parseBooleanEnv } from '../config/parse-env.js';
 import { GoogleCloudLoggerConfig } from './gcloud-logger-config.js';
 import { getLogLevelFromFilters, parseEnv } from './log-filters.js';
 import type { LogLevel } from './log-levels.js';
@@ -37,11 +38,14 @@ export function createLogger(module: string): Logger {
     debug: (msg: string, data?: unknown) => logFn('debug', msg, data),
     /** Log as trace. Use for when we want to denial-of-service any recipient of the logs. */
     trace: (msg: string, data?: unknown) => logFn('trace', msg, data),
+    /** Level of the logger */
     level: pinoLogger.level as LogLevel,
     /** Whether the given level is enabled for this logger. */
     isLevelEnabled: (level: LogLevel) => isLevelEnabled(pinoLogger, level),
     /** Module name for the logger. */
     module,
+    /** Creates another logger by extending this logger module name. */
+    createChild: (childModule: string) => createLogger(`${module}:${childModule}`),
   };
 }
 
@@ -99,11 +103,38 @@ const customLevels = { verbose: 25 };
 
 // Global pino options, tweaked for google cloud if running there.
 const useGcloudLogging = parseBooleanEnv(process.env['USE_GCLOUD_LOGGING' satisfies EnvVar]);
+
+const redactedPaths = [
+  'validatorPrivateKeys',
+  // for both the validator and the prover
+  'publisherPrivateKeys',
+  'peerIdPrivateKey',
+  // bot keys
+  'l1PrivateKey',
+  'senderPrivateKey',
+  // blob sink
+  'l1ConsensusHostApiKeys',
+  // sensitive options used in the CLI
+  'privateKey',
+  'mnemonic',
+  'l1Mnemonic',
+  'l1PrivateKey',
+];
+
 const pinoOpts: pino.LoggerOptions<keyof typeof customLevels> = {
   customLevels,
   messageKey: 'msg',
   useOnlyCustomLevels: false,
   level: logLevel,
+  redact: {
+    paths: [
+      ...redactedPaths,
+      ...redactedPaths.map(p => `config.${p}`),
+      ...redactedPaths.map(p => `cfg.${p}`),
+      ...redactedPaths.map(p => `options.${p}`),
+      ...redactedPaths.map(p => `opts.${p}`),
+    ],
+  },
   ...(useGcloudLogging ? GoogleCloudLoggerConfig : {}),
 };
 
@@ -221,7 +252,7 @@ export function registerLoggingStream(stream: Writable): void {
 }
 
 /** Log function that accepts an exception object */
-type ErrorLogFn = (msg: string, err?: Error | unknown, data?: LogData) => void;
+type ErrorLogFn = (msg: string, err?: unknown, data?: LogData) => void;
 
 /**
  * Logger that supports multiple severity levels.
@@ -230,6 +261,7 @@ export type Logger = { [K in LogLevel]: LogFn } & { /** Error log function */ er
   level: LogLevel;
   isLevelEnabled: (level: LogLevel) => boolean;
   module: string;
+  createChild: (childModule: string) => Logger;
 };
 
 /**
@@ -238,6 +270,6 @@ export type Logger = { [K in LogLevel]: LogFn } & { /** Error log function */ er
  * @param err - Error to log
  * @returns A string with both the log message and the error message.
  */
-function formatErr(msg: string, err?: Error | unknown): string {
+function formatErr(msg: string, err?: unknown): string {
   return err ? `${msg}: ${inspect(err)}` : msg;
 }

package/src/message/index.ts

@@ -31,7 +31,11 @@ interface TypedMessageLike {
 }
 
 export class TypedMessage<T, B> {
-  public constructor(public readonly msgType: T, public readonly header: MessageHeader, public readonly value: B) {}
+  public constructor(
+    public readonly msgType: T,
+    public readonly header: MessageHeader,
+    public readonly value: B,
+  ) {}
 
   static fromMessagePack<T, B>(data: TypedMessageLike): TypedMessage<T, B> {
     return new TypedMessage<T, B>(data['msgType'] as T, MessageHeader.fromMessagePack(data['header']), data['value']);

package/src/mutex/mutex_database.ts

@@ -3,10 +3,9 @@
  * Provides functionality for acquiring, extending, and releasing locks on resources to ensure exclusive access and prevent conflicts in concurrent applications.
  */
 export interface MutexDatabase {
-  // eslint-disable-next-line jsdoc/require-jsdoc
   acquireLock(name: string, timeout: number): Promise<boolean>;
-  // eslint-disable-next-line jsdoc/require-jsdoc
+
   extendLock(name: string, timeout: number): Promise<void>;
-  // eslint-disable-next-line jsdoc/require-jsdoc
+
   releaseLock(name: string): Promise<void>;
 }

package/src/number/index.ts

@@ -0,0 +1,14 @@
+/** Bounds the given value between the min and max provided (both inclusive) */
+export function boundInclusive(value: number, min: number, max: number): number {
+  if (min > max) {
+    throw new Error('Minimum bound cannot be greater than maximum bound');
+  }
+
+  if (value < min) {
+    return min;
+  } else if (value > max) {
+    return max;
+  } else {
+    return value;
+  }
+}

package/src/profiler/index.ts

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

package/src/profiler/profiler.ts

@@ -0,0 +1,125 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { performance } from 'node:perf_hooks';
+
+interface Span {
+  label: string;
+  start: number;
+  dur: number;
+  count: number;
+  children: Span[];
+  parent: Span | undefined;
+}
+
+interface ProfileData {
+  spans: SerializedSpan[];
+  timestamp: string;
+  totalTime: number;
+}
+
+interface SerializedSpan {
+  label: string;
+  dur: number;
+  count: number;
+  children: SerializedSpan[];
+}
+
+const als = new AsyncLocalStorage<Span>();
+const roots: Span[] = [];
+
+function reset(): void {
+  roots.length = 0;
+}
+
+// Strip out circular references (parent) and unused fields (start) for JSON serialization
+function serializeSpans(spans: Span[]): SerializedSpan[] {
+  return spans.map(span => ({
+    label: span.label,
+    dur: span.dur,
+    count: span.count,
+    children: serializeSpans(span.children),
+  }));
+}
+
+let i = 0;
+function save(): void {
+  if (roots.length === 0) {
+    return;
+  }
+
+  // Find max single execution time across all spans (dur/count since dur is accumulated)
+  const findMaxSingleDuration = (spans: Span[]): number => {
+    let max = 0;
+    for (const span of spans) {
+      const singleDur = span.dur / span.count;
+      max = Math.max(max, singleDur);
+      if (span.children.length > 0) {
+        max = Math.max(max, findMaxSingleDuration(span.children));
+      }
+    }
+    return max;
+  };
+
+  const profileData: ProfileData = {
+    spans: serializeSpans(roots),
+    timestamp: new Date().toISOString(),
+    totalTime: findMaxSingleDuration(roots),
+  };
+
+  const profilePath = path.join(process.cwd(), `profile-${i++}.json`);
+  process.stdout.write(`Writing profile data to ${profilePath}\n`);
+  fs.writeFileSync(profilePath, JSON.stringify(profileData, null, 2));
+}
+
+// Hook into Jest to save after each test
+if (typeof afterEach === 'function') {
+  afterEach(() => {
+    save();
+    reset();
+  });
+}
+
+// Also save on process exit for non-Jest environments
+process.on('exit', () => {
+  save();
+});
+
+// Wrapper for async functions to maintain context properly
+async function runAsync<ReturnType>(label: string, fn: () => Promise<ReturnType>): Promise<ReturnType> {
+  const parent = als.getStore();
+
+  // Check if we already have a span with this label in the current context
+  let existingSpan: Span | undefined;
+  if (parent) {
+    existingSpan = parent.children.find(c => c.label === label);
+  } else {
+    existingSpan = roots.find(r => r.label === label);
+  }
+
+  let span: Span;
+  if (existingSpan) {
+    // Reuse existing span and increment count
+    span = existingSpan;
+    span.count++;
+  } else {
+    // Create new span
+    span = { label, start: performance.now(), dur: 0, count: 1, children: [], parent };
+    if (parent) {
+      parent.children.push(span);
+    } else {
+      roots.push(span);
+    }
+  }
+
+  const startTime = performance.now();
+  const result: ReturnType = await als.run(span, fn);
+  const elapsed = performance.now() - startTime;
+
+  // Add to total duration (for averaging)
+  span.dur += elapsed;
+
+  return result;
+}
+
+export const profiler = { reset, runAsync };

package/src/promise/running-promise.ts

@@ -43,7 +43,7 @@ export class RunningPromise {
   public start() {
     if (this.running) {
       this.logger.warn(`Attempted to start running promise that was already started`);
-      return;
+      return this;
     }
     this.running = true;
 
@@ -73,6 +73,7 @@ export class RunningPromise {
       }
     };
     this.runningPromise = poll();
+    return this;
   }
 
   /**
@@ -81,7 +82,6 @@ export class RunningPromise {
    */
   async stop(): Promise<void> {
     if (!this.running) {
-      this.logger.warn(`Running promise was not started`);
       return;
     }
     this.running = false;

package/src/queue/batch_queue.ts

@@ -13,7 +13,7 @@ type Batch<T, K> = {
  * A queue that groups items into batches based on a group key.
  *
  * The batching algorithm is greedy, meaning that as long as consecutive items have the same group key then they will
- * be batvched together. As soon as an item with a different group key is encountered, the old batch is flushed to the
+ * be batched together. As soon as an item with a different group key is encountered, the old batch is flushed to the
  * queue and a new batch is started.
  *
  * A batch can also be flushed to the queue if:

package/src/queue/bounded_serial_queue.ts

@@ -10,7 +10,10 @@ export class BoundedSerialQueue {
   private readonly queue = new SerialQueue();
   private semaphore: Semaphore;
 
-  constructor(maxQueueSize: number, private log = createLogger('foundation:bounded_serial_queue')) {
+  constructor(
+    maxQueueSize: number,
+    private log = createLogger('foundation:bounded_serial_queue'),
+  ) {
     this.semaphore = new Semaphore(maxQueueSize);
   }
 

package/src/queue/serial_queue.ts

@@ -5,7 +5,7 @@ import { FifoMemoryQueue } from './fifo_memory_queue.js';
  */
 export class SerialQueue {
   private readonly queue = new FifoMemoryQueue<() => Promise<void>>();
-  private runningPromise!: Promise<void>;
+  private runningPromises: Promise<void>[] = [];
   private started = false;
 
   /**
@@ -14,11 +14,11 @@ export class SerialQueue {
    * 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() {
+  public start(numWorkers = 1) {
     if (this.started) {
       return;
     }
-    this.runningPromise = this.queue.process(fn => fn());
+    this.runningPromises = Array.from({ length: numWorkers }, () => this.queue.process(fn => fn()));
     this.started = true;
   }
 
@@ -41,7 +41,7 @@ export class SerialQueue {
    */
   public cancel() {
     this.queue.cancel();
-    return this.runningPromise;
+    return Promise.all(this.runningPromises).then(() => {});
   }
 
   /**
@@ -52,7 +52,7 @@ export class SerialQueue {
    */
   public end() {
     this.queue.end();
-    return this.runningPromise;
+    return Promise.all(this.runningPromises).then(() => {});
   }
 
   /**

package/src/retry/index.ts

@@ -1,5 +1,5 @@
 import { TimeoutError } from '../error/index.js';
-import { createLogger } from '../log/index.js';
+import { type Logger, createLogger } from '../log/index.js';
 import { sleep } from '../sleep/index.js';
 import { Timer } from '../timer/index.js';
 
@@ -49,7 +49,7 @@ export async function retry<Result>(
   fn: () => Promise<Result>,
   name = 'Operation',
   backoff = backoffGenerator(),
-  log = createLogger('foundation:retry'),
+  log: Logger = createLogger('foundation:retry'),
   failSilently = false,
 ) {
   while (true) {
@@ -64,8 +64,8 @@ export async function retry<Result>(
       if (s === undefined) {
         throw err;
       }
-      log.verbose(`${name} failed. Will retry in ${s}s...`);
-      !failSilently && log.error(`Error while retrying ${name}`, err);
+      log?.debug(`${name} failed. Will retry in ${s}s...`);
+      !failSilently && log?.error(`Error while retrying ${name}`, err);
       await sleep(s * 1000);
       continue;
     }
@@ -83,7 +83,12 @@ export async function retry<Result>(
  * @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) {
+export async function retryUntil<T>(
+  fn: () => (T | undefined) | Promise<T | undefined>,
+  name = '',
+  timeout = 0,
+  interval = 1,
+) {
   const timer = new Timer();
   while (true) {
     const result = await fn();
@@ -98,3 +103,21 @@ export async function retryUntil<T>(fn: () => Promise<T | undefined>, name = '',
     }
   }
 }
+
+/**
+ * Convenience wrapper around retryUntil with fast polling for tests.
+ * Uses 10s timeout and 100ms polling interval by default.
+ *
+ * @param fn - The function to retry until it returns a truthy value.
+ * @param name - Description of what we're waiting for (for error messages).
+ * @param timeout - Optional timeout in seconds. Defaults to 10s.
+ * @param interval - Optional interval in seconds. Defaults to 0.1s (100ms).
+ */
+export function retryFastUntil<T>(
+  fn: () => (T | undefined) | Promise<T | undefined>,
+  name = '',
+  timeout = 10,
+  interval = 0.1,
+) {
+  return retryUntil(fn, name, timeout, interval);
+}

package/src/schemas/api.ts

@@ -19,10 +19,10 @@ type ZodReturnTypeFor<T> = z.ZodType<T, z.ZodTypeDef, any>;
 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;
+    ? [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> = {

package/src/schemas/parse.ts

@@ -22,7 +22,7 @@ export function parseWithOptionals<T extends z.AnyZodTuple>(args: any[], schema:
 function isOptional(schema: z.ZodTypeAny) {
   try {
     return schema.isOptional();
-  } catch (err) {
+  } catch {
     // See https://github.com/colinhacks/zod/issues/1911
     return schema._def.typeName === 'ZodOptional';
   }

package/src/schemas/schemas.ts

@@ -1,13 +1,22 @@
 import { z } from 'zod';
 
+import { EpochNumber, EpochNumberSchema } from '../branded-types/epoch.js';
+import { SlotNumber, SlotNumberSchema } from '../branded-types/slot.js';
 import { Buffer32 } from '../buffer/buffer32.js';
+import { SecretValue } from '../config/secret_value.js';
+import { Fq, Fr } from '../curves/bn254/field.js';
+import { Point } from '../curves/grumpkin/point.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 { isHex, withHexPrefix, withoutHexPrefix } from '../string/index.js';
 import { bufferSchema, hexSchema } from './utils.js';
 
 export const schemas = {
+  /** Accepts a number, bigint, or string as an EpochNumber. */
+  EpochNumber: EpochNumberSchema,
+
+  /** Accepts a number, bigint, or string as a SlotNumber. */
+  SlotNumber: SlotNumberSchema,
+
   /** Accepts a hex string. */
   EthAddress: EthAddress.schema,
 
@@ -20,6 +29,20 @@ export const schemas = {
   /** Point. Serialized as a hex string. */
   Point: Point.schema,
 
+  /** Coerces truthy-like string values to boolean. */
+  Boolean: z.union([
+    z.boolean(),
+    z
+      .number()
+      .refine(arg => arg === 0 || arg === 1, { message: `Numeric value for a boolean variable must be 0 or 1` })
+      .transform(arg => arg === 1),
+    z
+      .string()
+      .transform(arg => arg.trim().toLowerCase())
+      .refine(arg => ['true', 'false', '1', '0'].includes(arg))
+      .transform(arg => arg === '1' || arg === 'true'),
+  ]),
+
   /** Coerces any input to bigint. */
   BigInt: z.union([z.bigint(), z.number(), z.string()]).pipe(z.coerce.bigint()),
 
@@ -35,19 +58,19 @@ export const schemas = {
       .max(2 ** 32 - 1),
   ),
 
+  /** Coerces input to UInt64. */
+  UInt64: z.union([z.bigint(), z.number(), z.string()]).pipe(
+    z.coerce
+      .bigint()
+      .min(0n)
+      .max(2n ** 64n - 1n),
+  ),
+
   /** 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)),
-  ]),
+  Buffer: bufferSchema,
 
   /** Accepts a hex string as a buffer. */
   BufferHex: z
@@ -58,7 +81,13 @@ export const schemas = {
 
   /** Hex string with an optional 0x prefix which gets removed as part of the parsing. */
   HexString: hexSchema,
+
+  /** Hex string with an optional 0x prefix which gets enforced as part of the parsing. */
+  HexStringWith0x: z.string().refine(isHex, 'Not a valid hex string').transform(withHexPrefix),
+
+  /** A secret config value */
+  SecretValue: SecretValue.schema,
 };
 
 // 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 };
+export type { EpochNumber, EthAddress, Fq, Fr, Point, SlotNumber };

package/src/schemas/types.ts

@@ -1,3 +1,36 @@
 import type { ZodType } from 'zod';
 
 export type ZodFor<T> = ZodType<T, any, any>;
+
+/**
+ * Creates a schema validator that enforces all properties of type T are present in the schema.
+ * This provides compile-time safety to ensure schemas don't miss optional properties.
+ *
+ * @example
+ * ```ts
+ * interface MyConfig {
+ *   foo: string;
+ *   bar?: number;
+ * }
+ *
+ * // ✅ This will work - all keys present
+ * const schema1 = zodFor<MyConfig>()(z.object({
+ *   foo: z.string(),
+ *   bar: z.number().optional(),
+ * }));
+ *
+ * // ❌ This will error - 'bar' is missing
+ * const schema2 = zodFor<MyConfig>()(z.object({
+ *   foo: z.string(),
+ * }));
+ * ```
+ */
+export function zodFor<T>() {
+  return (schema => schema) as <S extends ZodType<any, any, any>>(
+    schema: keyof T extends keyof S['_output']
+      ? keyof S['_output'] extends keyof T
+        ? S
+        : S & { __error__: 'Schema has extra keys not in type'; __extra__: Exclude<keyof S['_output'], keyof T> }
+      : S & { __error__: 'Schema is missing keys from type'; __missing__: Exclude<keyof T, keyof S['_output']> },
+  ) => S;
+}

package/src/schemas/utils.ts

@@ -21,13 +21,25 @@ export const hexSchema = z.string().refine(isHex, 'Not a valid hex string').tran
 // 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'));
+/** Schema for a buffer represented as a base64 string or a Buffer object. */
+export const bufferSchema: ZodFor<Buffer> = z.union([
+  // Serialization from base64 string.
+  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')),
+  // Serialization from Buffer-annotated object.
+  z
+    .object({
+      type: z.literal('Buffer'),
+      data: z.array(z.number().int().min(0).max(255)),
+    })
+    .transform(({ data }) => Buffer.from(data)),
+  // Serialization from Buffer
+  z.instanceof(Buffer),
+]);
 
 export class ZodNullableOptional<T extends ZodTypeAny> extends ZodOptional<T> {
   _isNullableOptional = true;
@@ -88,12 +100,13 @@ 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
 > {
-  return bufferSchema.transform(klazz.fromBuffer.bind(klazz));
+  return bufferSchema.refine(refinement ?? (() => true), 'Not a valid buffer').transform(klazz.fromBuffer.bind(klazz));
 }
 
 /** Creates a schema for a js Map type that matches the serialization used in jsonStringify. */