@aztec/foundation 0.0.1-commit.d6f2b3f94 → 0.0.1-commit.d939eb5aa

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.
@@ -118,14 +115,18 @@ abstract class BaseField {
   }
 
   cmp(rhs: BaseField): -1 | 0 | 1 {
-    const rhsBigInt = rhs.asBigInt;
-    return this.asBigInt === rhsBigInt ? 0 : this.asBigInt < 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.asBigInt === 0n;
   }
@@ -183,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();
+  }
 }
 
 /**
@@ -194,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) {
@@ -208,10 +226,6 @@ export class Fr extends BaseField {
     return `Fr<${this.toString()}>`;
   }
 
-  protected modulus() {
-    return Fr.MODULUS;
-  }
-
   static random() {
     return random(Fr);
   }
@@ -316,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
@@ -341,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);
@@ -466,9 +467,6 @@ export class Fq extends BaseField {
   }
 }
 
-// For deserializing JSON.
-TypeRegistry.register('Fq', Fq);
-
 // Beware: Performance bottleneck below
 
 /**

package/src/curves/grumpkin/point.ts

@@ -65,7 +65,7 @@ export class Point {
   }
 
   /**
-   * Generate a random Point instance.
+   * Generate a random Point instance that is on the curve.
    *
    * @returns A randomly generated Point instance.
    */
@@ -125,9 +125,12 @@ export class Point {
   }
 
   /**
-   * Returns the contents of the point as an array of 2 fields.
-   * @returns The point as an array of 2 fields
+   * Returns the contents of the point as an array of 3 fields.
+   * @returns The point as an array of 3 fields
    */
+  // TODO(F-553): Once we take the breaking change and drop the custom Noir `Point` wrapper in
+  // `noir-projects/noir-protocol-circuits/crates/types/src/point.nr`, revert this to serialize as `[x, y]` (2 fields)
+  // and drop the `is_infinite` flag from `fromFields` / `toNoirStruct` below.
   toFields() {
     return [this.x, this.y, new Fr(this.isInfinite)];
   }

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/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/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();
+}

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

@@ -43,17 +43,18 @@ export async function defaultFetch(
   }
 
   let responseJson;
+  const responseText = await resp.text();
   try {
-    responseJson = await resp.json();
+    responseJson = JSON.parse(responseText);
   } catch {
     if (!resp.ok) {
       throw new Error(resp.statusText);
     }
-    throw new Error(`Failed to parse body as JSON: ${await resp.text()}`);
+    throw new Error(`Failed to parse body as JSON: ${responseText}`);
   }
 
   if (!resp.ok) {
-    const errorMessage = `Error ${resp.status} from server ${host}: ${responseJson.error.message}`;
+    const errorMessage = `Error ${resp.status} from server ${host}: ${responseJson?.error?.message ?? JSON.stringify(responseJson)}`;
     if (noRetry || (resp.status >= 400 && resp.status < 500)) {
       throw new NoRetryError(errorMessage);
     } else {

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

@@ -44,18 +44,20 @@ export function makeUndiciFetch(client = new Agent()): JsonRpcFetch {
     let responseJson: any;
     const responseOk = resp.statusCode >= 200 && resp.statusCode <= 299;
     const contentEncoding = resp.headers['content-encoding'];
+    let responseText: string;
     try {
       if (contentEncoding === 'gzip') {
         const jsonBuffer = await gunzip(await resp.body.arrayBuffer());
-        responseJson = JSON.parse(jsonBuffer.toString('utf-8'));
+        responseText = jsonBuffer.toString('utf-8');
       } else {
-        responseJson = await resp.body.json();
+        responseText = await resp.body.text();
       }
+      responseJson = JSON.parse(responseText);
     } catch {
       if (!responseOk) {
         throw new Error('HTTP ' + resp.statusCode);
       }
-      throw new Error(`Failed to parse body as JSON. encoding: ${contentEncoding}, body: ${await resp.body.text()}`);
+      throw new Error(`Failed to parse body as JSON. encoding: ${contentEncoding}, body: ${responseText!}`);
     }
 
     if (!responseOk) {

package/src/json-rpc/server/api_key_auth.ts

@@ -0,0 +1,63 @@
+import { timingSafeEqual } from 'crypto';
+import type Koa from 'koa';
+
+import { sha256 } from '../../crypto/sha256/index.js';
+import { createLogger } from '../../log/index.js';
+
+const log = createLogger('json-rpc:api-key-auth');
+
+/**
+ * Computes the SHA-256 hash of a string and returns it as a Buffer.
+ * @param input - The input string to hash.
+ * @returns The SHA-256 hash as a Buffer.
+ */
+export function sha256Hash(input: string): Buffer {
+  return sha256(Buffer.from(input));
+}
+
+/**
+ * Creates a Koa middleware that enforces API key authentication on all requests
+ * except the health check endpoint (GET /status).
+ *
+ * The API key can be provided via the `x-api-key` header or the `Authorization: Bearer <key>` header.
+ * Comparison is done by hashing the provided key with SHA-256 and comparing against the stored hash.
+ *
+ * @param apiKeyHash - The SHA-256 hash of the expected API key as a Buffer.
+ * @returns A Koa middleware that rejects requests without a valid API key.
+ */
+export function getApiKeyAuthMiddleware(
+  apiKeyHash: Buffer,
+): (ctx: Koa.Context, next: () => Promise<void>) => Promise<void> {
+  return async (ctx: Koa.Context, next: () => Promise<void>) => {
+    // Allow health check through without auth
+    if (ctx.path === '/status' && ctx.method === 'GET') {
+      return next();
+    }
+
+    const providedKey = ctx.get('x-api-key') || ctx.get('authorization')?.replace(/^Bearer\s+/i, '');
+    if (!providedKey) {
+      log.warn(`Rejected admin RPC request from ${ctx.ip}: missing API key`);
+      ctx.status = 401;
+      ctx.body = {
+        jsonrpc: '2.0',
+        id: null,
+        error: { code: -32000, message: 'Unauthorized: invalid or missing API key' },
+      };
+      return;
+    }
+
+    const providedHashBuf = sha256Hash(providedKey);
+    if (!timingSafeEqual(apiKeyHash, providedHashBuf)) {
+      log.warn(`Rejected admin RPC request from ${ctx.ip}: invalid API key`);
+      ctx.status = 401;
+      ctx.body = {
+        jsonrpc: '2.0',
+        id: null,
+        error: { code: -32000, message: 'Unauthorized: invalid or missing API key' },
+      };
+      return;
+    }
+
+    await next();
+  };
+}

package/src/json-rpc/server/index.ts

@@ -1 +1,2 @@
+export * from './api_key_auth.js';
 export * from './safe_json_rpc_server.js';

package/src/log/bigint-utils.ts

@@ -0,0 +1,25 @@
+/**
+ * Converts bigint values to strings recursively in a log object to avoid serialization issues.
+ */
+export function convertBigintsToStrings(obj: unknown): unknown {
+  if (typeof obj === 'bigint') {
+    return String(obj);
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(item => convertBigintsToStrings(item));
+  }
+
+  if (obj !== null && typeof obj === 'object') {
+    if (typeof (obj as any).toJSON === 'function') {
+      return convertBigintsToStrings((obj as any).toJSON());
+    }
+    const result: Record<string, unknown> = {};
+    for (const key in obj) {
+      result[key] = convertBigintsToStrings((obj as Record<string, unknown>)[key]);
+    }
+    return result;
+  }
+
+  return obj;
+}

package/src/log/gcloud-logger-config.ts

@@ -1,5 +1,7 @@
 import type { pino } from 'pino';
 
+import { convertBigintsToStrings } from './bigint-utils.js';
+
 /* eslint-disable camelcase */
 
 const GOOGLE_CLOUD_TRACE_ID = 'logging.googleapis.com/trace';
@@ -15,6 +17,9 @@ export const GoogleCloudLoggerConfig = {
   messageKey: 'message',
   formatters: {
     log(object: Record<string, unknown>): Record<string, unknown> {
+      // Convert bigints to strings recursively to avoid serialization issues
+      object = convertBigintsToStrings(object) as Record<string, unknown>;
+
       // Add trace context attributes following Cloud Logging structured log format described
       // in https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
       const { trace_id, span_id, trace_flags, ...rest } = object;

package/src/log/pino-logger.ts

@@ -7,6 +7,7 @@ import { inspect } from 'util';
 import { compactArray } from '../collection/array.js';
 import type { EnvVar } from '../config/index.js';
 import { parseBooleanEnv } from '../config/parse-env.js';
+import { convertBigintsToStrings } from './bigint-utils.js';
 import { GoogleCloudLoggerConfig } from './gcloud-logger-config.js';
 import { getLogLevelFromFilters, parseLogLevelEnvVar } from './log-filters.js';
 import type { LogLevel } from './log-levels.js';
@@ -20,6 +21,8 @@ export type LoggerBindings = {
   instanceId?: string;
 };
 
+const MAX_MODULE_NAME_LENGTH = 256;
+
 // Allow global hooks for providing default bindings.
 // Used by withLoggerBindings in pino-logger-server to propagate bindings via AsyncLocalStorage.
 type LogBindingsHandler = () => LoggerBindings | undefined;
@@ -47,7 +50,7 @@ function getBindingsFromHandlers(): LoggerBindings | undefined {
 }
 
 export function createLogger(module: string, bindings?: LoggerBindings): Logger {
-  module = module.replace(/^aztec:/, '');
+  module = module.slice(0, MAX_MODULE_NAME_LENGTH).replace(/^aztec:/, '');
 
   const resolvedBindings = { ...getBindingsFromHandlers(), ...bindings };
   const actor = resolvedBindings?.actor;
@@ -165,6 +168,9 @@ const pinoOpts: pino.LoggerOptions<keyof typeof customLevels> = {
       ...redactedPaths.map(p => `opts.${p}`),
     ],
   },
+  formatters: {
+    log: obj => convertBigintsToStrings(obj) as Record<string, unknown>,
+  },
   ...(useGcloudLogging ? GoogleCloudLoggerConfig : {}),
 };
 
@@ -371,5 +377,20 @@ export type Logger = { [K in LogLevel]: LogFn } & { /** Error log function */ er
  * @returns A string with both the log message and the error message.
  */
 function formatErr(msg: string, err?: unknown): string {
-  return err ? `${msg}: ${inspect(err)}` : msg;
+  if (!err) {
+    return msg;
+  }
+
+  try {
+    return `${msg}: ${inspect(err)}`;
+  } catch {
+    // inspect can crash on error objects with broken property descriptors
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-base-to-string
+      return `${msg}: ${err instanceof Error ? `${err.name}: ${err.message}` : String(err)}`;
+    } catch {
+      // if even String(err) fails, return the original message with a note about the error
+      return `${msg}: [unserializable error]`;
+    }
+  }
 }

package/src/queue/batch_queue.ts

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

package/src/retry/index.ts

@@ -104,6 +104,36 @@ export async function retryUntil<T>(
   }
 }
 
+/**
+ * Retry an asynchronous function until it returns a truthy value or the maximum number of retries is exceeded.
+ * The function is retried periodically with a fixed interval between attempts.
+ *
+ * @param fn - The asynchronous function to be retried, which should return a truthy value upon success or undefined otherwise.
+ * @param name - The optional name of the operation, used for generating error messages.
+ * @param maxRetries - The maximum number of retry attempts before throwing an error.
+ * @param retryInterval - The optional interval, in seconds, between retry attempts. Defaults to 1 second.
+ * @returns A Promise that resolves with the successful (truthy) result of the provided function, or rejects if retries are exhausted.
+ */
+export async function retryTimes<T>(
+  fn: () => (T | undefined) | Promise<T | undefined>,
+  name = '',
+  maxRetries: number,
+  retryInterval = 1,
+) {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const result = await fn();
+    if (result) {
+      return result;
+    }
+
+    if (attempt < maxRetries) {
+      await sleep(retryInterval * 1000);
+    }
+  }
+
+  throw new Error(name ? `Retries exhausted awaiting ${name}` : 'Retries exhausted');
+}
+
 /**
  * Convenience wrapper around retryUntil with fast polling for tests.
  * Uses 10s timeout and 100ms polling interval by default.

package/src/schemas/api.ts

@@ -37,7 +37,10 @@ export type ApiSchema = {
 };
 
 /** Return whether an API schema defines a valid function schema for a given method name. */
-export function schemaHasMethod(schema: ApiSchema, methodName: string) {
+export function schemaHasMethod<T extends ApiSchema>(
+  schema: T,
+  methodName: string,
+): methodName is Extract<keyof T, string> {
   return (
     typeof methodName === 'string' &&
     Object.hasOwn(schema, methodName) &&

package/src/serialize/buffer_reader.ts

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