@0xbow/privacy-pools-core-sdk 0.0.0-b21c14ba

package/src/circuits/circuits.impl.ts

@@ -0,0 +1,232 @@
+import { CircuitInitialization, FetchArtifact } from "../internal.js";
+import {
+  Binaries,
+  CircuitArtifacts,
+  CircuitName,
+  CircuitNameString,
+  CircuitsInterface,
+  circuitToAsset,
+  Version,
+  VersionString,
+} from "./circuits.interface.js";
+import { importFetchVersionedArtifact } from "./fetchArtifacts.js";
+
+interface CircuitOptions {
+  baseUrl?: string;
+  browser?: boolean;
+}
+
+/**
+ * Class representing circuit management and artifact handling.
+ * Implements the CircuitsInterface.
+ */
+export class Circuits implements CircuitsInterface {
+  /**
+   * Indicates whether the circuits have been initialized.
+   * @type {boolean}
+   * @protected
+   */
+  protected initialized: boolean = false;
+  /**
+   * The version of the circuit artifacts being used.
+   * @type {VersionString}
+   * @protected
+   */
+  protected version: VersionString = Version.Latest;
+  /**
+   * The binaries containing circuit artifacts such as wasm, vkey, and zkey files.
+   * @type {Binaries}
+   * @protected
+   */
+  protected binaries!: Binaries;
+  /**
+   * The base URL for fetching circuit artifacts.
+   * @type {string}
+   * @protected
+   */
+  protected baseUrl: string = import.meta.url;
+
+  protected readonly browser: boolean = true;
+
+  /**
+   * Constructor to initialize the Circuits class with an optional custom base URL.
+   * @param {string} [options.baseUrl] - The base URL for fetching circuit artifacts (optional).
+   * @param {boolean} [options.browser] - Controls how the circuits will be loaded, using either `fetch` if true or `fs` otherwise. Defaults to true.
+   */
+  constructor(options?: CircuitOptions) {
+    if (options?.baseUrl) {
+      this.baseUrl = options.baseUrl;
+    }
+    if (options?.browser !== undefined) {
+      this.browser = options.browser;
+    }
+  }
+
+  /**
+   * Determines whether the environment is a browser.
+   * @returns {boolean} True if running in a browser environment, false otherwise.
+   * @protected
+   */
+  _browser(): boolean {
+    return typeof window !== "undefined";
+  }
+
+  /**
+   * Initializes the circuit manager with binaries and a version.
+   * @param {Binaries} binaries - The binaries containing circuit artifacts.
+   * @param {VersionString} version - The version of the circuit artifacts.
+   * @protected
+   */
+  protected _initialize(binaries: Binaries, version: VersionString) {
+    this.binaries = binaries;
+    this.version = version;
+    this.initialized = true;
+  }
+
+  /**
+   * Handles initialization of circuit artifacts, fetching them if necessary.
+   * @param {VersionString} [version=Version.latest] - The version of the circuit artifacts.
+   * @throws {CircuitInitialization} If an error occurs during initialization.
+   * @protected
+   * @async
+   */
+  protected async _handleInitialization(
+    version: VersionString = Version.Latest,
+  ) {
+    if (!this.initialized || this.binaries === undefined) {
+      try {
+        await this.initArtifacts(version);
+      } catch (e) {
+        if (e instanceof FetchArtifact) {
+          throw new CircuitInitialization(`${e.name}: ${e.message}`);
+        } else {
+          console.error(e);
+          throw new CircuitInitialization(`UnknownError: ${e}`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Fetches a versioned artifact from a given path.
+   * @param {string} artifactPath - The path to the artifact.
+   * @param {VersionString} version - The version of the artifact.
+   * @returns {Promise<Uint8Array>} A promise that resolves to the artifact as a Uint8Array.
+   * @throws {FetchArtifact} If the artifact cannot be fetched.
+   * @protected
+   * @async
+   */
+  async _fetchVersionedArtifact(artifactPath: string): Promise<Uint8Array> {
+    const artifactUrl = new URL(artifactPath, this.baseUrl);
+    const { fetchVersionedArtifact } = await importFetchVersionedArtifact(
+      this.browser,
+    );
+    return fetchVersionedArtifact(artifactUrl);
+  }
+
+  /**
+   * Downloads and returns the circuit artifacts for a specific circuit.
+   * @param {CircuitNameString} circuitName - The name of the circuit.
+   * @returns {Promise<CircuitArtifacts>} A promise that resolves to the circuit artifacts.
+   * @protected
+   * @async
+   */
+  async _downloadCircuitArtifacts(
+    circuitName: CircuitNameString,
+  ): Promise<CircuitArtifacts> {
+    const assetName = circuitToAsset[circuitName];
+
+    const [wasm, vkey, zkey] = await Promise.all([
+      this._fetchVersionedArtifact(["artifacts", assetName.wasm].join("/")),
+      this._fetchVersionedArtifact(["artifacts", assetName.vkey].join("/")),
+      this._fetchVersionedArtifact(["artifacts", assetName.zkey].join("/")),
+    ]);
+    return { wasm, vkey, zkey };
+  }
+
+  /**
+   * Downloads all circuit artifacts for the specified version.
+   * @param {VersionString} version - The version of the artifacts.
+   * @returns {Promise<Binaries>} A promise that resolves to the binaries containing all circuit artifacts.
+   * @async
+   */
+  // prettier-ignore
+  async downloadArtifacts(version: VersionString): Promise<Binaries> { // eslint-disable-line @typescript-eslint/no-unused-vars
+    const [commitment, withdraw] = await Promise.all([
+      this._downloadCircuitArtifacts(CircuitName.Commitment),
+      this._downloadCircuitArtifacts(CircuitName.Withdraw),
+    ]);
+    return {
+      commitment,
+      withdraw,
+    } as Binaries;
+  }
+
+  /**
+   * Initializes the circuit artifacts for the specified version.
+   * @param {VersionString} version - The version of the artifacts.
+   * @returns {Promise<void>} A promise that resolves when initialization is complete.
+   * @async
+   */
+  async initArtifacts(version: VersionString): Promise<void> {
+    const binaries = await this.downloadArtifacts(version);
+    this._initialize(binaries, version);
+  }
+
+  /**
+   * Retrieves the verification key for a specified circuit.
+   * @param {CircuitNameString} circuitName - The name of the circuit.
+   * @param {VersionString} [version=Version.latest] - The version of the artifacts.
+   * @returns {Promise<Uint8Array>} A promise that resolves to the verification key.
+   * @async
+   */
+  async getVerificationKey(
+    circuitName: CircuitNameString,
+    version: VersionString = Version.Latest,
+  ): Promise<Uint8Array> {
+    await this._handleInitialization(version);
+    const artifacts = this.binaries[circuitName];
+    if (!artifacts) {
+      throw new CircuitInitialization(`Circuit artifacts not found for ${circuitName}`);
+    }
+    return artifacts.vkey;
+  }
+
+  /**
+   * Retrieves the proving key for a specified circuit.
+   * @param {CircuitNameString} circuitName - The name of the circuit.
+   * @param {VersionString} [version=Version.latest] - The version of the artifacts.
+   * @returns {Promise<Uint8Array>} A promise that resolves to the proving key.
+   * @async
+   */
+  async getProvingKey(
+    circuitName: CircuitNameString,
+    version: VersionString = Version.Latest,
+  ): Promise<Uint8Array> {
+    await this._handleInitialization(version);
+    const artifacts = this.binaries[circuitName];
+    if (!artifacts) {
+      throw new CircuitInitialization(`Circuit artifacts not found for ${circuitName}`);
+    }
+    return artifacts.zkey;
+  }
+
+  /**
+   * Retrieves the wasm file for a specified circuit.
+   * @param {CircuitNameString} circuitName - The name of the circuit.
+   * @param {VersionString} [version=Version.latest] - The version of the artifacts.
+   * @returns {Promise<Uint8Array>} A promise that resolves to the wasm file.
+   * @async
+   */
+  async getWasm(
+    circuitName: CircuitNameString,
+    version: VersionString = Version.Latest,
+  ): Promise<Uint8Array> {
+    await this._handleInitialization(version);
+    const artifacts = this.binaries[circuitName];
+    if (!artifacts) {
+      throw new CircuitInitialization(`Circuit artifacts not found for ${circuitName}`);
+    }
+    return artifacts.wasm;
+  }
+}

package/src/circuits/circuits.interface.ts

@@ -0,0 +1,166 @@
+/**
+ * Enum representing available versions of circuit artifacts.
+ */
+export enum Version {
+  /**
+   * The latest version of the circuit artifacts.
+   */
+  Latest = "latest",
+}
+
+/**
+ * Type representing a version string, which is a string literal derived from the Version enum.
+ */
+export type VersionString = `${Version}`;
+
+/**
+ * Enum representing the names of available circuits.
+ */
+export enum CircuitName {
+  /**
+   * Circuit for commitments.
+   */
+  Commitment = "commitment",
+  /**
+   * Circuit for Merkle tree operations.
+   */
+  MerkleTree = "merkleTree",
+  /**
+   * Circuit for withdrawal operations.
+   */
+  Withdraw = "withdraw",
+}
+
+/**
+ * Type representing a circuit name string, which is a string literal derived from the CircuitName enum.
+ */
+export type CircuitNameString = `${CircuitName}`;
+
+/**
+ * Interface representing the artifacts associated with a circuit.
+ */
+export interface CircuitArtifacts {
+  /**
+   * The precompiled wasm file for the circuit.
+   * @type {Uint8Array}
+   */
+  wasm: Uint8Array;
+  /**
+   * The verification key for the circuit.
+   * @type {Uint8Array}
+   */
+  vkey: Uint8Array;
+  /**
+   * The proving key for the circuit.
+   * @type {Uint8Array}
+   */
+  zkey: Uint8Array;
+}
+
+/**
+ * Type representing the mapping of circuit names to their respective asset file paths.
+ */
+export type Circ2Asset = {
+  [key in CircuitName]: {
+    /**
+     * The filename of the compiled wasm file.
+     */
+    wasm: string;
+    /**
+     * The filename of the verification key file.
+     */
+    vkey: string;
+    /**
+     * The filename of the proving key file.
+     */
+    zkey: string;
+  };
+};
+
+/**
+ * Mapping of circuit names to their respective asset file paths.
+ * @const
+ */
+export const circuitToAsset: Circ2Asset = {
+  [CircuitName.Commitment]: {
+    wasm: "commitment.wasm",
+    vkey: "commitment.vkey",
+    zkey: "commitment.zkey",
+  },
+  [CircuitName.MerkleTree]: {
+    wasm: "merkleTree.wasm",
+    vkey: "merkleTree.vkey",
+    zkey: "merkleTree.zkey",
+  },
+  [CircuitName.Withdraw]: {
+    wasm: "withdraw.wasm",
+    vkey: "withdraw.vkey",
+    zkey: "withdraw.zkey",
+  },
+} as const;
+
+/**
+ * Type representing the mapping of circuit name strings to their associated circuit artifacts.
+ */
+export interface Binaries {
+  commitment: CircuitArtifacts;
+  withdraw: CircuitArtifacts;
+  merkleTree?: CircuitArtifacts;
+}
+
+/**
+ * Interface defining the methods required for managing circuits and their artifacts.
+ */
+export interface CircuitsInterface {
+  /**
+   * Downloads all artifacts for the specified version of circuits.
+   * @param {VersionString} version - The version of the artifacts to download.
+   * @returns {Promise<Binaries>} A promise that resolves to the binaries containing all circuit artifacts.
+   * @async
+   */
+  downloadArtifacts(version: VersionString): Promise<Binaries>;
+
+  /**
+   * Initializes the artifacts for the specified version of circuits.
+   * @param {VersionString} version - The version of the artifacts to initialize.
+   * @returns {Promise<void>} A promise that resolves when initialization is complete.
+   * @async
+   */
+  initArtifacts(version: VersionString): Promise<void>;
+
+  /**
+   * Retrieves the verification key for a specified circuit.
+   * @param {CircuitNameString} circuitName - The name of the circuit.
+   * @param {VersionString} [version] - The version of the artifacts (defaults to the latest).
+   * @returns {Promise<Uint8Array>} A promise that resolves to the verification key.
+   * @async
+   */
+  getVerificationKey(
+    circuitName: CircuitNameString,
+    version?: VersionString,
+  ): Promise<Uint8Array>;
+
+  /**
+   * Retrieves the proving key for a specified circuit.
+   * @param {CircuitNameString} circuitName - The name of the circuit.
+   * @param {VersionString} [version] - The version of the artifacts (defaults to the latest).
+   * @returns {Promise<Uint8Array>} A promise that resolves to the proving key.
+   * @async
+   */
+  getProvingKey(
+    circuitName: CircuitNameString,
+    version?: VersionString,
+  ): Promise<Uint8Array>;
+
+  /**
+   * Retrieves the wasm file for a specified circuit.
+   * @param {CircuitNameString} circuitName - The name of the circuit.
+   * @param {VersionString} [version] - The version of the artifacts (defaults to the latest).
+   * @returns {Promise<Uint8Array>} A promise that resolves to the wasm file.
+   * @async
+   */
+  getWasm(
+    circuitName: CircuitNameString,
+    version?: VersionString,
+  ): Promise<Uint8Array>;
+}

package/src/circuits/fetchArtifacts.esm.ts

@@ -0,0 +1,12 @@
+import { FetchArtifact } from "../exceptions/fetchArtifacts.exception.js";
+
+export async function fetchVersionedArtifact(
+  artifactUrl: URL,
+): Promise<Uint8Array> {
+  const res = await fetch(artifactUrl);
+  if (res.status !== 200) {
+    throw new FetchArtifact(artifactUrl);
+  }
+  const aBuf = await res.arrayBuffer();
+  return new Uint8Array(aBuf);
+}

package/src/circuits/fetchArtifacts.node.ts

@@ -0,0 +1,23 @@
+import { FetchArtifact } from "../exceptions/fetchArtifacts.exception.js";
+
+export async function fetchVersionedArtifact(
+  artifactUrl: URL,
+): Promise<Uint8Array> {
+  try {
+    const fs = (await import("fs")).default;
+    const readPromise: Promise<Buffer> = new Promise((resolve, reject) => {
+      fs.readFile(artifactUrl.pathname, (err, data) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve(data);
+        }
+      });
+    });
+    const buf = await readPromise;
+    return new Uint8Array(buf);
+  } catch (error) {
+    console.error(error);
+    throw new FetchArtifact(artifactUrl);
+  }
+}

package/src/circuits/fetchArtifacts.ts

@@ -0,0 +1,7 @@
+export async function importFetchVersionedArtifact(isBrowser: boolean) {
+  if (isBrowser) {
+    return import(`./fetchArtifacts.esm.js`);
+  } else {
+    return import(`./fetchArtifacts.node.js`);
+  }
+}

package/src/circuits/index.ts

@@ -0,0 +1,2 @@
+export { Circuits } from "./circuits.impl.js";
+export type { CircuitsInterface } from "./circuits.interface.js";

package/src/constants.ts

@@ -0,0 +1,3 @@
+export const SNARK_SCALAR_FIELD_STRING =
+  "21888242871839275222246405745257275088548364400416034343698204186575808495617";
+export const SNARK_SCALAR_FIELD = BigInt(SNARK_SCALAR_FIELD_STRING);