@utxopia/sdk 0.1.0-alpha.1

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

@@ -0,0 +1,597 @@
+/**
+ * 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 { poseidonHashSync, computeJoinSplitCommitmentSync, computeJoinSplitNullifierSync, } from "../poseidon";
+import { BN254_FIELD_PRIME } from "../crypto";
+import { TREE_DEPTH } from "../merkle";
+import { getConfig } from "../config";
+import { MAX_SAFE_JOINSPLIT_SIZE } from "../vk-registry";
+/** Maximum satoshis (total BTC supply) */
+const MAX_SATOSHIS = 21000000n * 100000000n;
+/**
+ * Validate that proof inputs are within BN254 field bounds.
+ */
+function validateFieldInputs(fields) {
+    for (const [name, value] of Object.entries(fields)) {
+        if (value < 0n) {
+            throw new Error(`Invalid proof input: ${name} is negative`);
+        }
+        if (value >= BN254_FIELD_PRIME) {
+            throw new Error(`Invalid proof input: ${name} exceeds BN254 field prime`);
+        }
+    }
+}
+function validateAmount(amount, label) {
+    if (amount <= 0n) {
+        throw new Error(`Invalid proof input: ${label} must be positive`);
+    }
+    if (amount > MAX_SATOSHIS) {
+        throw new Error(`Invalid proof input: ${label} exceeds total BTC supply`);
+    }
+}
+// Environment detection
+const isBrowser = typeof window !== "undefined";
+const isNode = typeof process !== "undefined" && process.versions?.node;
+// Configurable circuit paths
+let circuitBasePath = isBrowser ? "/circuits/groth16" : "./circuits";
+/**
+ * Set the base path for circuit artifacts
+ */
+export function setCircuitPath(path) {
+    if (path === circuitBasePath)
+        return;
+    circuitBasePath = path;
+    circuitCache.clear();
+    artifactBytesCache.clear();
+    artifactDownloadCache.clear();
+}
+/**
+ * Get the current circuit base path
+ */
+export function getCircuitPath() {
+    return circuitBasePath;
+}
+// Lazy-loaded snarkjs module
+let snarkjs = null;
+const circuitCache = new Map();
+let proverInitialized = false;
+/**
+ * Load snarkjs module
+ */
+async function ensureSnarkjsLoaded() {
+    if (snarkjs)
+        return;
+    console.log("[Prover] Loading snarkjs module...");
+    // Prefer an app-provided instance: browser bundlers resolve snarkjs's
+    // `browser` export themselves and hand it over via globalThis, since the
+    // string-indirected import below is (deliberately) opaque to them.
+    snarkjs = globalThis.snarkjs ?? null;
+    if (!snarkjs) {
+        const snarkjsModule = "snarkjs";
+        snarkjs = await import(snarkjsModule).catch(() => null);
+    }
+    if (!snarkjs) {
+        throw new Error("Groth16 prover requires the snarkjs package. " +
+            "Install it with: bun add snarkjs");
+    }
+}
+/**
+ * Fully-downloaded circuit artifacts, keyed by URL. Proving reads zkey
+ * sections non-sequentially; over HTTP that becomes thousands of small
+ * range requests, which dominates proving time. Downloading once into
+ * memory (Railgun-style) makes proving IO-free.
+ */
+const artifactBytesCache = new Map();
+const artifactDownloadCache = new Map();
+/**
+ * Expected SHA-256 of each artifact, keyed by its path under the circuit base — e.g.
+ * `joinsplit_1x1/joinsplit_1x1_js/joinsplit_1x1.wasm`. Empty until a caller supplies one.
+ */
+let artifactDigests = null;
+/**
+ * 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 function setCircuitArtifactDigests(digests) {
+    artifactDigests = digests;
+    // Anything admitted under the old policy must be re-checked under the new one.
+    artifactBytesCache.clear();
+}
+const toHex = (buf) => Array.from(new Uint8Array(buf), (b) => b.toString(16).padStart(2, "0")).join("");
+async function verifyArtifactBytes(url, bytes) {
+    if (!artifactDigests)
+        return;
+    // Key by path-under-base so one manifest works across origins (local dev vs CDN).
+    const key = Object.keys(artifactDigests).find((k) => url.endsWith(k));
+    if (!key) {
+        throw new Error(`No integrity digest recorded for circuit artifact ${url} — refusing to prove. ` +
+            `Regenerate the artifact manifest so it covers every shape this origin serves.`);
+    }
+    const actual = toHex(await crypto.subtle.digest("SHA-256", bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength)));
+    if (actual !== artifactDigests[key]) {
+        throw new Error(`Circuit artifact ${key} failed its integrity check (expected ${artifactDigests[key]}, ` +
+            `got ${actual}). Refusing to prove against an artifact this build does not recognise.`);
+    }
+}
+async function fetchArtifactToMemory(url) {
+    const cached = artifactBytesCache.get(url);
+    if (cached)
+        return { type: "mem", data: cached };
+    let download = artifactDownloadCache.get(url);
+    if (!download) {
+        download = (async () => {
+            const res = await fetch(url, { cache: "force-cache" });
+            if (!res.ok) {
+                throw new Error(`Failed to fetch circuit artifact ${url}: HTTP ${res.status}`);
+            }
+            const bytes = new Uint8Array(await res.arrayBuffer());
+            // Before the cache, so a rejected artifact is never reachable from it.
+            await verifyArtifactBytes(url, bytes);
+            artifactBytesCache.set(url, bytes);
+            return bytes;
+        })();
+        artifactDownloadCache.set(url, download);
+        void download.finally(() => artifactDownloadCache.delete(url)).catch(() => { });
+    }
+    const bytes = await download;
+    return { type: "mem", data: bytes };
+}
+/**
+ * In browsers (or with remote artifact URLs), resolve artifacts to in-memory
+ * fastfile objects; in Node, local file paths are already fast.
+ */
+async function resolveProveArtifacts(artifacts) {
+    const isRemote = artifacts.zkeyPath.startsWith("http://") || artifacts.zkeyPath.startsWith("https://");
+    if (!isBrowser && !isRemote) {
+        return { wasm: artifacts.wasmPath, zkey: artifacts.zkeyPath };
+    }
+    const [wasm, zkey] = await Promise.all([
+        fetchArtifactToMemory(artifacts.wasmPath),
+        fetchArtifactToMemory(artifacts.zkeyPath),
+    ]);
+    return { wasm, zkey };
+}
+/**
+ * Resolve circuit artifact paths
+ */
+function getCircuitArtifactPaths(circuitType) {
+    if (circuitCache.has(circuitType)) {
+        return circuitCache.get(circuitType);
+    }
+    const name = circuitType; // "joinsplit_NxM"
+    const artifact = {
+        wasmPath: `${circuitBasePath}/${name}/${name}_js/${name}.wasm`,
+        zkeyPath: `${circuitBasePath}/${name}/${name}.zkey`,
+    };
+    circuitCache.set(circuitType, artifact);
+    return artifact;
+}
+function getJoinSplitCircuitType(nInputs, nOutputs) {
+    if (!Number.isInteger(nInputs) ||
+        !Number.isInteger(nOutputs) ||
+        nInputs < 1 ||
+        nOutputs < 1 ||
+        nInputs + nOutputs > MAX_SAFE_JOINSPLIT_SIZE) {
+        throw new Error(`Invalid JoinSplit dimensions: ${nInputs}x${nOutputs} ` +
+            `(N+M must be 2..${MAX_SAFE_JOINSPLIT_SIZE})`);
+    }
+    return `joinsplit_${nInputs}x${nOutputs}`;
+}
+/**
+ * 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 async function preloadJoinSplitCircuit(nInputs, nOutputs) {
+    const circuitType = getJoinSplitCircuitType(nInputs, nOutputs);
+    await resolveProveArtifacts(getCircuitArtifactPaths(circuitType));
+}
+// Detect bun runtime (snarkjs WASM hangs in bun)
+const isBun = typeof process !== "undefined" && !!process.versions?.bun;
+/**
+ * Generate a Groth16 proof for a circuit with given inputs.
+ * Uses Node.js subprocess when running in bun (snarkjs WASM incompatibility).
+ */
+async function generateProof(circuitType, inputs) {
+    console.log(`[Prover] Generating ${circuitType} Groth16 proof...`);
+    const startTime = typeof performance !== "undefined" ? performance.now() : Date.now();
+    const artifacts = getCircuitArtifactPaths(circuitType);
+    let proof;
+    let publicSignals;
+    if (isBun && isNode) {
+        const result = await generateProofViaNodeSubprocess(artifacts, inputs);
+        proof = result.proof;
+        publicSignals = result.publicSignals;
+    }
+    else {
+        await ensureSnarkjsLoaded();
+        const resolved = await resolveProveArtifacts(artifacts);
+        // Browser: ffjavascript's worker pool can deadlock (proofs hang
+        // indefinitely); single-thread proving completes in seconds.
+        const proverOptions = isBrowser ? { singleThread: true } : undefined;
+        const result = await snarkjs.groth16.fullProve(inputs, resolved.wasm, resolved.zkey, undefined, undefined, proverOptions);
+        proof = result.proof;
+        publicSignals = result.publicSignals;
+    }
+    const elapsed = (typeof performance !== "undefined" ? performance.now() : Date.now()) - startTime;
+    console.log(`[Prover] Groth16 proof generated in ${elapsed.toFixed(0)}ms`);
+    const proofBytes = serializeProof(proof);
+    console.log(`[Prover] Proof size: ${proofBytes.length} bytes`);
+    return {
+        proof: proofBytes,
+        publicInputs: publicSignals,
+    };
+}
+/**
+ * Generate proof via Node.js subprocess (for bun compatibility)
+ */
+async function generateProofViaNodeSubprocess(artifacts, inputs) {
+    // Build a CommonJS-aware `require` that works in both CJS and ESM execution
+    // contexts. In ESM, `require` isn't a global; `module.createRequire(url)`
+    // creates one bound to a given module URL.
+    // `import.meta.url` is only valid in ESM modules; in CJS bundles
+    // (`type: "commonjs"`) we fall back to the inherited `require`. Both
+    // bundlers (esbuild / tsc) preserve `import.meta.url` correctly.
+    let _require;
+    if (typeof globalThis.require === "function") {
+        _require = globalThis.require;
+    }
+    else {
+        const nodeModuleSpecifier = "node:" + "module";
+        const { createRequire } = await import(nodeModuleSpecifier);
+        _require = createRequire(import.meta.url);
+    }
+    const { execFileSync } = _require("child_process");
+    const fs = _require("fs");
+    const path = _require("path");
+    const os = _require("os");
+    const wasmPath = path.resolve(artifacts.wasmPath);
+    const zkeyPath = path.resolve(artifacts.zkeyPath);
+    // Private 0700 tmp dir so the prover input (nullifyingKey, values, leaf indices)
+    // is not world-readable in the shared circuit-artifact dir.
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "utxopia-prover-"));
+    const tmpInput = path.join(tmpDir, "input.json");
+    const tmpProof = path.join(tmpDir, "proof.json");
+    const tmpPublic = path.join(tmpDir, "public.json");
+    fs.writeFileSync(tmpInput, JSON.stringify(inputs), { mode: 0o600 });
+    try {
+        // Use execFileSync to avoid shell injection via file paths
+        // Take the last 5 argv entries — Node 24's --eval TypeScript transform
+        // can prepend extra paths, so positional destructuring [,, ...] breaks.
+        const script = `
+      const snarkjs = require('snarkjs');
+      const fs = require('fs');
+      const [inputPath, wasmP, zkeyP, proofPath, publicPath] = process.argv.slice(-5);
+      (async () => {
+        const input = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
+        const { proof, publicSignals } = await snarkjs.groth16.fullProve(input, wasmP, zkeyP);
+        fs.writeFileSync(proofPath, JSON.stringify(proof));
+        fs.writeFileSync(publicPath, JSON.stringify(publicSignals));
+        process.exit(0);
+      })().catch(e => { console.error(e); process.exit(1); });
+    `;
+        execFileSync("node", ["-e", script, tmpInput, wasmPath, zkeyPath, tmpProof, tmpPublic], {
+            timeout: 120000,
+        });
+        const proof = JSON.parse(fs.readFileSync(tmpProof, "utf8"));
+        const publicSignals = JSON.parse(fs.readFileSync(tmpPublic, "utf8"));
+        return { proof, publicSignals };
+    }
+    finally {
+        // Best-effort overwrite-then-remove of the secret-bearing input, then the dir.
+        try {
+            fs.writeFileSync(tmpInput, "0".repeat(64), { mode: 0o600 });
+        }
+        catch { }
+        try {
+            fs.unlinkSync(tmpInput);
+        }
+        catch { }
+        try {
+            fs.unlinkSync(tmpProof);
+        }
+        catch { }
+        try {
+            fs.unlinkSync(tmpPublic);
+        }
+        catch { }
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { }
+    }
+}
+/**
+ * Serialize snarkjs Groth16 proof to 256 bytes (2 G1 + 1 G2 on BN254)
+ */
+function serializeProof(proof) {
+    const bytes = new Uint8Array(256);
+    const piA = proof.pi_a;
+    const piB = proof.pi_b;
+    const piC = proof.pi_c;
+    // G1 point A (64 bytes)
+    writeBigIntBE(bytes, 0, BigInt(piA[0]), 32);
+    writeBigIntBE(bytes, 32, BigInt(piA[1]), 32);
+    // G2 point B (128 bytes): [x_imag, x_real, y_imag, y_real]
+    writeBigIntBE(bytes, 64, BigInt(piB[0][1]), 32);
+    writeBigIntBE(bytes, 96, BigInt(piB[0][0]), 32);
+    writeBigIntBE(bytes, 128, BigInt(piB[1][1]), 32);
+    writeBigIntBE(bytes, 160, BigInt(piB[1][0]), 32);
+    // G1 point C (64 bytes)
+    writeBigIntBE(bytes, 192, BigInt(piC[0]), 32);
+    writeBigIntBE(bytes, 224, BigInt(piC[1]), 32);
+    return bytes;
+}
+function writeBigIntBE(buf, offset, value, length) {
+    for (let i = length - 1; i >= 0; i--) {
+        buf[offset + i] = Number(value & 0xffn);
+        value >>= 8n;
+    }
+}
+// ==========================================================================
+// Public API
+// ==========================================================================
+/**
+ * Initialize the prover (preloads snarkjs module)
+ */
+export async function initProver() {
+    await ensureSnarkjsLoaded();
+    proverInitialized = true;
+    console.log("[Prover] Groth16 prover initialized and ready");
+}
+/**
+ * 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 async function generateGenericGroth16Proof(circuitName, inputs) {
+    // Reuse the same artifact lookup pattern as JoinSplit variants.
+    const artifacts = {
+        wasmPath: `${circuitBasePath}/${circuitName}/${circuitName}_js/${circuitName}.wasm`,
+        zkeyPath: `${circuitBasePath}/${circuitName}/${circuitName}.zkey`,
+    };
+    let proof;
+    let publicSignals;
+    if (isBun && isNode) {
+        const result = await generateProofViaNodeSubprocess(artifacts, inputs);
+        proof = result.proof;
+        publicSignals = result.publicSignals;
+    }
+    else {
+        await ensureSnarkjsLoaded();
+        const resolved = await resolveProveArtifacts(artifacts);
+        const proverOptions = isBrowser ? { singleThread: true } : undefined;
+        const result = await snarkjs.groth16.fullProve(inputs, resolved.wasm, resolved.zkey, undefined, undefined, proverOptions);
+        proof = result.proof;
+        publicSignals = result.publicSignals;
+    }
+    return {
+        proof: serializeProof(proof),
+        publicInputs: publicSignals,
+    };
+}
+/**
+ * Check if prover is available in current environment
+ */
+export async function isProverAvailable() {
+    try {
+        await ensureSnarkjsLoaded();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 async function verifyGroth16Proof(vkey, publicSignals, proof) {
+    await ensureSnarkjsLoaded();
+    return snarkjs.groth16.verify(vkey, publicSignals, proof);
+}
+/**
+ * Generate a JoinSplit proof
+ *
+ * Unified prover for all JoinSplit variants.
+ * Selects the joinsplit_NxM circuit based on nInputs/nOutputs.
+ */
+export async function generateJoinSplitProof(inputs) {
+    const { nInputs, nOutputs } = inputs;
+    const variantName = getJoinSplitCircuitType(nInputs, nOutputs);
+    // Validate array lengths match declared dimensions
+    if (inputs.inputs.length !== nInputs) {
+        throw new Error(`Expected ${nInputs} inputs, got ${inputs.inputs.length}`);
+    }
+    if (inputs.outputs.length !== nOutputs) {
+        throw new Error(`Expected ${nOutputs} outputs, got ${inputs.outputs.length}`);
+    }
+    validateFieldInputs({
+        merkleRoot: inputs.merkleRoot,
+        boundParamsHash: inputs.boundParamsHash,
+        token: inputs.token,
+        publicKeyX: inputs.publicKey[0],
+        publicKeyY: inputs.publicKey[1],
+        nullifyingKey: inputs.nullifyingKey,
+    });
+    // Validate input amounts and Merkle proof depths
+    let totalIn = 0n;
+    for (let i = 0; i < inputs.inputs.length; i++) {
+        const inp = inputs.inputs[i];
+        validateAmount(inp.value, `input[${i}].value`);
+        validateFieldInputs({ [`input[${i}].random`]: inp.random });
+        if (inp.merkleProof.siblings.length !== TREE_DEPTH) {
+            throw new Error(`input[${i}].merkleProof: expected ${TREE_DEPTH} siblings, got ${inp.merkleProof.siblings.length}`);
+        }
+        if (inp.merkleProof.indices.length !== TREE_DEPTH) {
+            throw new Error(`input[${i}].merkleProof: expected ${TREE_DEPTH} indices, got ${inp.merkleProof.indices.length}`);
+        }
+        totalIn += inp.value;
+    }
+    // Validate output amounts
+    let totalOut = 0n;
+    for (let i = 0; i < inputs.outputs.length; i++) {
+        const out = inputs.outputs[i];
+        validateAmount(out.value, `output[${i}].value`);
+        validateFieldInputs({ [`output[${i}].npk`]: out.npk });
+        totalOut += out.value;
+    }
+    // Validate conservation of value (inputs must equal outputs)
+    if (totalIn !== totalOut) {
+        throw new Error(`Value mismatch: inputs sum to ${totalIn} sats but outputs sum to ${totalOut} sats`);
+    }
+    // Compute nullifiers
+    const nullifiers = [];
+    for (const inp of inputs.inputs) {
+        const nullifier = computeJoinSplitNullifierSync(inputs.nullifyingKey, inp.leafIndex);
+        nullifiers.push(nullifier);
+    }
+    // Compute output commitments
+    const commitmentsOut = [];
+    for (const out of inputs.outputs) {
+        const commitment = computeJoinSplitCommitmentSync(out.npk, inputs.token, out.value);
+        commitmentsOut.push(commitment);
+    }
+    // Compute message hash: Poseidon(merkleRoot, boundParamsHash, nullifiers..., commitmentsOut...)
+    const hashInputs = [
+        inputs.merkleRoot,
+        inputs.boundParamsHash,
+        ...nullifiers,
+        ...commitmentsOut,
+    ];
+    const _msgHash = poseidonHashSync(hashInputs);
+    // Build circuit inputs
+    const circuitInputs = {
+        merkleRoot: inputs.merkleRoot.toString(),
+        boundParamsHash: inputs.boundParamsHash.toString(),
+        nullifiers: nullifiers.map(n => n.toString()),
+        commitmentsOut: commitmentsOut.map(c => c.toString()),
+        token: inputs.token.toString(),
+        publicKey: inputs.publicKey.map(p => p.toString()),
+        signature: inputs.signature.map(s => s.toString()),
+        nullifyingKey: inputs.nullifyingKey.toString(),
+        randomIn: inputs.inputs.map(i => i.random.toString()),
+        valueIn: inputs.inputs.map(i => i.value.toString()),
+        leavesIndices: inputs.inputs.map(i => i.leafIndex.toString()),
+        npkOut: inputs.outputs.map(o => o.npk.toString()),
+        valueOut: inputs.outputs.map(o => o.value.toString()),
+    };
+    // Circuit derives path-direction bits from leavesIndices, so only siblings are passed.
+    const pathElements = [];
+    for (const inp of inputs.inputs) {
+        pathElements.push(inp.merkleProof.siblings.map(s => s.toString()));
+    }
+    circuitInputs.pathElements = pathElements;
+    return generateProof(variantName, circuitInputs);
+}
+// ==========================================================================
+// Circuit Availability & Verification
+// ==========================================================================
+/**
+ * Check if circuit artifacts exist for a given circuit type
+ */
+export async function circuitExists(circuitType) {
+    try {
+        const artifacts = getCircuitArtifactPaths(circuitType);
+        const isUrl = artifacts.wasmPath.startsWith("http://") || artifacts.wasmPath.startsWith("https://");
+        if (isBrowser || isUrl) {
+            // Browser or remote URL (S3, CDN) — use fetch
+            const [wasmRes, zkeyRes] = await Promise.all([
+                fetch(artifacts.wasmPath, { method: "HEAD" }),
+                fetch(artifacts.zkeyPath, { method: "HEAD" }),
+            ]);
+            return wasmRes.ok && zkeyRes.ok;
+        }
+        // Node/Bun with local paths
+        const _require = new Function("m", "return require(m)");
+        const { existsSync } = _require("fs");
+        return existsSync(artifacts.wasmPath) && existsSync(artifacts.zkeyPath);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Convert proof to raw bytes for on-chain submission
+ */
+export function proofToBytes(proof) {
+    return proof.proof;
+}
+/**
+ * Cleanup all cached resources
+ */
+export async function cleanup() {
+    circuitCache.clear();
+    console.log("[Prover] Cleaned up all cached resources");
+}
+// ==========================================================================
+// Solana Instruction Building (for Groth16 on-chain verification)
+// ==========================================================================
+/**
+ * Groth16 verifier program ID (from current config)
+ */
+export function getGroth16VerifierProgramId() {
+    const config = getConfig();
+    return config.groth16VerifierProgramId;
+}
+/**
+ * Build instruction data for Groth16 verification
+ */
+export function buildVerifyInstructionData(proof, publicSignals, vkHash) {
+    const piBytes = publicSignals.flatMap((pi) => {
+        const bytes = new Array(32).fill(0);
+        const bigint = BigInt(pi);
+        for (let i = 31; i >= 0; i--) {
+            bytes[i] = Number((bigint >> BigInt((31 - i) * 8)) & 0xffn);
+        }
+        return bytes;
+    });
+    const cleanHex = vkHash.startsWith("0x") ? vkHash.slice(2) : vkHash;
+    const vkHashBytes = new Uint8Array(cleanHex.length / 2);
+    for (let i = 0; i < vkHashBytes.length; i++) {
+        vkHashBytes[i] = parseInt(cleanHex.substr(i * 2, 2), 16);
+    }
+    const totalSize = proof.length + 4 + piBytes.length + 32;
+    const data = new Uint8Array(totalSize);
+    let offset = 0;
+    data.set(proof, offset);
+    offset += proof.length;
+    const piCount = publicSignals.length;
+    data[offset++] = piCount & 0xff;
+    data[offset++] = (piCount >> 8) & 0xff;
+    data[offset++] = (piCount >> 16) & 0xff;
+    data[offset++] = (piCount >> 24) & 0xff;
+    data.set(new Uint8Array(piBytes), offset);
+    offset += piBytes.length;
+    data.set(vkHashBytes, offset);
+    return data;
+}

package/packages/sdk/dist/psbt.d.ts

@@ -0,0 +1,73 @@
+/**
+ * PSBT builder for UTXOpia non-interactive deposits.
+ *
+ * Creates a Partially-Signed Bitcoin Transaction with:
+ *   - Input(s): user's UTXOs (P2TR or P2WPKH)
+ *   - Output 1: P2TR deposit (commitment-bound Taproot address)
+ *   - Output 2: OP_RETURN (73 bytes: header || poolTag || ephemeralPub || npk)
+ *   - Output 3: change back to user (if needed)
+ *
+ * Uses @scure/btc-signer for PSBT construction.
+ */
+/** UTXO descriptor for PSBT inputs */
+export interface UtxoDescriptor {
+    /** Transaction ID (hex, 64 chars) */
+    txid: string;
+    /** Output index */
+    vout: number;
+    /** Value in satoshis */
+    value: number;
+    /** Raw scriptPubkey (hex) */
+    scriptPubkeyHex: string;
+    /** Witness UTXO script type (inferred from scriptPubkey if omitted) */
+    type?: "p2tr" | "p2wpkh";
+}
+/** Parameters for building a deposit PSBT */
+export interface BuildDepositPsbtParams {
+    /** Sender's UTXOs to spend */
+    senderUtxos: UtxoDescriptor[];
+    /** Taproot deposit address (bc1p... or tb1p...) */
+    depositAddress: string;
+    /** Deposit amount in satoshis */
+    depositAmountSats: number;
+    /** Compact deposit OP_RETURN payload (from buildDepositOpReturn) */
+    opReturnPayload: Uint8Array;
+    /** Change address (same type as sender) */
+    changeAddress: string;
+    /** Fee rate in sats/vbyte */
+    feeRate: number;
+    /** Bitcoin network */
+    network?: "mainnet" | "testnet" | "signet";
+}
+/** Result of PSBT construction */
+export interface BuildDepositPsbtResult {
+    /** PSBT encoded as base64 */
+    psbtBase64: string;
+    /** PSBT encoded as hex */
+    psbtHex: string;
+    /** Estimated transaction fee in satoshis */
+    estimatedFee: number;
+    /** Total input value in satoshis */
+    totalInput: number;
+    /** Change amount in satoshis (0 if no change) */
+    changeAmount: number;
+}
+/**
+ * Estimate the transaction fee for a deposit PSBT.
+ */
+export declare function estimateDepositFee(numInputs: number, feeRate: number, inputType?: "p2tr" | "p2wpkh", hasChange?: boolean): number;
+/**
+ * Build a deposit PSBT with OP_RETURN for non-interactive stealth deposits.
+ *
+ * The PSBT is unsigned — it must be signed by the user's wallet (e.g. via sats-connect).
+ */
+export declare function buildDepositPsbt(params: BuildDepositPsbtParams): BuildDepositPsbtResult;
+/**
+ * Fetch UTXOs for an address from mempool.space API.
+ */
+export declare function fetchUtxos(address: string, network?: "mainnet" | "testnet" | "signet"): Promise<UtxoDescriptor[]>;
+/**
+ * Select UTXOs to cover the target amount + estimated fee.
+ * Simple greedy algorithm: sort descending by value, take until covered.
+ */
+export declare function selectUtxos(utxos: UtxoDescriptor[], targetSats: number, feeRate: number): UtxoDescriptor[];