@utxopia/sdk 0.1.0-alpha.2 → 0.1.0-alpha.3

package/src/poseidon.ts

@@ -0,0 +1,175 @@
+/**
+ * Poseidon Hash - BN254 compatible with circom circuits and Solana's sol_poseidon
+ *
+ * Uses poseidon-lite: pure JavaScript, zero dependencies, works in
+ * Browser, Node.js, and React Native (no WASM required).
+ *
+ * UNIFIED MODEL:
+ * - Commitment = Poseidon(pub_key_x, amount)
+ * - Nullifier = Poseidon(priv_key, leaf_index)
+ * - Nullifier Hash = Poseidon(nullifier)
+ */
+
+import {
+  poseidon1,
+  poseidon2,
+  poseidon3,
+  poseidon4,
+  poseidon5,
+  poseidon6,
+  poseidon7,
+  poseidon8,
+  poseidon9,
+  poseidon10,
+  poseidon11,
+  poseidon12,
+  poseidon13,
+  poseidon14,
+  poseidon15,
+  poseidon16,
+} from "poseidon-lite";
+
+// Lookup table for poseidon hash by input count. JoinSplit currently needs at
+// most 12 (2 fixed fields + N+M<=10); the larger arities remain available to
+// other SDK callers.
+const poseidonFns = [
+  undefined,    // 0 — unused
+  poseidon1,    // 1 input
+  poseidon2,    // 2 inputs
+  poseidon3,    // 3 inputs
+  poseidon4,    // 4 inputs
+  poseidon5,    // 5 inputs
+  poseidon6,    // 6 inputs
+  poseidon7,    // 7 inputs
+  poseidon8,    // 8 inputs
+  poseidon9,    // 9 inputs
+  poseidon10,   // 10 inputs
+  poseidon11,   // 11 inputs
+  poseidon12,   // 12 inputs
+  poseidon13,   // 13 inputs
+  poseidon14,   // 14 inputs
+  poseidon15,   // 15 inputs
+  poseidon16,   // 16 inputs
+] as const;
+
+/**
+ * Initialize poseidon (no-op — poseidon-lite needs no initialization)
+ * Kept for backward API compatibility.
+ */
+export async function initPoseidon(): Promise<void> {
+  // poseidon-lite is synchronous and ready immediately
+}
+
+/**
+ * Whether Poseidon can hash right now.
+ *
+ * Always true: poseidon-lite is pure synchronous JS with nothing to load, so `initPoseidon()`
+ * exists only so callers written against a WASM-backed hasher keep working. Kept honest rather
+ * than tracking a flag — the previous version lived in note.ts over its own state and reported
+ * false no matter what you called.
+ */
+export function isPoseidonReady(): boolean {
+  return true;
+}
+
+/*
+ * The async forms of these hashes are gone: poseidonHash, computeUnifiedCommitment,
+ * computeNullifier, hashNullifier, computeMPK, computeNPK, computeJoinSplitCommitment and
+ * computeJoinSplitNullifier were each `return xSync(...)`. poseidon-lite is pure synchronous JS,
+ * so awaiting them promised work that never happened and pushed async up through every caller
+ * for nothing — which is why all eight were unused outside this file while the *Sync forms are
+ * called 130-odd times. Use the *Sync functions.
+ */
+
+/**
+ * Synchronous Poseidon hash (no initialization required with poseidon-lite)
+ */
+export function poseidonHashSync(inputs: bigint[]): bigint {
+  const n = inputs.length;
+  if (n < 1 || n > 16) {
+    throw new Error(`Poseidon: unsupported input count ${n} (expected 1-16)`);
+  }
+  return poseidonFns[n]!(inputs as any);
+}
+
+// BN254 scalar field prime
+export const BN254_SCALAR_FIELD =
+  21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+
+// ============================================================================
+// Unified Model Functions (Primary API) - Async versions
+// ============================================================================
+
+// ============================================================================
+// Synchronous versions (internal use only - require prior initPoseidon call)
+// These are used by prover.ts which needs sync computation for circuit inputs
+// ============================================================================
+
+export function computeUnifiedCommitmentSync(pubKeyX: bigint, amount: bigint): bigint {
+  return poseidonHashSync([pubKeyX, amount]);
+}
+
+export function computeNullifierSync(privKey: bigint, leafIndex: bigint): bigint {
+  return poseidonHashSync([privKey, leafIndex]);
+}
+
+export function hashNullifierSync(nullifier: bigint): bigint {
+  return poseidonHashSync([nullifier]);
+}
+
+// ============================================================================
+// JoinSplit Primitives (Railgun-aligned 3-key model)
+// ============================================================================
+
+export function computeMPKSync(pkX: bigint, pkY: bigint, nullifyingKey: bigint): bigint {
+  return poseidonHashSync([pkX, pkY, nullifyingKey]);
+}
+
+export function computeNPKSync(mpk: bigint, random: bigint): bigint {
+  return poseidonHashSync([mpk, random]);
+}
+
+export function computeJoinSplitCommitmentSync(npk: bigint, token: bigint, amount: bigint): bigint {
+  return poseidonHashSync([npk, token, amount]);
+}
+
+export function computeJoinSplitNullifierSync(nullifyingKey: bigint, leafIndex: bigint): bigint {
+  return poseidonHashSync([nullifyingKey, leafIndex]);
+}
+
+// ============================================================================
+// Multi-Token Utilities
+// ============================================================================
+
+/**
+ * Reduce a 32-byte big-endian value to BN254 scalar field (mod p).
+ * Must match on-chain reduce_to_field_exact in crypto.rs.
+ */
+export function reduceToField(bytes: Uint8Array): bigint {
+  // Convert big-endian bytes to bigint
+  let value = 0n;
+  for (const b of bytes) {
+    value = (value << 8n) | BigInt(b);
+  }
+  return value % BN254_SCALAR_FIELD;
+}
+
+/**
+ * Compute token_id from mint address: Poseidon(reduce_to_field(mint), 0)
+ *
+ * Must match on-chain compute_token_id in crypto.rs which uses
+ * poseidon2_hash(reduce_to_field_exact(mint), [0u8; 32]).
+ */
+export function computeTokenId(mintBytes: Uint8Array): bigint {
+  const reduced = reduceToField(mintBytes);
+  return poseidonHashSync([reduced, 0n]);
+}
+
+/**
+ * Convenience: compute token_id from a Solana address string
+ */
+export function computeTokenIdFromAddress(mintAddress: string): bigint {
+  // Base58 decode — import from @solana/kit if available, otherwise use raw bytes
+  // For now, caller should pass raw bytes via computeTokenId
+  throw new Error("Use computeTokenId(mintBytes) with raw pubkey bytes");
+}

package/src/prover/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Prover Subpath
+ *
+ * Auto-detects platform and exports the appropriate prover backend.
+ * For explicit imports, use:
+ * - @utxopia/sdk/prover/web for browser/Node.js snarkjs Groth16 prover
+ * - @utxopia/sdk/prover/mobile for React Native Groth16 prover
+ */
+
+// Re-export everything from the web prover (default for browser/Node.js)
+export * from "./web";
+
+// Re-export types
+export type {
+  MerkleProofInput,
+  ProofData,
+  CircuitType,
+  JoinSplitProofInputs,
+} from "./web";

package/src/prover/mobile.ts

@@ -0,0 +1,303 @@
+/**
+ * Mobile Prover for React Native (JoinSplit Architecture)
+ *
+ * Uses mopro-ffi native Groth16 prover for iOS/Android.
+ * Circuit .zkey files are resolved via an injected circuit resolver
+ * (bundled for tier 1+2, on-demand from Cloudflare R2 for others).
+ */
+
+// Re-export types from web for API compatibility
+export type {
+  MerkleProofInput,
+  ProofData,
+  CircuitType,
+  JoinSplitProofInputs,
+} from "./web";
+
+import type { ProofData, CircuitType, JoinSplitProofInputs } from "./web";
+import {
+  computeJoinSplitNullifierSync,
+  computeJoinSplitCommitmentSync,
+} from "../poseidon";
+
+// ---------------------------------------------------------------------------
+// Module state
+// ---------------------------------------------------------------------------
+
+type CircuitResolver = (
+  circuitName: string,
+  onProgress?: (progress: number) => void,
+) => Promise<string>;
+
+let moproModule: any = null;
+let circuitResolver: CircuitResolver | null = null;
+let proverReady = false;
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Inject the circuit file resolver (called from the mobile app layer).
+ * The resolver maps a circuit name like "joinsplit_2x2" to the local
+ * file-system path of the corresponding .zkey file.
+ */
+export function setCircuitResolver(resolver: CircuitResolver): void {
+  circuitResolver = resolver;
+}
+
+// ---------------------------------------------------------------------------
+// Initialisation
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialise the native mopro-ffi prover.
+ * Safe to call multiple times — subsequent calls are no-ops.
+ */
+export async function initProver(): Promise<void> {
+  if (proverReady) return;
+
+  try {
+    // Dynamic require so bundlers don't resolve this at compile time
+    // when the native module isn't installed yet.
+    moproModule = require("mopro-ffi");
+  } catch {
+    throw new Error(
+      "mopro-ffi native module not found. " +
+        "Run the ubrn build step first (see MoproBindings/package.json).",
+    );
+  }
+
+  proverReady = true;
+  console.log("[MobileProver] mopro-ffi native prover initialised");
+}
+
+/**
+ * Check whether the native prover is available in the current runtime.
+ */
+export async function isProverAvailable(): Promise<boolean> {
+  try {
+    if (!moproModule) {
+      moproModule = require("mopro-ffi");
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Proof generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a JoinSplit Groth16 proof using the native mopro-ffi prover.
+ *
+ * @param inputs    - JoinSplit proof inputs (typed) OR pre-formatted inputs object
+ * @param circuitType - Override circuit variant (default: derived from inputs)
+ * @param onProgress  - Optional progress callback (0..1)
+ */
+export async function generateJoinSplitProof(
+  inputs: JoinSplitProofInputs | any,
+  circuitType?: string,
+  onProgress?: (progress: number) => void,
+): Promise<ProofData> {
+  if (!proverReady) await initProver();
+  if (!circuitResolver) {
+    throw new Error(
+      "Circuit resolver not set. Call setCircuitResolver() before generating proofs.",
+    );
+  }
+
+  // Determine circuit variant
+  const nIn: number = inputs.nInputs ?? inputs.inputs?.length ?? 1;
+  const nOut: number = inputs.nOutputs ?? inputs.outputs?.length ?? 2;
+  const variant: CircuitType =
+    (circuitType as CircuitType) ?? `joinsplit_${nIn}x${nOut}`;
+
+  console.log(`[MobileProver] Generating ${variant} Groth16 proof...`);
+  const startTime = Date.now();
+
+  // Resolve the .zkey path (may trigger a download)
+  onProgress?.(0);
+  const zkeyPath = await circuitResolver(variant, onProgress);
+  onProgress?.(0.1);
+
+  // Format inputs for mopro's flat Record<string, string[]> format
+  const flatInputs = formatCircuitInputs(inputs, nIn, nOut);
+
+  // Call the native prover
+  onProgress?.(0.2);
+  const result = await moproModule.generateCircomProof(zkeyPath, flatInputs);
+  onProgress?.(0.9);
+
+  const elapsed = Date.now() - startTime;
+  console.log(`[MobileProver] Proof generated in ${elapsed}ms`);
+
+  // Convert mopro result to our ProofData format
+  const proofData = convertMoproResult(result);
+  onProgress?.(1);
+
+  return proofData;
+}
+
+// ---------------------------------------------------------------------------
+// Input formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert JoinSplitProofInputs to mopro's flat Record<string, string[]>.
+ *
+ * mopro expects every value as a string array — scalars become single-element
+ * arrays, vectors become multi-element arrays.
+ */
+function formatCircuitInputs(
+  inputs: JoinSplitProofInputs | any,
+  nIn: number,
+  nOut: number,
+): Record<string, string[]> {
+  const flat: Record<string, string[]> = {};
+
+  // If inputs are already in flat format, pass through
+  if (!inputs.merkleRoot && !inputs.inputs) {
+    const result: Record<string, string[]> = {};
+    for (const [key, value] of Object.entries(inputs)) {
+      if (Array.isArray(value)) {
+        result[key] = (value as any[]).map((v) => String(v));
+      } else {
+        result[key] = [String(value)];
+      }
+    }
+    return result;
+  }
+
+  // Typed JoinSplitProofInputs — convert to circuit signal names
+  const typed = inputs as JoinSplitProofInputs;
+
+  flat["merkleRoot"] = [typed.merkleRoot.toString()];
+  flat["boundParamsHash"] = [typed.boundParamsHash.toString()];
+  flat["token"] = [typed.token.toString()];
+  flat["publicKey"] = typed.publicKey.map((p) => p.toString());
+  flat["signature"] = typed.signature.map((s) => s.toString());
+  flat["nullifyingKey"] = [typed.nullifyingKey.toString()];
+
+  // Input arrays
+  flat["randomIn"] = typed.inputs.map((i) => i.random.toString());
+  flat["valueIn"] = typed.inputs.map((i) => i.value.toString());
+  flat["leavesIndices"] = typed.inputs.map((i) => i.leafIndex.toString());
+
+  // Output arrays
+  flat["npkOut"] = typed.outputs.map((o) => o.npk.toString());
+  flat["valueOut"] = typed.outputs.map((o) => o.value.toString());
+
+  // Compute nullifiers: Poseidon(nullifyingKey, leafIndex)
+  const nullifiers: bigint[] = [];
+  for (const inp of typed.inputs) {
+    nullifiers.push(computeJoinSplitNullifierSync(typed.nullifyingKey, inp.leafIndex));
+  }
+  flat["nullifiers"] = nullifiers.map((n) => n.toString());
+
+  // Compute output commitments: Poseidon(npk, token, value)
+  const commitmentsOut: bigint[] = [];
+  for (const out of typed.outputs) {
+    commitmentsOut.push(computeJoinSplitCommitmentSync(out.npk, typed.token, out.value));
+  }
+  flat["commitmentsOut"] = commitmentsOut.map((c) => c.toString());
+
+  // Flattened siblings pathElements[i][j]; circuit derives path bits from leavesIndices.
+  const pathElements: string[] = [];
+  for (const inp of typed.inputs) {
+    for (const sibling of inp.merkleProof.siblings) {
+      pathElements.push(sibling.toString());
+    }
+  }
+  flat["pathElements"] = pathElements;
+
+  return flat;
+}
+
+// ---------------------------------------------------------------------------
+// Result conversion
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert mopro's CircomProofResult to our ProofData format.
+ *
+ * mopro returns: { proof: { a: {x, y}, b: {x: [x0,x1], y: [y0,y1]}, c: {x, y} }, inputs: string[] }
+ * We need: { proof: Uint8Array(256), publicInputs: string[] }
+ */
+function convertMoproResult(result: any): ProofData {
+  const { proof, inputs: publicInputs } = result;
+
+  const bytes = new Uint8Array(256);
+
+  // G1 point A (64 bytes): x, y
+  writeBigIntBE(bytes, 0, BigInt(proof.a.x), 32);
+  writeBigIntBE(bytes, 32, BigInt(proof.a.y), 32);
+
+  // G2 point B (128 bytes): [x_imag, x_real, y_imag, y_real]
+  // mopro b.x = [x0, x1], b.y = [y0, y1]
+  // On-chain layout: x_imag(x1), x_real(x0), y_imag(y1), y_real(y0)
+  writeBigIntBE(bytes, 64, BigInt(proof.b.x[1]), 32);
+  writeBigIntBE(bytes, 96, BigInt(proof.b.x[0]), 32);
+  writeBigIntBE(bytes, 128, BigInt(proof.b.y[1]), 32);
+  writeBigIntBE(bytes, 160, BigInt(proof.b.y[0]), 32);
+
+  // G1 point C (64 bytes): x, y
+  writeBigIntBE(bytes, 192, BigInt(proof.c.x), 32);
+  writeBigIntBE(bytes, 224, BigInt(proof.c.y), 32);
+
+  return {
+    proof: bytes,
+    publicInputs: publicInputs ?? [],
+  };
+}
+
+function writeBigIntBE(
+  buf: Uint8Array,
+  offset: number,
+  value: bigint,
+  length: number,
+): void {
+  for (let i = length - 1; i >= 0; i--) {
+    buf[offset + i] = Number(value & 0xffn);
+    value >>= 8n;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a ProofData to raw 256-byte proof for on-chain submission.
+ */
+export function proofToBytes(proof: ProofData): Uint8Array {
+  return proof.proof;
+}
+
+/**
+ * Check if a circuit variant is available (resolver can find the .zkey).
+ */
+export async function circuitExists(
+  circuitType?: CircuitType | string,
+): Promise<boolean> {
+  if (!circuitResolver) return false;
+  const name = circuitType ?? "joinsplit_2x2";
+  try {
+    await circuitResolver(name);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reset module state (for testing or hot-reload scenarios).
+ */
+export async function cleanup(): Promise<void> {
+  moproModule = null;
+  circuitResolver = null;
+  proverReady = false;
+  console.log("[MobileProver] Cleaned up");
+}