@aztec/foundation 0.0.0-test.0

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/jest/setup.mjs

@@ -0,0 +1,9 @@
+import { overwriteLoggingStream, pinoPrettyOpts } from '@aztec/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
+overwriteLoggingStream(pretty(pinoPrettyOpts));

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,103 @@
+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,
+  rpcMethod: string,
+  body: any,
+  useApiEndpoints: boolean,
+  extraHeaders?: Record<string, string>,
+  noRetry?: boolean,
+) => Promise<{ response: any; headers: { get: (header: string) => string | null | undefined } }>;
+
+/**
+ * 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).
+ * @returns The parsed JSON response, or throws an error.
+ */
+export async function defaultFetch(
+  host: string,
+  rpcMethod: string,
+  body: any,
+  useApiEndpoints: boolean,
+  extraHeaders: Record<string, string> = {},
+  noRetry = false,
+): Promise<{ response: any; headers: { get: (header: string) => string | null | undefined } }> {
+  log.debug(format(`JsonRpcClient.fetch`, host, rpcMethod, '->', body));
+  let resp: Response;
+  try {
+    if (useApiEndpoints) {
+      resp = await fetch(`${host}/${rpcMethod}`, {
+        method: 'POST',
+        body: jsonStringify(body),
+        headers: { 'content-type': 'application/json', ...extraHeaders },
+      });
+    } else {
+      resp = await fetch(host, {
+        method: 'POST',
+        body: jsonStringify({ ...body, method: rpcMethod }),
+        headers: { 'content-type': 'application/json', ...extraHeaders },
+      });
+    }
+  } catch (err) {
+    const errorMessage = `Error fetching from host ${host} with method ${rpcMethod}: ${inspect(err)}`;
+    throw new Error(errorMessage);
+  }
+
+  let responseJson;
+  try {
+    responseJson = await resp.json();
+  } catch (err) {
+    if (!resp.ok) {
+      throw new Error(resp.statusText);
+    }
+    throw new Error(`Failed to parse body as JSON: ${resp.text()}`);
+  }
+
+  if (!resp.ok) {
+    const errorMessage = `Error ${resp.status} from server ${host} on ${rpcMethod}: ${responseJson.error.message}`;
+    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.
+ * @returns A fetch function.
+ */
+export function makeFetch(retries: number[], defaultNoRetry: boolean, log?: Logger): typeof defaultFetch {
+  return async (
+    host: string,
+    rpcMethod: string,
+    body: any,
+    useApiEndpoints: boolean,
+    extraHeaders: Record<string, string> = {},
+    noRetry?: boolean,
+  ) => {
+    return await retry(
+      () => defaultFetch(host, rpcMethod, body, useApiEndpoints, extraHeaders, noRetry ?? defaultNoRetry),
+      `JsonRpcClient request ${rpcMethod} 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,67 @@
+import { format } from 'util';
+
+import { type Logger, createLogger } from '../../log/pino-logger.js';
+import { type ApiSchema, type ApiSchemaFor, schemaHasMethod } from '../../schemas/api.js';
+import { type JsonRpcFetch, defaultFetch } from './fetch.js';
+
+export type SafeJsonRpcClientOptions = {
+  useApiEndpoints?: boolean;
+  namespaceMethods?: string | false;
+  fetch?: JsonRpcFetch;
+  log?: Logger;
+  onResponse?: (res: {
+    response: any;
+    headers: { get: (header: string) => string | null | undefined };
+  }) => 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 useApiEndpoints - Whether to use the API endpoints or the default RPC endpoint.
+ * @param namespaceMethods - String value (or false/empty) to namespace all methods sent to the server. e.g. 'getInfo' -\> 'pxe_getInfo'
+ * @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 { useApiEndpoints = false, namespaceMethods = false } = config;
+
+  let id = 0;
+  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 = { jsonrpc: '2.0', id: id++, method, params };
+
+    log.debug(format(`request`, method, params));
+    const { response, headers } = await fetch(host, method, body, useApiEndpoints);
+    log.debug(format(`result`, method, response));
+
+    if (config.onResponse) {
+      await config.onResponse({ response, headers });
+    }
+    if (response.error) {
+      throw 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 (schema as ApiSchema)[methodName].returnType().parseAsync(response.result);
+  };
+
+  const proxy: any = {};
+  for (const method of Object.keys(schema)) {
+    proxy[method] = (...params: any[]) => request(method, params);
+  }
+
+  return proxy as T;
+}

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

@@ -0,0 +1,75 @@
+import { Agent, type Dispatcher } from 'undici';
+
+import { createLogger } from '../../log/pino-logger.js';
+import { NoRetryError } from '../../retry/index.js';
+import { jsonStringify } from '../convert.js';
+import type { JsonRpcFetch } from './fetch.js';
+
+const log = createLogger('json-rpc:json_rpc_client:undici');
+
+export { Agent };
+
+export function makeUndiciFetch(client = new Agent()): JsonRpcFetch {
+  return async (
+    host: string,
+    rpcMethod: string,
+    body: any,
+    useApiEndpoints: boolean,
+    extraHeaders: Record<string, string> = {},
+    noRetry = false,
+  ) => {
+    log.trace(`JsonRpcClient.fetch: ${host} ${rpcMethod}`, { host, rpcMethod, body });
+    let resp: Dispatcher.ResponseData<string>;
+    try {
+      resp = await client.request<string>({
+        method: 'POST',
+        origin: new URL(host),
+        path: useApiEndpoints ? rpcMethod : '/',
+        body: jsonStringify(body),
+        headers: {
+          ...extraHeaders,
+          'content-type': 'application/json',
+        },
+      });
+    } catch (err) {
+      const errorMessage = `Error fetching from host ${host} with method ${rpcMethod}: ${String(err)}`;
+      throw new Error(errorMessage);
+    }
+
+    let responseJson: any;
+    const responseOk = resp.statusCode >= 200 && resp.statusCode <= 299;
+    try {
+      responseJson = await resp.body.json();
+    } catch (err) {
+      if (!responseOk) {
+        throw new Error('HTTP ' + resp.statusCode);
+      }
+      throw new Error(`Failed to parse body as JSON: ${await resp.body.text()}`);
+    }
+
+    if (!responseOk) {
+      const errorMessage = `Error ${resp.statusCode} response from server ${host} on ${rpcMethod}: ${responseJson.error.message}`;
+      if (noRetry || (resp.statusCode >= 400 && resp.statusCode < 500)) {
+        throw new NoRetryError(errorMessage);
+      } else {
+        throw new Error(errorMessage);
+      }
+    }
+
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(resp.headers)) {
+      if (typeof value === 'string') {
+        headers.append(key, value);
+      } else if (Array.isArray(value)) {
+        for (const v of value) {
+          headers.append(key, v);
+        }
+      }
+    }
+
+    return {
+      response: responseJson,
+      headers,
+    };
+  };
+}

package/src/json-rpc/convert.ts

@@ -0,0 +1,61 @@
+import { Buffer } from 'buffer';
+
+import type { ZodFor } from '../schemas/types.js';
+
+/**
+ * Parses a json string and then feeds it to a zod schema.
+ * @param json - JSON string.
+ * @param schema - Zod schema.
+ * @returns Result of parsing json with schema.
+ */
+export function jsonParseWithSchema<T>(json: string, schema: ZodFor<T>): Promise<T> {
+  return schema.parseAsync(JSON.parse(json));
+}
+/**
+ * Parses a json string and then feeds it to a zod schema.
+ * @param json - JSON string.
+ * @param schema - Zod schema.
+ * @returns Result of parsing json with schema.
+ */
+export function jsonParseWithSchemaSync<T>(json: string, schema: ZodFor<T>): T {
+  return schema.parse(JSON.parse(json));
+}
+
+/**
+ * JSON.stringify helper that stringifies bigints, buffers, maps, and sets.
+ * @param obj - The object to be stringified.
+ * @returns The resulting string.
+ */
+export function jsonStringify(obj: object, prettify?: boolean): string {
+  return JSON.stringify(
+    obj,
+    (_key, value) => {
+      if (typeof value === 'bigint') {
+        return value.toString();
+      } else if (typeof value === 'object' && value && value.type === 'Buffer' && Array.isArray(value.data)) {
+        return Buffer.from(value.data).toString('base64');
+      } else if (typeof value === 'object' && value && Buffer.isBuffer(value)) {
+        return value.toString('base64');
+      } else if (typeof value === 'object' && value instanceof Map) {
+        return Array.from(value.entries());
+      } else if (typeof value === 'object' && value instanceof Set) {
+        return Array.from(value.values());
+      } else {
+        return value;
+      }
+    },
+    prettify ? 2 : 0,
+  );
+}
+
+/**
+ * Calls jsonStringify but swallows errors.
+ * Use for logging, when you don't want to potentially introduce another thing that throws.
+ */
+export function tryJsonStringify(obj: any, prettify?: boolean): string | undefined {
+  try {
+    return jsonStringify(obj, prettify);
+  } catch (e) {
+    return undefined;
+  }
+}

package/src/json-rpc/fixtures/class_a.ts

@@ -0,0 +1,15 @@
+/**
+ * Test class for testing string converter.
+ */
+export class ToStringClass {
+  constructor(/** A value */ public readonly x: string, /** Another value */ public readonly y: string) {}
+
+  toString(): string {
+    return [this.x, this.y].join('-');
+  }
+
+  static fromString(value: string) {
+    const [x, y] = value.split('-');
+    return new ToStringClass(x, y);
+  }
+}

package/src/json-rpc/fixtures/class_b.ts

@@ -0,0 +1,15 @@
+/**
+ * Test class for testing string converter.
+ */
+export class ToStringClass {
+  constructor(/** A value */ public readonly x: string, /** Another value */ public readonly y: string) {}
+
+  toString(): string {
+    return [this.x, this.y].join('-');
+  }
+
+  static fromString(value: string) {
+    const [x, y] = value.split('-');
+    return new ToStringClass(x, y);
+  }
+}

package/src/json-rpc/fixtures/test_state.ts

@@ -0,0 +1,143 @@
+import { z } from 'zod';
+
+import { type ApiSchemaFor, optional, schemas } from '../../schemas/index.js';
+import { sleep } from '../../sleep/index.js';
+
+/**
+ * Contrived example for JSON RPC tests.
+ */
+export class TestNote {
+  constructor(private data: string) {}
+
+  static get schema() {
+    return z.object({ data: z.string() }).transform(({ data }) => new TestNote(data));
+  }
+
+  toJSON() {
+    return { data: this.data };
+  }
+
+  /**
+   * Create a string representation of this class.
+   * @returns The string representation.
+   */
+  toString(): string {
+    return this.data;
+  }
+  /**
+   * Creates a string representation of this class.
+   * @param data - The data.
+   * @returns The string representation.
+   */
+  static fromString(data: string): TestNote {
+    return new TestNote(data);
+  }
+}
+
+export interface TestStateApi {
+  getNote: (index: number) => Promise<TestNote | undefined>;
+  getNotes: (limit?: number) => Promise<TestNote[]>;
+  getNotes2: (limit: bigint | undefined) => Promise<TestNote[]>;
+  getNotes3: (limit?: number) => Promise<TestNote[]>;
+  clear: () => Promise<void>;
+  addNotes: (notes: TestNote[]) => Promise<TestNote[]>;
+  fail: () => Promise<void>;
+  count: () => Promise<number>;
+  getStatus: () => Promise<{ status: string; count: bigint }>;
+  getTuple(): Promise<[string, string | undefined, number]>;
+}
+
+/**
+ * Represents a simple state management for TestNote instances.
+ * Provides functionality to get a note by index and add notes asynchronously.
+ * Primarily used for testing JSON RPC-related functionalities.
+ */
+export class TestState implements TestStateApi {
+  constructor(public notes: TestNote[]) {}
+  /**
+   * Retrieve the TestNote instance at the specified index from the notes array.
+   * This method allows getting a desired TestNote from the collection of notes
+   * maintained by the TestState instance using the provided index value.
+   *
+   * @param index - The index of the TestNote to be retrieved from the notes array.
+   * @returns The TestNote instance corresponding to the given index.
+   */
+  async getNote(index: number): Promise<TestNote> {
+    await sleep(0.1);
+    return this.notes[index];
+  }
+
+  fail(): Promise<void> {
+    throw new Error('Test state failed');
+  }
+
+  async count(): Promise<number> {
+    await sleep(0.1);
+    return this.notes.length;
+  }
+
+  async getNotes(limit?: number): Promise<TestNote[]> {
+    await sleep(0.1);
+    return limit ? this.notes.slice(0, limit) : this.notes;
+  }
+
+  async getNotes2(limit: bigint | undefined): Promise<TestNote[]> {
+    await sleep(0.1);
+    return limit ? this.notes.slice(0, Number(limit)) : this.notes;
+  }
+
+  async getNotes3(limit = 1): Promise<TestNote[]> {
+    await sleep(0.1);
+    return limit ? this.notes.slice(0, Number(limit)) : this.notes;
+  }
+
+  async clear(): Promise<void> {
+    await sleep(0.1);
+    this.notes = [];
+  }
+
+  /**
+   * Add an array of TestNote instances to the current TestState's notes.
+   * This function simulates asynchronous behavior by waiting for a duration
+   * equal to the number of notes being added. It then returns the updated
+   * list of TestNote instances in the TestState.
+   *
+   * @param notes - An array of TestNote instances to be added.
+   * @returns A Promise that resolves to an array of TestNote instances, including the newly added notes.
+   */
+  async addNotes(notes: TestNote[]): Promise<TestNote[]> {
+    for (const note of notes) {
+      this.notes.push(note);
+    }
+    await sleep(notes.length);
+    return this.notes;
+  }
+
+  async forceClear() {
+    await sleep(0.1);
+    this.notes = [];
+  }
+
+  async getStatus(): Promise<{ status: string; count: bigint }> {
+    await sleep(0.1);
+    return { status: 'ok', count: BigInt(this.notes.length) };
+  }
+
+  async getTuple(): Promise<[string, string | undefined, number]> {
+    await sleep(0.1);
+    return ['a', undefined, 1];
+  }
+}
+
+export const TestStateSchema: ApiSchemaFor<TestStateApi> = {
+  getNote: z.function().args(z.number()).returns(TestNote.schema.optional()),
+  getNotes: z.function().args(optional(schemas.Integer)).returns(z.array(TestNote.schema)),
+  getNotes2: z.function().args(optional(schemas.BigInt)).returns(z.array(TestNote.schema)),
+  getNotes3: z.function().args(optional(schemas.Integer)).returns(z.array(TestNote.schema)),
+  clear: z.function().returns(z.void()),
+  addNotes: z.function().args(z.array(TestNote.schema)).returns(z.array(TestNote.schema)),
+  fail: z.function().returns(z.void()),
+  count: z.function().returns(z.number()),
+  getStatus: z.function().returns(z.object({ status: z.string(), count: schemas.BigInt })),
+  getTuple: z.function().returns(z.tuple([z.string(), optional(z.string()), z.number()])),
+};

package/src/json-rpc/index.ts

@@ -0,0 +1 @@
+export { jsonStringify, jsonParseWithSchema, jsonParseWithSchemaSync, tryJsonStringify } from './convert.js';

package/src/json-rpc/js_utils.ts

@@ -0,0 +1,21 @@
+// Make sure this property was not inherited
+// TODO(palla): Delete this file
+
+/**
+ * Does this own the property?
+ * @param obj - An object.
+ * @param method - A property name.
+ */
+export const hasOwnProperty = (obj: any, propertyName: string) =>
+  Object.prototype.hasOwnProperty.call(obj, propertyName);
+
+/**
+ * Helper function to assert a condition is truthy
+ * @param x - A boolean condition to assert.
+ * @param err - Error message to throw if x isn't met.
+ */
+export function assert(x: any, err: string): asserts x {
+  if (!x) {
+    throw new Error(err);
+  }
+}

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

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