@unlink-xyz/core 0.1.0 → 0.1.2

package/prover/prover.ts

@@ -0,0 +1,405 @@
+import { Groth16Proof, PublicSignals } from "snarkjs";
+import * as snarkjs from "snarkjs";
+
+import { CoreError } from "../errors.js";
+import {
+  ArtifactType,
+  buildArtifactUrl,
+  DEFAULT_CONFIG,
+  getLocalArtifactPath,
+  Runtime,
+} from "./config.js";
+import {
+  getCircuitConfig,
+  SUPPORTED_CIRCUITS,
+  type CircuitConfig,
+} from "./registry.js";
+
+// Cache for loaded artifacts to avoid reloading 18MB of files on every call
+// Now keyed by circuit name to support multiple circuits
+const artifactCache: Record<
+  string,
+  {
+    wasm: Uint8Array;
+    zkey: Uint8Array;
+    vkey: VerificationKey;
+  }
+> = {};
+
+export interface JoinsplitProof {
+  readonly proof: Groth16Proof;
+  readonly publicSignals: PublicSignals;
+}
+
+export interface VerificationKey {
+  readonly protocol: string;
+  readonly curve: string;
+  readonly nPublic: number;
+  readonly vk_alpha_1: string[];
+  readonly vk_beta_2: string[][];
+  readonly vk_gamma_2: string[][];
+  readonly vk_delta_2: string[][];
+  readonly vk_alphabeta_12: string[][][];
+  readonly IC: string[][];
+}
+
+export interface JoinsplitProofInput {
+  readonly merkleRoot: bigint;
+  readonly boundParamsHash: bigint;
+  readonly nullifiers: bigint[];
+  readonly commitmentsOut: bigint[];
+  readonly token: bigint;
+  readonly publicKey: bigint[];
+  readonly signature: bigint[];
+  readonly randomIn: bigint[];
+  readonly valueIn: bigint[];
+  readonly pathElements: bigint[][];
+  readonly leavesIndices: bigint[];
+  readonly nullifyingKey: bigint;
+  readonly npkOut: bigint[];
+  readonly valueOut: bigint[];
+}
+
+/**
+ * Select the appropriate circuit based on input/output dimensions
+ * @param inputs Number of inputs (nullifiers)
+ * @param outputs Number of outputs (commitments)
+ * @returns Circuit configuration
+ * @throws CoreError if no matching circuit is found
+ */
+function selectCircuit(inputs: number, outputs: number): CircuitConfig {
+  const config = getCircuitConfig(inputs, outputs);
+
+  if (!config) {
+    throw new CoreError(
+      `No circuit available for ${inputs} inputs and ${outputs} outputs. ` +
+        `Supported circuits: ${SUPPORTED_CIRCUITS.join(", ")}`,
+    );
+  }
+
+  return config;
+}
+
+/**
+ * Fetch circuit artifacts for a specific circuit
+ * Supports both browser (remote) and Node.js (local) environments
+ * @param circuitName Full circuit name (e.g., "joinsplit_2x3_16")
+ * @returns Artifacts object with wasm, zkey, and vkey
+ */
+async function fetchCircuitArtifacts(circuitName: string) {
+  // Check cache first
+  if (artifactCache[circuitName]) {
+    return artifactCache[circuitName];
+  }
+
+  let wasm: Uint8Array | undefined;
+  let zkey: Uint8Array | undefined;
+  let vkey: VerificationKey | undefined;
+
+  // Browser environment: fetch from artifact server
+  if (Runtime.isBrowser()) {
+    try {
+      const baseUrl = DEFAULT_CONFIG.rpcUrl;
+
+      const wasmUrl = buildArtifactUrl(circuitName, ArtifactType.WASM, baseUrl);
+      const zkeyUrl = buildArtifactUrl(circuitName, ArtifactType.ZKEY, baseUrl);
+      const vkeyUrl = buildArtifactUrl(circuitName, ArtifactType.VKEY, baseUrl);
+
+      const [wasmRes, zkeyRes, vkeyRes] = await Promise.all([
+        fetch(wasmUrl),
+        fetch(zkeyUrl),
+        fetch(vkeyUrl),
+      ]);
+
+      if (!wasmRes.ok || !zkeyRes.ok || !vkeyRes.ok) {
+        throw new CoreError(
+          `Failed to fetch artifacts for ${circuitName} from ${baseUrl}. ` +
+            `Status: wasm=${wasmRes.status}, zkey=${zkeyRes.status}, vkey=${vkeyRes.status}`,
+        );
+      }
+
+      wasm = new Uint8Array(await wasmRes.arrayBuffer());
+      zkey = new Uint8Array(await zkeyRes.arrayBuffer());
+      vkey = await vkeyRes.json();
+    } catch (error) {
+      throw new CoreError(
+        `Failed to fetch artifacts from server for ${circuitName}: ${(error as Error).message}`,
+      );
+    }
+  }
+  // Node.js environment: try local file paths
+  else {
+    const wasmCandidates = getLocalArtifactPath(circuitName, ArtifactType.WASM);
+    const zkeyCandidates = getLocalArtifactPath(circuitName, ArtifactType.ZKEY);
+    const vkeyCandidates = getLocalArtifactPath(circuitName, ArtifactType.VKEY);
+
+    let wasmLoaded = false;
+    for (const candidate of wasmCandidates) {
+      try {
+        wasm = await readBinaryResource(candidate);
+        wasmLoaded = true;
+        break;
+      } catch {
+        // Try next candidate
+      }
+    }
+
+    if (!wasmLoaded) {
+      throw new CoreError(
+        `Could not find WASM artifact for ${circuitName}. ` +
+          `Please run 'pnpm run build:all' in the circuits package.`,
+      );
+    }
+
+    // Load zkey
+    let zkeyLoaded = false;
+    for (const candidate of zkeyCandidates) {
+      try {
+        zkey = await readBinaryResource(candidate);
+        zkeyLoaded = true;
+        break;
+      } catch {
+        // Try next candidate
+      }
+    }
+
+    if (!zkeyLoaded) {
+      throw new CoreError(
+        `Could not find zkey artifact for ${circuitName}. ` +
+          `Please run 'pnpm run build:all' in the circuits package.`,
+      );
+    }
+
+    // Load vkey
+    let vkeyLoaded = false;
+    for (const candidate of vkeyCandidates) {
+      try {
+        const vkeyText = await readTextResource(candidate);
+        vkey = JSON.parse(vkeyText);
+        vkeyLoaded = true;
+        break;
+      } catch {
+        // Try next candidate
+      }
+    }
+
+    if (!vkeyLoaded) {
+      throw new CoreError(
+        `Could not find verification key for ${circuitName}. ` +
+          `Please run 'pnpm run build:all' in the circuits package.`,
+      );
+    }
+  }
+
+  // Verify all artifacts were loaded
+  if (!wasm || !zkey || !vkey) {
+    throw new CoreError(
+      `Failed to load all artifacts for ${circuitName}. ` +
+        `Missing: ${!wasm ? "wasm " : ""}${!zkey ? "zkey " : ""}${!vkey ? "vkey" : ""}`,
+    );
+  }
+
+  // Cache the artifacts for future calls
+  // TypeScript now knows these are defined after the check above
+  const artifacts = { wasm, zkey, vkey };
+  artifactCache[circuitName] = artifacts;
+
+  return artifacts;
+}
+
+async function readBinaryResource(relativePath: string): Promise<Uint8Array> {
+  const url = new URL(relativePath, import.meta.url);
+
+  try {
+    if (url.protocol === "file:") {
+      const fs = (await import("fs")).default;
+      const readPromise: Promise<Buffer> = new Promise((resolve, reject) => {
+        fs.readFile(url.pathname, (err, data) => {
+          if (err) {
+            reject(err);
+          } else {
+            resolve(data);
+          }
+        });
+      });
+      const buf = await readPromise;
+      return new Uint8Array(buf);
+    }
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new CoreError(
+        `failed to fetch ${relativePath}: ${response.statusText}`,
+      );
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  } catch (error) {
+    throw new CoreError(
+      `failed to read binary resource ${relativePath}: ${
+        (error as Error).message
+      }`,
+    );
+  }
+}
+
+async function readTextResource(relativePath: string): Promise<string> {
+  const url = new URL(relativePath, import.meta.url);
+  if (url.protocol === "file:") {
+    const fs = (await import("fs")).default;
+    const readPromise: Promise<Buffer> = new Promise((resolve, reject) => {
+      fs.readFile(url.pathname, (err, data) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve(data);
+        }
+      });
+    });
+    const buf = await readPromise;
+    return buf.toString("utf-8");
+  }
+
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new CoreError(
+      `failed to fetch ${relativePath}: ${response.statusText}`,
+    );
+  }
+  return response.text();
+}
+
+export async function proveTransaction(
+  input: JoinsplitProofInput,
+): Promise<JoinsplitProof> {
+  try {
+    // Auto-detect circuit based on input dimensions
+    const nInputs = input.nullifiers.length;
+    const nOutputs = input.commitmentsOut.length;
+
+    const circuit = selectCircuit(nInputs, nOutputs);
+
+    // Fetch circuit artifacts (wasm and zkey)
+    const { wasm, vkey, zkey } = await fetchCircuitArtifacts(circuit.name);
+
+    const inputSignals = input as unknown as Record<
+      string,
+      bigint | bigint[] | string
+    >;
+
+    const { proof, publicSignals } = await snarkjs.groth16.fullProve(
+      inputSignals,
+      wasm,
+      zkey,
+    );
+
+    // Additional verification step (optional)
+    const isValid = await snarkjs.groth16.verify(vkey, publicSignals, proof);
+    if (!isValid) {
+      throw new CoreError("generated proof is invalid");
+    }
+
+    return {
+      proof,
+      publicSignals,
+    };
+  } catch (error) {
+    throw new CoreError("proof generation failed: " + (error as Error).message);
+  }
+}
+
+/**
+ * Get verification key for a specific circuit configuration
+ * @param inputs Number of inputs (nullifiers)
+ * @param outputs Number of outputs (commitments)
+ * @returns Verification key for the circuit
+ */
+export async function getVerificationKey(
+  inputs: number,
+  outputs: number,
+): Promise<VerificationKey> {
+  try {
+    const circuit = selectCircuit(inputs, outputs);
+    const { vkey } = await fetchCircuitArtifacts(circuit.name);
+    return vkey;
+  } catch (error) {
+    throw new CoreError(
+      "failed to load verification key: " + (error as Error).message,
+    );
+  }
+}
+
+/**
+ * Verify a proof with public signals
+ * Auto-detects the circuit from the public signals structure
+ * @param proof Groth16 proof
+ * @param publicSignals Public signals array
+ * @returns True if proof is valid
+ */
+export async function verifyProof(
+  proof: Groth16Proof,
+  publicSignals: PublicSignals,
+): Promise<boolean> {
+  try {
+    // Public signals structure: [merkleRoot, boundParamsHash, ...nullifiers, ...commitments]
+    // We need to determine the circuit from the length
+    // This is tricky without additional context, so we'll need to try to infer
+    // or require explicit circuit specification
+
+    // For now, extract nullifier and commitment counts from the public signals
+    // The caller should know this information, but we can make an educated guess
+    // based on the total length and circuit registry
+
+    // Length = 2 (root + hash) + nInputs + nOutputs
+    const totalLength = publicSignals.length;
+    const variableCount = totalLength - 2; // Remove merkleRoot and boundParamsHash
+
+    // Try to find a matching circuit
+    let vkey: VerificationKey | null = null;
+    for (const circuitKey of SUPPORTED_CIRCUITS) {
+      const parts = circuitKey.split("x");
+      const config = getCircuitConfig(parseInt(parts[0]!), parseInt(parts[1]!));
+      if (config && config.inputs + config.outputs === variableCount) {
+        const artifacts = await fetchCircuitArtifacts(config.name);
+        vkey = artifacts.vkey;
+        break;
+      }
+    }
+
+    if (!vkey) {
+      throw new CoreError(
+        `Could not determine circuit from ${totalLength} public signals`,
+      );
+    }
+
+    return await snarkjs.groth16.verify(vkey, publicSignals, proof);
+  } catch (error) {
+    throw new CoreError(
+      "proof verification failed: " + (error as Error).message,
+    );
+  }
+}
+
+/**
+ * Verify a proof with explicit circuit specification
+ * Preferred method when you know the circuit dimensions
+ * @param proof Groth16 proof
+ * @param publicSignals Public signals array
+ * @param inputs Number of inputs (nullifiers)
+ * @param outputs Number of outputs (commitments)
+ * @returns True if proof is valid
+ */
+export async function verifyProofWithCircuit(
+  proof: Groth16Proof,
+  publicSignals: PublicSignals,
+  inputs: number,
+  outputs: number,
+): Promise<boolean> {
+  try {
+    const circuit = selectCircuit(inputs, outputs);
+    const { vkey } = await fetchCircuitArtifacts(circuit.name);
+    return await snarkjs.groth16.verify(vkey, publicSignals, proof);
+  } catch (error) {
+    throw new CoreError(
+      "proof verification failed: " + (error as Error).message,
+    );
+  }
+}

package/prover/registry.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  CIRCUIT_REGISTRY,
+  getCircuitConfig,
+  isCircuitSupported,
+  SUPPORTED_CIRCUITS,
+  type CircuitKey,
+} from "./registry.js";
+
+describe("Circuit Registry", () => {
+  it("should have all expected circuits", () => {
+    const expectedCircuits: CircuitKey[] = ["1x1", "1x2", "2x3", "3x3"];
+    expect(SUPPORTED_CIRCUITS).toEqual(
+      expect.arrayContaining(expectedCircuits),
+    );
+  });
+
+  it("should correctly map circuit keys to configurations", () => {
+    const config2x3 = CIRCUIT_REGISTRY["2x3"];
+    expect(config2x3).toBeDefined();
+    expect(config2x3.name).toBe("joinsplit_2x3_16");
+    expect(config2x3.inputs).toBe(2);
+    expect(config2x3.outputs).toBe(3);
+    expect(config2x3.depth).toBe(16);
+  });
+
+  describe("getCircuitConfig", () => {
+    it("should return config for valid circuit dimensions", () => {
+      const config = getCircuitConfig(2, 3);
+      expect(config).toBeDefined();
+      expect(config?.name).toBe("joinsplit_2x3_16");
+      expect(config?.inputs).toBe(2);
+      expect(config?.outputs).toBe(3);
+    });
+
+    it("should return undefined for unsupported dimensions", () => {
+      const config = getCircuitConfig(4, 5);
+      expect(config).toBeUndefined();
+    });
+
+    it("should handle all supported circuit dimensions", () => {
+      const testCases = [
+        { inputs: 1, outputs: 1, name: "joinsplit_1x1_16" },
+        { inputs: 1, outputs: 2, name: "joinsplit_1x2_16" },
+        { inputs: 2, outputs: 3, name: "joinsplit_2x3_16" },
+        { inputs: 3, outputs: 3, name: "joinsplit_3x3_16" },
+      ];
+
+      for (const testCase of testCases) {
+        const config = getCircuitConfig(testCase.inputs, testCase.outputs);
+        expect(config).toBeDefined();
+        expect(config?.name).toBe(testCase.name);
+        expect(config?.inputs).toBe(testCase.inputs);
+        expect(config?.outputs).toBe(testCase.outputs);
+      }
+    });
+  });
+
+  describe("isCircuitSupported", () => {
+    it("should return true for supported circuits", () => {
+      expect(isCircuitSupported(1, 1)).toBe(true);
+      expect(isCircuitSupported(1, 2)).toBe(true);
+      expect(isCircuitSupported(2, 3)).toBe(true);
+      expect(isCircuitSupported(3, 3)).toBe(true);
+    });
+
+    it("should return false for unsupported circuits", () => {
+      expect(isCircuitSupported(4, 4)).toBe(false);
+      expect(isCircuitSupported(0, 0)).toBe(false);
+      expect(isCircuitSupported(1, 3)).toBe(false);
+      expect(isCircuitSupported(2, 2)).toBe(false);
+    });
+  });
+
+  it("should have consistent registry entries", () => {
+    for (const [key, config] of Object.entries(CIRCUIT_REGISTRY)) {
+      // Key should match inputs x outputs
+      const [inputs, outputs] = key.split("x").map(Number);
+      expect(config.inputs).toBe(inputs);
+      expect(config.outputs).toBe(outputs);
+
+      // Name should contain the key
+      expect(config.name).toContain(`${inputs}x${outputs}`);
+
+      // Depth should be 16 for all current circuits
+      expect(config.depth).toBe(16);
+    }
+  });
+});

package/prover/registry.ts

@@ -0,0 +1,82 @@
+// AUTO-GENERATED FILE - DO NOT EDIT MANUALLY
+// Generated by scripts/generate-registry.ts
+// Source: circuits/circuits.json
+// Generated at: 2025-11-25T13:26:58.576Z
+
+/**
+ * Circuit registry for automatic prover selection
+ * Maps circuit dimensions (inputs x outputs) to circuit configurations
+ */
+
+export interface CircuitConfig {
+  /** Full circuit name (e.g., "joinsplit_2x3_16") */
+  readonly name: string;
+  /** Number of inputs (nullifiers) */
+  readonly inputs: number;
+  /** Number of outputs (commitments) */
+  readonly outputs: number;
+  /** Merkle tree depth */
+  readonly depth: number;
+}
+
+export type CircuitKey = "3x3" | "2x3" | "1x2" | "1x1";
+
+/**
+ * Registry of available circuits
+ * Auto-generated from circuits/circuits.json
+ */
+export const CIRCUIT_REGISTRY: Record<CircuitKey, CircuitConfig> = {
+  "3x3": {
+    name: "joinsplit_3x3_16",
+    inputs: 3,
+    outputs: 3,
+    depth: 16,
+  },
+  "2x3": {
+    name: "joinsplit_2x3_16",
+    inputs: 2,
+    outputs: 3,
+    depth: 16,
+  },
+  "1x2": {
+    name: "joinsplit_1x2_16",
+    inputs: 1,
+    outputs: 2,
+    depth: 16,
+  },
+  "1x1": {
+    name: "joinsplit_1x1_16",
+    inputs: 1,
+    outputs: 1,
+    depth: 16,
+  },
+} as const;
+
+/**
+ * Get list of all supported circuit keys
+ */
+export const SUPPORTED_CIRCUITS = Object.keys(CIRCUIT_REGISTRY) as CircuitKey[];
+
+/**
+ * Get circuit configuration by dimensions
+ * @param inputs Number of inputs (nullifiers)
+ * @param outputs Number of outputs (commitments)
+ * @returns Circuit configuration or undefined if not supported
+ */
+export function getCircuitConfig(
+  inputs: number,
+  outputs: number,
+): CircuitConfig | undefined {
+  const key = `${inputs}x${outputs}` as CircuitKey;
+  return CIRCUIT_REGISTRY[key];
+}
+
+/**
+ * Check if a circuit configuration is supported
+ * @param inputs Number of inputs (nullifiers)
+ * @param outputs Number of outputs (commitments)
+ * @returns True if supported
+ */
+export function isCircuitSupported(inputs: number, outputs: number): boolean {
+  return getCircuitConfig(inputs, outputs) !== undefined;
+}

package/schema.ts

@@ -0,0 +1,17 @@
+import { SchemaMismatchError } from "./errors.js";
+import type { Storage } from "./types.js";
+
+export const CORE_SCHEMA_VERSION = 1;
+
+export async function migrate(storage: Storage) {
+  await storage.open();
+  const current = await storage.getSchemaVersion();
+  if (current === 0) {
+    // seed structures if needed
+    await storage.setSchemaVersion(CORE_SCHEMA_VERSION);
+    return;
+  }
+  if (current !== CORE_SCHEMA_VERSION) {
+    throw new SchemaMismatchError(current, CORE_SCHEMA_VERSION);
+  }
+}

package/setup-artifacts.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+
+# Script to setup SDK artifacts from circuits build
+# Creates symlinks to avoid duplicating large files
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SDK_ARTIFACTS="$SCRIPT_DIR/artifacts/circuits"
+CIRCUITS_ARTIFACTS="$SCRIPT_DIR/../../circuits/artifacts"
+
+echo "Setting up SDK circuit artifacts..."
+echo "Source: $CIRCUITS_ARTIFACTS"
+echo "Target: $SDK_ARTIFACTS"
+
+mkdir -p "$SDK_ARTIFACTS"
+
+# Check if circuits artifacts exist
+if [ ! -d "$CIRCUITS_ARTIFACTS" ]; then
+    echo "❌ Error: Circuit artifacts not found at $CIRCUITS_ARTIFACTS"
+    echo "Please run 'pnpm run circuits:build' in the root directory first."
+    exit 1
+fi
+
+# Remove old flat structure if it exists
+if [ -f "$SDK_ARTIFACTS/joinsplit.wasm" ]; then
+    echo "Removing old artifact structure..."
+    rm -f "$SDK_ARTIFACTS/joinsplit.wasm"
+    rm -f "$SDK_ARTIFACTS/joinsplit.zkey"
+    rm -f "$SDK_ARTIFACTS/joinsplit.vkey.json"
+fi
+
+# Create circuit-specific directories and symlink artifacts
+for circuit_dir in "$CIRCUITS_ARTIFACTS"/*; do
+    if [ -d "$circuit_dir" ]; then
+        circuit_name=$(basename "$circuit_dir")
+        target_dir="$SDK_ARTIFACTS/$circuit_name"
+
+        echo "Setting up $circuit_name..."
+
+        # Create target directory
+        mkdir -p "$target_dir"
+
+        # Create symlinks
+        ln -sf "$circuit_dir/joinsplit.wasm" "$target_dir/joinsplit.wasm"
+        ln -sf "$circuit_dir/joinsplit.zkey" "$target_dir/joinsplit.zkey"
+        ln -sf "$circuit_dir/joinsplit.vkey.json" "$target_dir/joinsplit.vkey.json"
+
+        echo "  ✓ Linked $circuit_name artifacts"
+    fi
+done
+
+echo ""
+echo "✓ SDK artifacts setup complete!"
+echo ""
+echo "Available circuits:"
+ls -1 "$SDK_ARTIFACTS"

package/state/index.ts

@@ -0,0 +1,2 @@
+export * from "./merkle/index.js";
+export * from "./store/index.js";