@aztec/foundation 0.0.1-commit.b655e406 → 0.0.1-commit.b9865e97

package/src/schemas/utils.ts

@@ -1,16 +1,4 @@
-import {
-  OK,
-  type ParseInput,
-  type ParseReturnType,
-  ZodFirstPartyTypeKind,
-  type ZodObject,
-  ZodOptional,
-  ZodParsedType,
-  type ZodRawShape,
-  type ZodType,
-  type ZodTypeAny,
-  z,
-} from 'zod';
+import { type ZodObject, type ZodRawShape, type ZodType, type ZodTypeAny, z } from 'zod';
 
 import { pick } from '../collection/object.js';
 import { isHex, withoutHexPrefix } from '../string/index.js';
@@ -21,32 +9,27 @@ export const hexSchema = z.string().refine(isHex, 'Not a valid hex string').tran
 // Copied from zod internals, which was copied from https://stackoverflow.com/questions/7860392/determine-if-string-is-in-base64-using-javascript
 const base64Regex = /^([0-9a-zA-Z+/]{4})*(([0-9a-zA-Z+/]{2}==)|([0-9a-zA-Z+/]{3}=))?$/;
 
-/** Schema for a buffer represented as a base64 string. */
-export const bufferSchema = z
-  .string()
-  // We only test the str for base64 if it's shorter than 1024 bytes, otherwise we've run into maximum
-  // stack size exceeded errors when trying to validate excessively long strings (such as contract bytecode).
-  .refine(str => str.length > 1024 || base64Regex.test(str), 'Not a valid base64 string')
-  .transform(data => Buffer.from(data, 'base64'));
+/** Schema for a buffer represented as a base64 string or a Buffer object. */
+export const bufferSchema: ZodFor<Buffer> = z.union([
+  // Serialization from base64 string.
+  z
+    .string()
+    // We only test the str for base64 if it's shorter than 1024 bytes, otherwise we've run into maximum
+    // stack size exceeded errors when trying to validate excessively long strings (such as contract bytecode).
+    .refine(str => str.length > 1024 || base64Regex.test(str), 'Not a valid base64 string')
+    .transform(data => Buffer.from(data, 'base64')),
+  // Serialization from Buffer-annotated object.
+  z
+    .object({
+      type: z.literal('Buffer'),
+      data: z.array(z.number().int().min(0).max(255)),
+    })
+    .transform(({ data }) => Buffer.from(data)),
+  // Serialization from Buffer
+  z.instanceof(Buffer),
+]);
 
-export class ZodNullableOptional<T extends ZodTypeAny> extends ZodOptional<T> {
-  _isNullableOptional = true;
-
-  override _parse(input: ParseInput): ParseReturnType<this['_output']> {
-    const parsedType = this._getType(input);
-    if (parsedType === ZodParsedType.undefined || parsedType === ZodParsedType.null) {
-      return OK(undefined);
-    }
-    return this._def.innerType._parse(input);
-  }
-
-  static override create<T extends ZodTypeAny>(type: T): ZodNullableOptional<T> {
-    return new ZodNullableOptional({
-      innerType: type,
-      typeName: ZodFirstPartyTypeKind.ZodOptional,
-    }) as any;
-  }
-}
+export type ZodNullableOptional<T extends ZodTypeAny> = ZodType<z.output<T> | undefined, z.input<T> | null | undefined>;
 
 /**
  * Declares a parameter as optional. Use this over z.optional in order to accept nulls as undefineds.
@@ -54,7 +37,7 @@ export class ZodNullableOptional<T extends ZodTypeAny> extends ZodOptional<T> {
  * need to convert nulls to undefineds as we parse.
  */
 export function optional<T extends ZodTypeAny>(schema: T) {
-  return ZodNullableOptional.create(schema);
+  return schema.nullish().transform(value => value ?? undefined);
 }
 
 type ToJsonIs<T, TRet> = T extends { toJSON(): TRet } ? T : never;
@@ -71,7 +54,6 @@ export function hexSchemaFor<TClass extends { fromString(str: string): any } | {
   TClass extends { fromString(str: string): infer TInstance } | { fromBuffer(buf: Buffer): infer TInstance }
     ? ToJsonIs<TInstance, string>
     : never,
-  any,
   string
 > {
   const stringSchema = refinement ? z.string().refine(refinement, `Not a valid instance`) : z.string();
@@ -88,12 +70,9 @@ export function hexSchemaFor<TClass extends { fromString(str: string): any } | {
  */
 export function bufferSchemaFor<TClass extends { fromBuffer(buf: Buffer): any }>(
   klazz: TClass,
-): ZodType<
-  TClass extends { fromBuffer(buf: Buffer): infer TInstance } ? ToJsonIs<TInstance, Buffer> : never,
-  any,
-  string
-> {
-  return bufferSchema.transform(klazz.fromBuffer.bind(klazz));
+  refinement?: (buf: Buffer) => boolean,
+): ZodType<TClass extends { fromBuffer(buf: Buffer): infer TInstance } ? ToJsonIs<TInstance, Buffer> : never, string> {
+  return bufferSchema.refine(refinement ?? (() => true), 'Not a valid buffer').transform(klazz.fromBuffer.bind(klazz));
 }
 
 /** Creates a schema for a js Map type that matches the serialization used in jsonStringify. */

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();
@@ -224,15 +239,22 @@ export class BufferReader {
    * deserializing each one using the 'fromBuffer' method of 'itemDeserializer'.
    *
    * @param itemDeserializer - Object with 'fromBuffer' method to deserialize vector elements.
+   * @param maxSize - Optional maximum allowed size for the vector. If the size exceeds this, an error is thrown.
    * @returns An array of deserialized elements of type T.
    */
-  public readVector<T>(itemDeserializer: {
-    /**
-     * A method to deserialize data from a buffer.
-     */
-    fromBuffer: (reader: BufferReader) => T;
-  }): T[] {
+  public readVector<T>(
+    itemDeserializer: {
+      /**
+       * A method to deserialize data from a buffer.
+       */
+      fromBuffer: (reader: BufferReader) => T;
+    },
+    maxSize?: number,
+  ): T[] {
     const size = this.readNumber();
+    if (maxSize !== undefined && size > maxSize) {
+      throw new Error(`Vector size ${size} exceeds maximum allowed ${maxSize}`);
+    }
     const result = new Array<T>(size);
     for (let i = 0; i < size; i++) {
       result[i] = itemDeserializer.fromBuffer(this);
@@ -344,10 +366,11 @@ export class BufferReader {
    * The method first reads the size of the string, then reads the corresponding
    * number of bytes from the buffer and converts them to a string.
    *
+   * @param maxSize - Optional maximum allowed size for the string buffer. If the size exceeds this, an error is thrown.
    * @returns The read string from the buffer.
    */
-  public readString(): string {
-    return this.readBuffer().toString();
+  public readString(maxSize?: number): string {
+    return this.readBuffer(maxSize).toString();
   }
 
   /**
@@ -356,10 +379,14 @@ export class BufferReader {
    * a Buffer with that size containing the bytes. Useful for reading variable-length
    * binary data encoded as (size, data) format.
    *
+   * @param maxSize - Optional maximum allowed size for the buffer. If the size exceeds this, an error is thrown.
    * @returns A Buffer containing the read bytes.
    */
-  public readBuffer(): Buffer {
+  public readBuffer(maxSize?: number): Buffer {
     const size = this.readNumber();
+    if (maxSize !== undefined && size > maxSize) {
+      throw new Error(`Buffer size ${size} exceeds maximum allowed ${maxSize}`);
+    }
     this.#rangeCheck(size);
     return this.readBytes(size);
   }

package/src/serialize/buffer_sink.ts

@@ -0,0 +1,350 @@
+/**
+ * A value that can be appended to a {@link BufferSink}. Mirrors `Bufferable`, but the object arm allows the
+ * optional-sink overload of `toBuffer` so a legacy `toBuffer(): Buffer` and a migrated `toBuffer(sink?)` both fit.
+ */
+export type Sinkable =
+  | boolean
+  | Buffer
+  | Uint8Array
+  | number
+  | bigint
+  | string
+  | { toBuffer(sink?: BufferSink): Buffer | void }
+  | Sinkable[];
+
+const DEFAULT_INITIAL_CAPACITY = 1024;
+const MASK_64 = (1n << 64n) - 1n;
+
+/**
+ * A growable, append-only binary sink backed by a single `ArrayBuffer`.
+ *
+ * It exists to replace the recursive `toBuffer()` chain — which allocates a `Buffer` at every node and
+ * `Buffer.concat`s at every level — with one buffer that the whole object graph streams into and that is sliced
+ * exactly once at the root. Encodings are big-endian, matching `serializeToBuffer` byte-for-byte.
+ *
+ * The migration contract is the optional-sink `toBuffer`:
+ *
+ * ```ts
+ * toBuffer(): Buffer;
+ * toBuffer(sink: BufferSink): void;
+ * toBuffer(sink?: BufferSink): Buffer | void {
+ *   if (!sink) return BufferSink.serialize(this); // own a sink, fill it, slice once
+ *   serializeToSink(sink, this.a, this.b, this.c); // stream into the caller's sink
+ * }
+ * ```
+ *
+ * When a sink is passed it writes and returns `undefined`; otherwise it returns its own buffer. Nodes that have
+ * not been migrated keep their plain `toBuffer(): Buffer` and are folded in via the return-value fallback in
+ * {@link serializeToSink}, so the tree stays valid at every step of an incremental migration.
+ *
+ * Performance note: bigints are written via `DataView.setBigUint64` limbs ({@link writeBigInt},
+ * {@link writeField}), NOT a per-byte shift loop. The limb form is ~16x faster than the legacy hex round-trip
+ * on field-heavy structures, and faster than the legacy path at every width — a naive per-byte shift loop is
+ * actually the slowest option, since each byte allocates a fresh BigInt. See the spike benchmark.
+ */
+export class BufferSink {
+  private buffer: Uint8Array;
+  private view: DataView;
+  private offset = 0;
+
+  constructor(initialCapacity: number = DEFAULT_INITIAL_CAPACITY) {
+    const ab = new ArrayBuffer(initialCapacity);
+    this.buffer = new Uint8Array(ab);
+    this.view = new DataView(ab);
+  }
+
+  /** Number of bytes written so far. */
+  public get length(): number {
+    return this.offset;
+  }
+
+  /**
+   * Serialize a migrated value into a fresh sink and return the single resulting buffer. This is the no-sink
+   * branch of every migrated `toBuffer`: one allocation, one slice, only at the root.
+   *
+   * @param obj - The value to serialize via its sink-aware `toBuffer`.
+   * @param initialCapacity - Optional size hint (e.g. from `getSize()`) to skip reallocations on hot paths.
+   */
+  public static serialize(obj: { toBuffer(sink: BufferSink): void }, initialCapacity?: number): Buffer {
+    const sink = new BufferSink(initialCapacity);
+    obj.toBuffer(sink);
+    return sink.toBuffer();
+  }
+
+  private ensure(extra: number): void {
+    const required = this.offset + extra;
+    if (required <= this.buffer.length) {
+      return;
+    }
+    let next = this.buffer.length * 2;
+    while (next < required) {
+      next *= 2;
+    }
+    const grown = new Uint8Array(next);
+    grown.set(this.buffer.subarray(0, this.offset));
+    this.buffer = grown;
+    this.view = new DataView(grown.buffer);
+  }
+
+  /** Append a single byte (0/1) for a boolean, matching `boolToBuffer`. */
+  public writeBool(value: boolean): void {
+    this.ensure(1);
+    this.buffer[this.offset++] = value ? 1 : 0;
+  }
+
+  /** Append an unsigned 8-bit integer. */
+  public writeUInt8(value: number): void {
+    this.ensure(1);
+    this.buffer[this.offset++] = value & 0xff;
+  }
+
+  /** Append a big-endian unsigned 16-bit integer. */
+  public writeUInt16(value: number): void {
+    this.ensure(2);
+    this.view.setUint16(this.offset, value, false);
+    this.offset += 2;
+  }
+
+  /** Append a big-endian unsigned 32-bit integer, matching `numToUInt32BE`. */
+  public writeNumber(value: number): void {
+    this.ensure(4);
+    this.view.setUint32(this.offset, value, false);
+    this.offset += 4;
+  }
+
+  /** Append a big-endian unsigned 64-bit integer, matching `bigintToUInt64BE`. */
+  public writeUInt64(value: bigint): void {
+    this.ensure(8);
+    this.view.setBigUint64(this.offset, value, false);
+    this.offset += 8;
+  }
+
+  /**
+   * Append a non-negative bigint as a big-endian unsigned integer of `width` bytes (default 32), matching
+   * `serializeBigInt` / `toBufferBE`. Every width is written limb-wise via `setBigUint64` rather than the
+   * legacy per-byte BigInt shift loop — that loop allocated a fresh BigInt per byte and benchmarked as the
+   * *slowest* option (slower even than the legacy hex round-trip); the limb form is faster at every width.
+   *
+   * The bulk of the value is written as 64-bit big-endian limbs from the least-significant tail upward, and
+   * a final `width % 8` (at most 7) high bytes that don't fill a whole limb are written individually. The
+   * common widths (8/16/32) are exact multiples of 8, so they take the pure-limb path with no remainder.
+   * `width === 32` keeps its own straight-line four-limb form (shared with {@link writeField}) since it is
+   * the `Fr`/`Fq`/Chonk-proof hot path and the unrolled body is marginally faster than the loop.
+   *
+   * @param value - The non-negative bigint to serialize.
+   * @param width - Output width in bytes.
+   */
+  public writeBigInt(value: bigint, width = 32): void {
+    if (value < 0n) {
+      throw new Error(`Cannot serialize negative bigint ${value}`);
+    }
+    this.ensure(width);
+    const o = this.offset;
+    if (width === 32) {
+      let x = value;
+      this.view.setBigUint64(o + 24, x & MASK_64, false);
+      x >>= 64n;
+      this.view.setBigUint64(o + 16, x & MASK_64, false);
+      x >>= 64n;
+      this.view.setBigUint64(o + 8, x & MASK_64, false);
+      x >>= 64n;
+      this.view.setBigUint64(o, x & MASK_64, false);
+      x >>= 64n;
+      if (x !== 0n) {
+        throw new Error(`BigInt ${value} does not fit into 32 bytes`);
+      }
+      this.offset += 32;
+      return;
+    }
+    let x = value;
+    let pos = o + width;
+    while (pos - 8 >= o) {
+      pos -= 8;
+      this.view.setBigUint64(pos, x & MASK_64, false);
+      x >>= 64n;
+    }
+    for (let i = pos - 1; i >= o; i--) {
+      this.buffer[i] = Number(x & 0xffn);
+      x >>= 8n;
+    }
+    if (x !== 0n) {
+      throw new Error(`BigInt ${value} does not fit into ${width} bytes`);
+    }
+    this.offset += width;
+  }
+
+  /**
+   * Append a 32-byte (256-bit) big-endian non-negative bigint. Specialized form of {@link writeBigInt}
+   * with no width parameter and no width-branch, so V8 can inline the four `setBigUint64` limb writes
+   * without the wider branchy form's instability. This is the Fr/Fq leaf hot path; prefer it over
+   * `writeBigInt(value, 32)` in callers that always serialize 32-byte fields.
+   */
+  public writeField(value: bigint): void {
+    if (value < 0n) {
+      throw new Error(`Cannot serialize negative bigint ${value}`);
+    }
+    this.ensure(32);
+    const o = this.offset;
+    let x = value;
+    this.view.setBigUint64(o + 24, x & MASK_64, false);
+    x >>= 64n;
+    this.view.setBigUint64(o + 16, x & MASK_64, false);
+    x >>= 64n;
+    this.view.setBigUint64(o + 8, x & MASK_64, false);
+    x >>= 64n;
+    this.view.setBigUint64(o, x & MASK_64, false);
+    if (x >> 64n !== 0n) {
+      throw new Error(`BigInt ${value} does not fit into 32 bytes`);
+    }
+    this.offset = o + 32;
+  }
+
+  /**
+   * Append an array of field elements (or any objects exposing `toBigInt(): bigint`) as a contiguous
+   * sequence of 32-byte big-endian limbs. Iterates inline — no per-element `toBuffer` dispatch and no
+   * per-element function-call indirection through the generic sinkable dispatcher. Use this in classes
+   * that hold large flat field arrays (e.g. the 1632-element ChonkProof field list).
+   */
+  public writeFields(fields: ReadonlyArray<{ toBigInt(): bigint }>): void {
+    this.ensure(32 * fields.length);
+    for (let i = 0, n = fields.length; i < n; i++) {
+      const value = fields[i].toBigInt();
+      if (value < 0n) {
+        throw new Error(`Cannot serialize negative bigint ${value}`);
+      }
+      const o = this.offset;
+      let x = value;
+      this.view.setBigUint64(o + 24, x & MASK_64, false);
+      x >>= 64n;
+      this.view.setBigUint64(o + 16, x & MASK_64, false);
+      x >>= 64n;
+      this.view.setBigUint64(o + 8, x & MASK_64, false);
+      x >>= 64n;
+      this.view.setBigUint64(o, x & MASK_64, false);
+      if (x >> 64n !== 0n) {
+        throw new Error(`BigInt ${value} does not fit into 32 bytes`);
+      }
+      this.offset = o + 32;
+    }
+  }
+
+  /** Append raw bytes verbatim (no length prefix), matching how a `Buffer`/`Uint8Array` is serialized inline. */
+  public writeBytes(bytes: Uint8Array): void {
+    this.ensure(bytes.length);
+    this.buffer.set(bytes, this.offset);
+    this.offset += bytes.length;
+  }
+
+  /** Append a string as a 4-byte big-endian length prefix followed by its UTF-8 bytes, matching the string case. */
+  public writeString(value: string): void {
+    const bytes = Buffer.from(value);
+    this.writeNumber(bytes.length);
+    this.writeBytes(bytes);
+  }
+
+  /**
+   * Reset the write cursor without releasing the backing buffer. Lets the same sink be reused across many
+   * serializations without reallocating — the per-call cost drops to the bytes written (no `new ArrayBuffer`).
+   * Any `Buffer` previously returned by {@link toBuffer} is a fresh copy and remains valid; any view from
+   * {@link asUint8Array} aliases the buffer and is invalidated.
+   */
+  public reset(): void {
+    this.offset = 0;
+  }
+
+  /** Copy the written region into a freshly allocated `Buffer`. The single allocation of the whole serialization. */
+  public toBuffer(): Buffer {
+    return Buffer.from(this.buffer.subarray(0, this.offset));
+  }
+
+  /** A zero-copy view of the written region. Valid only until the next write (which may reallocate). */
+  public asUint8Array(): Uint8Array {
+    return this.buffer.subarray(0, this.offset);
+  }
+}
+
+/**
+ * Streaming counterpart to `serializeToBufferArray`: walk a list of {@link Sinkable}s and append each to the sink.
+ * Dispatch matches `serializeToBufferArray` byte-for-byte. An object is serialized via `obj.toBuffer(sink)`; a
+ * migrated node writes into the sink and returns `undefined`, while a not-yet-migrated node ignores the argument
+ * and returns its `Buffer`, which we copy in. That return-value fallback is what makes the migration incremental.
+ *
+ * Dispatch is hot-pathed for the common case of objects exposing `toBuffer` (Fr/Fq and every other migrated leaf),
+ * and arrays recurse via an inner-array helper to avoid the per-call rest-args allocation that a spread-recurse
+ * would force on large flat arrays like the 1632-element ChonkProof field list.
+ *
+ * @param sink - The destination sink.
+ * @param objs - The values to serialize, in order.
+ */
+export function serializeToSink(sink: BufferSink, ...objs: Sinkable[]): void {
+  serializeArrayToSinkInner(sink, objs);
+}
+
+function serializeArrayToSinkInner(sink: BufferSink, objs: Sinkable[]): void {
+  for (let i = 0, n = objs.length; i < n; i++) {
+    serializeOneToSink(sink, objs[i]);
+  }
+}
+
+function serializeOneToSink(sink: BufferSink, obj: Sinkable): void {
+  if (typeof obj === 'object' && obj !== null) {
+    // Hot path: migrated nodes (anything implementing toBuffer, including Fr/Fq via BaseField). This branch
+    // is taken for the vast majority of recursive serialization, so it is checked before the typeof primitives.
+    if ((obj as any).toBuffer !== undefined) {
+      const ret = (obj as { toBuffer(sink: BufferSink): Buffer | void }).toBuffer(sink);
+      if (ret !== undefined) {
+        sink.writeBytes(ret);
+      }
+      return;
+    }
+    if (Array.isArray(obj)) {
+      serializeArrayToSinkInner(sink, obj);
+      return;
+    }
+    if (Buffer.isBuffer(obj) || obj instanceof Uint8Array) {
+      sink.writeBytes(obj);
+      return;
+    }
+    throw new Error(`Cannot serialize input to sink: ${typeof obj} ${(obj as any).constructor?.name}`);
+  }
+  if (typeof obj === 'boolean') {
+    sink.writeBool(obj);
+  } else if (typeof obj === 'bigint') {
+    sink.writeBigInt(obj);
+  } else if (typeof obj === 'number') {
+    sink.writeNumber(obj);
+  } else if (typeof obj === 'string') {
+    sink.writeString(obj);
+  } else {
+    throw new Error(`Cannot serialize input to sink: ${typeof obj}`);
+  }
+}
+
+/**
+ * Streaming counterpart to `serializeArrayOfBufferableToVector`: write a length prefix (1 or 4 bytes) giving the
+ * number of serialized elements, then each element. Byte-identical to the buffer version.
+ *
+ * @param sink - The destination sink.
+ * @param objs - The vector elements.
+ * @param prefixLength - Width of the count prefix in bytes (1 or 4).
+ */
+export function serializeArrayToSink(sink: BufferSink, objs: Sinkable[], prefixLength = 4): void {
+  const count = countSinkables(objs);
+  if (prefixLength === 1) {
+    sink.writeUInt8(count);
+  } else if (prefixLength === 4) {
+    sink.writeNumber(count);
+  } else {
+    throw new Error(`Unsupported prefix length. Got ${prefixLength}, expected 1 or 4`);
+  }
+  serializeArrayToSinkInner(sink, objs);
+}
+
+/** Count how many top-level buffers `serializeToBufferArray` would emit, flattening nested arrays as it does. */
+function countSinkables(objs: Sinkable[]): number {
+  let count = 0;
+  for (const obj of objs) {
+    count += Array.isArray(obj) ? countSinkables(obj) : 1;
+  }
+  return count;
+}

package/src/serialize/field_reader.ts

@@ -1,4 +1,4 @@
-import { Fq, type Fr } from '../fields/fields.js';
+import { Fq, type Fr } from '../curves/bn254/field.js';
 import type { Tuple } from './types.js';
 
 /**

package/src/serialize/free_funcs.ts

@@ -1,5 +1,5 @@
 import { toBufferBE } from '../bigint-buffer/index.js';
-import { Fr } from '../fields/fields.js';
+import { Fr } from '../curves/bn254/field.js';
 import type { Tuple } from './types.js';
 
 /**

package/src/serialize/index.ts

@@ -1,5 +1,6 @@
 export * from './free_funcs.js';
 export * from './buffer_reader.js';
+export * from './buffer_sink.js';
 export * from './field_reader.js';
 export * from './types.js';
 export * from './serialize.js';

package/src/serialize/serialize.ts

@@ -1,5 +1,5 @@
 import { toBigIntBE, toBufferBE } from '../bigint-buffer/index.js';
-import { Fr } from '../fields/fields.js';
+import { Fr } from '../curves/bn254/field.js';
 import { numToUInt32BE } from './free_funcs.js';
 
 /**
@@ -269,6 +269,22 @@ export function serializeBigInt(n: bigint, width = 32) {
   return toBufferBE(n, width);
 }
 
+/**
+ * Serialize a signed BigInt value into a Buffer of specified width using two's complement.
+ * @param n - The signed BigInt value to be serialized.
+ * @param width - The width (in bytes) of the output Buffer, optional with default value 32.
+ * @returns A Buffer containing the serialized signed BigInt value in big-endian format.
+ */
+export function serializeSignedBigInt(n: bigint, width = 32) {
+  const widthBits = BigInt(width * 8);
+  const max = 1n << (widthBits - 1n);
+  if (n < -max || n >= max) {
+    throw new Error(`Signed BigInt ${n.toString()} does not fit into ${width} bytes`);
+  }
+  const unsigned = n < 0n ? (1n << widthBits) + n : n;
+  return toBufferBE(unsigned, width);
+}
+
 /**
  * Deserialize a big integer from a buffer, given an offset and width.
  * Reads the specified number of bytes from the buffer starting at the offset, converts it to a big integer, and returns the deserialized result along with the number of bytes read (advanced).
@@ -282,6 +298,22 @@ export function deserializeBigInt(buf: Buffer, offset = 0, width = 32) {
   return { elem: toBigIntBE(buf.subarray(offset, offset + width)), adv: width };
 }
 
+/**
+ * Deserialize a signed BigInt from a buffer (two's complement).
+ * @param buf - The buffer containing the signed big integer to be deserialized.
+ * @param offset - The position in the buffer where the integer starts. Defaults to 0.
+ * @param width - The number of bytes to read from the buffer for the integer. Defaults to 32.
+ * @returns An object containing the deserialized signed bigint value ('elem') and bytes advanced ('adv').
+ */
+export function deserializeSignedBigInt(buf: Buffer, offset = 0, width = 32) {
+  const { elem, adv } = deserializeBigInt(buf, offset, width);
+  const widthBits = BigInt(width * 8);
+  const signBit = 1n << (widthBits - 1n);
+  const fullRange = 1n << widthBits;
+  const signed = elem >= signBit ? elem - fullRange : elem;
+  return { elem: signed, adv };
+}
+
 /**
  * Serializes a Date object into a Buffer containing its timestamp as a big integer value.
  * The resulting Buffer has a fixed width of 8 bytes, representing a 64-bit big-endian integer.

package/src/sleep/index.ts

@@ -22,6 +22,7 @@ import { InterruptError } from '../error/index.js';
  */
 export class InterruptibleSleep {
   private interrupts: Array<(shouldThrow: boolean) => void> = [];
+  private timeoutIds: NodeJS.Timeout[] = [];
 
   /**
    * Sleep for a specified amount of time in milliseconds.
@@ -38,9 +39,15 @@ export class InterruptibleSleep {
       this.interrupts.push(resolve);
     });
 
-    const timeoutPromise = new Promise<boolean>(resolve => setTimeout(() => resolve(false), ms));
+    let timeoutId: NodeJS.Timeout;
+    const timeoutPromise = new Promise<boolean>(resolve => {
+      timeoutId = setTimeout(() => resolve(false), ms);
+      this.timeoutIds.push(timeoutId);
+    });
     const shouldThrow = await Promise.race([interruptPromise, timeoutPromise]);
 
+    clearTimeout(timeoutId!);
+    this.timeoutIds = this.timeoutIds.filter(id => id !== timeoutId);
     this.interrupts = this.interrupts.filter(res => res !== interruptResolve);
 
     if (shouldThrow) {
@@ -58,6 +65,8 @@ export class InterruptibleSleep {
   public interrupt(sleepShouldThrow = false): void {
     this.interrupts.forEach(resolve => resolve(sleepShouldThrow));
     this.interrupts = [];
+    this.timeoutIds.forEach(id => clearTimeout(id));
+    this.timeoutIds = [];
   }
 }
 
@@ -73,3 +82,9 @@ export class InterruptibleSleep {
 export function sleep<T>(ms: number, returnValue?: T): Promise<T> {
   return new Promise(resolve => setTimeout(() => resolve(returnValue as T), ms));
 }
+
+/** Sleeps until the target date */
+export function sleepUntil<T>(target: Date, now: Date, returnValue?: T): Promise<T> {
+  const ms = target.getTime() - now.getTime();
+  return sleep(ms, returnValue);
+}

package/src/string/index.ts

@@ -58,7 +58,7 @@ export function urlJoin(...args: string[]): string {
       end--;
     }
 
-    if (start < end) {
+    if (start <= end) {
       processed.push(arg.slice(start, end + 1));
     }
   }

package/src/testing/files/index.ts

@@ -63,7 +63,7 @@ export function updateProtocolCircuitSampleInputs(circuitName: string, value: st
   logger(`Updated test data in ${targetFile} for ${circuitName}`);
 }
 
-function getPathToFile(targetFileFromRepoRoot: string) {
+export function getPathToFile(targetFileFromRepoRoot: string) {
   const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../../../../');
   if (!existsSync(join(repoRoot, 'CODEOWNERS'))) {
     throw new Error(`Path to repo root is incorrect (got ${repoRoot})`);