@aztec/foundation 0.0.1-commit.5914bae → 0.0.1-commit.59a0419c6

package/src/config/index.ts

@@ -10,14 +10,15 @@ export type { EnvVar, NetworkNames };
 export type { NetworkConfig, NetworkConfigMap } from './network_config.js';
 export { NetworkConfigMapSchema, NetworkConfigSchema } from './network_config.js';
 
-export interface ConfigMapping {
+export interface ConfigMapping<T> {
   env?: EnvVar;
-  parseEnv?: (val: string) => any;
-  defaultValue?: any;
+  /** Parse an env-var string into `T`. Throws on invalid input. */
+  parseEnv?: (val: string) => T;
+  defaultValue?: T;
   printDefault?: (val: any) => string;
   description: string;
   isBoolean?: boolean;
-  nested?: Record<string, ConfigMapping>;
+  nested?: Record<string, ConfigMapping<any>>;
   fallback?: EnvVar[];
   /**
    * List of deprecated env vars that are still supported but will log a warning.
@@ -30,7 +31,9 @@ export function isBooleanConfigValue<T>(obj: T, key: keyof T): boolean {
   return typeof obj[key] === 'boolean';
 }
 
-export type ConfigMappingsType<T> = Record<keyof T, ConfigMapping>;
+export type ConfigMappingsType<T> = {
+  [K in keyof T]-?: ConfigMapping<Required<T>[K]>;
+};
 
 /**
  * Shared utility function to get a value from environment variables with fallback support.
@@ -66,8 +69,8 @@ export function getValueFromEnvWithFallback<T>(
     }
   }
 
-  // Parse the value if needed
-  if (value !== undefined) {
+  // Parse the value if needed. Empty strings are treated as "not set".
+  if (value !== undefined && value !== '') {
     return parseFunc ? parseFunc(value) : (value as unknown as T);
   }
 
@@ -84,7 +87,11 @@ export function getConfigFromMappings<T>(configMappings: ConfigMappingsType<T>):
       (config as any)[key] = getConfigFromMappings(nested);
     } else {
       // Use the shared utility function
-      (config as any)[key] = getValueFromEnvWithFallback(env, parseEnv, defaultValue, fallback);
+      try {
+        (config as any)[key] = getValueFromEnvWithFallback(env, parseEnv, defaultValue, fallback);
+      } catch (e: any) {
+        throw new Error(`Failed to parse config '${key}' (env: ${env ?? 'none'}): ${e.message}`);
+      }
 
       // Check for deprecated env vars and warn if logger is set
       if (deprecatedFallback?.length) {
@@ -123,7 +130,7 @@ export function omitConfigMappings<T, K extends keyof T>(
  * @param defaultVal - The default numerical value to use if the environment variable is not set or is invalid
  * @returns Object with parseEnv and default values for a numerical config value
  */
-export function numberConfigHelper(defaultVal: number): Pick<ConfigMapping, 'parseEnv' | 'defaultValue'> {
+export function numberConfigHelper(defaultVal: number): Pick<ConfigMapping<number>, 'parseEnv' | 'defaultValue'> {
   return {
     parseEnv: (val: string) => safeParseNumber(val, defaultVal),
     defaultValue: defaultVal,
@@ -138,7 +145,7 @@ export function numberConfigHelper(defaultVal: number): Pick<ConfigMapping, 'par
 export function floatConfigHelper(
   defaultVal: number,
   validationFn?: (val: number) => void,
-): Pick<ConfigMapping, 'parseEnv' | 'defaultValue'> {
+): Pick<ConfigMapping<number>, 'parseEnv' | 'defaultValue'> {
   return {
     parseEnv: (val: string): number => {
       const parsed = safeParseFloat(val, defaultVal);
@@ -152,7 +159,7 @@ export function floatConfigHelper(
 /**
  * Parses an environment variable to a 0-1 percentage value
  */
-export function percentageConfigHelper(defaultVal: number): Pick<ConfigMapping, 'parseEnv' | 'defaultValue'> {
+export function percentageConfigHelper(defaultVal: number): Pick<ConfigMapping<number>, 'parseEnv' | 'defaultValue'> {
   return {
     parseEnv: (val: string): number => {
       const parsed = safeParseFloat(val, defaultVal);
@@ -171,12 +178,13 @@ export function percentageConfigHelper(defaultVal: number): Pick<ConfigMapping,
  * @param defaultVal - The default numerical value to use if the environment variable is not set or is invalid
  * @returns Object with parseEnv and default values for a numerical config value
  */
-export function bigintConfigHelper(defaultVal?: bigint): Pick<ConfigMapping, 'parseEnv' | 'defaultValue'> {
+export function bigintConfigHelper(defaultVal: bigint): Pick<ConfigMapping<bigint>, 'parseEnv' | 'defaultValue'>;
+export function bigintConfigHelper(): Pick<ConfigMapping<bigint | undefined>, 'parseEnv' | 'defaultValue'>;
+export function bigintConfigHelper(
+  defaultVal?: bigint,
+): Pick<ConfigMapping<bigint | undefined>, 'parseEnv' | 'defaultValue'> {
   return {
     parseEnv: (val: string) => {
-      if (val === '') {
-        return defaultVal;
-      }
       // Handle scientific notation (e.g. "1e+23", "2E23") which BigInt() doesn't accept directly.
       // We parse it losslessly using bigint arithmetic instead of going through float64.
       if (/[eE]/.test(val)) {
@@ -200,32 +208,37 @@ export function bigintConfigHelper(defaultVal?: bigint): Pick<ConfigMapping, 'pa
 
 /**
  * Generates parseEnv for an optional numerical config value.
+ * Empty strings are already handled by getValueFromEnvWithFallback.
  */
-export function optionalNumberConfigHelper(): Pick<ConfigMapping, 'parseEnv'> {
+export function optionalNumberConfigHelper(): Pick<ConfigMapping<number>, 'parseEnv'> {
   return {
-    parseEnv: (val: string | undefined) => {
-      if (val !== undefined && val.length > 0) {
-        const parsedValue = parseInt(val);
-        return Number.isSafeInteger(parsedValue) ? parsedValue : undefined;
+    parseEnv: (val: string) => {
+      const parsedValue = parseInt(val);
+      if (!Number.isSafeInteger(parsedValue)) {
+        throw new Error(`Invalid number: ${val}`);
       }
-      return undefined;
+      return parsedValue;
     },
   };
 }
 
 /** Generates parseEnv for an enum-like config value. */
+export function enumConfigHelper<T extends string>(
+  values: T[],
+  defaultValue: NoInfer<T>,
+): Pick<ConfigMapping<T>, 'parseEnv' | 'defaultValue'>;
+export function enumConfigHelper<T extends string>(
+  values: T[],
+): Pick<ConfigMapping<T | undefined>, 'parseEnv' | 'defaultValue'>;
 export function enumConfigHelper<T extends string>(
   values: T[],
   defaultValue?: NoInfer<T>,
-): Pick<ConfigMapping, 'parseEnv' | 'defaultValue'> {
+): Pick<ConfigMapping<T | undefined>, 'parseEnv' | 'defaultValue'> {
   return {
     parseEnv: (val: string) => {
-      const sanitizedVal = (val ?? '').trim().toLowerCase();
-      if (values.includes(sanitizedVal as T)) {
-        return sanitizedVal as T;
-      }
-      if (!val && defaultValue) {
-        return defaultValue;
+      const sanitizedVal = val.trim().toLowerCase();
+      if (values.some(v => v.toLowerCase() === sanitizedVal)) {
+        return values.find(v => v.toLowerCase() === sanitizedVal)!;
       }
       throw new Error(`Invalid config value '${val}' (must be one of ${values.join(', ')})`);
     },
@@ -240,7 +253,9 @@ export function enumConfigHelper<T extends string>(
  */
 export function booleanConfigHelper(
   defaultVal = false,
-): Required<Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & { parseVal: (val: string) => boolean }> {
+): Required<
+  Pick<ConfigMapping<boolean>, 'parseEnv' | 'defaultValue' | 'isBoolean'> & { parseVal: (val: string) => boolean }
+> {
   const parse = (val: string | boolean) => (typeof val === 'boolean' ? val : parseBooleanEnv(val));
   return {
     parseEnv: parse,
@@ -250,91 +265,88 @@ export function booleanConfigHelper(
   };
 }
 
-export function secretValueConfigHelper<T>(parse: (val: string | undefined) => T): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<T>;
-  }
-> {
+export function secretValueConfigHelper<T>(parse: (val: string | undefined) => T): Pick<
+  ConfigMapping<SecretValue<T>>,
+  'parseEnv' | 'defaultValue'
+> & {
+  parseVal: (val: string) => SecretValue<T>;
+} {
   const wrap = (val: string) => new SecretValue(parse(val));
   return {
     parseEnv: wrap,
     parseVal: wrap,
     defaultValue: new SecretValue(parse(undefined)),
-    isBoolean: true,
   };
 }
 
 export { parseBooleanEnv } from './parse-env.js';
 
-export function secretStringConfigHelper(): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<string | undefined>;
-  }
->;
-export function secretStringConfigHelper(defaultValue: string): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<string>;
-  }
->;
-export function secretStringConfigHelper(defaultValue?: string): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<string | typeof defaultValue>;
-  }
-> {
+export function secretStringConfigHelper(): {
+  parseEnv: (val: string) => SecretValue<string>;
+  parseVal: (val: string) => SecretValue<string>;
+  defaultValue: undefined;
+};
+export function secretStringConfigHelper(defaultValue: string): {
+  parseEnv: (val: string) => SecretValue<string>;
+  parseVal: (val: string) => SecretValue<string>;
+  defaultValue: SecretValue<string>;
+};
+export function secretStringConfigHelper(defaultValue?: string): {
+  parseEnv: (val: string) => SecretValue<string>;
+  parseVal: (val: string) => SecretValue<string>;
+  defaultValue: SecretValue<string> | undefined;
+} {
   const parse = (val: string) => new SecretValue(val);
   return {
     parseEnv: parse,
     parseVal: parse,
     defaultValue: defaultValue !== undefined ? new SecretValue(defaultValue) : undefined,
-    isBoolean: true,
   };
 }
 
-export function secretFrConfigHelper(): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<Fr | undefined>;
-  }
->;
-export function secretFrConfigHelper(defaultValue: Fr): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<Fr>;
-  }
->;
-export function secretFrConfigHelper(defaultValue?: Fr): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<Fr | typeof defaultValue>;
-  }
-> {
+export function secretFrConfigHelper(): {
+  parseEnv: (val: string) => SecretValue<Fr>;
+  parseVal: (val: string) => SecretValue<Fr>;
+  defaultValue: undefined;
+};
+export function secretFrConfigHelper(defaultValue: Fr): {
+  parseEnv: (val: string) => SecretValue<Fr>;
+  parseVal: (val: string) => SecretValue<Fr>;
+  defaultValue: SecretValue<Fr>;
+};
+export function secretFrConfigHelper(defaultValue?: Fr): {
+  parseEnv: (val: string) => SecretValue<Fr>;
+  parseVal: (val: string) => SecretValue<Fr>;
+  defaultValue: SecretValue<Fr> | undefined;
+} {
   const parse = (val: string) => new SecretValue(Fr.fromHexString(val));
   return {
     parseEnv: parse,
     parseVal: parse,
     defaultValue: defaultValue !== undefined ? new SecretValue(defaultValue) : undefined,
-    isBoolean: true,
   };
 }
 
-export function secretFqConfigHelper(defaultValue: Fq): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<Fq>;
-  }
->;
-export function secretFqConfigHelper(): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<Fq | undefined>;
-  }
->;
-export function secretFqConfigHelper(defaultValue?: Fq): Required<
-  Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {
-    parseVal: (val: string) => SecretValue<Fq | typeof defaultValue>;
-  }
-> {
+export function secretFqConfigHelper(): {
+  parseEnv: (val: string) => SecretValue<Fq>;
+  parseVal: (val: string) => SecretValue<Fq>;
+  defaultValue: undefined;
+};
+export function secretFqConfigHelper(defaultValue: Fq): {
+  parseEnv: (val: string) => SecretValue<Fq>;
+  parseVal: (val: string) => SecretValue<Fq>;
+  defaultValue: SecretValue<Fq>;
+};
+export function secretFqConfigHelper(defaultValue?: Fq): {
+  parseEnv: (val: string) => SecretValue<Fq>;
+  parseVal: (val: string) => SecretValue<Fq>;
+  defaultValue: SecretValue<Fq> | undefined;
+} {
   const parse = (val: string) => new SecretValue(Fq.fromHexString(val));
   return {
     parseEnv: parse,
     parseVal: parse,
-    defaultValue: typeof defaultValue !== 'undefined' ? new SecretValue(defaultValue) : undefined,
-    isBoolean: true,
+    defaultValue: defaultValue !== undefined ? new SecretValue(defaultValue) : undefined,
   };
 }
 

package/src/config/network_config.ts

@@ -10,8 +10,8 @@ export const NetworkConfigSchema = z
     feeAssetHandlerAddress: z.string().optional(),
     l1ChainId: z.number(),
     blockDurationMs: z.number().positive().optional(),
-    nodeVersion: z.string().optional(),
     txPublicSetupAllowListExtend: z.string().optional(),
+    nodeVersion: z.string().optional(),
   })
   .passthrough(); // Allow additional unknown fields to pass through
 

package/src/config/network_name.ts

@@ -5,7 +5,8 @@ export type NetworkNames =
   | 'testnet'
   | 'mainnet'
   | 'next-net'
-  | 'devnet';
+  | 'devnet'
+  | `v${number}-devnet-${number}`;
 
 export function getActiveNetworkName(name?: string): NetworkNames {
   const network = name || process.env.NETWORK;
@@ -23,6 +24,8 @@ export function getActiveNetworkName(name?: string): NetworkNames {
     return 'next-net';
   } else if (network === 'devnet') {
     return 'devnet';
+  } else if (/^v\d+-devnet-\d+$/.test(network)) {
+    return network as `v${number}-devnet-${number}`;
   }
   throw new Error(`Unknown network: ${network}`);
 }

package/src/crypto/aes128/index.ts

@@ -59,10 +59,19 @@ export class Aes128 {
    * @param iv - AES initialization vector.
    * @param key - Key to decrypt with.
    * @returns Decrypted data.
+   * @throws If the decrypted buffer has invalid PKCS#7 padding.
    */
   public async decryptBufferCBC(data: Uint8Array, iv: Uint8Array, key: Uint8Array) {
     const paddedBuffer = await this.decryptBufferCBCKeepPadding(data, iv, key);
-    const paddingToRemove = paddedBuffer[paddedBuffer.length - 1];
-    return paddedBuffer.subarray(0, paddedBuffer.length - paddingToRemove);
+    const paddingLen = paddedBuffer[paddedBuffer.length - 1];
+    if (paddingLen === 0 || paddingLen > 16) {
+      throw new Error(`Invalid PKCS#7 padding length: ${paddingLen}`);
+    }
+    for (let i = paddedBuffer.length - paddingLen; i < paddedBuffer.length; i++) {
+      if (paddedBuffer[i] !== paddingLen) {
+        throw new Error('Invalid PKCS#7 padding');
+      }
+    }
+    return paddedBuffer.subarray(0, paddedBuffer.length - paddingLen);
   }
 }

package/src/crypto/bls/bn254_keystore.ts

@@ -262,26 +262,3 @@ export function decryptBn254KeystoreFromObject(keystore: Bn254Keystore, password
     throw new Bn254KeystoreError(`Failed to decrypt keystore: ${String(error)}`, error as Error);
   }
 }
-
-/**
- * Validates that a decrypted private key matches the public key in the keystore.
- *
- * @param privateKeyHex - Decrypted private key (0x-prefixed)
- * @param expectedPubkey - Expected public key from keystore
- * @param computePublicKey - Function to compute public key from private key
- * @returns true if keys match, false otherwise
- */
-export function verifyBn254Keypair(
-  privateKeyHex: string,
-  expectedPubkey: string,
-  computePublicKey: (privateKey: string) => string,
-): boolean {
-  try {
-    const computedPubkey = computePublicKey(privateKeyHex);
-    const normalizedExpected = expectedPubkey.toLowerCase().replace(/^0x/i, '');
-    const normalizedComputed = computedPubkey.toLowerCase().replace(/^0x/i, '');
-    return normalizedExpected === normalizedComputed;
-  } catch {
-    return false;
-  }
-}

package/src/curves/bls12/field.ts

@@ -6,7 +6,6 @@ import { toBigIntBE, toBufferBE } from '../../bigint-buffer/index.js';
 import { randomBytes } from '../../crypto/random/index.js';
 import { hexSchemaFor } from '../../schemas/utils.js';
 import { BufferReader } from '../../serialize/buffer_reader.js';
-import { TypeRegistry } from '../../serialize/type_registry.js';
 import { Fr } from '../bn254/field.js';
 
 /**
@@ -323,9 +322,6 @@ export class BLS12Fr extends BLS12Field {
   }
 }
 
-// For deserializing JSON.
-TypeRegistry.register('BLS12Fr', BLS12Fr);
-
 /**
  * Fq field class.
  * @dev This class is used to represent elements of BLS12-381 base field.
@@ -458,6 +454,3 @@ export class BLS12Fq extends BLS12Field {
     return hexSchemaFor(BLS12Fq);
   }
 }
-
-// For deserializing JSON.
-TypeRegistry.register('BLS12Fq', BLS12Fq);

package/src/curves/bn254/field.ts

@@ -6,9 +6,6 @@ import { toBigIntBE, toBufferBE } from '../../bigint-buffer/index.js';
 import { randomBytes } from '../../crypto/random/index.js';
 import { hexSchemaFor } from '../../schemas/utils.js';
 import { BufferReader } from '../../serialize/buffer_reader.js';
-import { TypeRegistry } from '../../serialize/type_registry.js';
-
-/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
 
 /**
  * Represents a field derived from BaseField.
@@ -187,10 +184,25 @@ function fromHexString<T extends BaseField>(buf: string, f: DerivedField<T>) {
   return new f(toBigIntBE(buffer));
 }
 
-/** Branding to ensure fields are not interchangeable types. */
-export interface Fr {
-  /** Brand. */
-  _branding: 'Fr';
+/**
+ * Abstract unbranded base class for BN254 scalar field elements.
+ * Extend this instead of Fr when defining a branded subtype (e.g. BlockHash)
+ * to avoid inheriting Fr's `_branding`.
+ */
+export abstract class BaseFr extends BaseField {
+  static MODULUS = 0x30644e72e131a029b85045b68181585d2833e84879b9709143e1f593f0000001n;
+
+  constructor(value: number | bigint | boolean | BaseField | Buffer) {
+    super(value);
+  }
+
+  protected modulus() {
+    return BaseFr.MODULUS;
+  }
+
+  toJSON() {
+    return this.toString();
+  }
 }
 
 /**
@@ -198,10 +210,12 @@ export interface Fr {
  * @dev This class is used to represent elements of BN254 scalar field or elements in the base field of Grumpkin.
  * (Grumpkin's scalar field corresponds to BN254's base field and vice versa.)
  */
-export class Fr extends BaseField {
+export class Fr extends BaseFr {
+  /** Branding for nominal typing. */
+  declare private readonly _branding: 'Fr';
+  static override MODULUS = 0x30644e72e131a029b85045b68181585d2833e84879b9709143e1f593f0000001n;
   static ZERO = new Fr(0n);
   static ONE = new Fr(1n);
-  static MODULUS = 0x30644e72e131a029b85045b68181585d2833e84879b9709143e1f593f0000001n;
   static MAX_FIELD_VALUE = new Fr(this.MODULUS - 1n);
 
   constructor(value: number | bigint | boolean | Fr | Buffer) {
@@ -212,10 +226,6 @@ export class Fr extends BaseField {
     return `Fr<${this.toString()}>`;
   }
 
-  protected modulus() {
-    return Fr.MODULUS;
-  }
-
   static random() {
     return random(Fr);
   }
@@ -320,10 +330,6 @@ export class Fr extends BaseField {
     return Fr.fromBuffer(Buffer.from(response.value));
   }
 
-  toJSON() {
-    return this.toString();
-  }
-
   /**
    * Creates an Fr instance from a plain object without Zod validation.
    * This method is optimized for performance and skips validation, making it suitable
@@ -345,23 +351,14 @@ export class Fr extends BaseField {
   }
 }
 
-// For deserializing JSON.
-TypeRegistry.register('Fr', Fr);
-
-/**
- * Branding to ensure fields are not interchangeable types.
- */
-export interface Fq {
-  /** Brand. */
-  _branding: 'Fq';
-}
-
 /**
  * Fq field class.
  * @dev This class is used to represent elements of BN254 base field or elements in the scalar field of Grumpkin.
  * (Grumpkin's scalar field corresponds to BN254's base field and vice versa.)
  */
 export class Fq extends BaseField {
+  /** Branding for nominal typing. */
+  declare private readonly _branding: 'Fq';
   static ZERO = new Fq(0n);
   static MODULUS = 0x30644e72e131a029b85045b68181585d97816a916871ca8d3c208c16d87cfd47n;
   private static HIGH_SHIFT = BigInt((BaseField.SIZE_IN_BYTES / 2) * 8);
@@ -470,9 +467,6 @@ export class Fq extends BaseField {
   }
 }
 
-// For deserializing JSON.
-TypeRegistry.register('Fq', Fq);
-
 // Beware: Performance bottleneck below
 
 /**

package/src/eth-address/index.ts

@@ -5,7 +5,6 @@ import { randomBytes } from '../crypto/random/index.js';
 import { Fr } from '../curves/bn254/index.js';
 import { hexSchemaFor } from '../schemas/utils.js';
 import { BufferReader, FieldReader } from '../serialize/index.js';
-import { TypeRegistry } from '../serialize/type_registry.js';
 import { bufferToHex } from '../string/index.js';
 
 /**
@@ -268,6 +267,3 @@ export class EthAddress {
     return addrA.equals(addrB);
   }
 }
-
-// For deserializing JSON.
-TypeRegistry.register('EthAddress', EthAddress);

package/src/fifo/fifo_frame_reader.ts

@@ -0,0 +1,98 @@
+import EventEmitter from 'node:events';
+import * as fs from 'node:fs';
+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, highWaterMark = 64 * 1024): void {
+    this.startFromStream(fs.createReadStream(fifoPath, { highWaterMark }));
+  }
+
+  /** 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/jest/setup.mjs

@@ -10,3 +10,30 @@ import pretty from 'pino-pretty';
 if (!parseBooleanEnv(process.env.LOG_JSON)) {
   overwriteLoggingStream(pretty(pinoPrettyOpts));
 }
+
+// Prevent timers from keeping the process alive after tests complete.
+// Libraries like viem create internal polling loops (via setTimeout) that
+// reschedule themselves indefinitely. In test environments we never want a
+// timer to be the reason the process can't exit. We also unref stdout/stderr
+// which, when they are pipes (as in Jest workers), remain ref'd by default.
+{
+  const origSetTimeout = globalThis.setTimeout;
+  const origSetInterval = globalThis.setInterval;
+  globalThis.setTimeout = function unrefSetTimeout(...args) {
+    const id = origSetTimeout.apply(this, args);
+    id?.unref?.();
+    return id;
+  };
+  // Preserve .unref, .__promisify__ etc. that may exist on the original
+  Object.setPrototypeOf(globalThis.setTimeout, origSetTimeout);
+
+  globalThis.setInterval = function unrefSetInterval(...args) {
+    const id = origSetInterval.apply(this, args);
+    id?.unref?.();
+    return id;
+  };
+  Object.setPrototypeOf(globalThis.setInterval, origSetInterval);
+
+  if (process.stdout?._handle?.unref) process.stdout._handle.unref();
+  if (process.stderr?._handle?.unref) process.stderr._handle.unref();
+}