@aztec/foundation 0.22.0 → 0.24.0

package/src/json-rpc/class_converter.ts

@@ -0,0 +1,213 @@
+import { assert } from './js_utils.js';
+
+/**
+ * Represents a class compatible with our class conversion system.
+ * E.g. PublicKey here satisfies 'StringIOClass'.
+ * ```
+ *    class PublicKey {
+ *      toString() {
+ *        return '...';
+ *      }
+ *      static fromString(str) {
+ *        return new PublicKey(...);
+ *      }
+ *    }
+ * ```
+ */
+interface StringIOClass {
+  new (...args: any): any;
+
+  // TODO(#4254): Ensure that toString method is checked for as well.
+
+  /**
+   * Creates an IOClass from a given string.
+   */
+  fromString: (str: string) => any;
+}
+
+/**
+ * Represents a class compatible with our class conversion system.
+ * E.g. PublicKey here satisfies 'ObjIOClass'.
+ * ```
+ *    class PublicKey {
+ *      toJSON() {
+ *        return {...};
+ *      }
+ *      static fromJSON(obj) {
+ *        return new PublicKey({...});
+ *      }
+ *    }
+ * ```
+ */
+interface ObjIOClass {
+  new (...args: any): any;
+
+  // TODO(#4254): Ensure that toJSON method is checked for as well.
+
+  /**
+   * Creates an IOClass from a given JSON object.
+   */
+  fromJSON: (str: object) => any;
+}
+
+/**
+ * Either a StringIOClass or ObjIOClass
+ */
+type IOClass = ObjIOClass | StringIOClass;
+
+/**
+ * Registered classes available for conversion.
+ */
+export interface StringClassConverterInput {
+  [className: string]: StringIOClass;
+}
+
+/**
+ * Registered classes available for conversion.
+ */
+export interface JsonClassConverterInput {
+  [className: string]: ObjIOClass;
+}
+
+/**
+ * Represents a class in a JSON-friendly encoding.
+ */
+export interface StringEncodedClass {
+  /**
+   * The class type.
+   */
+  type: string;
+  /**
+   * The class data string.
+   */
+  data: string;
+}
+
+/**
+ * Represents a class in a JSON-friendly encoding.
+ */
+export interface JsonEncodedClass {
+  /**
+   * The class type.
+   */
+  type: string;
+  /**
+   * The class data string.
+   */
+  data: object;
+}
+/**
+ * Whether a class is a complex object or simply represented by a string.
+ */
+export type ClassEncoding = 'string' | 'object';
+
+/**
+ * Handles mapping of classes to names, and calling toString and fromString to convert to and from JSON-friendly formats.
+ * Takes a class map as input.
+ */
+export class ClassConverter {
+  private toClass = new Map<string, [IOClass, ClassEncoding]>();
+  private toName = new Map<IOClass, [string, ClassEncoding]>();
+
+  /**
+   * Create a class converter from a table of classes.
+   * @param stringClassMap - The class table of string encoded classes.
+   * @param objectClassMap - The class table of complex object classes
+   */
+  constructor(stringClassMap?: StringClassConverterInput, objectClassMap?: JsonClassConverterInput) {
+    if (stringClassMap) {
+      for (const key of Object.keys(stringClassMap)) {
+        this.register(key, stringClassMap[key], 'string');
+      }
+    }
+    if (objectClassMap) {
+      for (const key of Object.keys(objectClassMap)) {
+        this.register(key, objectClassMap[key], 'object');
+      }
+    }
+  }
+
+  /**
+   * Register a class with a certain name.
+   * This name is used for conversion from and to this class.
+   * @param type - The class name to use for serialization.
+   * @param class_ - The class object.
+   * @param encoding - Whether the class is a complex object or simply represented by a string.
+   */
+  register(type: string, class_: IOClass, encoding: ClassEncoding) {
+    assert(type !== 'Buffer', "'Buffer' handling is hardcoded. Cannot use as name.");
+    assert(
+      class_.prototype['toString'] || class_.prototype['toJSON'],
+      `Class ${type} must define a toString() OR toJSON() method.`,
+    );
+    assert(
+      (class_ as StringIOClass)['fromString'] || (class_ as ObjIOClass)['fromJSON'],
+      `Class ${type} must define a fromString() OR fromJSON() static method.`,
+    );
+    this.toName.set(class_, [type, encoding]);
+    this.toClass.set(type, [class_, encoding]);
+  }
+
+  /**
+   * Does this type name have a registered class?
+   * @param type - The type name.
+   * @returns If there's a registered class.
+   */
+  isRegisteredClassName(type: string) {
+    return this.toClass.has(type);
+  }
+  /**
+   * Is this class object registered?
+   * @param obj - The class object.
+   * @returns If it is a registered class.
+   */
+  isRegisteredClass(obj: any) {
+    const name = obj.prototype.constructor.name;
+    return this.toName.has(obj) || this.isRegisteredClassName(name);
+  }
+  /**
+   * Convert a JSON-like object to a class object.
+   * @param jsonObj - An object encoding a class.
+   * @returns The class object.
+   */
+  toClassObj(jsonObj: JsonEncodedClass | StringEncodedClass): any {
+    const result = this.toClass.get(jsonObj.type);
+    assert(result, `Could not find type in lookup.`);
+
+    const [class_, encoding] = result;
+    if (encoding === 'string' && typeof jsonObj.data === 'string') {
+      return (class_ as StringIOClass)!.fromString!(jsonObj.data);
+    } else {
+      return (class_ as ObjIOClass)!.fromJSON!(jsonObj.data as object);
+    }
+  }
+  /**
+   * Convert a class object to a JSON object.
+   * @param classObj - A JSON encoding a class.
+   * @returns The class object.
+   */
+  toJsonObj(classObj: any): JsonEncodedClass | StringEncodedClass {
+    const { type, encoding } = this.lookupObject(classObj);
+    const data = encoding === 'string' ? classObj.toString() : classObj.toJSON();
+    return { type: type!, data };
+  }
+
+  /**
+   * Loads the corresponding type for this class based on constructor first and constructor name if not found.
+   * Constructor match works in the event of a minifier changing function names, and constructor name match
+   * works in the event of duplicated instances of node modules being loaded (see #1826).
+   * @param classObj - Object to lookup in the registered types.
+   * @returns Registered type name and encoding.
+   */
+  private lookupObject(classObj: any) {
+    const nameResult = this.toName.get(classObj.constructor);
+    if (nameResult) {
+      return { type: nameResult[0], encoding: nameResult[1] };
+    }
+    const classResult = this.toClass.get(classObj.constructor.name);
+    if (classResult) {
+      return { type: classObj.constructor.name, encoding: classResult[1] };
+    }
+    throw new Error(`Could not find class ${classObj.constructor.name} in lookup.`);
+  }
+}

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

@@ -0,0 +1 @@
+export { createJsonRpcClient, defaultFetch, makeFetch } from './json_rpc_client.js';

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

@@ -0,0 +1,147 @@
+// comlink:
+//  Dev dependency just for the somewhat complex RemoteObject type
+//  This takes a {foo(): T} and makes {foo(): Promise<T>}
+//  while avoiding Promise of Promise.
+import { RemoteObject } from 'comlink';
+import { format } from 'util';
+
+import { DebugLogger, createDebugLogger } from '../../log/index.js';
+import { NoRetryError, makeBackoff, retry } from '../../retry/index.js';
+import { ClassConverter, JsonClassConverterInput, StringClassConverterInput } from '../class_converter.js';
+import { JsonStringify, convertFromJsonObj, convertToJsonObj } from '../convert.js';
+
+export { JsonStringify } from '../convert.js';
+
+const debug = createDebugLogger('json-rpc:json_rpc_client');
+/**
+ * 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 not ok 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,
+  noRetry = false,
+) {
+  debug(format(`JsonRpcClient.fetch`, host, rpcMethod, '->', body));
+  let resp: Response;
+  if (useApiEndpoints) {
+    resp = await fetch(`${host}/${rpcMethod}`, {
+      method: 'POST',
+      body: JsonStringify(body),
+      headers: { 'content-type': 'application/json' },
+    });
+  } else {
+    resp = await fetch(host, {
+      method: 'POST',
+      body: JsonStringify({ ...body, method: rpcMethod }),
+      headers: { 'content-type': 'application/json' },
+    });
+  }
+
+  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) {
+    if (noRetry) {
+      throw new NoRetryError('(JSON-RPC PROPAGATED) ' + responseJson.error.message);
+    } else {
+      throw new Error('(JSON-RPC PROPAGATED) ' + responseJson.error.message);
+    }
+  }
+
+  return responseJson;
+}
+
+/**
+ * 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[], noRetry: boolean, log?: DebugLogger) {
+  return async (host: string, rpcMethod: string, body: any, useApiEndpoints: boolean) => {
+    return await retry(
+      () => defaultFetch(host, rpcMethod, body, useApiEndpoints, noRetry),
+      `JsonRpcClient request to ${host}`,
+      makeBackoff(retries),
+      log,
+      true,
+    );
+  };
+}
+
+/**
+ * Creates a Proxy object that delegates over RPC and satisfies RemoteObject<T>.
+ * The server should have ran new JsonRpcServer().
+ * @param host - The host URL.
+ * @param stringClassMap - A map of class names to string representations.
+ * @param objectClassMap - A map of class names to class constructors.
+ * @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 createJsonRpcClient<T extends object>(
+  host: string,
+  stringClassMap: StringClassConverterInput,
+  objectClassMap: JsonClassConverterInput,
+  useApiEndpoints: boolean,
+  namespaceMethods?: string | false,
+  fetch = defaultFetch,
+) {
+  const classConverter = new ClassConverter(stringClassMap, objectClassMap);
+  let id = 0;
+  const request = async (method: string, params: any[]): Promise<any> => {
+    const body = {
+      jsonrpc: '2.0',
+      id: id++,
+      method,
+      params: params.map(param => convertToJsonObj(classConverter, param)),
+    };
+    debug(format(`JsonRpcClient.request`, method, '<-', params));
+    const res = await fetch(host, method, body, useApiEndpoints);
+    debug(format(`JsonRpcClient.result`, method, '->', res));
+    if (res.error) {
+      throw res.error;
+    }
+    if ([null, undefined, 'null', 'undefined'].includes(res.result)) {
+      return;
+    }
+    return convertFromJsonObj(classConverter, res.result);
+  };
+
+  // Intercept any RPC methods with a proxy
+  // This wraps 'request' with a method-call syntax wrapper
+  return new Proxy(
+    {},
+    {
+      get: (target, method: string) => {
+        let rpcMethod = method;
+        if (namespaceMethods) {
+          rpcMethod = `${namespaceMethods}_${method}`;
+        }
+        if (['then', 'catch'].includes(method)) {
+          return Reflect.get(target, method);
+        }
+        return (...params: any[]) => {
+          debug(format(`JsonRpcClient.constructor`, 'proxy', rpcMethod, '<-', params));
+          return request(rpcMethod, params);
+        };
+      },
+    },
+  ) as RemoteObject<T>;
+}

package/src/json-rpc/convert.ts

@@ -0,0 +1,163 @@
+import { Buffer } from 'buffer';
+import cloneDeepWith from 'lodash.clonedeepwith';
+
+import { ClassConverter } from './class_converter.js';
+
+/**
+ * Check prototype chain to determine if an object is 'plain' (not a class instance).
+ * @param obj - The object to check.
+ * @returns True if the object is 'plain'.
+ */
+function isPlainObject(obj: any) {
+  if (obj === null) {
+    return false;
+  }
+
+  let proto = obj;
+  let counter = 0;
+  const MAX_PROTOTYPE_CHAIN_LENGTH = 1000; // Adjust as needed
+  while (Object.getPrototypeOf(proto) !== null) {
+    if (counter >= MAX_PROTOTYPE_CHAIN_LENGTH) {
+      // This is a failsafe in case circular prototype chain has been created. It should not be hit
+      return false;
+    }
+    proto = Object.getPrototypeOf(proto);
+    counter++;
+  }
+
+  return Object.getPrototypeOf(obj) === proto;
+}
+
+/**
+ * Recursively looks through an object for bigints and converts them to object format.
+ * @param obj - The object to convert.
+ * @returns The converted object with stringified bigints.
+ */
+export const convertBigintsInObj = (obj: any) => {
+  return cloneDeepWith(obj, (value: any) => {
+    if (typeof value === 'bigint') {
+      return { type: 'bigint', data: value.toString() };
+    }
+  });
+};
+
+/**
+ * JSON.stringify helper that handles bigints.
+ * @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) =>
+      typeof value === 'bigint'
+        ? JSON.stringify({
+            type: 'bigint',
+            data: value.toString(),
+          })
+        : value,
+    prettify ? 2 : 0,
+  );
+}
+
+/**
+ * Convert a JSON-friendly object, which may encode a class object.
+ * @param cc - The class converter.
+ * @param obj - The encoded object.
+ * @returns The decoded object.
+ */
+export function convertFromJsonObj(cc: ClassConverter, obj: any): any {
+  if (obj === null) {
+    return undefined; // `null` doesn't work with default args.
+  }
+
+  if (!obj) {
+    return obj; // Primitive type
+  }
+  // Is this a serialized Node buffer?
+  if (obj.type === 'Buffer' && typeof obj.data === 'string') {
+    return Buffer.from(obj.data, 'base64');
+  }
+
+  if (obj.type === 'bigint' && typeof obj.data === 'string') {
+    return BigInt(obj.data);
+  }
+
+  // Is this a convertible type?
+  if (typeof obj.type === 'string') {
+    if (cc.isRegisteredClassName(obj.type)) {
+      return cc.toClassObj(obj);
+    } else {
+      throw new Error(`Object ${obj.type} not registered for serialization FROM JSON`);
+    }
+  }
+
+  // Is this an array?
+  if (Array.isArray(obj)) {
+    return obj.map((x: any) => convertFromJsonObj(cc, x));
+  }
+
+  // Is this a dictionary?
+  if (typeof obj === 'object') {
+    const newObj: any = {};
+    for (const key of Object.keys(obj)) {
+      newObj[key] = convertFromJsonObj(cc, obj[key]);
+    }
+    return newObj;
+  }
+
+  // Leave alone, assume JSON primitive
+  return obj;
+}
+
+/**
+ * Convert objects or classes to a JSON-friendly object.
+ * @param cc - The class converter.
+ * @param obj - The object.
+ * @returns The encoded object.
+ */
+export function convertToJsonObj(cc: ClassConverter, obj: any): any {
+  // Bigint is a primitive type that needs special handling since it's not serializable
+  if (typeof obj === 'bigint') {
+    return {
+      type: 'bigint',
+      data: obj.toString(),
+    };
+  }
+
+  if (!obj) {
+    return obj; // Primitive type
+  }
+
+  // Is this a Node buffer?
+  if (obj instanceof Buffer) {
+    return { type: 'Buffer', data: obj.toString('base64') };
+  }
+
+  // Is this a convertible type?
+  if (cc.isRegisteredClass(obj.constructor)) {
+    return cc.toJsonObj(obj);
+  }
+
+  // Is this an array?
+  if (Array.isArray(obj)) {
+    return obj.map((x: any) => convertToJsonObj(cc, x));
+  }
+
+  if (typeof obj === 'object') {
+    // Is this a dictionary?
+    if (isPlainObject(obj)) {
+      const newObj: any = {};
+      for (const key of Object.keys(obj)) {
+        newObj[key] = convertToJsonObj(cc, obj[key]);
+      }
+      return newObj;
+    } else {
+      // Throw if this is a non-primitive class that was not registered
+      throw new Error(`Object ${obj.constructor.name} not registered for serialization TO JSON`);
+    }
+  }
+
+  // Leave alone, assume JSON primitive
+  return obj;
+}

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,59 @@
+import { sleep } from '../../sleep/index.js';
+
+/**
+ * Contrived example for JSON RPC tests.
+ */
+export class TestNote {
+  constructor(private data: string) {}
+  /**
+   * 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);
+  }
+}
+
+/**
+ * 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 {
+  constructor(private 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.
+   */
+  getNote(index: number): TestNote {
+    return this.notes[index];
+  }
+  /**
+   * 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;
+  }
+}

package/src/json-rpc/index.ts

@@ -0,0 +1,8 @@
+export {
+  StringClassConverterInput,
+  JsonClassConverterInput as ObjClassConverterInput,
+  JsonEncodedClass,
+  ClassConverter,
+} from './class_converter.js';
+
+export { JsonStringify } from './convert.js';

package/src/json-rpc/js_utils.ts

@@ -0,0 +1,20 @@
+// Make sure this property was not inherited
+
+/**
+ * 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,2 @@
+export * from './json_rpc_server.js';
+export { JsonProxy } from './json_proxy.js';