@aztec/foundation 0.0.1-commit.9b94fc1 → 0.0.1-commit.9ee6fcc6

package/src/{fields/fields.ts → curves/bn254/field.ts}

@@ -2,13 +2,11 @@ import { BarretenbergSync } from '@aztec/bb.js';
 
 import { inspect } from 'util';
 
-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';
-
-const ZERO_BUFFER = Buffer.alloc(32);
+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 */
 
@@ -25,14 +23,12 @@ type DerivedField<T extends BaseField> = {
 
 /**
  * Base field class.
- * Conversions from Buffer to BigInt and vice-versa are not cheap.
- * We allow construction with either form and lazily convert to other as needed.
- * We only check we are within the field modulus when initializing with bigint.
+ * Uses bigint as the internal representation.
+ * Buffers are generated on demand from the bigint value.
  */
 abstract class BaseField {
   static SIZE_IN_BYTES = 32;
-  private asBuffer?: Buffer;
-  private asBigInt?: bigint;
+  private readonly asBigInt: bigint;
 
   /**
    * Return bigint representation.
@@ -52,53 +48,41 @@ abstract class BaseField {
       if (value.length > BaseField.SIZE_IN_BYTES) {
         throw new Error(`Value length ${value.length} exceeds ${BaseField.SIZE_IN_BYTES}`);
       }
-      this.asBuffer =
-        value.length === BaseField.SIZE_IN_BYTES
-          ? value
-          : Buffer.concat([Buffer.alloc(BaseField.SIZE_IN_BYTES - value.length), value]);
+      this.asBigInt = toBigIntBE(value);
     } else if (typeof value === 'bigint' || typeof value === 'number' || typeof value === 'boolean') {
       this.asBigInt = BigInt(value);
-      if (this.asBigInt >= this.modulus()) {
-        throw new Error(`Value 0x${this.asBigInt.toString(16)} is greater or equal to field modulus.`);
-      } else if (this.asBigInt < 0n) {
-        throw new Error(`Value 0x${this.asBigInt.toString(16)} is negative.`);
-      }
     } else if (value instanceof BaseField) {
-      this.asBuffer = value.asBuffer;
       this.asBigInt = value.asBigInt;
     } else {
       throw new Error(`Type '${typeof value}' with value '${value}' passed to BaseField ctor.`);
     }
+
+    if (this.asBigInt < 0n) {
+      throw new Error(`Value 0x${this.asBigInt.toString(16)} is negative.`);
+    } else if (this.asBigInt >= this.modulus()) {
+      throw new Error(`Value 0x${this.asBigInt.toString(16)} is greater or equal to field modulus.`);
+    }
   }
 
   protected abstract modulus(): bigint;
 
   /**
-   * We return a copy of the Buffer to ensure this remains immutable.
+   * Converts the bigint to a Buffer.
    */
   toBuffer(): Buffer {
-    if (!this.asBuffer) {
-      this.asBuffer = toBufferBE(this.asBigInt!, 32);
-    }
-    return Buffer.from(this.asBuffer);
+    return toBufferBE(this.asBigInt, 32);
   }
 
   toString(): `0x${string}` {
-    return `0x${this.toBuffer().toString('hex')}`;
+    return `0x${this.asBigInt.toString(16).padStart(64, '0')}`;
   }
 
   toBigInt(): bigint {
-    if (this.asBigInt === undefined) {
-      this.asBigInt = toBigIntBE(this.asBuffer!);
-      if (this.asBigInt >= this.modulus()) {
-        throw new Error(`Value 0x${this.asBigInt.toString(16)} is greater or equal to field modulus.`);
-      }
-    }
     return this.asBigInt;
   }
 
   toBool(): boolean {
-    return Boolean(this.toBigInt());
+    return this.asBigInt !== 0n;
   }
 
   /**
@@ -106,11 +90,10 @@ abstract class BaseField {
    * Throws if the underlying value is greater than MAX_SAFE_INTEGER.
    */
   toNumber(): number {
-    const value = this.toBigInt();
-    if (value > Number.MAX_SAFE_INTEGER) {
-      throw new Error(`Value ${value.toString(16)} greater than than max safe integer`);
+    if (this.asBigInt > Number.MAX_SAFE_INTEGER) {
+      throw new Error(`Value ${this.asBigInt.toString(16)} greater than than max safe integer`);
     }
-    return Number(value);
+    return Number(this.asBigInt);
   }
 
   /**
@@ -118,8 +101,7 @@ abstract class BaseField {
    * May cause loss of precision if the underlying value is greater than MAX_SAFE_INTEGER.
    */
   toNumberUnsafe(): number {
-    const value = this.toBigInt();
-    return Number(value);
+    return Number(this.asBigInt);
   }
 
   toShortString(): string {
@@ -128,21 +110,28 @@ abstract class BaseField {
   }
 
   equals(rhs: BaseField): boolean {
-    return this.toBuffer().equals(rhs.toBuffer());
+    return this.asBigInt === rhs.asBigInt;
   }
 
   lt(rhs: BaseField): boolean {
-    return this.toBigInt() < rhs.toBigInt();
+    return this.asBigInt < rhs.asBigInt;
   }
 
   cmp(rhs: BaseField): -1 | 0 | 1 {
-    const lhsBigInt = this.toBigInt();
-    const rhsBigInt = rhs.toBigInt();
-    return lhsBigInt === rhsBigInt ? 0 : lhsBigInt < rhsBigInt ? -1 : 1;
+    return BaseField.cmpAsBigInt(this.asBigInt, rhs.asBigInt);
+  }
+
+  static cmp(lhs: BaseField, rhs: BaseField): -1 | 0 | 1 {
+    return lhs.cmp(rhs);
+  }
+
+  // Actual bigint comparison. Arguments must have been validated previously.
+  static cmpAsBigInt(lhs: bigint, rhs: bigint): -1 | 0 | 1 {
+    return lhs === rhs ? 0 : lhs < rhs ? -1 : 1;
   }
 
   isZero(): boolean {
-    return this.toBuffer().equals(ZERO_BUFFER);
+    return this.asBigInt === 0n;
   }
 
   isEmpty(): boolean {
@@ -195,7 +184,7 @@ function fromHexString<T extends BaseField>(buf: string, f: DerivedField<T>) {
 
   const buffer = Buffer.from(checked.length % 2 === 1 ? '0' + checked : checked, 'hex');
 
-  return new f(buffer);
+  return new f(toBigIntBE(buffer));
 }
 
 /** Branding to ensure fields are not interchangeable types. */
@@ -511,14 +500,6 @@ function extendedEuclidean(a: bigint, modulus: bigint): [bigint, bigint, bigint]
   }
 }
 
-/**
- * GrumpkinScalar is an Fq.
- * @remarks Called GrumpkinScalar because it is used to represent elements in Grumpkin's scalar field as defined in
- *          the Aztec Protocol Specs.
- */
-export type GrumpkinScalar = Fq;
-export const GrumpkinScalar = Fq;
-
 /** Wraps a function that returns a buffer so that all results are reduced into a field of the given type. */
 export function reduceFn<TInput, TField extends BaseField>(fn: (input: TInput) => Buffer, field: DerivedField<TField>) {
   return (input: TInput) => fromBufferReduce(fn(input), field);

package/src/curves/bn254/index.ts

@@ -0,0 +1,2 @@
+export * from './field.js';
+export * from './point.js';

package/src/curves/bn254/point.ts

@@ -0,0 +1,170 @@
+import {
+  BN254_G1_GENERATOR,
+  BN254_G2_GENERATOR,
+  BarretenbergSync,
+  type Bn254G1Point as BbApiBn254G1Point,
+  type Bn254G2Point as BbApiBn254G2Point,
+} from '@aztec/bb.js';
+
+import { Fq, Fr } from './field.js';
+
+/**
+ * BN254 G1 point using foundation field classes.
+ * Represents a point on the BN254 elliptic curve in affine coordinates.
+ */
+export class Bn254G1Point {
+  constructor(
+    public readonly x: Fq,
+    public readonly y: Fq,
+  ) {}
+
+  private toBbApiPoint(): BbApiBn254G1Point {
+    return {
+      x: this.x.toBuffer(),
+      y: this.y.toBuffer(),
+    };
+  }
+
+  private static fromBbApiPoint(point: BbApiBn254G1Point): Bn254G1Point {
+    return new Bn254G1Point(Fq.fromBuffer(Buffer.from(point.x)), Fq.fromBuffer(Buffer.from(point.y)));
+  }
+
+  async isOnCurve(): Promise<boolean> {
+    await BarretenbergSync.initSingleton();
+    const api = BarretenbergSync.getSingleton();
+
+    const apiPoint = this.toBbApiPoint();
+    const response = api.bn254G1IsOnCurve({ point: apiPoint });
+    return response.isOnCurve;
+  }
+
+  /**
+   * Get the generator point for BN254 G1, or perform scalar multiplication.
+   * When called without arguments, returns the base generator point.
+   * When called with a scalar, returns scalar * generator (useful for public key derivation).
+   */
+  static async generator(scalar?: Fr): Promise<Bn254G1Point> {
+    if (!scalar) {
+      return new Bn254G1Point(
+        Fq.fromBuffer(Buffer.from(BN254_G1_GENERATOR.x)),
+        Fq.fromBuffer(Buffer.from(BN254_G1_GENERATOR.y)),
+      );
+    }
+
+    await BarretenbergSync.initSingleton();
+    const api = BarretenbergSync.getSingleton();
+
+    const response = api.bn254G1Mul({
+      point: BN254_G1_GENERATOR,
+      scalar: scalar.toBuffer(),
+    });
+
+    return Bn254G1Point.fromBbApiPoint(response.point);
+  }
+
+  /**
+   * Decompress a BN254 G1 point from compressed form (32 bytes).
+   * The compressed format encodes the x-coordinate and the sign bit of the y-coordinate
+   * in the most significant bit.
+   */
+  static async fromCompressed(compressed: Buffer): Promise<Bn254G1Point> {
+    if (compressed.length !== 32) {
+      throw new Error('Invalid compressed point length');
+    }
+    await BarretenbergSync.initSingleton();
+    const api = BarretenbergSync.getSingleton();
+
+    const response = api.bn254G1FromCompressed({
+      compressed: new Uint8Array(compressed),
+    });
+
+    return Bn254G1Point.fromBbApiPoint(response.point);
+  }
+
+  /**
+   * Compress this BN254 G1 point to 32 bytes.
+   * The compressed format encodes the x-coordinate and the sign bit of the y-coordinate
+   * in the most significant bit (bit 255).
+   */
+  compress(): Buffer {
+    const xBytes = this.x.toBuffer();
+    // Get the least significant bit of y to determine the sign
+    const yLsb = this.y.toBigInt() & 1n;
+    // If y is odd, set the most significant bit (bit 255) of the output
+    if (yLsb === 1n) {
+      xBytes[0] |= 0x80;
+    }
+    return xBytes;
+  }
+
+  equals(other: Bn254G1Point): boolean {
+    return this.x.equals(other.x) && this.y.equals(other.y);
+  }
+
+  toString(): string {
+    return `Bn254G1Point(x: ${this.x.toString()}, y: ${this.y.toString()})`;
+  }
+}
+
+/**
+ * BN254 G2 point using foundation field classes.
+ * Represents a point on the BN254 G2 curve (twist curve) in affine coordinates.
+ * G2 points use extension field coordinates (Fq2).
+ */
+export class Bn254G2Point {
+  constructor(
+    public readonly x: [Fq, Fq],
+    public readonly y: [Fq, Fq],
+  ) {}
+
+  private toBbApiPoint(): BbApiBn254G2Point {
+    return {
+      x: [this.x[0].toBuffer(), this.x[1].toBuffer()],
+      y: [this.y[0].toBuffer(), this.y[1].toBuffer()],
+    };
+  }
+
+  private static fromBbApiPoint(point: BbApiBn254G2Point): Bn254G2Point {
+    return new Bn254G2Point(
+      [Fq.fromBuffer(Buffer.from(point.x[0])), Fq.fromBuffer(Buffer.from(point.x[1]))],
+      [Fq.fromBuffer(Buffer.from(point.y[0])), Fq.fromBuffer(Buffer.from(point.y[1]))],
+    );
+  }
+
+  /**
+   * Get the generator point for BN254 G2, or perform scalar multiplication.
+   * When called without arguments, returns the base generator point.
+   * When called with a scalar, returns scalar * generator.
+   */
+  static async generator(scalar?: Fr): Promise<Bn254G2Point> {
+    if (!scalar) {
+      return new Bn254G2Point(
+        [Fq.fromBuffer(Buffer.from(BN254_G2_GENERATOR.x[0])), Fq.fromBuffer(Buffer.from(BN254_G2_GENERATOR.x[1]))],
+        [Fq.fromBuffer(Buffer.from(BN254_G2_GENERATOR.y[0])), Fq.fromBuffer(Buffer.from(BN254_G2_GENERATOR.y[1]))],
+      );
+    }
+
+    await BarretenbergSync.initSingleton();
+    const api = BarretenbergSync.getSingleton();
+
+    const response = api.bn254G2Mul({
+      point: BN254_G2_GENERATOR as BbApiBn254G2Point,
+      scalar: scalar.toBuffer(),
+    });
+
+    return Bn254G2Point.fromBbApiPoint(response.point);
+  }
+
+  equals(other: Bn254G2Point): boolean {
+    return (
+      this.x[0].equals(other.x[0]) &&
+      this.x[1].equals(other.x[1]) &&
+      this.y[0].equals(other.y[0]) &&
+      this.y[1].equals(other.y[1])
+    );
+  }
+
+  toString(): string {
+    return `Bn254G2Point(x: (${this.x[0].toString()}, ${this.x[1].toString()}), y: (${this.y[0].toString()}, ${this.y[1].toString()}))`;
+  }
+}

package/src/curves/grumpkin/index.ts

@@ -0,0 +1,11 @@
+import { Fq } from '../bn254/field.js';
+
+export * from './point.js';
+
+/**
+ * GrumpkinScalar is an Fq.
+ * @remarks Called GrumpkinScalar because it is used to represent elements in Grumpkin's scalar field as defined in
+ *          the Aztec Protocol Specs.
+ */
+export type GrumpkinScalar = Fq;
+export const GrumpkinScalar = Fq;

package/src/{fields → curves/grumpkin}/point.ts

@@ -1,10 +1,10 @@
-import { toBigIntBE } from '../bigint-buffer/index.js';
-import { poseidon2Hash } from '../crypto/poseidon/index.js';
-import { randomBoolean } from '../crypto/random/index.js';
-import { hexSchemaFor } from '../schemas/utils.js';
-import { BufferReader, FieldReader, serializeToBuffer } from '../serialize/index.js';
-import { bufferToHex, hexToBuffer } from '../string/index.js';
-import { Fr } from './fields.js';
+import { toBigIntBE } from '../../bigint-buffer/index.js';
+import { poseidon2Hash } from '../../crypto/poseidon/index.js';
+import { randomBoolean } from '../../crypto/random/index.js';
+import { hexSchemaFor } from '../../schemas/utils.js';
+import { BufferReader, FieldReader, serializeToBuffer } from '../../serialize/index.js';
+import { bufferToHex, hexToBuffer } from '../../string/index.js';
+import { Fr } from '../bn254/field.js';
 
 /**
  * Represents a Point on an elliptic curve with x and y coordinates.

package/src/eth-address/index.ts

@@ -2,7 +2,7 @@ import { inspect } from 'util';
 
 import { keccak256String } from '../crypto/keccak/index.js';
 import { randomBytes } from '../crypto/random/index.js';
-import { Fr } from '../fields/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';
@@ -249,7 +249,7 @@ export class EthAddress {
   /** Converts a number into an address. Useful for testing. */
   static fromNumber(num: bigint | number): EthAddress {
     const buffer = Buffer.alloc(EthAddress.SIZE_IN_BYTES);
-    buffer.writeBigUInt64BE(BigInt(num), 0);
+    buffer.writeBigUInt64BE(BigInt(num), EthAddress.SIZE_IN_BYTES - 8);
     return new EthAddress(buffer);
   }
 
@@ -261,6 +261,12 @@ export class EthAddress {
     // Serialization from hex string.
     return hexSchemaFor(EthAddress, EthAddress.isAddress);
   }
+
+  static areEqual(a: EthAddress | string, b: EthAddress | string) {
+    const addrA = typeof a === 'string' ? EthAddress.fromString(a) : a;
+    const addrB = typeof b === 'string' ? EthAddress.fromString(b) : b;
+    return addrA.equals(addrB);
+  }
 }
 
 // For deserializing JSON.

package/src/eth-signature/eth_signature.ts

@@ -1,8 +1,10 @@
 import { Buffer32 } from '@aztec/foundation/buffer';
 import { BufferReader, serializeToBuffer } from '@aztec/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';
 
 /**
@@ -77,8 +79,12 @@ export class 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 {
-    return new Signature(Buffer32.random(), Buffer32.random(), 1);
+    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 {

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/iterator/filter.ts

@@ -0,0 +1,11 @@
+/** Wraps an async iterable iterator such that it filters values based on a predicate. */
+export async function* filter<T>(
+  iterator: AsyncIterableIterator<T>,
+  predicate: (item: T) => boolean | Promise<boolean>,
+): AsyncIterableIterator<T> {
+  for await (const item of iterator) {
+    if (await predicate(item)) {
+      yield item;
+    }
+  }
+}

package/src/iterator/index.ts

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

package/src/jest/setup.mjs

@@ -1,3 +1,4 @@
+import { parseBooleanEnv } from '@aztec/foundation/config';
 import { overwriteLoggingStream, pinoPrettyOpts } from '@aztec/foundation/log';
 
 import pretty from 'pino-pretty';
@@ -6,4 +7,33 @@ import pretty from 'pino-pretty';
 // file so we don't mess up with dependencies in non-testing environments,
 // since pino-pretty messes up with browser bundles.
 // See also https://www.npmjs.com/package/pino-pretty?activeTab=readme#user-content-usage-with-jest
-overwriteLoggingStream(pretty(pinoPrettyOpts));
+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();
+}

package/src/json-rpc/client/safe_json_rpc_client.ts

@@ -24,6 +24,7 @@ export type SafeJsonRpcClientOptions = {
   batchWindowMS?: number;
   maxBatchSize?: number;
   maxRequestBodySize?: number;
+  extraHeaders?: Record<string, string>;
   onResponse?: (res: {
     response: any;
     headers: { get: (header: string) => string | null | undefined };
@@ -129,6 +130,7 @@ export function createSafeJsonRpcClient<T extends object>(
       const { response, headers } = await fetch(
         host,
         rpcCalls.map(({ request }) => request),
+        config.extraHeaders,
       );
 
       if (config.onResponse) {

package/src/json-rpc/client/undici.ts

@@ -1,3 +1,5 @@
+import { promisify } from 'node:util';
+import { gunzip as gunzipCb, gzip as gzipCb } from 'node:zlib';
 import { Agent, type Dispatcher } from 'undici';
 
 import { createLogger } from '../../log/pino-logger.js';
@@ -5,8 +7,14 @@ import { NoRetryError } from '../../retry/index.js';
 import { jsonStringify } from '../convert.js';
 import type { JsonRpcFetch } from './fetch.js';
 
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
+
 const log = createLogger('json-rpc:json_rpc_client:undici');
 
+/** Minimum request size in bytes to trigger compression. */
+const COMPRESSION_THRESHOLD = 1024;
+
 export { Agent };
 
 export function makeUndiciFetch(client = new Agent()): JsonRpcFetch {
@@ -14,14 +22,18 @@ export function makeUndiciFetch(client = new Agent()): JsonRpcFetch {
     log.trace(`JsonRpcClient.fetch: ${host}`, { host, body });
     let resp: Dispatcher.ResponseData;
     try {
+      const jsonBody = Buffer.from(jsonStringify(body));
+      const shouldCompress = jsonBody.length >= COMPRESSION_THRESHOLD;
       resp = await client.request({
         method: 'POST',
         origin: new URL(host),
         path: '/',
-        body: jsonStringify(body),
+        body: shouldCompress ? await gzip(jsonBody) : jsonBody,
         headers: {
           ...extraHeaders,
           'content-type': 'application/json',
+          ...(shouldCompress && { 'content-encoding': 'gzip' }),
+          'accept-encoding': 'gzip',
         },
       });
     } catch (err) {
@@ -31,13 +43,19 @@ export function makeUndiciFetch(client = new Agent()): JsonRpcFetch {
 
     let responseJson: any;
     const responseOk = resp.statusCode >= 200 && resp.statusCode <= 299;
+    const contentEncoding = resp.headers['content-encoding'];
     try {
-      responseJson = await resp.body.json();
+      if (contentEncoding === 'gzip') {
+        const jsonBuffer = await gunzip(await resp.body.arrayBuffer());
+        responseJson = JSON.parse(jsonBuffer.toString('utf-8'));
+      } else {
+        responseJson = await resp.body.json();
+      }
     } catch {
       if (!responseOk) {
         throw new Error('HTTP ' + resp.statusCode);
       }
-      throw new Error(`Failed to parse body as JSON: ${await resp.body.text()}`);
+      throw new Error(`Failed to parse body as JSON. encoding: ${contentEncoding}, body: ${await resp.body.text()}`);
     }
 
     if (!responseOk) {