@aztec/foundation 0.61.0 → 0.63.0

package/src/aztec-address/index.ts

@@ -1,9 +1,16 @@
+/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
 import { inspect } from 'util';
 
 import { Fr, fromBuffer } from '../fields/index.js';
 import { type BufferReader, FieldReader } from '../serialize/index.js';
 import { TypeRegistry } from '../serialize/type_registry.js';
+import { hexToBuffer } from '../string/index.js';
 
+/** Branding to ensure fields are not interchangeable types. */
+export interface AztecAddress {
+  /** Brand. */
+  _branding: 'AztecAddress';
+}
 /**
  * AztecAddress represents a 32-byte address in the Aztec Protocol.
  * It provides methods to create, manipulate, and compare addresses.
@@ -11,51 +18,90 @@ import { TypeRegistry } from '../serialize/type_registry.js';
  * It should have a value less than or equal to this max value.
  * This class also provides helper functions to convert addresses from strings, buffers, and other formats.
  */
-export class AztecAddress extends Fr {
-  constructor(buffer: Buffer) {
-    if (buffer.length !== 32) {
+export class AztecAddress {
+  private value: Fr;
+
+  constructor(buffer: Buffer | Fr) {
+    if ('length' in buffer && buffer.length !== 32) {
       throw new Error(`Invalid AztecAddress length ${buffer.length}.`);
     }
-    super(buffer);
+    this.value = new Fr(buffer);
   }
 
   [inspect.custom]() {
     return `AztecAddress<${this.toString()}>`;
   }
 
-  static override ZERO = new AztecAddress(Buffer.alloc(32));
+  static isAddress(str: string) {
+    return /^(0x)?[a-fA-F0-9]{64}$/.test(str);
+  }
+
+  static SIZE_IN_BYTES = Fr.SIZE_IN_BYTES;
+
+  static ZERO = new AztecAddress(Buffer.alloc(32, 0));
 
-  static override zero(): AztecAddress {
+  static zero(): AztecAddress {
     return AztecAddress.ZERO;
   }
 
-  static override fromBuffer(buffer: Buffer | BufferReader) {
-    return fromBuffer(buffer, AztecAddress);
+  static fromField(fr: Fr) {
+    return new AztecAddress(fr);
   }
 
-  static fromField(fr: Fr) {
-    return new AztecAddress(fr.toBuffer());
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    return new AztecAddress(fromBuffer(buffer, Fr));
   }
 
   static fromFields(fields: Fr[] | FieldReader) {
     const reader = FieldReader.asReader(fields);
-    return AztecAddress.fromField(reader.readField());
+    return new AztecAddress(reader.readField());
   }
 
   static fromBigInt(value: bigint) {
-    return AztecAddress.fromField(new Fr(value));
+    return new AztecAddress(new Fr(value));
+  }
+
+  static fromNumber(value: number) {
+    return new AztecAddress(new Fr(value));
+  }
+
+  static fromString(buf: string) {
+    return new AztecAddress(hexToBuffer(buf));
+  }
+
+  static random() {
+    return new AztecAddress(Fr.random());
+  }
+
+  get size() {
+    return this.value.size;
+  }
+
+  equals(other: AztecAddress) {
+    return this.value.equals(other.value);
+  }
+
+  isZero() {
+    return this.value.isZero();
+  }
+
+  toBuffer() {
+    return this.value.toBuffer();
+  }
+
+  toBigInt() {
+    return this.value.toBigInt();
   }
 
-  static override fromString(buf: string) {
-    const buffer = Buffer.from(buf.replace(/^0x/i, ''), 'hex');
-    return new AztecAddress(buffer);
+  toField() {
+    return this.value;
   }
 
-  static override random() {
-    return new AztecAddress(super.random().toBuffer());
+  toString() {
+    return this.value.toString();
   }
 
-  override toJSON() {
+  toJSON() {
     return {
       type: 'AztecAddress',
       value: this.toString(),

package/src/buffer/buffer32.ts

@@ -70,6 +70,10 @@ export class Buffer32 {
     return this.buffer.toString('hex');
   }
 
+  toJSON() {
+    return this.toString();
+  }
+
   public to0xString(): `0x${string}` {
     return `0x${this.buffer.toString('hex')}`;
   }
@@ -89,6 +93,7 @@ export class Buffer32 {
   public static fromBigInt(hash: bigint) {
     return new Buffer32(serializeBigInt(hash, Buffer32.SIZE));
   }
+
   public static fromField(hash: Fr) {
     return new Buffer32(serializeBigInt(hash.toBigInt()));
   }

package/src/config/env_var.ts

@@ -1,7 +1,7 @@
 export type EnvVar =
   | 'ACVM_BINARY_PATH'
   | 'ACVM_WORKING_DIRECTORY'
-  | 'APELLA_CONTRACT_ADDRESS'
+  | 'GOVERNANCE_CONTRACT_ADDRESS'
   | 'API_KEY'
   | 'API_PREFIX'
   | 'ARCHIVER_MAX_LOGS'
@@ -33,8 +33,11 @@ export type EnvVar =
   | 'BOT_TOKEN_SALT'
   | 'BOT_TX_INTERVAL_SECONDS'
   | 'BOT_TX_MINED_WAIT_SECONDS'
+  | 'BOT_MAX_CONSECUTIVE_ERRORS'
+  | 'BOT_STOP_WHEN_UNHEALTHY'
   | 'COINBASE'
   | 'DATA_DIRECTORY'
+  | 'DATA_STORE_MAP_SIZE_KB'
   | 'DEBUG'
   | 'DEPLOY_AZTEC_CONTRACTS_SALT'
   | 'DEPLOY_AZTEC_CONTRACTS'
@@ -44,8 +47,8 @@ export type EnvVar =
   | 'FEE_JUICE_CONTRACT_ADDRESS'
   | 'FEE_JUICE_PORTAL_CONTRACT_ADDRESS'
   | 'FEE_RECIPIENT'
-  | 'GEROUSIA_CONTRACT_ADDRESS'
-  | 'GEROUSIA_PAYLOAD_ADDRESS'
+  | 'GOVERNANCE_PROPOSER_CONTRACT_ADDRESS'
+  | 'GOVERNANCE_PROPOSER_PAYLOAD_ADDRESS'
   | 'INBOX_CONTRACT_ADDRESS'
   | 'L1_CHAIN_ID'
   | 'L1_PRIVATE_KEY'
@@ -55,12 +58,16 @@ export type EnvVar =
   | 'MNEMONIC'
   | 'NETWORK_NAME'
   | 'NETWORK'
-  | 'NOMISMATOKOPIO_CONTRACT_ADDRESS'
+  | 'COIN_ISSUER_CONTRACT_ADDRESS'
   | 'OTEL_EXPORTER_OTLP_METRICS_ENDPOINT'
   | 'OTEL_EXPORTER_OTLP_TRACES_ENDPOINT'
+  | 'OTEL_EXPORTER_OTLP_LOGS_ENDPOINT'
   | 'OTEL_SERVICE_NAME'
+  | 'OTEL_COLLECT_INTERVAL_MS'
+  | 'OTEL_EXPORT_TIMEOUT_MS'
   | 'OUTBOX_CONTRACT_ADDRESS'
   | 'P2P_BLOCK_CHECK_INTERVAL_MS'
+  | 'P2P_BLOCK_REQUEST_BATCH_SIZE'
   | 'P2P_ENABLED'
   | 'P2P_GOSSIPSUB_D'
   | 'P2P_GOSSIPSUB_DHI'
@@ -106,7 +113,6 @@ export type EnvVar =
   | 'PROVER_REQUIRED_CONFIRMATIONS'
   | 'PROVER_TEST_DELAY_MS'
   | 'PXE_BLOCK_POLLING_INTERVAL_MS'
-  | 'PXE_DATA_DIRECTORY'
   | 'PXE_L2_STARTING_BLOCK'
   | 'PXE_PROVER_ENABLED'
   | 'QUOTE_PROVIDER_BASIS_POINT_FEE'
@@ -127,12 +133,13 @@ export type EnvVar =
   | 'SEQ_PUBLISHER_PRIVATE_KEY'
   | 'SEQ_REQUIRED_CONFIRMATIONS'
   | 'SEQ_TX_POLLING_INTERVAL_MS'
-  | 'SYSSTIA_CONTRACT_ADDRESS'
+  | 'SEQ_ENFORCE_TIME_TABLE'
+  | 'REWARD_DISTRIBUTOR_CONTRACT_ADDRESS'
   | 'TELEMETRY'
   | 'TEST_ACCOUNTS'
   | 'TX_GOSSIP_VERSION'
   | 'TXE_PORT'
-  | 'VALIDATOR_ATTESTATIONS_POOLING_INTERVAL_MS'
+  | 'VALIDATOR_ATTESTATIONS_POLLING_INTERVAL_MS'
   | 'VALIDATOR_ATTESTATIONS_WAIT_TIMEOUT_MS'
   | 'VALIDATOR_DISABLED'
   | 'VALIDATOR_PRIVATE_KEY'
@@ -143,4 +150,11 @@ export type EnvVar =
   | 'VERIFIER_VIEM_POLLING_INTERVAL_MS'
   | 'L1_READER_VIEM_POLLING_INTERVAL_MS'
   | 'PROVER_VIEM_POLLING_INTERVAL_MS'
-  | 'SEQ_VIEM_POLLING_INTERVAL_MS';
+  | 'SEQ_VIEM_POLLING_INTERVAL_MS'
+  | 'WS_DB_MAP_SIZE_KB'
+  | 'WS_DATA_DIRECTORY'
+  | 'ETHEREUM_SLOT_DURATION'
+  | 'AZTEC_SLOT_DURATION'
+  | 'AZTEC_EPOCH_DURATION'
+  | 'AZTEC_TARGET_COMMITTEE_SIZE'
+  | 'AZTEC_EPOCH_PROOF_CLAIM_WINDOW_IN_L2_SLOTS';

package/src/crypto/index.ts

@@ -7,6 +7,7 @@ export * from './sha512/index.js';
 export * from './pedersen/index.js';
 export * from './poseidon/index.js';
 export * from './secp256k1-signer/index.js';
+export * from './keys/index.js';
 
 /**
  * Init the bb singleton. This constructs (if not already) the barretenberg sync api within bb.js itself.

package/src/crypto/keys/index.ts

@@ -0,0 +1,9 @@
+import { BarretenbergSync, RawBuffer } from '@aztec/bb.js';
+
+import { Fr } from '../../fields/fields.js';
+
+export function vkAsFieldsMegaHonk(input: Buffer): Fr[] {
+  return BarretenbergSync.getSingleton()
+    .acirVkAsFieldsMegaHonk(new RawBuffer(input))
+    .map(bbFr => Fr.fromBuffer(Buffer.from(bbFr.toBuffer()))); // TODO(#4189): remove this conversion
+}

package/src/eth-address/index.ts

@@ -13,13 +13,9 @@ import { TypeRegistry } from '../serialize/type_registry.js';
  * and can be serialized/deserialized from a buffer or BufferReader.
  */
 export class EthAddress {
-  /**
-   * The size of an Ethereum address in bytes.
-   */
+  /** The size of an Ethereum address in bytes. */
   public static SIZE_IN_BYTES = 20;
-  /**
-   * Represents a zero Ethereum address with 20 bytes filled with zeros.
-   */
+  /** Represents a zero Ethereum address with 20 bytes filled with zeros. */
   public static ZERO = new EthAddress(Buffer.alloc(EthAddress.SIZE_IN_BYTES));
 
   constructor(private buffer: Buffer) {

package/src/eth-signature/eth_signature.ts

@@ -45,6 +45,10 @@ export class Signature {
     return new Signature(r, s, v, isEmpty);
   }
 
+  static isValid0xString(sig: `0x${string}`): boolean {
+    return /^0x[0-9a-f]{129,}$/i.test(sig);
+  }
+
   /**
    * A seperate method exists for this as when signing locally with viem, as when
    * parsing from viem, we can expect the v value to be a u8, rather than our
@@ -106,4 +110,8 @@ export class Signature {
       isEmpty: this.isEmpty,
     };
   }
+
+  toJSON() {
+    return this.to0xString();
+  }
 }

package/src/fields/fields.ts

@@ -182,9 +182,7 @@ function fromHexString<T extends BaseField>(buf: string, f: DerivedField<T>) {
   return new f(buffer);
 }
 
-/**
- * Branding to ensure fields are not interchangeable types.
- */
+/** Branding to ensure fields are not interchangeable types. */
 export interface Fr {
   /** Brand. */
   _branding: 'Fr';
@@ -302,6 +300,7 @@ export class Fr extends BaseField {
     return Fr.fromBuffer(rootBuf);
   }
 
+  // TODO(palla/schemas): Use toString instead of structured type
   toJSON() {
     return {
       type: 'Fr',

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

@@ -0,0 +1,81 @@
+import { format } from 'util';
+
+import { type DebugLogger, createDebugLogger } from '../../log/index.js';
+import { NoRetryError, makeBackoff, retry } from '../../retry/index.js';
+import { jsonStringify } from '../convert.js';
+
+const log = 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 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,
+  noRetry = false,
+) {
+  log.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) {
+    const errorMessage = `(JSON-RPC PROPAGATED) (host ${host}) (method ${rpcMethod}) (code ${resp.status}) ${responseJson.error.message}`;
+    if (noRetry || (resp.status >= 400 && resp.status < 500)) {
+      throw new NoRetryError(errorMessage);
+    } else {
+      throw new Error(errorMessage);
+    }
+  }
+
+  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[], defaultNoRetry: boolean, log?: DebugLogger) {
+  return async (host: string, rpcMethod: string, body: any, useApiEndpoints: boolean, noRetry?: boolean) => {
+    return await retry(
+      () => defaultFetch(host, rpcMethod, body, useApiEndpoints, noRetry ?? defaultNoRetry),
+      `JsonRpcClient request ${rpcMethod} to ${host}`,
+      makeBackoff(retries),
+      log,
+      false,
+    );
+  };
+}

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

@@ -1 +1,2 @@
-export { createJsonRpcClient, defaultFetch, makeFetch } from './json_rpc_client.js';
+export * from './safe_json_rpc_client.js';
+export * from './fetch.js';

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

@@ -0,0 +1,61 @@
+import { format } from 'util';
+
+import { createDebugLogger } from '../../log/logger.js';
+import { type ApiSchema, type ApiSchemaFor, schemaHasMethod } from '../../schemas/api.js';
+import { defaultFetch } from './fetch.js';
+
+/**
+ * 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>,
+  useApiEndpoints: boolean = false,
+  namespaceMethods?: string | false,
+  fetch = defaultFetch,
+  log = createDebugLogger('json-rpc:client'),
+): T {
+  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 res = await fetch(host, method, body, useApiEndpoints);
+    log.debug(format(`result`, method, res));
+
+    if (res.error) {
+      throw res.error;
+    }
+    // TODO(palla/schemas): Find a better way to handle null responses (JSON.stringify(null) is string "null").
+    if ([null, undefined, 'null', 'undefined'].includes(res.result)) {
+      return;
+    }
+
+    return (schema as ApiSchema)[methodName].returnType().parse(res.result);
+  };
+
+  // Intercept any RPC methods with a proxy
+  const proxy = new Proxy(
+    {},
+    {
+      get: (target, method: string) => {
+        if (['then', 'catch'].includes(method)) {
+          return Reflect.get(target, method);
+        }
+        return (...params: any[]) => request(method, params);
+      },
+    },
+  ) as T;
+
+  return proxy;
+}

package/src/json-rpc/convert.ts

@@ -1,163 +1,50 @@
 import { Buffer } from 'buffer';
-import cloneDeepWith from 'lodash.clonedeepwith';
 
-import { type ClassConverter } from './class_converter.js';
+import { type ZodFor } from '../schemas/types.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'.
+ * 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.
  */
-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;
+export function jsonParseWithSchema<T>(json: string, schema: ZodFor<T>): T {
+  return schema.parse(JSON.parse(json));
 }
 
 /**
- * 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.
+ * 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 {
+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,
+    (_key, value) => {
+      if (typeof value === 'bigint') {
+        return value.toString();
+      } else if (typeof value === 'object' && 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,
   );
 }
 
 /**
- * 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.
+ * Calls jsonStringify but swallows errors.
+ * Use for logging, when you don't want to potentially introduce another thing that throws.
  */
-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;
+export function tryJsonStringify(obj: any, prettify?: boolean): string | undefined {
+  try {
+    return jsonStringify(obj, prettify);
+  } catch (e) {
+    return undefined;
   }
-
-  // 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 (Buffer.isBuffer(obj)) {
-    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;
 }