@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/dist/poseidon.js

@@ -0,0 +1,136 @@
+/**
+ * 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
+];
+/**
+ * Initialize poseidon (no-op — poseidon-lite needs no initialization)
+ * Kept for backward API compatibility.
+ */
+export async function initPoseidon() {
+    // 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() {
+    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) {
+    const n = inputs.length;
+    if (n < 1 || n > 16) {
+        throw new Error(`Poseidon: unsupported input count ${n} (expected 1-16)`);
+    }
+    return poseidonFns[n](inputs);
+}
+// 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, amount) {
+    return poseidonHashSync([pubKeyX, amount]);
+}
+export function computeNullifierSync(privKey, leafIndex) {
+    return poseidonHashSync([privKey, leafIndex]);
+}
+export function hashNullifierSync(nullifier) {
+    return poseidonHashSync([nullifier]);
+}
+// ============================================================================
+// JoinSplit Primitives (Railgun-aligned 3-key model)
+// ============================================================================
+export function computeMPKSync(pkX, pkY, nullifyingKey) {
+    return poseidonHashSync([pkX, pkY, nullifyingKey]);
+}
+export function computeNPKSync(mpk, random) {
+    return poseidonHashSync([mpk, random]);
+}
+export function computeJoinSplitCommitmentSync(npk, token, amount) {
+    return poseidonHashSync([npk, token, amount]);
+}
+export function computeJoinSplitNullifierSync(nullifyingKey, leafIndex) {
+    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) {
+    // 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) {
+    const reduced = reduceToField(mintBytes);
+    return poseidonHashSync([reduced, 0n]);
+}
+/**
+ * Convenience: compute token_id from a Solana address string
+ */
+export function computeTokenIdFromAddress(mintAddress) {
+    // 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/packages/sdk/dist/prover/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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
+ */
+export * from "./web";
+export type { MerkleProofInput, ProofData, CircuitType, JoinSplitProofInputs, } from "./web";

package/packages/sdk/dist/prover/index.js

@@ -0,0 +1,10 @@
+/**
+ * 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";

package/packages/sdk/dist/prover/mobile.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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).
+ */
+export type { MerkleProofInput, ProofData, CircuitType, JoinSplitProofInputs, } from "./web";
+import type { ProofData, CircuitType, JoinSplitProofInputs } from "./web";
+type CircuitResolver = (circuitName: string, onProgress?: (progress: number) => void) => Promise<string>;
+/**
+ * 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 declare function setCircuitResolver(resolver: CircuitResolver): void;
+/**
+ * Initialise the native mopro-ffi prover.
+ * Safe to call multiple times — subsequent calls are no-ops.
+ */
+export declare function initProver(): Promise<void>;
+/**
+ * Check whether the native prover is available in the current runtime.
+ */
+export declare function isProverAvailable(): Promise<boolean>;
+/**
+ * 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 declare function generateJoinSplitProof(inputs: JoinSplitProofInputs | any, circuitType?: string, onProgress?: (progress: number) => void): Promise<ProofData>;
+/**
+ * Convert a ProofData to raw 256-byte proof for on-chain submission.
+ */
+export declare function proofToBytes(proof: ProofData): Uint8Array;
+/**
+ * Check if a circuit variant is available (resolver can find the .zkey).
+ */
+export declare function circuitExists(circuitType?: CircuitType | string): Promise<boolean>;
+/**
+ * Reset module state (for testing or hot-reload scenarios).
+ */
+export declare function cleanup(): Promise<void>;

package/packages/sdk/dist/prover/mobile.js

@@ -0,0 +1,227 @@
+/**
+ * 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).
+ */
+import { computeJoinSplitNullifierSync, computeJoinSplitCommitmentSync, } from "../poseidon";
+let moproModule = null;
+let circuitResolver = 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 = resolver;
+}
+// ---------------------------------------------------------------------------
+// Initialisation
+// ---------------------------------------------------------------------------
+/**
+ * Initialise the native mopro-ffi prover.
+ * Safe to call multiple times — subsequent calls are no-ops.
+ */
+export async function initProver() {
+    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() {
+    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, circuitType, onProgress) {
+    if (!proverReady)
+        await initProver();
+    if (!circuitResolver) {
+        throw new Error("Circuit resolver not set. Call setCircuitResolver() before generating proofs.");
+    }
+    // Determine circuit variant
+    const nIn = inputs.nInputs ?? inputs.inputs?.length ?? 1;
+    const nOut = inputs.nOutputs ?? inputs.outputs?.length ?? 2;
+    const variant = 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, nIn, nOut) {
+    const flat = {};
+    // If inputs are already in flat format, pass through
+    if (!inputs.merkleRoot && !inputs.inputs) {
+        const result = {};
+        for (const [key, value] of Object.entries(inputs)) {
+            if (Array.isArray(value)) {
+                result[key] = value.map((v) => String(v));
+            }
+            else {
+                result[key] = [String(value)];
+            }
+        }
+        return result;
+    }
+    // Typed JoinSplitProofInputs — convert to circuit signal names
+    const typed = inputs;
+    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 = [];
+    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 = [];
+    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 = [];
+    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) {
+    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, offset, value, length) {
+    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) {
+    return proof.proof;
+}
+/**
+ * Check if a circuit variant is available (resolver can find the .zkey).
+ */
+export async function circuitExists(circuitType) {
+    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() {
+    moproModule = null;
+    circuitResolver = null;
+    proverReady = false;
+    console.log("[MobileProver] Cleaned up");
+}

package/packages/sdk/dist/prover/web.d.ts

@@ -0,0 +1,136 @@
+/**
+ * WASM-based Groth16 Proof Generator for UTXOPIA
+ *
+ * Universal prover that works in both Browser and Node.js environments.
+ * Uses Groth16 proofs via snarkjs with lazy loading.
+ *
+ * JOINSPLIT MODEL:
+ * - Commitment = Poseidon(npk, token, amount)
+ * - Nullifier = Poseidon(nullifyingKey, leafIndex)
+ * - Signature = EdDSA-Poseidon over (merkleRoot, boundParamsHash, nullifiers..., commitmentsOut...)
+ */
+import type { Address } from "@solana/kit";
+export interface MerkleProofInput {
+    siblings: bigint[];
+    indices: number[];
+}
+export interface ProofData {
+    proof: Uint8Array;
+    publicInputs: string[];
+    verificationKey?: Uint8Array;
+}
+export type CircuitType = `joinsplit_${number}x${number}`;
+/** Names of non-JoinSplit auxiliary circuits (selective disclosure). */
+export type AuxCircuitName = "ownership" | "range_sum" | "range_sum_4" | "range_sum_16";
+/**
+ * Set the base path for circuit artifacts
+ */
+export declare function setCircuitPath(path: string): void;
+/**
+ * Get the current circuit base path
+ */
+export declare function getCircuitPath(): string;
+/**
+ * Pin the circuit artifacts this app is willing to prove with.
+ *
+ * Worth doing even though it costs a hash per download. The `.wasm` is the witness generator:
+ * it is handed the spending key, the nullifying key, note randomness, amounts and the full
+ * Merkle path in the clear. It arrives over plain `fetch`, where subresource integrity does not
+ * apply, and CDNs typically serve it `immutable, max-age=31536000` — so a substituted file keeps
+ * working out of browser and edge caches long after the origin is cleaned up. The proofs it
+ * produces still verify, so nothing fails and no user notices.
+ *
+ * Digests must come from the consuming build (they change whenever circuits are rebuilt), which
+ * is why the SDK cannot ship them. Once set, verification is enforced and fails closed: an
+ * artifact with no recorded digest is refused rather than trusted.
+ */
+export declare function setCircuitArtifactDigests(digests: Record<string, string> | null): void;
+/**
+ * Download the selected JoinSplit artifacts into the browser cache and the
+ * prover's in-memory fastfile cache without generating a proof. Calling this
+ * while the user reviews a transaction removes CDN latency from the confirm
+ * path. Concurrent preloads and proofs share the same downloads.
+ */
+export declare function preloadJoinSplitCircuit(nInputs: number, nOutputs: number): Promise<void>;
+/**
+ * Initialize the prover (preloads snarkjs module)
+ */
+export declare function initProver(): Promise<void>;
+/**
+ * Generate a Groth16 proof for any circuit by name. Useful for non-JoinSplit
+ * circuits (ownership, range_sum) that follow the same artifact layout
+ * `<circuitBasePath>/<name>/<name>_js/<name>.wasm` + `<circuitBasePath>/<name>/<name>.zkey`.
+ *
+ * Returns `{ proof: 256 bytes, publicInputs }` matching `ProofData`.
+ */
+export declare function generateGenericGroth16Proof(circuitName: string, inputs: Record<string, string | string[] | number[] | string[][] | number[][]>): Promise<ProofData>;
+/**
+ * Check if prover is available in current environment
+ */
+export declare function isProverAvailable(): Promise<boolean>;
+/**
+ * Verify a Groth16 proof against a verifying key + public signals.
+ *
+ * Accepts the snarkjs-native shapes:
+ *   - `vkey`:           the JSON emitted by `snarkjs zkey export verificationkey`
+ *   - `publicSignals`:  array of decimal strings
+ *   - `proof`:          `{ pi_a, pi_b, pi_c, protocol, curve }` as produced by `snarkjs.groth16.fullProve`
+ *
+ * Lazy-loads snarkjs so calling code doesn't pay the bundle cost unless it
+ * verifies. Returns true on a valid proof, false on an invalid one; throws
+ * if snarkjs is missing or the inputs are structurally malformed.
+ */
+export declare function verifyGroth16Proof(vkey: unknown, publicSignals: ReadonlyArray<string>, proof: unknown): Promise<boolean>;
+/**
+ * JoinSplit proof inputs
+ */
+export interface JoinSplitProofInputs {
+    nInputs: number;
+    nOutputs: number;
+    merkleRoot: bigint;
+    boundParamsHash: bigint;
+    token: bigint;
+    publicKey: [bigint, bigint];
+    signature: [bigint, bigint, bigint];
+    nullifyingKey: bigint;
+    inputs: Array<{
+        random: bigint;
+        value: bigint;
+        leafIndex: bigint;
+        merkleProof: {
+            siblings: bigint[];
+            indices: number[];
+        };
+    }>;
+    outputs: Array<{
+        npk: bigint;
+        value: bigint;
+    }>;
+}
+/**
+ * Generate a JoinSplit proof
+ *
+ * Unified prover for all JoinSplit variants.
+ * Selects the joinsplit_NxM circuit based on nInputs/nOutputs.
+ */
+export declare function generateJoinSplitProof(inputs: JoinSplitProofInputs): Promise<ProofData>;
+/**
+ * Check if circuit artifacts exist for a given circuit type
+ */
+export declare function circuitExists(circuitType: CircuitType): Promise<boolean>;
+/**
+ * Convert proof to raw bytes for on-chain submission
+ */
+export declare function proofToBytes(proof: ProofData): Uint8Array;
+/**
+ * Cleanup all cached resources
+ */
+export declare function cleanup(): Promise<void>;
+/**
+ * Groth16 verifier program ID (from current config)
+ */
+export declare function getGroth16VerifierProgramId(): Address;
+/**
+ * Build instruction data for Groth16 verification
+ */
+export declare function buildVerifyInstructionData(proof: Uint8Array, publicSignals: string[], vkHash: string): Uint8Array;