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

package/src/config/env_var.ts

@@ -12,6 +12,9 @@ export type EnvVar =
   | 'ARCHIVER_VIEM_POLLING_INTERVAL_MS'
   | 'ARCHIVER_BATCH_SIZE'
   | 'AZTEC_ADMIN_PORT'
+  | 'AZTEC_ADMIN_API_KEY_HASH'
+  | 'AZTEC_DISABLE_ADMIN_API_KEY'
+  | 'AZTEC_RESET_ADMIN_API_KEY'
   | 'AZTEC_NODE_ADMIN_URL'
   | 'AZTEC_NODE_URL'
   | 'AZTEC_PORT'
@@ -47,7 +50,10 @@ export type EnvVar =
   | 'BOT_TX_MINED_WAIT_SECONDS'
   | 'BOT_MAX_CONSECUTIVE_ERRORS'
   | 'BOT_STOP_WHEN_UNHEALTHY'
-  | 'BOT_AMM_TXS'
+  | 'BOT_MODE'
+  | 'BOT_L2_TO_L1_MESSAGES_PER_TX'
+  | 'BOT_L1_TO_L2_SEED_COUNT'
+  | 'BOT_L1_TO_L2_SEED_INTERVAL'
   | 'COINBASE'
   | 'CRS_PATH'
   | 'DATA_DIRECTORY'
@@ -64,6 +70,7 @@ export type EnvVar =
   | 'PUBLIC_DATA_TREE_MAP_SIZE_KB'
   | 'DEBUG'
   | 'DEBUG_P2P_DISABLE_COLOCATION_PENALTY'
+  | 'ENABLE_PROVER_NODE'
   | 'ETHEREUM_HOSTS'
   | 'ETHEREUM_DEBUG_HOSTS'
   | 'ETHEREUM_ALLOW_NO_DEBUG_HOSTS'
@@ -75,6 +82,7 @@ export type EnvVar =
   | 'L1_CONSENSUS_HOST_URLS'
   | 'L1_CONSENSUS_HOST_API_KEYS'
   | 'L1_CONSENSUS_HOST_API_KEY_HEADERS'
+  | 'L1_TX_FAILED_STORE'
   | 'LOG_JSON'
   | 'LOG_MULTILINE'
   | 'LOG_NO_COLOR_PER_ACTOR'
@@ -141,9 +149,9 @@ export type EnvVar =
   | 'P2P_PREFERRED_PEERS'
   | 'P2P_MAX_PENDING_TX_COUNT'
   | 'P2P_SEEN_MSG_CACHE_SIZE'
-  | 'P2P_DROP_TX'
   | 'P2P_DROP_TX_CHANCE'
   | 'P2P_TX_POOL_DELETE_TXS_AFTER_REORG'
+  | 'P2P_MIN_TX_POOL_AGE_MS'
   | 'DEBUG_P2P_INSTRUMENT_MESSAGES'
   | 'PEER_ID_PRIVATE_KEY'
   | 'PEER_ID_PRIVATE_KEY_PATH'
@@ -208,9 +216,11 @@ export type EnvVar =
   | 'SEQ_L1_PUBLISHING_TIME_ALLOWANCE_IN_SLOT'
   | 'SEQ_ATTESTATION_PROPAGATION_TIME'
   | 'SEQ_BLOCK_DURATION_MS'
+  | 'SEQ_EXPECTED_BLOCK_PROPOSALS_PER_SLOT'
   | 'SEQ_BUILD_CHECKPOINT_IF_EMPTY'
   | 'SEQ_SECONDS_BEFORE_INVALIDATING_BLOCK_AS_COMMITTEE_MEMBER'
   | 'SEQ_SECONDS_BEFORE_INVALIDATING_BLOCK_AS_NON_COMMITTEE_MEMBER'
+  | 'SEQ_SKIP_CHECKPOINT_PUBLISH_PERCENT'
   | 'SLASH_MIN_PENALTY_PERCENTAGE'
   | 'SLASH_MAX_PENALTY_PERCENTAGE'
   | 'SLASH_VALIDATORS_ALWAYS'
@@ -237,6 +247,7 @@ export type EnvVar =
   | 'TELEMETRY'
   | 'TEST_ACCOUNTS'
   | 'SPONSORED_FPC'
+  | 'PREFUND_ADDRESSES'
   | 'TX_COLLECTION_FAST_NODES_TIMEOUT_BEFORE_REQ_RESP_MS'
   | 'TX_COLLECTION_SLOW_NODES_INTERVAL_MS'
   | 'TX_COLLECTION_SLOW_REQ_RESP_INTERVAL_MS'
@@ -251,6 +262,12 @@ export type EnvVar =
   | 'TX_COLLECTION_FILE_STORE_URLS'
   | 'TX_COLLECTION_FILE_STORE_SLOW_DELAY_MS'
   | 'TX_COLLECTION_FILE_STORE_FAST_DELAY_MS'
+  | 'TX_COLLECTION_FILE_STORE_FAST_WORKER_COUNT'
+  | 'TX_COLLECTION_FILE_STORE_SLOW_WORKER_COUNT'
+  | 'TX_COLLECTION_FILE_STORE_FAST_BACKOFF_BASE_MS'
+  | 'TX_COLLECTION_FILE_STORE_SLOW_BACKOFF_BASE_MS'
+  | 'TX_COLLECTION_FILE_STORE_FAST_BACKOFF_MAX_MS'
+  | 'TX_COLLECTION_FILE_STORE_SLOW_BACKOFF_MAX_MS'
   | 'TX_FILE_STORE_URL'
   | 'TX_FILE_STORE_UPLOAD_CONCURRENCY'
   | 'TX_FILE_STORE_MAX_QUEUE_SIZE'
@@ -269,6 +286,7 @@ export type EnvVar =
   | 'WS_BLOCK_REQUEST_BATCH_SIZE'
   | 'L1_READER_VIEM_POLLING_INTERVAL_MS'
   | 'WS_DATA_DIRECTORY'
+  | 'WS_NUM_HISTORIC_CHECKPOINTS'
   | 'WS_NUM_HISTORIC_BLOCKS'
   | 'ETHEREUM_SLOT_DURATION'
   | 'AZTEC_SLOT_DURATION'

package/src/config/index.ts

@@ -177,6 +177,21 @@ export function bigintConfigHelper(defaultVal?: bigint): Pick<ConfigMapping, 'pa
       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)) {
+        const match = val.match(/^(-?\d+(?:\.(\d+))?)[eE]([+-]?\d+)$/);
+        if (!match) {
+          throw new Error(`Cannot convert '${val}' to a BigInt`);
+        }
+        const digits = match[1].replace('.', '');
+        const decimalPlaces = match[2]?.length ?? 0;
+        const exponent = parseInt(match[3], 10) - decimalPlaces;
+        if (exponent < 0) {
+          throw new Error(`Cannot convert '${val}' to a BigInt: result is not an integer`);
+        }
+        return BigInt(digits) * 10n ** BigInt(exponent);
+      }
       return BigInt(val);
     },
     defaultValue: defaultVal,

package/src/config/network_config.ts

@@ -9,6 +9,7 @@ export const NetworkConfigSchema = z
     feeAssetHandlerAddress: z.string().optional(),
     l1ChainId: z.number(),
     blockDurationMs: z.number().positive().optional(),
+    txPublicSetupAllowListExtend: 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/poseidon/index.ts

@@ -1,4 +1,4 @@
-import { BarretenbergSync } from '@aztec/bb.js';
+import { Barretenberg } from '@aztec/bb.js';
 
 import { Fr } from '../../curves/bn254/field.js';
 import { type Fieldable, serializeToFields } from '../../serialize/serialize.js';
@@ -10,9 +10,9 @@ import { type Fieldable, serializeToFields } from '../../serialize/serialize.js'
  */
 export async function poseidon2Hash(input: Fieldable[]): Promise<Fr> {
   const inputFields = serializeToFields(input);
-  await BarretenbergSync.initSingleton();
-  const api = BarretenbergSync.getSingleton();
-  const response = api.poseidon2Hash({
+  await Barretenberg.initSingleton();
+  const api = Barretenberg.getSingleton();
+  const response = await api.poseidon2Hash({
     inputs: inputFields.map(i => i.toBuffer()),
   });
   return Fr.fromBuffer(Buffer.from(response.hash));
@@ -27,9 +27,9 @@ export async function poseidon2Hash(input: Fieldable[]): Promise<Fr> {
 export async function poseidon2HashWithSeparator(input: Fieldable[], separator: number): Promise<Fr> {
   const inputFields = serializeToFields(input);
   inputFields.unshift(new Fr(separator));
-  await BarretenbergSync.initSingleton();
-  const api = BarretenbergSync.getSingleton();
-  const response = api.poseidon2Hash({
+  await Barretenberg.initSingleton();
+  const api = Barretenberg.getSingleton();
+  const response = await api.poseidon2Hash({
     inputs: inputFields.map(i => i.toBuffer()),
   });
   return Fr.fromBuffer(Buffer.from(response.hash));
@@ -44,9 +44,9 @@ export async function poseidon2Permutation(input: Fieldable[]): Promise<Fr[]> {
   const inputFields = serializeToFields(input);
   // We'd like this assertion but it's not possible to use it in the browser.
   // assert(input.length === 4, 'Input state must be of size 4');
-  await BarretenbergSync.initSingleton();
-  const api = BarretenbergSync.getSingleton();
-  const response = api.poseidon2Permutation({
+  await Barretenberg.initSingleton();
+  const api = Barretenberg.getSingleton();
+  const response = await api.poseidon2Permutation({
     inputs: inputFields.map(i => i.toBuffer()),
   });
   // We'd like this assertion but it's not possible to use it in the browser.
@@ -65,9 +65,9 @@ export async function poseidon2HashBytes(input: Buffer): Promise<Fr> {
     inputFields.push(Fr.fromBuffer(fieldBytes));
   }
 
-  await BarretenbergSync.initSingleton();
-  const api = BarretenbergSync.getSingleton();
-  const response = api.poseidon2Hash({
+  await Barretenberg.initSingleton();
+  const api = Barretenberg.getSingleton();
+  const response = await api.poseidon2Hash({
     inputs: inputFields.map(i => i.toBuffer()),
   });
 

package/src/crypto/secp256k1-signer/utils.ts

@@ -210,3 +210,35 @@ export function recoverPublicKey(hash: Buffer32, signature: Signature, opts: Rec
   const publicKey = sig.recoverPublicKey(hash.buffer).toHex(false);
   return Buffer.from(publicKey, 'hex');
 }
+
+/** Arbitrary hash used for testing signature recoverability. */
+const PROBE_HASH = Buffer32.fromBuffer(keccak256(Buffer.from('signature-recoverability-probe')));
+
+/**
+ * Generates a random valid ECDSA signature that is recoverable to some address.
+ * Since Signature.random() produces real signatures via secp256k1 signing, the result is always
+ * recoverable, but we verify defensively by checking tryRecoverAddress.
+ */
+export function generateRecoverableSignature(): Signature {
+  for (let i = 0; i < 100; i++) {
+    const sig = Signature.random();
+    if (tryRecoverAddress(PROBE_HASH, sig) !== undefined) {
+      return sig;
+    }
+  }
+  throw new Secp256k1Error('Failed to generate a recoverable signature after 100 attempts');
+}
+
+/**
+ * Generates a random signature where ECDSA address recovery fails.
+ * Uses random r/s values (not from real signing) so that r is unlikely to be a valid secp256k1 x-coordinate.
+ */
+export function generateUnrecoverableSignature(): Signature {
+  for (let i = 0; i < 100; i++) {
+    const sig = new Signature(Buffer32.random(), Buffer32.random(), 27);
+    if (tryRecoverAddress(PROBE_HASH, sig) === undefined) {
+      return sig;
+    }
+  }
+  throw new Secp256k1Error('Failed to generate an unrecoverable signature after 100 attempts');
+}

package/src/curves/bn254/field.ts

@@ -118,14 +118,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;
   }

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/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/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/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';
@@ -165,6 +166,9 @@ const pinoOpts: pino.LoggerOptions<keyof typeof customLevels> = {
       ...redactedPaths.map(p => `opts.${p}`),
     ],
   },
+  formatters: {
+    log: obj => convertBigintsToStrings(obj) as Record<string, unknown>,
+  },
   ...(useGcloudLogging ? GoogleCloudLoggerConfig : {}),
 };
 

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();

package/src/serialize/serialize.ts

@@ -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 = [];
   }
 }
 

package/src/timer/date.ts

@@ -32,6 +32,12 @@ export class TestDateProvider extends DateProvider {
     this.logger.warn(`Time set to ${new Date(timeMs).toISOString()}`, { offset: this.offset, timeMs });
   }
 
+  /** Resets the time back to real time (offset = 0). */
+  public reset() {
+    this.offset = 0;
+    this.logger.warn('Time reset to real time');
+  }
+
   /** Advances the time by the given number of seconds. */
   public advanceTime(seconds: number) {
     this.offset += seconds * 1000;

package/src/transport/transport_client.ts

@@ -91,7 +91,7 @@ export class TransportClient<Payload> extends EventEmitter {
     }
     const msgId = this.msgId++;
     const msg = { msgId, payload };
-    log.debug(format(`->`, msg));
+    log.trace(format(`->`, msg));
     return new Promise<any>((resolve, reject) => {
       this.pendingRequests.push({ resolve, reject, msgId });
       this.socket!.send(msg, transfer).catch(reject);
@@ -111,7 +111,7 @@ export class TransportClient<Payload> extends EventEmitter {
       this.close();
       return;
     }
-    log.debug(format(`<-`, msg));
+    log.trace(format(`<-`, msg));
     if (isEventMessage(msg)) {
       this.emit('event_msg', msg.payload);
       return;