@aztec-labs/foundation 6.0.0-nightly.20260829

package/src/eth-signature/eth_signature.ts

@@ -0,0 +1,155 @@
+import { Buffer32 } from '@aztec-labs/foundation/buffer';
+import { BufferReader, serializeToBuffer } from '@aztec-labs/foundation/serialize';
+import { secp256k1 } from '@noble/curves/secp256k1';
+import { z } from 'zod';
+
+import { randomBytes } from '../crypto/random/index.js';
+import { hasHexPrefix, hexToBuffer } from '../string/index.js';
+
+/**
+ * A version of the Signature class that uses `0x${string}` values for r and s rather than Buffer32s
+ */
+export type ViemSignature = {
+  r: `0x${string}`;
+  s: `0x${string}`;
+  v: number;
+};
+
+export type ViemTransactionSignature = {
+  r: `0x${string}`;
+  s: `0x${string}`;
+  yParity: 0 | 1;
+};
+
+/**
+ * Contains a signature split into it's primary components (r,s,v)
+ */
+export class Signature {
+  // Cached values
+  private size: number | undefined;
+
+  public readonly empty: boolean;
+
+  constructor(
+    /** The r value of the signature */
+    public readonly r: Buffer32,
+    /** The s value of the signature */
+    public readonly s: Buffer32,
+    /** The v value of the signature */
+    public readonly v: number,
+  ) {
+    this.empty = r.isZero() && s.isZero() && v === 0;
+  }
+
+  static fromBuffer(buf: Buffer | BufferReader): Signature {
+    const reader = BufferReader.asReader(buf);
+
+    const r = reader.readObject(Buffer32);
+    const s = reader.readObject(Buffer32);
+    const v = reader.readNumber();
+
+    return new Signature(r, s, v);
+  }
+
+  static isValidString(sig: `0x${string}`): boolean {
+    return /^0x[0-9a-f]{129,}$/i.test(sig);
+  }
+
+  /**
+   * A seperate method exists for this as when signing locally with viem, as when
+   * parsing from viem, we can expect the v value to be a u8, rather than our
+   * default serialization of u32
+   */
+  static fromString(sig: `0x${string}`): Signature {
+    const buf = hexToBuffer(sig);
+    const reader = BufferReader.asReader(buf);
+    const r = reader.readObject(Buffer32);
+    const s = reader.readObject(Buffer32);
+    const v = parseInt(sig.slice(2 + 64 * 2), 16);
+
+    return new Signature(r, s, v);
+  }
+
+  static fromViemSignature(sig: ViemSignature): Signature {
+    return new Signature(Buffer32.fromBuffer(hexToBuffer(sig.r)), Buffer32.fromBuffer(hexToBuffer(sig.s)), sig.v);
+  }
+
+  static fromViemTransactionSignature(sig: ViemTransactionSignature): Signature {
+    return new Signature(Buffer32.fromBuffer(hexToBuffer(sig.r)), Buffer32.fromBuffer(hexToBuffer(sig.s)), sig.yParity);
+  }
+
+  /** Generates a random valid ECDSA signature with a low s-value by signing a random message with a random key. */
+  static random(): Signature {
+    const privateKey = randomBytes(32);
+    const message = randomBytes(32);
+    const { r, s, recovery } = secp256k1.sign(message, privateKey);
+    return new Signature(Buffer32.fromBigInt(r), Buffer32.fromBigInt(s), recovery ? 28 : 27);
+  }
+
+  static empty(): Signature {
+    return new Signature(Buffer32.ZERO, Buffer32.ZERO, 0);
+  }
+
+  isEmpty(): boolean {
+    return this.empty;
+  }
+
+  equals(other: Signature): boolean {
+    return this.r.equals(other.r) && this.s.equals(other.s) && this.v === other.v && this.empty === other.empty;
+  }
+
+  toBuffer(): Buffer {
+    return serializeToBuffer([this.r, this.s, this.v]);
+  }
+
+  getSize(): number {
+    // We cache size to avoid recalculating it
+    if (this.size) {
+      return this.size;
+    }
+
+    this.size = this.toBuffer().length;
+    return this.size;
+  }
+
+  toString(): `0x${string}` {
+    return `0x${this.r.buffer.toString('hex')}${this.s.buffer.toString('hex')}${this.v.toString(16)}`;
+  }
+
+  /**
+   * Return the signature with `0x${string}` encodings for r and s
+   */
+  toViemSignature(): ViemSignature {
+    return {
+      r: this.r.toString(),
+      s: this.s.toString(),
+      v: this.v,
+    };
+  }
+
+  /**
+   * Return the signature with `0x${string}` encodings for r and s. Verifies v is valid
+   */
+  toViemTransactionSignature(): ViemTransactionSignature {
+    if (this.v !== 0 && this.v !== 1) {
+      throw new Error('Invalid transaction signature');
+    }
+    return {
+      r: this.r.toString(),
+      s: this.s.toString(),
+      yParity: this.v,
+    };
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  static get schema() {
+    return z
+      .string()
+      .refine(hasHexPrefix, 'No hex prefix')
+      .refine(Signature.isValidString, 'Not a valid Ethereum signature')
+      .transform(Signature.fromString);
+  }
+}

package/src/eth-signature/index.ts

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

package/src/fifo/fifo_frame_reader.ts

@@ -0,0 +1,113 @@
+import EventEmitter from 'node:events';
+import * as fs from 'node:fs';
+import * as net from 'node:net';
+import type { Readable } from 'node:stream';
+
+/**
+ * Events emitted by FifoFrameReader.
+ *
+ * - `frame`: A complete frame payload (without the 4-byte length header).
+ * - `error`: An unrecoverable error (invalid frame length, stream error).
+ * - `end`: The underlying stream has ended.
+ */
+export interface FifoFrameReaderEvents {
+  frame: [payload: Buffer];
+  error: [error: Error];
+  end: [];
+}
+
+/**
+ * Reads length-delimited frames from a readable stream (typically a named FIFO pipe).
+ *
+ * Wire format: `[4-byte big-endian payload length][payload bytes]`
+ *
+ * Emits a `frame` event for each complete frame with the raw payload buffer.
+ * Callers are responsible for deserializing the payload (e.g., via msgpack).
+ *
+ * On encountering an invalid payload length (0 or >maxPayloadSize), emits `error`
+ * and destroys the stream.
+ */
+export class FifoFrameReader extends EventEmitter<FifoFrameReaderEvents> {
+  private stream: Readable | null = null;
+  private pendingBuf: Buffer = Buffer.alloc(0);
+  private running = false;
+
+  constructor(private readonly maxPayloadSize = 10 * 1024 * 1024) {
+    super();
+  }
+
+  /** Open a FIFO at the given path and start reading frames. */
+  start(fifoPath: string): void {
+    // Read the FIFO through a libuv pipe handle (net.Socket) rather than fs.createReadStream.
+    // An fs read stream services the pipe with a blocking threadpool read that destroy() cannot
+    // cancel: if a writer never closes, that read stays parked and keeps the host process alive
+    // (manifesting as Jest "did not exit"). Opening O_NONBLOCK and wrapping the fd in a pipe
+    // handle makes reads epoll-based, so stop()'s destroy() releases the handle immediately,
+    // regardless of whether the writer is still attached.
+    const fd = fs.openSync(fifoPath, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+    let socket: net.Socket;
+    try {
+      socket = new net.Socket({ fd, readable: true, writable: false });
+    } catch (err) {
+      fs.closeSync(fd);
+      throw err;
+    }
+    this.startFromStream(socket);
+  }
+
+  /** Start reading frames from an existing readable stream. */
+  startFromStream(stream: Readable): void {
+    if (this.running) {
+      throw new Error('FifoFrameReader is already running');
+    }
+    this.running = true;
+    this.pendingBuf = Buffer.alloc(0);
+    this.stream = stream;
+
+    stream.on('data', (chunk: Buffer | string) => {
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      this.pendingBuf = this.pendingBuf.length > 0 ? Buffer.concat([this.pendingBuf, buf]) : buf;
+      this.drainFrames();
+    });
+
+    stream.on('error', (err: Error) => {
+      if (this.running) {
+        this.emit('error', err);
+      }
+    });
+
+    stream.on('end', () => {
+      this.emit('end');
+    });
+  }
+
+  /** Stop reading and destroy the underlying stream. */
+  stop(): void {
+    this.running = false;
+    if (this.stream) {
+      this.stream.destroy();
+      this.stream = null;
+    }
+  }
+
+  /** Parse complete frames out of the pending buffer. */
+  private drainFrames(): void {
+    while (this.pendingBuf.length >= 4) {
+      const payloadLen = this.pendingBuf.readUInt32BE(0);
+      if (payloadLen === 0 || payloadLen > this.maxPayloadSize) {
+        this.emit('error', new Error(`Invalid payload length: ${payloadLen}`));
+        this.stop();
+        return;
+      }
+
+      const frameLen = 4 + payloadLen;
+      if (this.pendingBuf.length < frameLen) {
+        break; // Wait for more data
+      }
+
+      const payload = this.pendingBuf.subarray(4, frameLen);
+      this.pendingBuf = this.pendingBuf.subarray(frameLen);
+      this.emit('frame', Buffer.from(payload));
+    }
+  }
+}

package/src/fifo/index.ts

@@ -0,0 +1 @@
+export { FifoFrameReader } from './fifo_frame_reader.js';

package/src/fifo_set/fifo_set.ts

@@ -0,0 +1,52 @@
+/** A Set capped to a fixed number of entries, evicting the oldest inserted value when full. */
+export class FifoSet<T> extends Set<T> {
+  private _limit: number | undefined;
+
+  private constructor(values?: Iterable<T>) {
+    super(values);
+  }
+
+  /** Creates a bounded set with a positive integer limit. */
+  static withLimit<T>(limit: number, values?: Iterable<T>): FifoSet<T> {
+    if (!Number.isSafeInteger(limit) || limit <= 0) {
+      throw new TypeError(`FifoSet limit must be a positive safe integer: ${limit}`);
+    }
+
+    const set = new FifoSet(values);
+    set._limit = limit;
+    set.compact();
+
+    return set;
+  }
+
+  override add(value: T): this {
+    super.add(value);
+    this.compact();
+    return this;
+  }
+
+  /** Maximum number of entries retained by this set. */
+  public get limit(): number {
+    return this._limit ?? Infinity;
+  }
+
+  /** Evicts oldest entries until the set is within its limit. */
+  public compact(): void {
+    while (this.size > this.limit) {
+      const head = this.values().next();
+      if (head.done) {
+        return;
+      }
+      this.delete(head.value);
+    }
+  }
+
+  /** Adds a value only if it is absent, returning whether the set changed. */
+  public addIfAbsent(value: T): boolean {
+    if (this.has(value)) {
+      return false;
+    }
+    this.add(value);
+    return true;
+  }
+}

package/src/fifo_set/index.ts

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

package/src/fs/index.ts

@@ -0,0 +1,2 @@
+export * from './run_in_dir.js';
+export * from './try_rm_dir.js';

package/src/fs/run_in_dir.ts

@@ -0,0 +1,33 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+
+import { createLogger } from '../log/pino-logger.js';
+
+// Create a random directory underneath a 'base' directory
+// Calls a provided method, ensures the random directory is cleaned up afterwards unless the operation fails
+export async function runInDirectory<T>(
+  workingDirBase: string,
+  fn: (dir: string) => Promise<T>,
+  skipCleanup: boolean | undefined,
+  logger = createLogger('foundation:run-in-directory'),
+): Promise<T> {
+  // Create random directory to be used for temp files
+  const workingDirectory = await fs.mkdtemp(path.join(workingDirBase, 'tmp-'));
+
+  await fs.access(workingDirectory);
+
+  try {
+    return await fn(workingDirectory);
+  } catch (err) {
+    skipCleanup = true;
+    throw err;
+  } finally {
+    if (!skipCleanup) {
+      try {
+        await fs.rm(workingDirectory, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+      } catch (err) {
+        logger.warn(`Failed to cleanup temporary directory ${workingDirectory}: ${err}`, { err });
+      }
+    }
+  }
+}

package/src/fs/try_rm_dir.ts

@@ -0,0 +1,15 @@
+import { rm } from 'fs/promises';
+
+import type { Logger } from '../log/index.js';
+
+export async function tryRmDir(dir: string | undefined, logger?: Logger): Promise<void> {
+  if (dir === undefined) {
+    return;
+  }
+  try {
+    logger?.debug(`Cleaning up directory at ${dir}`);
+    await rm(dir, { recursive: true, force: true, maxRetries: 3 });
+  } catch (err) {
+    logger?.warn(`Failed to delete directory at ${dir}: ${err}`);
+  }
+}

package/src/iterable/all.ts

@@ -0,0 +1,32 @@
+import { isAsyncIterable } from './isAsyncIt.js';
+
+/**
+ * Collects all values from an (async) iterable and returns them as an array
+ * @param source - Iterable to collect all values from
+ * @returns All of the iterable's values as an array.
+ */
+function all<T>(source: Iterable<T>): T[];
+function all<T>(source: Iterable<T> | AsyncIterable<T>): Promise<T[]>;
+function all<T>(source: Iterable<T> | AsyncIterable<T>): Promise<T[]> | T[] {
+  if (isAsyncIterable(source)) {
+    return (async () => {
+      const arr = [];
+
+      for await (const entry of source) {
+        arr.push(entry);
+      }
+
+      return arr;
+    })();
+  }
+
+  const arr = [];
+
+  for (const entry of source) {
+    arr.push(entry);
+  }
+
+  return arr;
+}
+
+export { all };

package/src/iterable/filter.ts

@@ -0,0 +1,77 @@
+import { peek } from './peek.js';
+
+function isAsyncIterable<T>(thing: any): thing is AsyncIterable<T> {
+  return thing[Symbol.asyncIterator] != null;
+}
+
+/**
+ * Filters the passed (async) iterable by using the filter function.
+ * @param source - An iterable to filter.
+ * @returns A generator of the filtered values.
+ */
+function filter<T>(
+  source: Iterable<T>,
+  fn: (val: T, index: number) => Promise<boolean>,
+): AsyncGenerator<T, void, undefined>;
+function filter<T>(source: Iterable<T>, fn: (val: T, index: number) => boolean): Generator<T, void, undefined>;
+function filter<T>(
+  source: Iterable<T> | AsyncIterable<T>,
+  fn: (val: T, index: number) => boolean | Promise<boolean>,
+): AsyncGenerator<T, void, undefined>;
+function filter<T>(
+  source: Iterable<T> | AsyncIterable<T>,
+  fn: (val: T, index: number) => boolean | Promise<boolean>,
+): Generator<T, void, undefined> | AsyncGenerator<T, void, undefined> {
+  let index = 0;
+
+  if (isAsyncIterable(source)) {
+    return (async function* () {
+      for await (const entry of source) {
+        if (await fn(entry, index++)) {
+          yield entry;
+        }
+      }
+    })();
+  }
+
+  // if mapping function returns a promise we have to return an async generator
+  const peekable = peek(source);
+  const { value, done } = peekable.next();
+
+  if (done === true) {
+    return (function* () {})();
+  }
+
+  const res = fn(value, index++);
+
+  // @ts-expect-error .then is not present on O
+  if (typeof res.then === 'function') {
+    return (async function* () {
+      if (await res) {
+        yield value;
+      }
+
+      for (const entry of peekable) {
+        if (await fn(entry, index++)) {
+          yield entry;
+        }
+      }
+    })();
+  }
+
+  const func = fn as (val: T, index: number) => boolean;
+
+  return (function* () {
+    if (res === true) {
+      yield value;
+    }
+
+    for (const entry of peekable) {
+      if (func(entry, index++)) {
+        yield entry;
+      }
+    }
+  })();
+}
+
+export { filter };

package/src/iterable/first.ts

@@ -0,0 +1,14 @@
+/**
+ * Returns the first entry of an iterable, or undefined if it yields none, closing the underlying
+ * iterator either way. Use this instead of calling `.next()` once and abandoning the iterator:
+ * an abandoned generator never runs its finally blocks, so any resource it holds is leaked — e.g.
+ * a kv-store iterator's LMDB cursor, where enough leaks deadlock the store.
+ */
+export async function first<T>(
+  iterator: Iterable<T> | AsyncIterableIterator<T> | AsyncIterable<T> | IterableIterator<T>,
+): Promise<T | undefined> {
+  for await (const i of iterator) {
+    return i;
+  }
+  return undefined;
+}

package/src/iterable/index.ts

@@ -0,0 +1,8 @@
+export * from './map.js';
+export * from './filter.js';
+export * from './sort.js';
+export * from './take.js';
+export * from './all.js';
+export * from './first.js';
+export * from './peek.js';
+export * from './toArray.js';

package/src/iterable/isAsyncIt.ts

@@ -0,0 +1,8 @@
+/**
+ * Utility function to type check an AsyncIterable
+ * @param thing - Input to type check
+ * @returns Type-checked input
+ */
+export function isAsyncIterable<T>(thing: any): thing is AsyncIterable<T> {
+  return thing[Symbol.asyncIterator] != null;
+}

package/src/iterable/map.ts

@@ -0,0 +1,66 @@
+import { isAsyncIterable } from './isAsyncIt.js';
+import { peek } from './peek.js';
+
+/**
+ * Takes an (async) iterable and returns one with each item mapped by the passed
+ * function.
+ * @param source - The iterable to run the map function on.
+ * @param func - The function to run over the iterable's items.
+ * @returns A generator of the mapped items.
+ */
+function map<I, O>(
+  source: Iterable<I>,
+  func: (val: I, index: number) => Promise<O>,
+): AsyncGenerator<O, void, undefined>;
+function map<I, O>(source: Iterable<I>, func: (val: I, index: number) => O): Generator<O, void, undefined>;
+function map<I, O>(
+  source: AsyncIterable<I> | Iterable<I>,
+  func: (val: I, index: number) => O | Promise<O>,
+): AsyncGenerator<O, void, undefined>;
+function map<I, O>(
+  source: AsyncIterable<I> | Iterable<I>,
+  func: (val: I, index: number) => O | Promise<O>,
+): AsyncGenerator<O, void, undefined> | Generator<O, void, undefined> {
+  let index = 0;
+
+  if (isAsyncIterable(source)) {
+    return (async function* () {
+      for await (const val of source) {
+        yield func(val, index++);
+      }
+    })();
+  }
+
+  // if mapping function returns a promise we have to return an async generator
+  const peekable = peek(source);
+  const { value, done } = peekable.next();
+
+  if (done === true) {
+    return (function* () {})();
+  }
+
+  const res = func(value, index++);
+
+  // @ts-expect-error .then is not present on O
+  if (typeof res.then === 'function') {
+    return (async function* () {
+      yield await res;
+
+      for (const val of peekable) {
+        yield func(val, index++);
+      }
+    })();
+  }
+
+  const fn = func as (val: I, index: number) => O;
+
+  return (function* () {
+    yield res as O;
+
+    for (const val of peekable) {
+      yield fn(val, index++);
+    }
+  })();
+}
+
+export { map };

package/src/iterable/peek.ts

@@ -0,0 +1,58 @@
+export interface Peek<T> {
+  peek(): IteratorResult<T, undefined>;
+}
+
+export interface AsyncPeek<T> {
+  peek(): Promise<IteratorResult<T, undefined>>;
+}
+
+export interface Push<T> {
+  push(value: T): void;
+}
+
+export type Peekable<T> = Iterable<T> & Peek<T> & Push<T> & Iterator<T>;
+
+export type AsyncPeekable<T> = AsyncIterable<T> & AsyncPeek<T> & Push<T> & AsyncIterator<T>;
+
+/**
+ * Utility function that allows peeking into the contents of an async iterator.
+ * @param iterable - The async iterator to peek the values of.
+ */
+function peekable<T>(iterable: Iterable<T>): Peekable<T>;
+function peekable<T>(iterable: AsyncIterable<T>): AsyncPeekable<T>;
+function peekable<T>(iterable: Iterable<T> | AsyncIterable<T>): Peekable<T> | AsyncPeekable<T> {
+  const [iterator, symbol] =
+    // @ts-expect-error can't use Symbol.asyncIterator to index iterable since it might be Iterable
+    iterable[Symbol.asyncIterator] != null
+      ? // @ts-expect-error can't use Symbol.asyncIterator to index iterable since it might be Iterable
+        [iterable[Symbol.asyncIterator](), Symbol.asyncIterator]
+      : // @ts-expect-error can't use Symbol.iterator to index iterable since it might be AsyncIterable
+        [iterable[Symbol.iterator](), Symbol.iterator];
+
+  const queue: any[] = [];
+
+  // @ts-expect-error can't use symbol to index peekable
+  return {
+    peek: () => {
+      return iterator.next();
+    },
+    push: (value: any) => {
+      queue.push(value);
+    },
+    next: () => {
+      if (queue.length > 0) {
+        return {
+          done: false,
+          value: queue.shift(),
+        };
+      }
+
+      return iterator.next();
+    },
+    [symbol]() {
+      return this;
+    },
+  };
+}
+
+export { peekable as peek };

package/src/iterable/sort.ts

@@ -0,0 +1,39 @@
+import { all } from './all.js';
+import { isAsyncIterable } from './isAsyncIt.js';
+
+export interface CompareFunction<T> {
+  (a: T, b: T): number;
+}
+
+/**
+ * Collects all values from an async iterator, sorts them
+ * using the passed function and yields them.
+ * @param source - Iterable to sort.
+ * @param sorter - Sorting function.
+ * @returns A generator of the sorted values.
+ */
+function sort<T>(source: Iterable<T>, sorter: CompareFunction<T>): Generator<T, void, undefined>;
+function sort<T>(
+  source: Iterable<T> | AsyncIterable<T>,
+  sorter: CompareFunction<T>,
+): AsyncGenerator<T, void, undefined>;
+function sort<T>(
+  source: Iterable<T> | AsyncIterable<T>,
+  sorter: CompareFunction<T>,
+): AsyncGenerator<T, void, undefined> | Generator<T, void, undefined> {
+  if (isAsyncIterable(source)) {
+    return (async function* () {
+      const arr = await all(source);
+
+      yield* arr.sort(sorter);
+    })();
+  }
+
+  return (function* () {
+    const arr = all(source);
+
+    yield* arr.sort(sorter);
+  })();
+}
+
+export { sort };