@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/dist/psbt.js

@@ -0,0 +1,202 @@
+/**
+ * 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.
+ */
+import * as btc from "@scure/btc-signer";
+import { hex } from "@scure/base";
+import { DEPOSIT_OP_RETURN_SIZE, createOpReturnScriptFromPayload } from "./taproot";
+// =============================================================================
+// Constants
+// =============================================================================
+/** Dust limit for Bitcoin outputs (satoshis) */
+const DUST_LIMIT = 546;
+/** Estimated vbytes per P2TR key-path input */
+const P2TR_INPUT_VBYTES = 58;
+/** Estimated vbytes per P2WPKH input */
+const P2WPKH_INPUT_VBYTES = 68;
+/** Estimated vbytes for P2TR output */
+const P2TR_OUTPUT_VBYTES = 43;
+/** Estimated vbytes for OP_RETURN output (with compact deposit payload) */
+const OP_RETURN_OUTPUT_VBYTES = 84; // 8 value + 1 script_len + 1 OP_RETURN + 1 push + 73 payload
+/** Transaction overhead (version + locktime + segwit marker + input/output count) */
+const TX_OVERHEAD_VBYTES = 11;
+// =============================================================================
+// Fee Estimation
+// =============================================================================
+/**
+ * Estimate the transaction fee for a deposit PSBT.
+ */
+export function estimateDepositFee(numInputs, feeRate, inputType = "p2tr", hasChange = true) {
+    const inputVbytes = inputType === "p2tr" ? P2TR_INPUT_VBYTES : P2WPKH_INPUT_VBYTES;
+    const outputCount = hasChange ? 3 : 2; // deposit + OP_RETURN + optional change
+    const vsize = TX_OVERHEAD_VBYTES +
+        numInputs * inputVbytes +
+        P2TR_OUTPUT_VBYTES + // deposit output
+        OP_RETURN_OUTPUT_VBYTES + // OP_RETURN output
+        (hasChange ? P2TR_OUTPUT_VBYTES : 0); // change output
+    return Math.ceil(vsize * feeRate);
+}
+// =============================================================================
+// PSBT Builder
+// =============================================================================
+/**
+ * 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 function buildDepositPsbt(params) {
+    const { senderUtxos, depositAddress, depositAmountSats, opReturnPayload, changeAddress, feeRate, network = "testnet", } = params;
+    if (senderUtxos.length === 0) {
+        throw new Error("No UTXOs provided");
+    }
+    if (depositAmountSats < DUST_LIMIT) {
+        throw new Error(`Deposit amount ${depositAmountSats} is below dust limit ${DUST_LIMIT}`);
+    }
+    if (opReturnPayload.length !== DEPOSIT_OP_RETURN_SIZE) {
+        throw new Error(`OP_RETURN payload must be ${DEPOSIT_OP_RETURN_SIZE} bytes, got ${opReturnPayload.length}`);
+    }
+    const btcNetwork = network === "mainnet" ? btc.NETWORK : btc.TEST_NETWORK;
+    // Calculate total input value
+    const totalInput = senderUtxos.reduce((sum, u) => sum + u.value, 0);
+    // Detect input type from first UTXO
+    const firstScript = hex.decode(senderUtxos[0].scriptPubkeyHex);
+    const inputType = firstScript[0] === 0x51 ? "p2tr" : "p2wpkh";
+    // Estimate fee with change
+    const feeWithChange = estimateDepositFee(senderUtxos.length, feeRate, inputType, true);
+    const changeAmount = totalInput - depositAmountSats - feeWithChange;
+    // Check if we have enough funds
+    const feeWithoutChange = estimateDepositFee(senderUtxos.length, feeRate, inputType, false);
+    if (totalInput < depositAmountSats + feeWithoutChange) {
+        throw new Error(`Insufficient funds: have ${totalInput} sats, need ${depositAmountSats + feeWithoutChange} sats (including fee)`);
+    }
+    const hasChange = changeAmount > DUST_LIMIT;
+    const actualFee = hasChange ? feeWithChange : totalInput - depositAmountSats;
+    // Build the transaction using @scure/btc-signer
+    // allowUnknownOutputs is required for the OP_RETURN output script
+    const tx = new btc.Transaction({ allowUnknownOutputs: true });
+    // Add inputs
+    for (const utxo of senderUtxos) {
+        const scriptPubkey = hex.decode(utxo.scriptPubkeyHex);
+        if (scriptPubkey[0] === 0x51 && scriptPubkey.length === 34) {
+            // P2TR input
+            tx.addInput({
+                txid: utxo.txid,
+                index: utxo.vout,
+                witnessUtxo: {
+                    script: scriptPubkey,
+                    amount: BigInt(utxo.value),
+                },
+                tapInternalKey: scriptPubkey.slice(2), // x-only pubkey from OP_1 <32 bytes>
+            });
+        }
+        else if (scriptPubkey[0] === 0x00 && scriptPubkey.length === 22) {
+            // P2WPKH input
+            tx.addInput({
+                txid: utxo.txid,
+                index: utxo.vout,
+                witnessUtxo: {
+                    script: scriptPubkey,
+                    amount: BigInt(utxo.value),
+                },
+            });
+        }
+        else {
+            throw new Error(`Unsupported input script type for UTXO ${utxo.txid}:${utxo.vout}`);
+        }
+    }
+    // Output 1: P2TR deposit
+    tx.addOutputAddress(depositAddress, BigInt(depositAmountSats), btcNetwork);
+    // Output 2: OP_RETURN with compact deposit payload.
+    const opReturnScript = createOpReturnScriptFromPayload(opReturnPayload);
+    tx.addOutput({
+        script: opReturnScript,
+        amount: 0n,
+    });
+    // Output 3: Change (if above dust)
+    if (hasChange) {
+        tx.addOutputAddress(changeAddress, BigInt(changeAmount), btcNetwork);
+    }
+    // Extract PSBT
+    const psbtBytes = tx.toPSBT();
+    const psbtHex = hex.encode(psbtBytes);
+    const psbtBase64 = btoa(String.fromCharCode(...psbtBytes));
+    return {
+        psbtBase64,
+        psbtHex,
+        estimatedFee: actualFee,
+        totalInput,
+        changeAmount: hasChange ? changeAmount : 0,
+    };
+}
+/**
+ * Fetch UTXOs for an address from mempool.space API.
+ */
+export async function fetchUtxos(address, network = "testnet") {
+    const baseUrl = network === "mainnet"
+        ? "https://mempool.space/api"
+        : network === "signet"
+            ? "https://mempool.space/signet/api"
+            : "https://mempool.space/testnet/api";
+    // Fetch UTXOs
+    const utxoRes = await fetch(`${baseUrl}/address/${address}/utxo`);
+    if (!utxoRes.ok) {
+        throw new Error(`Failed to fetch UTXOs: ${utxoRes.status} ${utxoRes.statusText}`);
+    }
+    const utxos = await utxoRes.json();
+    // We need scriptPubkey for each UTXO. Fetch from the tx details.
+    // For efficiency, batch unique txids.
+    const txidSet = new Set(utxos.map((u) => u.txid));
+    const txCache = new Map();
+    await Promise.all([...txidSet].map(async (txid) => {
+        const txRes = await fetch(`${baseUrl}/tx/${txid}`);
+        if (txRes.ok) {
+            txCache.set(txid, await txRes.json());
+        }
+    }));
+    return utxos
+        .filter((u) => u.status.confirmed) // Only confirmed UTXOs
+        .map((u) => {
+        const tx = txCache.get(u.txid);
+        const output = tx?.vout?.[u.vout];
+        const scriptPubkeyHex = output?.scriptpubkey ?? "";
+        return {
+            txid: u.txid,
+            vout: u.vout,
+            value: u.value,
+            scriptPubkeyHex,
+        };
+    })
+        .filter((u) => u.scriptPubkeyHex.length > 0);
+}
+/**
+ * Select UTXOs to cover the target amount + estimated fee.
+ * Simple greedy algorithm: sort descending by value, take until covered.
+ */
+export function selectUtxos(utxos, targetSats, feeRate) {
+    // Sort descending by value
+    const sorted = [...utxos].sort((a, b) => b.value - a.value);
+    const selected = [];
+    let total = 0;
+    for (const utxo of sorted) {
+        selected.push(utxo);
+        total += utxo.value;
+        // Estimate fee for current selection
+        const fee = estimateDepositFee(selected.length, feeRate);
+        if (total >= targetSats + fee) {
+            return selected;
+        }
+    }
+    // Not enough funds
+    const fee = estimateDepositFee(selected.length, feeRate);
+    if (total < targetSats + fee) {
+        throw new Error(`Insufficient funds: have ${total} sats, need ${targetSats + fee} sats`);
+    }
+    return selected;
+}

package/packages/sdk/dist/selective-disclosure.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Selective ZK Disclosure (Phase 4 skeleton)
+ *
+ * Targeted ZK proofs that reveal a single fact about the prover's notes
+ * without handing over a viewing key. Two flavors:
+ *
+ *   1. Ownership proof — "I own commitment X, amount ≥ Y."
+ *      Useful for: proof-of-funds to a regulator, dispute resolution,
+ *      challenge-response with a counterparty.
+ *
+ *   2. Range-sum proof — "Σ amount_i over a slot range ≤ Z" across a
+ *      caller-provided set of leaf indices, with a check that I have
+ *      *committed* to the full set via a Merkle commitment over the set.
+ *
+ * Status (2026-05-13): types frozen, no live prover. Circuits for both
+ * (`ownership.circom`, `range_sum.circom`) need design + trusted setup before
+ * runtime can do real work. Until then both generator functions throw.
+ *
+ * Design notes:
+ *
+ *   Ownership proof. Algorithm sketch:
+ *     - Inputs (private): spendingPrivScalar, randomIn, valueIn, merkleProof
+ *     - Inputs (public): commitment, merkleRoot, threshold (Y), token
+ *     - Constraints:
+ *         (a) commitment == Poseidon(NPK, token, valueIn) where
+ *             NPK = Poseidon(MPK, randomIn) and MPK = Poseidon(spendingPub, nk)
+ *         (b) commitment ∈ tree(merkleRoot)
+ *         (c) valueIn >= threshold (range check)
+ *     - The proof produces a *non-spending* witness: no nullifier is emitted,
+ *       so generating the proof doesn't burn the note.
+ *
+ *   Range-sum proof. Algorithm sketch:
+ *     - Inputs (private): for each note i: randomIn[i], valueIn[i], merkleProof[i]
+ *     - Inputs (public): leafIndices[i], merkleRoot, ceiling (Z), token,
+ *         attestation = Poseidon(leafIndices, viewerNonce) — a binding so the
+ *         verifier knows the prover committed to *this exact* set of leaves
+ *     - Constraints:
+ *         (a) each commitment ∈ tree(merkleRoot)
+ *         (b) each commitment == Poseidon(NPK_i, token, valueIn[i])
+ *         (c) Σ valueIn[i] <= ceiling
+ *         (d) attestation matches
+ *     - Coverage check (the hard part: proving the prover didn't *omit* notes
+ *       in the slot range) is enforced by having the verifier independently
+ *       compute attestation = Poseidon(everyKnownLeaf, viewerNonce) and
+ *       compare. The verifier learns the leaf set from the public viewing key
+ *       handed over for that purpose.
+ *
+ * The viewing-key-coverage dependency means range-sum is most useful when
+ * paired with the auditor flow from Phase 1 — a one-shot disclosure that
+ * proves a property over the set the auditor already verified.
+ */
+import type { ProofData } from "./prover/web";
+export interface OwnershipProofInputs {
+    /** Witness data for the note. */
+    spendingPrivScalar: bigint;
+    nullifyingKey: bigint;
+    randomIn: bigint;
+    valueIn: bigint;
+    pathElements: bigint[];
+    pathIndices: number[];
+    /** Public commitments the prover is claiming. */
+    commitment: bigint;
+    merkleRoot: bigint;
+    /** Minimum amount the prover asserts the note holds. */
+    threshold: bigint;
+    tokenId: bigint;
+}
+export interface OwnershipPublicInputs {
+    commitment: bigint;
+    merkleRoot: bigint;
+    threshold: bigint;
+    tokenId: bigint;
+}
+/**
+ * Generate an ownership ZK proof.
+ *
+ * Calls into the generic snarkjs prover with the `ownership` circuit.
+ * Requires the compiled wasm + zkey under `<circuitBasePath>/ownership/`.
+ *
+ * Public inputs: [commitment, merkleRoot, threshold, tokenId]
+ */
+export declare function generateOwnershipProof(inputs: OwnershipProofInputs): Promise<ProofData>;
+export interface RangeSumProofInputs {
+    /** One entry per note in the prover's claimed set. */
+    notes: ReadonlyArray<{
+        randomIn: bigint;
+        valueIn: bigint;
+        pathElements: bigint[];
+        /** @deprecated No longer used: the circuit derives path bits from leafIndex. */
+        pathIndices?: number[];
+        commitment: bigint;
+        leafIndex: number;
+    }>;
+    /** Common shared data. */
+    spendingPrivScalar: bigint;
+    nullifyingKey: bigint;
+    merkleRoot: bigint;
+    /** Upper bound on the sum the prover asserts. */
+    ceiling: bigint;
+    tokenId: bigint;
+    /** Salt the verifier supplied, binding the proof to this verification round. */
+    viewerNonce: bigint;
+    /** Poseidon(leafIndices ++ [viewerNonce]) — must match the public input. */
+    attestation: bigint;
+}
+export interface RangeSumPublicInputs {
+    leafIndices: number[];
+    merkleRoot: bigint;
+    ceiling: bigint;
+    tokenId: bigint;
+    /** Poseidon(leafIndices ++ [viewerNonce]) committed to by the prover. */
+    attestation: bigint;
+}
+/**
+ * How the variant computes `attestation` from `(leafIndices, viewerNonce)`.
+ *
+ *   - "flat"    — `Poseidon(leafIndices ++ [viewerNonce])`. Cheap; requires
+ *                 N+1 ≤ 16 because circomlib's Poseidon caps at arity 16.
+ *   - "chunked" — `Poseidon(Poseidon(leafIndices[0..N/2]),
+ *                           Poseidon(leafIndices[N/2..N]),
+ *                           viewerNonce)`. Needed at N=16 where the flat
+ *                 form would require Poseidon(17). Only one nesting level
+ *                 ships today (N=16); deeper variants would extend the
+ *                 same pattern.
+ */
+export type RangeSumAttestationStyle = "flat" | "chunked";
+/**
+ * Compiled range-sum variants and the cardinality each handles. Add new
+ * entries here when you build a new sibling circuit. The `circuit` field
+ * must match the directory name under `circuits/build/`.
+ */
+export declare const RANGE_SUM_VARIANTS: readonly [{
+    readonly n: 4;
+    readonly circuit: "range_sum_4";
+    readonly attestation: "flat";
+}, {
+    readonly n: 8;
+    readonly circuit: "range_sum";
+    readonly attestation: "flat";
+}, {
+    readonly n: 16;
+    readonly circuit: "range_sum_16";
+    readonly attestation: "chunked";
+}];
+/** Number of notes accepted by each compiled variant. */
+export declare const RANGE_SUM_SIZES: (8 | 16 | 4)[];
+/**
+ * @deprecated Prefer `RANGE_SUM_VARIANTS` / `pickRangeSumVariant`. Retained
+ * for back-compat with older callers that assumed a single N.
+ */
+export declare const RANGE_SUM_N = 8;
+/** Look up the compiled circuit name for a given note cardinality. */
+export declare function pickRangeSumVariant(n: number): typeof RANGE_SUM_VARIANTS[number];
+/**
+ * Compute the range-sum attestation public input the way each compiled
+ * circuit expects. SDK + CLI must agree on this exactly or the verifier
+ * rejects the proof.
+ *
+ *   - flat:    Poseidon(leafIndices ++ [viewerNonce])
+ *   - chunked: Poseidon(Poseidon(leafIndices[0..N/2]),
+ *                       Poseidon(leafIndices[N/2..N]),
+ *                       viewerNonce)
+ *
+ * `style` defaults to the cardinality's compiled variant; pass it
+ * explicitly if you're computing the value without going through
+ * `generateRangeSumProof` (e.g. inside a CLI that lays out witness data
+ * up front).
+ */
+export declare function computeRangeSumAttestation(leafIndices: ReadonlyArray<number | bigint>, viewerNonce: bigint, style?: RangeSumAttestationStyle): Promise<bigint>;
+/**
+ * Generate a range-sum ZK proof. The variant is picked automatically from
+ * `inputs.notes.length` — compile + register new variants in
+ * `RANGE_SUM_VARIANTS` to extend the supported cardinalities.
+ *
+ * Calls into the generic snarkjs prover with the matching circuit.
+ * Requires the compiled wasm + zkey under
+ * `<circuitBasePath>/<variant.circuit>/`.
+ *
+ * Public inputs: [leafIndices(N), merkleRoot, ceiling, token, attestation]
+ */
+export declare function generateRangeSumProof(inputs: RangeSumProofInputs): Promise<ProofData>;

package/packages/sdk/dist/selective-disclosure.js

@@ -0,0 +1,172 @@
+/**
+ * Selective ZK Disclosure (Phase 4 skeleton)
+ *
+ * Targeted ZK proofs that reveal a single fact about the prover's notes
+ * without handing over a viewing key. Two flavors:
+ *
+ *   1. Ownership proof — "I own commitment X, amount ≥ Y."
+ *      Useful for: proof-of-funds to a regulator, dispute resolution,
+ *      challenge-response with a counterparty.
+ *
+ *   2. Range-sum proof — "Σ amount_i over a slot range ≤ Z" across a
+ *      caller-provided set of leaf indices, with a check that I have
+ *      *committed* to the full set via a Merkle commitment over the set.
+ *
+ * Status (2026-05-13): types frozen, no live prover. Circuits for both
+ * (`ownership.circom`, `range_sum.circom`) need design + trusted setup before
+ * runtime can do real work. Until then both generator functions throw.
+ *
+ * Design notes:
+ *
+ *   Ownership proof. Algorithm sketch:
+ *     - Inputs (private): spendingPrivScalar, randomIn, valueIn, merkleProof
+ *     - Inputs (public): commitment, merkleRoot, threshold (Y), token
+ *     - Constraints:
+ *         (a) commitment == Poseidon(NPK, token, valueIn) where
+ *             NPK = Poseidon(MPK, randomIn) and MPK = Poseidon(spendingPub, nk)
+ *         (b) commitment ∈ tree(merkleRoot)
+ *         (c) valueIn >= threshold (range check)
+ *     - The proof produces a *non-spending* witness: no nullifier is emitted,
+ *       so generating the proof doesn't burn the note.
+ *
+ *   Range-sum proof. Algorithm sketch:
+ *     - Inputs (private): for each note i: randomIn[i], valueIn[i], merkleProof[i]
+ *     - Inputs (public): leafIndices[i], merkleRoot, ceiling (Z), token,
+ *         attestation = Poseidon(leafIndices, viewerNonce) — a binding so the
+ *         verifier knows the prover committed to *this exact* set of leaves
+ *     - Constraints:
+ *         (a) each commitment ∈ tree(merkleRoot)
+ *         (b) each commitment == Poseidon(NPK_i, token, valueIn[i])
+ *         (c) Σ valueIn[i] <= ceiling
+ *         (d) attestation matches
+ *     - Coverage check (the hard part: proving the prover didn't *omit* notes
+ *       in the slot range) is enforced by having the verifier independently
+ *       compute attestation = Poseidon(everyKnownLeaf, viewerNonce) and
+ *       compare. The verifier learns the leaf set from the public viewing key
+ *       handed over for that purpose.
+ *
+ * The viewing-key-coverage dependency means range-sum is most useful when
+ * paired with the auditor flow from Phase 1 — a one-shot disclosure that
+ * proves a property over the set the auditor already verified.
+ */
+/**
+ * Generate an ownership ZK proof.
+ *
+ * Calls into the generic snarkjs prover with the `ownership` circuit.
+ * Requires the compiled wasm + zkey under `<circuitBasePath>/ownership/`.
+ *
+ * Public inputs: [commitment, merkleRoot, threshold, tokenId]
+ */
+export async function generateOwnershipProof(inputs) {
+    const { generateGenericGroth16Proof } = await import("./prover/web");
+    return generateGenericGroth16Proof("ownership", {
+        commitment: inputs.commitment.toString(),
+        merkleRoot: inputs.merkleRoot.toString(),
+        threshold: inputs.threshold.toString(),
+        token: inputs.tokenId.toString(),
+        spendingPrivScalar: inputs.spendingPrivScalar.toString(),
+        randomIn: inputs.randomIn.toString(),
+        valueIn: inputs.valueIn.toString(),
+        pathElements: inputs.pathElements.map((e) => e.toString()),
+        pathIndices: inputs.pathIndices,
+        nullifyingKey: inputs.nullifyingKey.toString(),
+    });
+}
+/**
+ * Compiled range-sum variants and the cardinality each handles. Add new
+ * entries here when you build a new sibling circuit. The `circuit` field
+ * must match the directory name under `circuits/build/`.
+ */
+export const RANGE_SUM_VARIANTS = [
+    { n: 4, circuit: "range_sum_4", attestation: "flat" },
+    { n: 8, circuit: "range_sum", attestation: "flat" },
+    { n: 16, circuit: "range_sum_16", attestation: "chunked" },
+];
+/** Number of notes accepted by each compiled variant. */
+export const RANGE_SUM_SIZES = RANGE_SUM_VARIANTS.map((v) => v.n);
+/**
+ * @deprecated Prefer `RANGE_SUM_VARIANTS` / `pickRangeSumVariant`. Retained
+ * for back-compat with older callers that assumed a single N.
+ */
+export const RANGE_SUM_N = 8;
+/** Look up the compiled circuit name for a given note cardinality. */
+export function pickRangeSumVariant(n) {
+    const v = RANGE_SUM_VARIANTS.find((x) => x.n === n);
+    if (!v) {
+        throw new Error(`range_sum has no compiled variant for N=${n}. Compiled variants: ` +
+            RANGE_SUM_SIZES.join(", ") +
+            ". Pad with zero-value notes or compile a new variant " +
+            "(see circuits/scripts/build-aux.sh).");
+    }
+    return v;
+}
+/**
+ * Compute the range-sum attestation public input the way each compiled
+ * circuit expects. SDK + CLI must agree on this exactly or the verifier
+ * rejects the proof.
+ *
+ *   - flat:    Poseidon(leafIndices ++ [viewerNonce])
+ *   - chunked: Poseidon(Poseidon(leafIndices[0..N/2]),
+ *                       Poseidon(leafIndices[N/2..N]),
+ *                       viewerNonce)
+ *
+ * `style` defaults to the cardinality's compiled variant; pass it
+ * explicitly if you're computing the value without going through
+ * `generateRangeSumProof` (e.g. inside a CLI that lays out witness data
+ * up front).
+ */
+export async function computeRangeSumAttestation(leafIndices, viewerNonce, style) {
+    // Only consult the variants registry when the caller didn't pick a style
+    // explicitly. The explicit-style path is for tests / parity checks that
+    // want to compute the hash without first compiling a variant.
+    const resolvedStyle = style ?? pickRangeSumVariant(leafIndices.length).attestation;
+    // circomlibjs's Poseidon caps at the same arity (16) as the circom-side
+    // hash. Importing the heavy circomlibjs module lazily keeps the SDK
+    // bundle slim for callers that never compute an attestation.
+    const { buildPoseidon } = await import("circomlibjs");
+    const poseidon = (await buildPoseidon());
+    const F = poseidon.F;
+    const indicesAsField = leafIndices.map((i) => F.e(BigInt(i)));
+    if (resolvedStyle === "flat") {
+        return F.toObject(poseidon([...indicesAsField, F.e(viewerNonce)]));
+    }
+    // chunked: split in half, hash each half, then hash the two digests + nonce.
+    const half = leafIndices.length / 2;
+    if (!Number.isInteger(half)) {
+        throw new Error(`chunked attestation requires an even cardinality; got N=${leafIndices.length}`);
+    }
+    const chunk1 = poseidon(indicesAsField.slice(0, half));
+    const chunk2 = poseidon(indicesAsField.slice(half));
+    return F.toObject(poseidon([chunk1, chunk2, F.e(viewerNonce)]));
+}
+/**
+ * Generate a range-sum ZK proof. The variant is picked automatically from
+ * `inputs.notes.length` — compile + register new variants in
+ * `RANGE_SUM_VARIANTS` to extend the supported cardinalities.
+ *
+ * Calls into the generic snarkjs prover with the matching circuit.
+ * Requires the compiled wasm + zkey under
+ * `<circuitBasePath>/<variant.circuit>/`.
+ *
+ * Public inputs: [leafIndices(N), merkleRoot, ceiling, token, attestation]
+ */
+export async function generateRangeSumProof(inputs) {
+    const variant = pickRangeSumVariant(inputs.notes.length);
+    const { generateGenericGroth16Proof } = await import("./prover/web");
+    return generateGenericGroth16Proof(variant.circuit, {
+        leafIndices: inputs.notes.map((n) => n.leafIndex),
+        merkleRoot: inputs.merkleRoot.toString(),
+        ceiling: inputs.ceiling.toString(),
+        token: inputs.tokenId.toString(),
+        attestation: inputs.attestation.toString(),
+        spendingPrivScalar: inputs.spendingPrivScalar.toString(),
+        nullifyingKey: inputs.nullifyingKey.toString(),
+        randomIn: inputs.notes.map((n) => n.randomIn.toString()),
+        valueIn: inputs.notes.map((n) => n.valueIn.toString()),
+        pathElements: inputs.notes.map((n) => n.pathElements.map((e) => e.toString())),
+        // pathIndices is derived in-circuit from the public leafIndices (Num2Bits),
+        // so it is no longer passed as a witness input.
+        viewerNonce: inputs.viewerNonce.toString(),
+        commitmentsIn: inputs.notes.map((n) => n.commitment.toString()),
+    });
+}