@veilo/sdk-core 0.1.17 → 0.3.3

package/dist/esm/index.js

@@ -0,0 +1,22 @@
+// Core client functions
+export * from "./client";
+// UTXO types and functions (replaces note.ts)
+export * from "./utxo";
+// Configuration constants and types
+export * from "./config";
+// Merkle tree implementation
+export * from "./merkle";
+// Proof types and helpers
+export * from "./proof";
+// On-chain event scanning and tree reconstruction
+export * from "./events";
+// Program factory and IDL
+export { createVeiloProgram, PRIVACY_POOL_IDL, PRIVACY_POOL_PROGRAM_ID, } from "./program";
+// Proof generation (requires snarkjs peer dependency)
+export { createTransactionProver, verifyProof } from "./prover";
+// Relayer API client
+export * from "./relayer";
+// RPC retry / resilience
+export { withRpcRetry, DEFAULT_RPC_RETRY } from "./retry";
+// Poseidon hash functions
+export { initPoseidon, getPoseidon, BN254_FR_MODULUS, bytesToBigIntBE, bigIntToBytesBE, frToBigInt, poseidon1, poseidon2, poseidon3, poseidon4, pubkeyToField, } from "./poseidon";

package/dist/esm/merkle.js

@@ -0,0 +1,129 @@
+import { BN254_FR_MODULUS, bytesToBigIntBE, bigIntToBytesBE, getPoseidon, frToBigInt, } from "./poseidon";
+// Poseidon-based hash of two 32-byte field elements.
+function hashPair(left, right) {
+    if (left.length !== 32 || right.length !== 32) {
+        throw new Error("hashPair expects 32-byte inputs");
+    }
+    const poseidon = getPoseidon();
+    const lf = bytesToBigIntBE(left) % BN254_FR_MODULUS;
+    const rf = bytesToBigIntBE(right) % BN254_FR_MODULUS;
+    const fe = poseidon([lf, rf]);
+    const outBig = frToBigInt(fe) % BN254_FR_MODULUS;
+    return bigIntToBytesBE(outBig);
+}
+/**
+ * Fixed-depth binary Merkle tree over BN254 Fr:
+ * - Leaves and internal nodes are 32-byte big-endian Fr elements.
+ * - Hash is Poseidon(2)(left, right).
+ * - Unfilled leaves use the Poseidon zero chain:
+ *     zero[0] = 0
+ *     zero[i+1] = Poseidon(zero[i], zero[i])
+ *
+ * Depth must match:
+ *   - Circom WithdrawCircuit(depth)
+ *   - Rust MERKLE_TREE_HEIGHT
+ */
+export class MerkleTree {
+    constructor(depth = 22) {
+        this.depth = depth;
+        this.zeroes = [];
+        this.layers = [];
+        // zero[0] = 0 (Fr), then zero[i+1] = Poseidon(zero[i], zero[i])
+        let zero = bigIntToBytesBE(0n);
+        this.zeroes.push(zero);
+        for (let level = 1; level <= depth; level++) {
+            zero = hashPair(zero, zero);
+            this.zeroes.push(zero);
+        }
+        // Allocate layers:
+        //  level 0: 2^depth leaves
+        //  level 1: 2^(depth-1) parents
+        //  ...
+        //  level depth: 1 root
+        for (let level = 0; level <= depth; level++) {
+            const size = 1 << (depth - level);
+            if (!Number.isSafeInteger(size) || size <= 0) {
+                throw new Error(`Invalid MerkleTree depth=${depth}, level=${level}, size=${size}`);
+            }
+            const arr = new Array(size);
+            for (let i = 0; i < size; i++) {
+                arr[i] = this.zeroes[level];
+            }
+            this.layers.push(arr);
+        }
+        this.nextIndex = 0;
+    }
+    get capacity() {
+        return 1 << this.depth;
+    }
+    get root() {
+        return this.layers[this.depth][0];
+    }
+    /**
+     * Insert a leaf and recompute the path up to the root.
+     * Returns the leaf index and the new root.
+     */
+    insert(leaf) {
+        if (leaf.length !== 32) {
+            throw new Error("leaf must be 32 bytes");
+        }
+        const index = this.nextIndex;
+        if (index >= this.capacity) {
+            throw new Error("Merkle tree is full");
+        }
+        // Set leaf
+        this.layers[0][index] = leaf;
+        // Bubble up
+        let idx = index;
+        for (let level = 1; level <= this.depth; level++) {
+            const parentIndex = Math.floor(idx / 2);
+            const leftIndex = parentIndex * 2;
+            const rightIndex = leftIndex + 1;
+            const left = this.layers[level - 1][leftIndex];
+            const right = rightIndex < this.layers[level - 1].length
+                ? this.layers[level - 1][rightIndex]
+                : this.zeroes[level - 1];
+            this.layers[level][parentIndex] = hashPair(left, right);
+            idx = parentIndex;
+        }
+        this.nextIndex++;
+        return { index, root: this.root };
+    }
+    /**
+     * Return Merkle proof (path + indices) for a given leaf index.
+     * This feeds directly into the Circom `MerklePathVerifier(depth)`:
+     *  - `pathElements[i]` = sibling
+     *  - `pathIndices[i]`  = 0/1 as defined above
+     */
+    getPath(index) {
+        if (index < 0 || index >= this.capacity) {
+            throw new Error("index out of range");
+        }
+        const path = [];
+        const indices = [];
+        let idx = index;
+        for (let level = 0; level < this.depth; level++) {
+            const isRight = idx % 2 === 1;
+            const siblingIndex = isRight ? idx - 1 : idx + 1;
+            const sibling = siblingIndex < this.layers[level].length
+                ? this.layers[level][siblingIndex]
+                : this.zeroes[level];
+            path.push(sibling);
+            // 0 = current is left, 1 = current is right
+            indices.push(isRight ? 1 : 0);
+            idx = Math.floor(idx / 2);
+        }
+        return { leafIndex: index, path, indices };
+    }
+    /**
+     * Return Merkle proof in circuit-compatible format.
+     * The circuit uses pathIndex directly and converts to bits via Num2Bits(levels).
+     */
+    getCircuitPath(index) {
+        const merklePath = this.getPath(index);
+        return {
+            pathIndex: index,
+            pathElements: merklePath.path.map((p) => bytesToBigIntBE(p) % BN254_FR_MODULUS),
+        };
+    }
+}

package/dist/esm/poseidon.js

@@ -0,0 +1,87 @@
+import { buildPoseidonReference } from "circomlibjs";
+let poseidonInstance = null;
+/** Initialize the Poseidon hash instance. Must be called once before using any UTXO/merkle/proof helpers. */
+export async function initPoseidon() {
+    poseidonInstance = (await buildPoseidonReference());
+}
+/** Get the initialized Poseidon instance. Throws if `initPoseidon()` has not been called. */
+export function getPoseidon() {
+    if (!poseidonInstance) {
+        throw new Error("Poseidon not initialized. Call initPoseidon() once before using utxo/merkle/proof helpers.");
+    }
+    return poseidonInstance;
+}
+/** The BN254 (alt_bn128) scalar field modulus. All Poseidon outputs are reduced modulo this value. */
+export const BN254_FR_MODULUS = BigInt("21888242871839275222246405745257275088548364400416034343698204186575808495617");
+/** Convert a big-endian byte array to a bigint. */
+export function bytesToBigIntBE(bytes) {
+    let x = 0n;
+    for (const b of bytes) {
+        x = (x << 8n) | BigInt(b);
+    }
+    return x;
+}
+/** Convert a bigint to a 32-byte big-endian array. */
+export function bigIntToBytesBE(x) {
+    const out = new Uint8Array(32);
+    let v = x;
+    for (let i = 31; i >= 0; i--) {
+        out[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return out;
+}
+/** Convert ffjavascript field element → bigint safely */
+export function frToBigInt(fe) {
+    const poseidon = getPoseidon();
+    const F = poseidon.F;
+    if (typeof fe === "bigint") {
+        return fe;
+    }
+    if (F && typeof F.toObject === "function") {
+        // This is how ffjavascript exposes the underlying BigInt
+        return F.toObject(fe);
+    }
+    // Fallback: treat as decimal string
+    return BigInt(fe.toString());
+}
+// -----------------------------------------------------------------------------
+// Helper functions for variable-arity Poseidon hashing
+// -----------------------------------------------------------------------------
+/** Poseidon hash with 1 input - used for keypair derivation: pubkey = Poseidon(privateKey) */
+export function poseidon1(a) {
+    const poseidon = getPoseidon();
+    const fe = poseidon([a % BN254_FR_MODULUS]);
+    return frToBigInt(fe) % BN254_FR_MODULUS;
+}
+/** Poseidon hash with 2 inputs */
+export function poseidon2(a, b) {
+    const poseidon = getPoseidon();
+    const fe = poseidon([a % BN254_FR_MODULUS, b % BN254_FR_MODULUS]);
+    return frToBigInt(fe) % BN254_FR_MODULUS;
+}
+/** Poseidon hash with 3 inputs - used for signature: Poseidon(privateKey, commitment, pathIndex) */
+export function poseidon3(a, b, c) {
+    const poseidon = getPoseidon();
+    const fe = poseidon([
+        a % BN254_FR_MODULUS,
+        b % BN254_FR_MODULUS,
+        c % BN254_FR_MODULUS,
+    ]);
+    return frToBigInt(fe) % BN254_FR_MODULUS;
+}
+/** Poseidon hash with 4 inputs - used for UTXO commitment: Poseidon(amount, pubkey, blinding, mintAddress) */
+export function poseidon4(a, b, c, d) {
+    const poseidon = getPoseidon();
+    const fe = poseidon([
+        a % BN254_FR_MODULUS,
+        b % BN254_FR_MODULUS,
+        c % BN254_FR_MODULUS,
+        d % BN254_FR_MODULUS,
+    ]);
+    return frToBigInt(fe) % BN254_FR_MODULUS;
+}
+/** Convert a Solana PublicKey to a BN254 field element */
+export function pubkeyToField(pubkey) {
+    return bytesToBigIntBE(pubkey.toBytes()) % BN254_FR_MODULUS;
+}

package/dist/esm/program.js

@@ -0,0 +1,31 @@
+import { Program, AnchorProvider } from "@coral-xyz/anchor";
+import { PublicKey } from "@solana/web3.js";
+import IDL_JSON from "./idl/privacy_pool.json";
+// Re-export so consumers can access the raw IDL if needed
+export const PRIVACY_POOL_IDL = IDL_JSON;
+/** Deployed program ID extracted from the bundled IDL. */
+export const PRIVACY_POOL_PROGRAM_ID = new PublicKey(IDL_JSON.address);
+/**
+ * Create an Anchor `Program` instance for the Veilo Privacy Pool.
+ *
+ * @param connection  Solana RPC connection
+ * @param wallet      Anchor-compatible wallet (must implement `publicKey` and `signTransaction`)
+ * @param opts        Optional commitment level (default: "confirmed")
+ *
+ * @example
+ * ```ts
+ * import { createVeiloProgram } from "@veilo/sdk-core";
+ * import { Connection } from "@solana/web3.js";
+ *
+ * const program = createVeiloProgram(
+ *   new Connection("https://api.devnet.solana.com"),
+ *   wallet,
+ * );
+ * ```
+ */
+export function createVeiloProgram(connection, wallet, opts) {
+    const provider = new AnchorProvider(connection, wallet, {
+        commitment: opts?.commitment ?? "confirmed",
+    });
+    return new Program(PRIVACY_POOL_IDL, provider);
+}

package/dist/esm/proof.js

@@ -0,0 +1,281 @@
+import { sha256 } from "@noble/hashes/sha256";
+import { BN254_FR_MODULUS, bigIntToBytesBE, bytesToBigIntBE, poseidon2, poseidon3, pubkeyToField, } from "./poseidon";
+import { deriveNullifier } from "./utxo";
+// -----------------------------------------------------------------------------
+// ExtData Hash Computation
+// -----------------------------------------------------------------------------
+/**
+ * Compute the external data hash.
+ * Matches on-chain computation:
+ *   hash1 = Poseidon(recipient, relayer)
+ *   hash2 = Poseidon(fee, refund)
+ *   extDataHash = Poseidon(hash1, hash2, claimant)
+ */
+export function computeExtDataHash(extData) {
+    const recipientField = pubkeyToField(extData.recipient);
+    const relayerField = pubkeyToField(extData.relayer);
+    const feeField = extData.fee % BN254_FR_MODULUS;
+    const refundField = extData.refund % BN254_FR_MODULUS;
+    const claimantField = pubkeyToField(extData.claimant);
+    const hash1 = poseidon2(recipientField, relayerField);
+    const hash2 = poseidon2(feeField, refundField);
+    const finalHash = poseidon3(hash1, hash2, claimantField);
+    return bigIntToBytesBE(finalHash);
+}
+// -----------------------------------------------------------------------------
+// Circuit Input Preparation
+// -----------------------------------------------------------------------------
+/**
+ * Convert i64 to field element (handles negative via modular arithmetic).
+ * For negative values, we add the field modulus to get the equivalent positive representation.
+ */
+export function i64ToField(value) {
+    if (value >= 0n) {
+        return value % BN254_FR_MODULUS;
+    }
+    return (BN254_FR_MODULUS + value) % BN254_FR_MODULUS;
+}
+/**
+ * Prepare transaction circuit inputs from high-level parameters.
+ * This converts the SDK types into the format expected by the circuit.
+ */
+export function prepareTransactionInputs(params) {
+    const { inputUTXOs, outputUTXOs, root, publicAmount, extData, mintAddress } = params;
+    const extDataHash = computeExtDataHash(extData);
+    const mintField = pubkeyToField(mintAddress);
+    // Prepare input UTXO data
+    const inAmount = [
+        inputUTXOs[0].amount,
+        inputUTXOs[1].amount,
+    ];
+    const inPubkey = [
+        inputUTXOs[0].pubkey,
+        inputUTXOs[1].pubkey,
+    ];
+    const inBlinding = [
+        inputUTXOs[0].blinding,
+        inputUTXOs[1].blinding,
+    ];
+    const inPathIndex = [
+        inputUTXOs[0].pathIndex,
+        inputUTXOs[1].pathIndex,
+    ];
+    const inPathElements = [
+        inputUTXOs[0].pathElements.map((e) => bytesToBigIntBE(e) % BN254_FR_MODULUS),
+        inputUTXOs[1].pathElements.map((e) => bytesToBigIntBE(e) % BN254_FR_MODULUS),
+    ];
+    const inPrivateKey = [
+        inputUTXOs[0].privateKey,
+        inputUTXOs[1].privateKey,
+    ];
+    // Prepare output UTXO data
+    const outAmount = [
+        outputUTXOs[0].amount,
+        outputUTXOs[1].amount,
+    ];
+    const outPubkey = [
+        outputUTXOs[0].pubkey,
+        outputUTXOs[1].pubkey,
+    ];
+    const outBlinding = [
+        outputUTXOs[0].blinding,
+        outputUTXOs[1].blinding,
+    ];
+    // Derive nullifiers for input UTXOs
+    const inputNullifiers = [
+        deriveNullifier(inputUTXOs[0], inputUTXOs[0].pathIndex, inputUTXOs[0].privateKey),
+        deriveNullifier(inputUTXOs[1], inputUTXOs[1].pathIndex, inputUTXOs[1].privateKey),
+    ];
+    return {
+        root,
+        publicAmount,
+        extDataHash,
+        mintAddress,
+        inputNullifiers,
+        outputCommitments: [outputUTXOs[0].commitment, outputUTXOs[1].commitment],
+        inAmount,
+        inPubkey,
+        inBlinding,
+        inPathIndex,
+        inPathElements,
+        inPrivateKey,
+        outAmount,
+        outPubkey,
+        outBlinding,
+    };
+}
+// -----------------------------------------------------------------------------
+// Proof Packing
+// -----------------------------------------------------------------------------
+/**
+ * Convert bigint to 32-byte big-endian representation.
+ * The alt_bn128 Solana precompile (and ark-works via change_endianness) expect BE.
+ */
+function bigintTo32BytesBE(x) {
+    const out = new Uint8Array(32);
+    let v = x;
+    for (let i = 31; i >= 0; i--) {
+        out[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return out;
+}
+/**
+ * Turn a snarkjs Groth16 proof into 256 bytes:
+ *   A(G1) | B(G2) | C(G1)
+ * where:
+ *   A = (ax, ay)               -> 64 bytes
+ *   B = (bx1, bx0, by1, by0)  -> 128 bytes  (swapped pairs for alt_bn128)
+ *   C = (cx, cy)               -> 64 bytes
+ *
+ * Each field element is encoded as 32-byte BE to match the on-chain verifier.
+ * We ignore the extra projective/z components snarkjs keeps.
+ */
+export function packProofToBytes(proof) {
+    const chunks = [];
+    const ax = BigInt(proof.pi_a[0]);
+    const ay = BigInt(proof.pi_a[1]);
+    chunks.push(bigintTo32BytesBE(ax), bigintTo32BytesBE(ay));
+    const bx = proof.pi_b[0];
+    const by = proof.pi_b[1];
+    const bx0 = BigInt(bx[0]);
+    const bx1 = BigInt(bx[1]);
+    const by0 = BigInt(by[0]);
+    const by1 = BigInt(by[1]);
+    // alt_bn128 expects the G2 pairs swapped: bx1 before bx0, by1 before by0
+    chunks.push(bigintTo32BytesBE(bx1), bigintTo32BytesBE(bx0), bigintTo32BytesBE(by1), bigintTo32BytesBE(by0));
+    const cx = BigInt(proof.pi_c[0]);
+    const cy = BigInt(proof.pi_c[1]);
+    chunks.push(bigintTo32BytesBE(cx), bigintTo32BytesBE(cy));
+    const out = new Uint8Array(32 * (2 + 4 + 2)); // 256
+    let offset = 0;
+    for (const c of chunks) {
+        out.set(c, offset);
+        offset += c.length;
+    }
+    return out;
+}
+/**
+ * Encode a snarkjs proof into the TransactionProofStruct format expected by the on-chain program.
+ */
+export function encodeSnarkjsProofToTransactionProof(proof) {
+    const full = packProofToBytes(proof);
+    if (full.length !== 256) {
+        throw new Error(`Expected 256 proof bytes, got ${full.length}`);
+    }
+    const proofA = full.slice(0, 64);
+    const proofB = full.slice(64, 192);
+    const proofC = full.slice(192, 256);
+    return {
+        proofA: Array.from(proofA),
+        proofB: Array.from(proofB),
+        proofC: Array.from(proofC),
+    };
+}
+// -----------------------------------------------------------------------------
+// Snarkjs Input Formatting
+// -----------------------------------------------------------------------------
+/**
+ * Convert TransactionCircuitInputs to the format expected by snarkjs.groth16.fullProve().
+ * All values are converted to strings (snarkjs expects string inputs for field elements).
+ */
+export function formatInputsForSnarkjs(inputs) {
+    return {
+        // Public inputs
+        root: bytesToBigIntBE(inputs.root).toString(),
+        publicAmount: i64ToField(inputs.publicAmount).toString(),
+        extDataHash: bytesToBigIntBE(inputs.extDataHash).toString(),
+        mintAddress: pubkeyToField(inputs.mintAddress).toString(),
+        inputNullifier: inputs.inputNullifiers.map((n) => bytesToBigIntBE(n).toString()),
+        outputCommitment: inputs.outputCommitments.map((c) => bytesToBigIntBE(c).toString()),
+        // Private inputs - Input UTXOs
+        inAmount: inputs.inAmount.map((a) => a.toString()),
+        inPubkey: inputs.inPubkey.map((p) => p.toString()),
+        inBlinding: inputs.inBlinding.map((b) => b.toString()),
+        inPathIndex: inputs.inPathIndex.map((i) => i.toString()),
+        inPathElements: inputs.inPathElements.map((path) => path.map((e) => e.toString())),
+        inPrivateKey: inputs.inPrivateKey.map((k) => k.toString()),
+        // Private inputs - Output UTXOs
+        outAmount: inputs.outAmount.map((a) => a.toString()),
+        outPubkey: inputs.outPubkey.map((p) => p.toString()),
+        outBlinding: inputs.outBlinding.map((b) => b.toString()),
+    };
+}
+/**
+ * Convert SwapCircuitInputs into the shape expected by
+ * snarkjs.groth16.fullProve() for swap.circom. Every value is emitted as a
+ * decimal string (or string array) because snarkjs only accepts field
+ * elements as strings.
+ *
+ * Mirrors `generateSwapProof` in
+ * relayer-server/src/controllers/swap.helpers.ts so SDK-side swap proofs
+ * verify against the same circuit the relayer uses.
+ */
+export function formatSwapInputsForSnarkjs(inputs) {
+    return {
+        // Public inputs
+        sourceRoot: bytesToBigIntBE(inputs.sourceRoot).toString(),
+        swapParamsHash: bytesToBigIntBE(inputs.swapParamsHash).toString(),
+        extDataHash: bytesToBigIntBE(inputs.extDataHash).toString(),
+        sourceMint: pubkeyToField(inputs.sourceMint).toString(),
+        destMint: pubkeyToField(inputs.destMint).toString(),
+        inputNullifier: inputs.inputNullifiers.map((n) => bytesToBigIntBE(n).toString()),
+        changeCommitment: bytesToBigIntBE(inputs.changeCommitment).toString(),
+        destCommitment: bytesToBigIntBE(inputs.destCommitment).toString(),
+        swapAmount: inputs.swapAmount.toString(),
+        // Private inputs - Input UTXOs
+        inAmount: inputs.inAmount.map((a) => a.toString()),
+        inPubkey: inputs.inPubkey.map((p) => p.toString()),
+        inBlinding: inputs.inBlinding.map((b) => b.toString()),
+        inPathIndex: inputs.inPathIndex.map((i) => i.toString()),
+        inPathElements: inputs.inPathElements.map((path) => path.map((e) => e.toString())),
+        inPrivateKey: inputs.inPrivateKey.map((k) => k.toString()),
+        // Private inputs - Change UTXO
+        changeAmount: inputs.changeAmount.toString(),
+        changePubkey: inputs.changePubkey.toString(),
+        changeBlinding: inputs.changeBlinding.toString(),
+        // Private inputs - Destination UTXO
+        destAmount: inputs.destAmount.toString(),
+        destPubkey: inputs.destPubkey.toString(),
+        destBlinding: inputs.destBlinding.toString(),
+        // Swap params
+        minAmountOut: inputs.minAmountOut.toString(),
+        deadline: inputs.deadline.toString(),
+    };
+}
+// -----------------------------------------------------------------------------
+// Swap Parameter Hashing
+// -----------------------------------------------------------------------------
+/**
+ * Compute the swap params hash that the swap circuit and on-chain program verify.
+ * Mirrors relayer-server/src/controllers/swap.helpers.ts `computeSwapParamsHash`.
+ *
+ * Circuit formula (swap.circom lines 293-307):
+ *   mintPairHash   = Poseidon(sourceMint, destMint)
+ *   swapTermsHash  = Poseidon(minAmountOut, deadline, destAmount)
+ *   swapParamsHash = Poseidon(mintPairHash, swapTermsHash)
+ *
+ * @param sourceMint   Source pool mint
+ * @param destMint     Destination pool mint
+ * @param minAmountOut Minimum accepted output amount (slippage protected)
+ * @param deadline     Unix timestamp deadline (i64, 0 = no deadline)
+ * @param destAmount   Actual amount committed to destination UTXO (≥ minAmountOut -
+ *                     relayerFee). If omitted, defaults to minAmountOut.
+ */
+export function computeSwapParamsHash(sourceMint, destMint, minAmountOut, deadline, destAmount) {
+    const srcField = pubkeyToField(sourceMint);
+    const dstField = pubkeyToField(destMint);
+    const mintPairHash = poseidon2(srcField, dstField);
+    const dest = destAmount ?? minAmountOut;
+    const swapTermsHash = poseidon3(minAmountOut, deadline, dest);
+    const paramsHash = poseidon2(mintPairHash, swapTermsHash);
+    return bigIntToBytesBE(paramsHash);
+}
+/**
+ * Compute the swap data hash committed on-chain for Jupiter instruction integrity.
+ * SHA-256 of the raw Jupiter swap instruction data bytes.
+ * Mirrors relayer-server/src/controllers/swap.helpers.ts `computeSwapDataHash`.
+ */
+export function computeSwapDataHash(swapData) {
+    return sha256(swapData instanceof Buffer ? new Uint8Array(swapData) : swapData);
+}

package/dist/esm/prover.js

@@ -0,0 +1,75 @@
+import { formatInputsForSnarkjs, } from "./proof";
+/** Lazy-load snarkjs — works in both CJS and ESM contexts. */
+async function loadSnarkjs() {
+    try {
+        // Dynamic import works in both CJS (Node 12+) and ESM
+        return await Function('return import("snarkjs")')();
+    }
+    catch {
+        throw new Error("snarkjs is required for proof generation. Install it: npm install snarkjs");
+    }
+}
+/**
+ * Create a proof builder function for the transaction circuit.
+ *
+ * Uses dynamic `import("snarkjs")` so the dependency is only loaded when
+ * proof generation is actually called. Install snarkjs as a peer dependency:
+ *
+ * ```
+ * npm install snarkjs
+ * ```
+ *
+ * @param artifacts  Paths or buffers to the circuit WASM and zkey files
+ * @returns A `TransactionProofBuilder` callback compatible with the SDK's client functions
+ *
+ * @example
+ * ```ts
+ * import { createTransactionProver } from "@veilo/sdk-core";
+ *
+ * const prover = createTransactionProver({
+ *   wasmPath: "./circuits/transaction.wasm",
+ *   zkeyPath: "./circuits/transaction_final.zkey",
+ * });
+ *
+ * // Pass to SDK functions that accept a TransactionProofBuilder
+ * const proof = await prover(circuitInputs);
+ * ```
+ */
+export function createTransactionProver(artifacts) {
+    return async (inputs) => {
+        const snarkjs = await loadSnarkjs();
+        const formattedInputs = formatInputsForSnarkjs(inputs);
+        const { proof } = await snarkjs.groth16.fullProve(formattedInputs, artifacts.wasmPath, artifacts.zkeyPath);
+        return proof;
+    };
+}
+/**
+ * Verify a Groth16 proof against public signals and a verification key.
+ *
+ * Useful for local verification before submitting to the relayer.
+ *
+ * @param proof       The raw snarkjs proof
+ * @param publicSignals  Array of public signal strings
+ * @param vkeyPath    Path to the verification key JSON file, or the parsed JSON object
+ * @returns true if the proof is valid
+ */
+export async function verifyProof(proof, publicSignals, vkey) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    let snarkjs;
+    try {
+        snarkjs = require("snarkjs");
+    }
+    catch {
+        throw new Error('snarkjs is required for proof verification. Install it: npm install snarkjs');
+    }
+    let vkeyObj;
+    if (typeof vkey === "string") {
+        // Node.js file path — read and parse
+        const fs = await import("fs");
+        vkeyObj = JSON.parse(fs.readFileSync(vkey, "utf-8"));
+    }
+    else {
+        vkeyObj = vkey;
+    }
+    return snarkjs.groth16.verify(vkeyObj, publicSignals, proof);
+}