@aztec-labs/foundation 6.0.0-nightly.20260829

package/src/iterable/take.ts

@@ -0,0 +1,54 @@
+import { isAsyncIterable } from './isAsyncIt.js';
+
+/**
+ * Stop iteration after n items have been received.
+ * @param source - An iterable to take n items from.
+ * @param limit - The number of items to take from the iterable.
+ * @returns A generator, limited to n items.
+ */
+function take<T>(source: Iterable<T>, limit: number): Generator<T, void, undefined>;
+function take<T>(source: Iterable<T> | AsyncIterable<T>, limit: number): AsyncGenerator<T, void, undefined>;
+function take<T>(
+  source: Iterable<T> | AsyncIterable<T>,
+  limit: number,
+): AsyncGenerator<T, void, undefined> | Generator<T, void, undefined> {
+  if (isAsyncIterable(source)) {
+    return (async function* () {
+      let items = 0;
+
+      if (limit < 1) {
+        return;
+      }
+
+      for await (const entry of source) {
+        yield entry;
+
+        items++;
+
+        if (items === limit) {
+          return;
+        }
+      }
+    })();
+  }
+
+  return (function* () {
+    let items = 0;
+
+    if (limit < 1) {
+      return;
+    }
+
+    for (const entry of source) {
+      yield entry;
+
+      items++;
+
+      if (items === limit) {
+        return;
+      }
+    }
+  })();
+}
+
+export { take };

package/src/iterable/toArray.ts

@@ -0,0 +1,9 @@
+export async function toArray<T>(
+  iterator: Iterable<T> | AsyncIterableIterator<T> | AsyncIterable<T> | IterableIterator<T>,
+): Promise<T[]> {
+  const arr = [];
+  for await (const i of iterator) {
+    arr.push(i);
+  }
+  return arr;
+}

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/env.mjs

@@ -0,0 +1,52 @@
+import { TestEnvironment } from 'jest-environment-node';
+
+// What errors should be ignored in after hooks
+const IgnoredErrors = ['HttpRequestError', 'CodeError'];
+
+/** Custom Jest environment that ignores any whitelisted unhandled rejections that occur during `after` hooks */
+export default class CustomEnvironment extends TestEnvironment {
+  constructor(config, context) {
+    super(config, context);
+  }
+
+  async handleTestEvent(event, state) {
+    if (event.name === 'setup') {
+      // Jest 29 reports both unhandledRejection and uncaughtException events as plain `error`, without any means to differentiate them
+      // (see https://github.com/jestjs/jest/issues/9210). Jest 30 fixes it as part of a larger change (see
+      // https://github.com/jestjs/jest/pull/14315/files#diff-9bdc1fdb60c8631b1e346eff6e4899c4e64ae3a44f4f12d0d7ac70c2aabd1d93R12-R29),
+      // but we cannot update to 30 as it is still in beta at the time of writing this code. So we remove jest's unhandledRejection listener,
+      // replace it with our own, and delegate to the original listener only if the error is not in the ignored list.
+      const parentProcess = event.parentProcess;
+      const [jestListener] = parentProcess.listeners('unhandledRejection');
+      parentProcess.removeAllListeners('unhandledRejection');
+      const patchedListener = (err, _promise) => {
+        if (state.isInAfterHook && IgnoredErrors.some(error => err && err.name && err.name.includes(error))) {
+          // Ignore the error only if it was an unhandled async rejection (not sync exception), it's on the IgnoredErrors list, and we're in an after hook.
+          console.error('Ignoring unhandled rejection in after hook:', err);
+        } else if (state.isInAfterHook) {
+          // Log non-ignored unhandled rejection in an after hook, and pass the error to the original jest listener to fail the test.
+          console.error(`Unhandled rejection in after hook:`, err);
+          jestListener && jestListener(err);
+        } else {
+          // Otherwise, just delegate to the original jest listener, to emit the `error` event under the hood.
+          jestListener && jestListener(err);
+        }
+      };
+      parentProcess.on('unhandledRejection', patchedListener);
+      state.patchedListener = patchedListener;
+    } else if (event.name === 'teardown') {
+      // Remove the patched handler we added in setup.
+      const parentProcess = state.parentProcess;
+      parentProcess.removeListener('unhandledRejection', state.patchedListener);
+    } else if (event.name === 'hook_start' && event.hook.type.startsWith('after')) {
+      // Track that we have entered an after hook.
+      state.isInAfterHook = true;
+    } else if (
+      (event.name === 'hook_success' || event.name === 'hook_failure') &&
+      event.hook.type.startsWith('after')
+    ) {
+      // Reset the flag that we are in an after hook when we exit it.
+      state.isInAfterHook = false;
+    }
+  }
+}

package/src/jest/setup.mjs

@@ -0,0 +1,38 @@
+import { parseBooleanEnv } from '@aztec-labs/foundation/config';
+import { overwriteLoggingStream, pinoPrettyOpts } from '@aztec-labs/foundation/log';
+import pretty from 'pino-pretty';
+
+// Overwrite logging stream with pino-pretty. We define this as a separate
+// 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
+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/jest/setupAfterEnv.mjs

@@ -0,0 +1,3 @@
+if (Array.isArray(globalThis.__extraEqualityTesters)) {
+  expect.addEqualityTesters(globalThis.__extraEqualityTesters);
+}

package/src/json-rpc/README.md

@@ -0,0 +1,55 @@
+# json-rpc
+
+json-rpc
+
+```
+-- src
+    -- client
+      Code to use by a client wishing to use a json-rpc server
+      Includes syntax sugar for making requests with normal method syntax
+    -- server
+      Code for easily turning a class into an exposed RPC with one endpoint per method
+```
+
+Each createJsonRpcClient and JsonRpcServer call needs a map of classes that will be translated in input and output values.
+By default, Buffer is handled, but other user-made classes need to define toString() and static fromString() like so:
+
+```
+   class PublicKey {
+     toString() {
+       return '...';
+     }
+     static fromString(str) {
+       return new PublicKey(...);
+     }
+   }
+```
+
+## Usage
+
+In Dapp:
+
+```
+const wallet = createJsonRpcClient<WalletImplementation>('wallet-server.com', /*register classes*/ {PublicKey, TxRequest});
+const response = await wallet.signTxRequest(accountPubKey, txRequest);
+```
+
+The client will send `[{ name: 'PublicKey', value: accountPubKey.toString() }, { name: 'TxRequest', txRequest.toString() }]` to the server.
+
+In wallet:
+
+```
+const publicClient = createJsonRpcClient<PublicClient>('public-client.com',  /*register classes*/ ...);
+const keyStore = createJsonRpcClient<KeyStore>('key-store.com',  /*register classes*/ ...);
+```
+
+Different clients for different services.
+
+-- server
+Running a wallet server:
+
+```
+const wallet = new WalletImplementation();
+const server = new JsonRpcServer(wallet,  /*register classes*/ ...);
+server.start(8080);
+```

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

@@ -0,0 +1,98 @@
+import { format, inspect } from 'util';
+
+import { type Logger, createLogger } from '../../log/index.js';
+import { NoRetryError, makeBackoff, retry } from '../../retry/index.js';
+import { jsonStringify } from '../convert.js';
+
+const log = createLogger('json-rpc:json_rpc_client');
+
+export type JsonRpcFetch = (
+  host: string,
+  body: any,
+  extraHeaders?: Record<string, string>,
+  noRetry?: boolean,
+) => Promise<{ response: any; headers: { get: (header: string) => string | null | undefined } }>;
+
+export type JsonRpcFetchConfig = {
+  credentials?: RequestCredentials;
+};
+
+/**
+ * A normal fetch function that does not retry.
+ * Alternatives are a fetch function with retries, or a mocked fetch.
+ * @param host - The host URL.
+ * @param method - The RPC method name.
+ * @param body - The RPC payload.
+ * @param noRetry - Whether to throw a `NoRetryError` in case the response is a 5xx error and the body contains an error
+ *                  message (see `retry` function for more details).
+ * @param config - Fetch transport configuration.
+ * @returns The parsed JSON response, or throws an error.
+ */
+export async function defaultFetch(
+  host: string,
+  body: unknown,
+  extraHeaders: Record<string, string> = {},
+  noRetry = false,
+  config: JsonRpcFetchConfig = {},
+): Promise<{ response: any; headers: { get: (header: string) => string | null | undefined } }> {
+  log.debug(format(`JsonRpcClient.fetch`, host, '->', body));
+  let resp: Response;
+  try {
+    resp = await fetch(host, {
+      method: 'POST',
+      body: jsonStringify(body),
+      headers: { 'content-type': 'application/json', ...extraHeaders },
+      credentials: config.credentials,
+    });
+  } catch (err) {
+    const errorMessage = `Error fetching from host ${host}: ${inspect(err)}`;
+    throw new Error(errorMessage);
+  }
+
+  let responseJson;
+  const responseText = await resp.text();
+  try {
+    responseJson = JSON.parse(responseText);
+  } catch {
+    if (!resp.ok) {
+      throw new Error(resp.statusText);
+    }
+    throw new Error(`Failed to parse body as JSON: ${responseText}`);
+  }
+
+  if (!resp.ok) {
+    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 {
+      throw new Error(errorMessage);
+    }
+  }
+
+  return { response: responseJson, headers: resp.headers };
+}
+
+/**
+ * Makes a fetch function that retries based on the given attempts.
+ * @param retries - Sequence of intervals (in seconds) to retry.
+ * @param noRetry - Whether to stop retries on server errors.
+ * @param log - Optional logger for logging attempts.
+ * @param config - Fetch transport configuration.
+ * @returns A fetch function.
+ */
+export function makeFetch(
+  retries: number[],
+  defaultNoRetry: boolean,
+  log?: Logger,
+  config: JsonRpcFetchConfig = {},
+): JsonRpcFetch {
+  return async (host: string, body: unknown, extraHeaders: Record<string, string> = {}, noRetry?: boolean) => {
+    return await retry(
+      () => defaultFetch(host, body, extraHeaders, noRetry ?? defaultNoRetry, config),
+      `JsonRpcClient request to ${host}`,
+      makeBackoff(retries),
+      log,
+      false,
+    );
+  };
+}

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

@@ -0,0 +1,2 @@
+export * from './safe_json_rpc_client.js';
+export * from './fetch.js';

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

@@ -0,0 +1,283 @@
+import { format } from 'util';
+
+import { type Logger, createLogger } from '../../log/pino-logger.js';
+import { type PromiseWithResolvers, promiseWithResolvers } from '../../promise/utils.js';
+import { type ApiSchema, type ApiSchemaFor, getSchemaReturnType, schemaHasMethod } from '../../schemas/api.js';
+import { jsonStringify } from '../convert.js';
+import { type JsonRpcFetch, defaultFetch } from './fetch.js';
+
+// batch window of 0 would capture all requests in the current sync iteration of the event loop
+// and send them all at once in a single batch
+// minimal latency
+const DEFAULT_BATCH_WINDOW_MS = 0;
+
+// the maximum size of a batched request
+const DEFAULT_MAX_BATCH_SIZE = 100;
+
+// 1 mb, matching the JSON-RPC server's default maxBodySizeBytes so the client never assembles a batch the
+// server rejects for exceeding the body limit
+const DEFAULT_MAX_REQUESTY_BODY_SIZE = 1 * 1024 * 1024;
+
+export type SafeJsonRpcClientOptions = {
+  namespaceMethods?: string | false;
+  fetch?: JsonRpcFetch;
+  log?: Logger;
+  batchWindowMS?: number;
+  maxBatchSize?: number;
+  maxRequestBodySize?: number;
+  extraHeaders?: Record<string, string>;
+  onResponse?: (res: {
+    response: any;
+    headers: { get: (header: string) => string | null | undefined };
+  }) => Promise<void>;
+};
+
+type JsonRpcRequest = {
+  jsonrpc: '2.0';
+  id?: number;
+  method: string;
+  params?: Array<any>;
+};
+
+type JsonRpcResponse =
+  | {
+      jsonrpc: '2.0';
+      id?: number;
+      result: any;
+    }
+  | {
+      jsonrpc: '2.0';
+      id?: number;
+      error: { code: number; data?: any; message: string };
+    };
+
+// expose helpful information on the RPC clients such that we can recognize them later
+const SEND_BATCH = Symbol('JsonRpcClient.sendBatch');
+const CLIENT_ID = Symbol('JsonRpcClient.clientId');
+
+let nextClientId = 1;
+// keep a reference to clients so that we can force send a batch
+const clients = new Map<number, WeakRef<{ [SEND_BATCH]: () => Promise<void> }>>();
+
+/**
+ * Creates a Proxy object that delegates over RPC and validates outputs against a given schema.
+ * The server is expected to be a JsonRpcServer.
+ * @param host - The host URL.
+ * @param schema - The api schema to validate returned data against.
+ * @param fetch - The fetch implementation to use.
+ */
+export function createSafeJsonRpcClient<T extends object>(
+  host: string,
+  schema: ApiSchemaFor<T>,
+  config: SafeJsonRpcClientOptions = {},
+): T {
+  const fetch = config.fetch ?? defaultFetch;
+  const log = config.log ?? createLogger('json-rpc:client');
+  const {
+    namespaceMethods = false,
+    batchWindowMS = DEFAULT_BATCH_WINDOW_MS,
+    maxBatchSize = DEFAULT_MAX_BATCH_SIZE,
+    maxRequestBodySize = DEFAULT_MAX_REQUESTY_BODY_SIZE,
+  } = config;
+
+  let id = 0;
+  let sendBatchTimeoutHandle: NodeJS.Timeout | undefined;
+  const queue: Array<{
+    request: JsonRpcRequest;
+    deferred: PromiseWithResolvers<JsonRpcResponse>;
+    encodedLength: number;
+  }> = [];
+
+  const sendBatch = async (): Promise<void> => {
+    if (sendBatchTimeoutHandle !== undefined) {
+      clearTimeout(sendBatchTimeoutHandle);
+      sendBatchTimeoutHandle = undefined;
+    }
+
+    const rpcCalls: typeof queue = [];
+    let bodySize = 0;
+
+    while (queue.length > 0 && rpcCalls.length < maxBatchSize && bodySize < maxRequestBodySize) {
+      const item = queue[0];
+      if (!item) {
+        break;
+      }
+
+      const tmpBodySize = bodySize + item.encodedLength;
+      if (tmpBodySize >= maxRequestBodySize) {
+        break;
+      }
+
+      bodySize = tmpBodySize;
+      queue.shift();
+      rpcCalls.push(item);
+    }
+
+    // no-op
+    if (rpcCalls.length === 0) {
+      return;
+    }
+
+    // schedule another call if there are more items to send
+    if (queue.length > 0) {
+      // eslint-disable-next-line @typescript-eslint/no-misused-promises
+      sendBatchTimeoutHandle = setTimeout(sendBatch, batchWindowMS);
+    }
+
+    log.debug(`Executing JSON-RPC batch of size: ${rpcCalls.length} body size: ${bodySize} bytes`, {
+      methods: rpcCalls.map(({ request }) => request.method),
+    });
+    try {
+      const { response, headers } = await fetch(
+        host,
+        rpcCalls.map(({ request }) => request),
+        config.extraHeaders,
+      );
+
+      if (config.onResponse) {
+        await config.onResponse({ response, headers });
+      }
+
+      if (!Array.isArray(response) || response.length !== rpcCalls.length) {
+        log.warn(
+          `Invalid response received from JSON-RPC server. Expected array of responses of length ${rpcCalls.length}`,
+          { response },
+        );
+        for (let i = 0; i < rpcCalls.length; i++) {
+          const { request, deferred } = rpcCalls[i];
+          deferred.resolve({
+            id: request.id,
+            jsonrpc: '2.0',
+            error: {
+              code: -32000,
+              data: response,
+              message: response.message ?? 'Failed request',
+            },
+          });
+        }
+      } else {
+        for (let i = 0; i < response.length; i++) {
+          const resp: JsonRpcResponse = response[i];
+          const { request, deferred } = rpcCalls[i];
+
+          if (resp.id !== request.id) {
+            log.warn(`Invalid response received at index ${i} from JSON-RPC server: id mismatch`, {
+              requestMethod: request.method,
+              requestId: request.id,
+              responseId: resp.id,
+            });
+            deferred.resolve({
+              id: request.id,
+              jsonrpc: '2.0',
+              error: {
+                code: -32001,
+                data: resp,
+                message: 'RPC id mismatch',
+              },
+            });
+          } else {
+            deferred.resolve(resp);
+          }
+        }
+      }
+    } catch (err) {
+      // Re-throw ComponentsVersionsError immediately without converting to JSON-RPC error
+      // This ensures version mismatch errors are surfaced to the user instead of being hidden
+      if (err && typeof err === 'object' && 'name' in err && err.name === 'ComponentsVersionsError') {
+        // Reject all pending requests with the version error
+        for (let i = 0; i < rpcCalls.length; i++) {
+          rpcCalls[i].deferred.reject(err);
+        }
+        return; // Return early, the promises are already rejected
+      }
+      log.warn(`Failed to fetch from the remote server`, err);
+      for (let i = 0; i < rpcCalls.length; i++) {
+        const { request, deferred } = rpcCalls[i];
+        deferred.resolve({
+          id: request.id,
+          jsonrpc: '2.0',
+          error: {
+            code: -32000,
+            data: err,
+            message: (err as any).message ?? 'Failed request',
+          },
+        });
+      }
+    }
+  };
+
+  const request = async (methodName: string, params: any[]): Promise<any> => {
+    if (!schemaHasMethod(schema, methodName)) {
+      throw new Error(`Unspecified method ${methodName} in client schema`);
+    }
+    const method = namespaceMethods ? `${namespaceMethods}_${methodName}` : methodName;
+    const body: JsonRpcRequest = { jsonrpc: '2.0', id: id++, method, params };
+
+    const deferred = promiseWithResolvers<JsonRpcResponse>();
+    const encodedLength = jsonStringify(body).length;
+    if (encodedLength >= maxRequestBodySize) {
+      throw new Error(`Request body too large: ${encodedLength}`);
+    }
+
+    queue.push({ request: body, deferred, encodedLength });
+
+    if (sendBatchTimeoutHandle === undefined) {
+      // eslint-disable-next-line @typescript-eslint/no-misused-promises
+      sendBatchTimeoutHandle = setTimeout(sendBatch, batchWindowMS);
+    }
+
+    log.debug(format(`request`, method, params));
+    const response = await deferred.promise;
+    log.debug(format(`result`, method, response));
+
+    if ('error' in response) {
+      throw new Error(response.error.message, { cause: response.error });
+    }
+    // TODO(palla/schemas): Find a better way to handle null responses (JSON.stringify(null) is string "null").
+    if ([null, undefined, 'null', 'undefined'].includes(response.result)) {
+      return;
+    }
+    return getSchemaReturnType((schema as ApiSchema)[methodName]).parseAsync(response.result);
+  };
+
+  const clientId = nextClientId++;
+  const proxy: any = { [CLIENT_ID]: clientId, [SEND_BATCH]: sendBatch };
+  for (const method of Object.keys(schema)) {
+    // attach the clientId to the promise so that if we want to trigger a batch immediately, we can do that
+    proxy[method] = (...params: any[]) => Object.assign(request(method, params), { [CLIENT_ID]: clientId });
+  }
+
+  clients.set(clientId, new WeakRef(proxy));
+
+  return proxy as T;
+}
+
+/**
+ * Triggers a batch to be sent immediately
+ */
+export async function batch<T extends readonly unknown[]>(
+  values: T,
+): Promise<{ -readonly [P in keyof T]: Awaited<T[P]> }> {
+  const clientIdsSeen = new Set<number>();
+
+  await Promise.allSettled(
+    values.map(val => {
+      if (typeof val === 'object' && val && Object.hasOwn(val, CLIENT_ID)) {
+        const clientId = (val as { [CLIENT_ID]: any })[CLIENT_ID];
+        if (typeof clientId === 'number') {
+          if (clientIdsSeen.has(clientId)) {
+            return;
+          }
+
+          clientIdsSeen.add(clientId);
+          const client = clients.get(clientId)?.deref();
+          if (client) {
+            return client[SEND_BATCH]();
+          }
+        }
+      }
+    }),
+  );
+
+  return Promise.all(values);
+}