@aztec/foundation 0.1.0-alpha10

package/src/fifo/serial_queue.ts

@@ -0,0 +1,78 @@
+import { MemoryFifo } from './memory_fifo.js';
+
+/**
+ * A more specialised fifo queue that enqueues functions to execute. Enqueued functions are executed in serial.
+ */
+export class SerialQueue {
+  private readonly queue = new MemoryFifo<() => Promise<void>>();
+  private runningPromise!: Promise<void>;
+
+  /**
+   * Initializes the execution of enqueued functions in the serial queue.
+   * Functions are executed in the order they were added to the queue, with each function
+   * waiting for the completion of the previous one before starting its execution.
+   * This method should be called once to start processing the queue.
+   */
+  public start() {
+    this.runningPromise = this.queue.process(fn => fn());
+  }
+
+  /**
+   * Returns the current number of enqueued functions in the serial queue.
+   * This provides a way to check the size of the queue and monitor its progress.
+   *
+   * @returns The length of the serial queue as a number.
+   */
+  public length() {
+    return this.queue.length();
+  }
+
+  /**
+   * Cancels the processing of the remaining functions in the serial queue and resolves the running promise.
+   * Any enqueued functions that have not yet been executed will be discarded. The queue can still accept new
+   * functions after cancellation, but the previously enqueued functions will not be re-processed.
+   *
+   * @returns The running promise which resolves when the current executing function (if any) completes.
+   */
+  public cancel() {
+    this.queue.cancel();
+    return this.runningPromise;
+  }
+
+  /**
+   * Signals the SerialQueue that it should finish processing its current task and stop accepting new tasks.
+   * The returned Promise resolves when all enqueued tasks have completed execution.
+   *
+   * @returns A Promise that resolves when the queue is completely emptied and no new tasks are allowed.
+   */
+  public end() {
+    this.queue.end();
+    return this.runningPromise;
+  }
+
+  /**
+   * Enqueues fn for execution on the serial queue.
+   * Returns the result of the function after execution.
+   * @param fn - The function to enqueue.
+   * @returns A resolution promise.
+   */
+  public put<T>(fn: () => Promise<T>): Promise<T> {
+    return new Promise((resolve, reject) => {
+      this.queue.put(async () => {
+        try {
+          const res = await fn();
+          resolve(res);
+        } catch (e) {
+          reject(e);
+        }
+      });
+    });
+  }
+
+  /**
+   * Awaiting this ensures the queue is empty before resuming.
+   */
+  public async syncPoint() {
+    await this.put(async () => {});
+  }
+}

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 usermade 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/class_converter.ts

@@ -0,0 +1,160 @@
+import { assert, hasOwnProperty } from './js_utils.js';
+
+/**
+ * Represents a class compatible with our class conversion system.
+ * E.g. PublicKey here satisfies 'IOClass'.
+ * ```
+ *    class PublicKey {
+ *      toString() {
+ *        return '...';
+ *      }
+ *      static fromString(str) {
+ *        return new PublicKey(...);
+ *      }
+ *    }
+ * ```
+ */
+interface IOClass {
+  new (...args: any): any;
+  /**
+   * Creates an IOClass from a given string.
+   */
+  fromString?: (str: string) => any;
+
+  /**
+   * Creates an IOClass from a given JSON object.
+   */
+  fromJSON?: (obj: object) => any;
+}
+
+/**
+ * Registered classes available for conversion.
+ */
+export interface ClassConverterInput {
+  [className: string]: IOClass;
+}
+
+/**
+ * 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?: ClassConverterInput, objectClassMap?: ClassConverterInput) {
+    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(
+      hasOwnProperty(class_.prototype, 'toString') || hasOwnProperty(class_.prototype, 'toJSON'),
+      `Class ${type} must define a toString() OR toJSON() method.`,
+    );
+    assert(
+      class_['fromString'] || class_['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) {
+    return this.toName.has(obj);
+  }
+  /**
+   * 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_!.fromString!(jsonObj.data);
+    } else {
+      return class_!.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 result = this.toName.get(classObj.constructor);
+    assert(result, `Could not find class in lookup.`);
+    const [type, encoding] = result;
+    const data = encoding === 'string' ? classObj.toString() : classObj.toJSON();
+    return { type: type!, data };
+  }
+}

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

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

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

@@ -0,0 +1,20 @@
+import request from 'supertest';
+import { JsonRpcServer } from '../server/json_rpc_server.js';
+import { TestState, TestNote } from '../fixtures/test_state.js';
+import { createJsonRpcClient } from './json_rpc_client.js';
+
+test('test an RPC function over client', async () => {
+  const mockFetch = async (host: string, method: string, body: any) => {
+    const server = new JsonRpcServer(new TestState([new TestNote('a'), new TestNote('b')]), { TestNote }, {}, true);
+    const result = await request(server.getApp().callback()).post(`/${method}`).send(body);
+    return JSON.parse(result.text);
+  };
+  const client = createJsonRpcClient<TestState>('', { TestNote }, {}, true, mockFetch);
+  const result = await client.addNotes([new TestNote('c')]);
+  expect(result[0]).toBeInstanceOf(TestNote);
+  expect(result[1]).toBeInstanceOf(TestNote);
+  expect(result[2]).toBeInstanceOf(TestNote);
+  expect(result[0].toString()).toBe('a');
+  expect(result[1].toString()).toBe('b');
+  expect(result[2].toString()).toBe('c');
+});

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

@@ -0,0 +1,103 @@
+// 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 { createDebugLogger } from '../../log/index.js';
+import { retry } from '../../retry/index.js';
+import { ClassConverter, ClassConverterInput } 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.
+ * @returns The parsed JSON response, or throws an error.
+ */
+export async function defaultFetch(host: string, rpcMethod: string, body: any, useApiEndpoints: boolean) {
+  debug(`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' },
+    });
+  }
+
+  if (!resp.ok) {
+    throw new Error(resp.statusText);
+  }
+
+  const text = await resp.text();
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw new Error(`Failed to parse body as JSON: ${text}`);
+  }
+}
+
+/**
+ * A fetch function with retries.
+ */
+export async function mustSucceedFetch(host: string, rpcMethod: string, body: any, useApiEndpoints: boolean) {
+  return await retry(() => defaultFetch(host, rpcMethod, body, useApiEndpoints), 'JsonRpcClient request');
+}
+
+/**
+ * Creates a Proxy object that delegates over RPC and satisfies RemoteObject<T>.
+ * The server should have ran new JsonRpcServer().
+ */
+export function createJsonRpcClient<T extends object>(
+  host: string,
+  stringClassMap: ClassConverterInput,
+  objectClassMap: ClassConverterInput,
+  useApiEndpoints: boolean,
+  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(`JsonRpcClient.request`, method, '<-', params);
+    const res = await fetch(host, method, body, useApiEndpoints);
+    debug(`JsonRpcClient.result`, method, '->', res);
+    if (res.error) {
+      throw res.error;
+    }
+    if ([null, undefined, 'null', 'undefined'].includes(res.result)) {
+      return;
+    }
+    return convertFromJsonObj(classConverter, JSON.parse(res.result));
+  };
+
+  // Intercept any RPC methods with a proxy
+  // This wraps 'request' with a method-call syntax wrapper
+  return new Proxy(
+    {},
+    {
+      get:
+        (_, rpcMethod: string) =>
+        (...params: any[]) => {
+          debug(`JsonRpcClient.constructor`, 'proxy', rpcMethod, '<-', params);
+          return request(rpcMethod, params);
+        },
+    },
+  ) as RemoteObject<T>;
+}

package/src/json-rpc/convert.test.ts

@@ -0,0 +1,15 @@
+import { ClassConverter } from './class_converter.js';
+import { convertFromJsonObj, convertToJsonObj } from './convert.js';
+import { TestNote } from './fixtures/test_state.js';
+
+import { Buffer } from 'buffer';
+
+const TEST_BASE64 = 'YmFzZTY0IGRlY29kZXI=';
+test('test an RPC function over client', () => {
+  const cc = new ClassConverter({ TestNote });
+  const buffer = Buffer.from(TEST_BASE64, 'base64');
+  expect(convertFromJsonObj(cc, convertToJsonObj(cc, buffer)).toString('base64')).toBe(TEST_BASE64);
+  const note = new TestNote('1');
+  expect(convertFromJsonObj(cc, convertToJsonObj(cc, note))).toBeInstanceOf(TestNote);
+  expect(convertFromJsonObj(cc, convertToJsonObj(cc, note)).toString()).toBe('1');
+});

package/src/json-rpc/convert.ts

@@ -0,0 +1,109 @@
+import { ClassConverter } from './class_converter.js';
+import { Buffer } from 'buffer';
+
+/**
+ * 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' && cc.isRegisteredClassName(obj.type)) {
+    return cc.toClassObj(obj);
+  }
+
+  // Is this an array?
+  if (Array.isArray(obj)) {
+    return obj.map((x: any) => convertFromJsonObj(cc, x));
+  }
+  // Is this a dictionary?
+  if (obj.constructor === 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 {
+  if (!obj) {
+    return obj; // Primitive type
+  }
+  // Is this a Node buffer?
+  if (obj instanceof Buffer) {
+    return { type: 'Buffer', data: obj.toString('base64') };
+  }
+
+  if (typeof obj === 'bigint') {
+    return {
+      type: 'bigint',
+      data: obj.toString(),
+    };
+  }
+
+  // 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));
+  }
+  // Is this a dictionary?
+  if (obj.constructor === Object) {
+    const newObj: any = {};
+    for (const key of Object.keys(obj)) {
+      newObj[key] = convertToJsonObj(cc, obj[key]);
+    }
+    return newObj;
+  }
+
+  // Leave alone, assume JSON primitive
+  return obj;
+}

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,3 @@
+export { ClassConverterInput, JsonEncodedClass, ClassConverter } from './class_converter.js';
+export { JsonRpcServer, JsonProxy } from './server/index.js';
+export { createJsonRpcClient, JsonStringify } from './client/index.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 { JsonRpcServer } from './json_rpc_server.js';
+export { JsonProxy } from './json_proxy.js';

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

@@ -0,0 +1,36 @@
+import { createDebugLogger } from '../../log/index.js';
+import { ClassConverter, ClassConverterInput } from '../class_converter.js';
+import { convertFromJsonObj, convertToJsonObj } from '../convert.js';
+import { assert, hasOwnProperty } from '../js_utils.js';
+
+const debug = createDebugLogger('json-rpc:json_proxy');
+
+/**
+ * Handles conversion of objects over the write.
+ * Delegates to a ClassConverter object.
+ */
+export class JsonProxy {
+  classConverter: ClassConverter;
+  constructor(private handler: object, stringClassMap: ClassConverterInput, objectClassMap: ClassConverterInput) {
+    this.classConverter = new ClassConverter(stringClassMap, objectClassMap);
+  }
+  /**
+   * Call an RPC method.
+   * @param methodName - The RPC method.
+   * @param jsonParams - The RPG parameters.
+   * @returns The remote result.
+   */
+  public async call(methodName: string, jsonParams: any[] = []) {
+    // Get access to our class members
+    const proto = Object.getPrototypeOf(this.handler);
+    assert(hasOwnProperty(proto, methodName), 'JsonProxy: Method not found!');
+    assert(Array.isArray(jsonParams), 'JsonProxy: Params not an array!');
+    // convert the params from json representation to classes
+    const convertedParams = jsonParams.map(param => convertFromJsonObj(this.classConverter, param));
+    debug('JsonProxy:call', methodName, '<-', convertedParams);
+    const rawRet = await (this.handler as any)[methodName](...convertedParams);
+    const ret = convertToJsonObj(this.classConverter, rawRet);
+    debug('JsonProxy:call', methodName, '->', ret);
+    return ret;
+  }
+}