@veilo/sdk-core 0.1.17 → 0.3.3

package/dist/cjs/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./client";
+export * from "./utxo";
+export * from "./config";
+export * from "./merkle";
+export * from "./proof";
+export * from "./events";
+export { createVeiloProgram, PRIVACY_POOL_IDL, PRIVACY_POOL_PROGRAM_ID, } from "./program";
+export { createTransactionProver, verifyProof } from "./prover";
+export type { CircuitArtifacts } from "./prover";
+export * from "./relayer";
+export { withRpcRetry, DEFAULT_RPC_RETRY } from "./retry";
+export type { RpcRetryPolicy } from "./retry";
+export { initPoseidon, getPoseidon, BN254_FR_MODULUS, bytesToBigIntBE, bigIntToBytesBE, frToBigInt, poseidon1, poseidon2, poseidon3, poseidon4, pubkeyToField, } from "./poseidon";

package/dist/cjs/index.js

@@ -0,0 +1,57 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pubkeyToField = exports.poseidon4 = exports.poseidon3 = exports.poseidon2 = exports.poseidon1 = exports.frToBigInt = exports.bigIntToBytesBE = exports.bytesToBigIntBE = exports.BN254_FR_MODULUS = exports.getPoseidon = exports.initPoseidon = exports.DEFAULT_RPC_RETRY = exports.withRpcRetry = exports.verifyProof = exports.createTransactionProver = exports.PRIVACY_POOL_PROGRAM_ID = exports.PRIVACY_POOL_IDL = exports.createVeiloProgram = void 0;
+// Core client functions
+__exportStar(require("./client"), exports);
+// UTXO types and functions (replaces note.ts)
+__exportStar(require("./utxo"), exports);
+// Configuration constants and types
+__exportStar(require("./config"), exports);
+// Merkle tree implementation
+__exportStar(require("./merkle"), exports);
+// Proof types and helpers
+__exportStar(require("./proof"), exports);
+// On-chain event scanning and tree reconstruction
+__exportStar(require("./events"), exports);
+// Program factory and IDL
+var program_1 = require("./program");
+Object.defineProperty(exports, "createVeiloProgram", { enumerable: true, get: function () { return program_1.createVeiloProgram; } });
+Object.defineProperty(exports, "PRIVACY_POOL_IDL", { enumerable: true, get: function () { return program_1.PRIVACY_POOL_IDL; } });
+Object.defineProperty(exports, "PRIVACY_POOL_PROGRAM_ID", { enumerable: true, get: function () { return program_1.PRIVACY_POOL_PROGRAM_ID; } });
+// Proof generation (requires snarkjs peer dependency)
+var prover_1 = require("./prover");
+Object.defineProperty(exports, "createTransactionProver", { enumerable: true, get: function () { return prover_1.createTransactionProver; } });
+Object.defineProperty(exports, "verifyProof", { enumerable: true, get: function () { return prover_1.verifyProof; } });
+// Relayer API client
+__exportStar(require("./relayer"), exports);
+// RPC retry / resilience
+var retry_1 = require("./retry");
+Object.defineProperty(exports, "withRpcRetry", { enumerable: true, get: function () { return retry_1.withRpcRetry; } });
+Object.defineProperty(exports, "DEFAULT_RPC_RETRY", { enumerable: true, get: function () { return retry_1.DEFAULT_RPC_RETRY; } });
+// Poseidon hash functions
+var poseidon_1 = require("./poseidon");
+Object.defineProperty(exports, "initPoseidon", { enumerable: true, get: function () { return poseidon_1.initPoseidon; } });
+Object.defineProperty(exports, "getPoseidon", { enumerable: true, get: function () { return poseidon_1.getPoseidon; } });
+Object.defineProperty(exports, "BN254_FR_MODULUS", { enumerable: true, get: function () { return poseidon_1.BN254_FR_MODULUS; } });
+Object.defineProperty(exports, "bytesToBigIntBE", { enumerable: true, get: function () { return poseidon_1.bytesToBigIntBE; } });
+Object.defineProperty(exports, "bigIntToBytesBE", { enumerable: true, get: function () { return poseidon_1.bigIntToBytesBE; } });
+Object.defineProperty(exports, "frToBigInt", { enumerable: true, get: function () { return poseidon_1.frToBigInt; } });
+Object.defineProperty(exports, "poseidon1", { enumerable: true, get: function () { return poseidon_1.poseidon1; } });
+Object.defineProperty(exports, "poseidon2", { enumerable: true, get: function () { return poseidon_1.poseidon2; } });
+Object.defineProperty(exports, "poseidon3", { enumerable: true, get: function () { return poseidon_1.poseidon3; } });
+Object.defineProperty(exports, "poseidon4", { enumerable: true, get: function () { return poseidon_1.poseidon4; } });
+Object.defineProperty(exports, "pubkeyToField", { enumerable: true, get: function () { return poseidon_1.pubkeyToField; } });

package/dist/cjs/merkle.d.ts

@@ -0,0 +1,64 @@
+export type MerklePath = {
+    /** Index of the leaf in the tree (0-based) */
+    leafIndex: number;
+    /** Sibling hashes from leaf level up to (but not including) the root */
+    path: Uint8Array[];
+    /**
+     * 0 = current node is left child, sibling is right
+     * 1 = current node is right child, sibling is left
+     * (matches your Circom `pathIndices` semantics)
+     */
+    indices: number[];
+};
+/**
+ * Circuit-compatible Merkle path format.
+ * The pathIndex is used directly (circuit converts to bits internally via Num2Bits).
+ */
+export type CircuitMerklePath = {
+    /** Leaf index (circuit converts to bits internally) */
+    pathIndex: number;
+    /** Sibling hashes as field elements */
+    pathElements: bigint[];
+};
+export type Bytes32 = Uint8Array;
+/**
+ * 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 declare class MerkleTree {
+    readonly depth: number;
+    readonly zeroes: Uint8Array[];
+    readonly layers: Uint8Array[][];
+    nextIndex: number;
+    constructor(depth?: number);
+    get capacity(): number;
+    get root(): Uint8Array;
+    /**
+     * Insert a leaf and recompute the path up to the root.
+     * Returns the leaf index and the new root.
+     */
+    insert(leaf: Uint8Array): {
+        index: number;
+        root: Uint8Array;
+    };
+    /**
+     * 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: number): MerklePath;
+    /**
+     * Return Merkle proof in circuit-compatible format.
+     * The circuit uses pathIndex directly and converts to bits via Num2Bits(levels).
+     */
+    getCircuitPath(index: number): CircuitMerklePath;
+}

package/dist/cjs/merkle.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MerkleTree = void 0;
+const poseidon_1 = require("./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 = (0, poseidon_1.getPoseidon)();
+    const lf = (0, poseidon_1.bytesToBigIntBE)(left) % poseidon_1.BN254_FR_MODULUS;
+    const rf = (0, poseidon_1.bytesToBigIntBE)(right) % poseidon_1.BN254_FR_MODULUS;
+    const fe = poseidon([lf, rf]);
+    const outBig = (0, poseidon_1.frToBigInt)(fe) % poseidon_1.BN254_FR_MODULUS;
+    return (0, poseidon_1.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
+ */
+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 = (0, poseidon_1.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) => (0, poseidon_1.bytesToBigIntBE)(p) % poseidon_1.BN254_FR_MODULUS),
+        };
+    }
+}
+exports.MerkleTree = MerkleTree;

package/dist/cjs/poseidon.d.ts

@@ -0,0 +1,29 @@
+import { PublicKey } from "@solana/web3.js";
+/** Poseidon hash function type from circomlibjs. */
+export type PoseidonFn = ((inputs: bigint[]) => any) & {
+    F: {
+        toObject: (e: any) => bigint;
+    };
+};
+/** Initialize the Poseidon hash instance. Must be called once before using any UTXO/merkle/proof helpers. */
+export declare function initPoseidon(): Promise<void>;
+/** Get the initialized Poseidon instance. Throws if `initPoseidon()` has not been called. */
+export declare function getPoseidon(): PoseidonFn;
+/** The BN254 (alt_bn128) scalar field modulus. All Poseidon outputs are reduced modulo this value. */
+export declare const BN254_FR_MODULUS: bigint;
+/** Convert a big-endian byte array to a bigint. */
+export declare function bytesToBigIntBE(bytes: Uint8Array): bigint;
+/** Convert a bigint to a 32-byte big-endian array. */
+export declare function bigIntToBytesBE(x: bigint): Uint8Array;
+/** Convert ffjavascript field element → bigint safely */
+export declare function frToBigInt(fe: any): bigint;
+/** Poseidon hash with 1 input - used for keypair derivation: pubkey = Poseidon(privateKey) */
+export declare function poseidon1(a: bigint): bigint;
+/** Poseidon hash with 2 inputs */
+export declare function poseidon2(a: bigint, b: bigint): bigint;
+/** Poseidon hash with 3 inputs - used for signature: Poseidon(privateKey, commitment, pathIndex) */
+export declare function poseidon3(a: bigint, b: bigint, c: bigint): bigint;
+/** Poseidon hash with 4 inputs - used for UTXO commitment: Poseidon(amount, pubkey, blinding, mintAddress) */
+export declare function poseidon4(a: bigint, b: bigint, c: bigint, d: bigint): bigint;
+/** Convert a Solana PublicKey to a BN254 field element */
+export declare function pubkeyToField(pubkey: PublicKey): bigint;

package/dist/cjs/poseidon.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BN254_FR_MODULUS = void 0;
+exports.initPoseidon = initPoseidon;
+exports.getPoseidon = getPoseidon;
+exports.bytesToBigIntBE = bytesToBigIntBE;
+exports.bigIntToBytesBE = bigIntToBytesBE;
+exports.frToBigInt = frToBigInt;
+exports.poseidon1 = poseidon1;
+exports.poseidon2 = poseidon2;
+exports.poseidon3 = poseidon3;
+exports.poseidon4 = poseidon4;
+exports.pubkeyToField = pubkeyToField;
+const circomlibjs_1 = require("circomlibjs");
+let poseidonInstance = null;
+/** Initialize the Poseidon hash instance. Must be called once before using any UTXO/merkle/proof helpers. */
+async function initPoseidon() {
+    poseidonInstance = (await (0, circomlibjs_1.buildPoseidonReference)());
+}
+/** Get the initialized Poseidon instance. Throws if `initPoseidon()` has not been called. */
+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. */
+exports.BN254_FR_MODULUS = BigInt("21888242871839275222246405745257275088548364400416034343698204186575808495617");
+/** Convert a big-endian byte array to a bigint. */
+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. */
+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 */
+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) */
+function poseidon1(a) {
+    const poseidon = getPoseidon();
+    const fe = poseidon([a % exports.BN254_FR_MODULUS]);
+    return frToBigInt(fe) % exports.BN254_FR_MODULUS;
+}
+/** Poseidon hash with 2 inputs */
+function poseidon2(a, b) {
+    const poseidon = getPoseidon();
+    const fe = poseidon([a % exports.BN254_FR_MODULUS, b % exports.BN254_FR_MODULUS]);
+    return frToBigInt(fe) % exports.BN254_FR_MODULUS;
+}
+/** Poseidon hash with 3 inputs - used for signature: Poseidon(privateKey, commitment, pathIndex) */
+function poseidon3(a, b, c) {
+    const poseidon = getPoseidon();
+    const fe = poseidon([
+        a % exports.BN254_FR_MODULUS,
+        b % exports.BN254_FR_MODULUS,
+        c % exports.BN254_FR_MODULUS,
+    ]);
+    return frToBigInt(fe) % exports.BN254_FR_MODULUS;
+}
+/** Poseidon hash with 4 inputs - used for UTXO commitment: Poseidon(amount, pubkey, blinding, mintAddress) */
+function poseidon4(a, b, c, d) {
+    const poseidon = getPoseidon();
+    const fe = poseidon([
+        a % exports.BN254_FR_MODULUS,
+        b % exports.BN254_FR_MODULUS,
+        c % exports.BN254_FR_MODULUS,
+        d % exports.BN254_FR_MODULUS,
+    ]);
+    return frToBigInt(fe) % exports.BN254_FR_MODULUS;
+}
+/** Convert a Solana PublicKey to a BN254 field element */
+function pubkeyToField(pubkey) {
+    return bytesToBigIntBE(pubkey.toBytes()) % exports.BN254_FR_MODULUS;
+}

package/dist/cjs/program.d.ts

@@ -0,0 +1,26 @@
+import { Program, Idl, Wallet } from "@coral-xyz/anchor";
+import { Connection, PublicKey } from "@solana/web3.js";
+export declare const PRIVACY_POOL_IDL: Idl;
+/** Deployed program ID extracted from the bundled IDL. */
+export declare const PRIVACY_POOL_PROGRAM_ID: PublicKey;
+/**
+ * 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 declare function createVeiloProgram(connection: Connection, wallet: Wallet, opts?: {
+    commitment?: "processed" | "confirmed" | "finalized";
+}): Program;

package/dist/cjs/program.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRIVACY_POOL_PROGRAM_ID = exports.PRIVACY_POOL_IDL = void 0;
+exports.createVeiloProgram = createVeiloProgram;
+const anchor_1 = require("@coral-xyz/anchor");
+const web3_js_1 = require("@solana/web3.js");
+const privacy_pool_json_1 = __importDefault(require("./idl/privacy_pool.json"));
+// Re-export so consumers can access the raw IDL if needed
+exports.PRIVACY_POOL_IDL = privacy_pool_json_1.default;
+/** Deployed program ID extracted from the bundled IDL. */
+exports.PRIVACY_POOL_PROGRAM_ID = new web3_js_1.PublicKey(privacy_pool_json_1.default.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,
+ * );
+ * ```
+ */
+function createVeiloProgram(connection, wallet, opts) {
+    const provider = new anchor_1.AnchorProvider(connection, wallet, {
+        commitment: opts?.commitment ?? "confirmed",
+    });
+    return new anchor_1.Program(exports.PRIVACY_POOL_IDL, provider);
+}

package/dist/cjs/proof.d.ts

@@ -0,0 +1,183 @@
+import { PublicKey } from "@solana/web3.js";
+import { SerializedUTXO, InputUTXO } from "./utxo";
+/**
+ * External data that gets hashed into ext_data_hash.
+ * These are public parameters that affect financial flows.
+ */
+export type ExtData = {
+    /** Who receives withdrawal (for withdrawals) */
+    recipient: PublicKey;
+    /** Who submits tx and gets fee */
+    relayer: PublicKey;
+    /** Fee to relayer in lamports/token units */
+    fee: bigint;
+    /** Refund to user in lamports/token units (for gas compensation) */
+    refund: bigint;
+    /** Claimant key committed into the proof */
+    claimant: PublicKey;
+};
+/**
+ * Transaction circuit inputs (8 public inputs, many private inputs).
+ * This structure is used to prepare inputs for the snarkjs prover.
+ */
+export type TransactionCircuitInputs = {
+    /** Merkle root of UTXO tree */
+    root: Uint8Array;
+    /** Net deposit/withdrawal amount (positive = deposit, negative = withdrawal) */
+    publicAmount: bigint;
+    /** Hash of external data (recipient, relayer, fee, refund) */
+    extDataHash: Uint8Array;
+    /** Token mint address */
+    mintAddress: PublicKey;
+    /** Nullifiers for the two input UTXOs */
+    inputNullifiers: [Uint8Array, Uint8Array];
+    /** Commitments for the two output UTXOs */
+    outputCommitments: [Uint8Array, Uint8Array];
+    inAmount: [bigint, bigint];
+    inPubkey: [bigint, bigint];
+    inBlinding: [bigint, bigint];
+    inPathIndex: [number, number];
+    inPathElements: [bigint[], bigint[]];
+    inPrivateKey: [bigint, bigint];
+    outAmount: [bigint, bigint];
+    outPubkey: [bigint, bigint];
+    outBlinding: [bigint, bigint];
+};
+/**
+ * Proof structure matching the on-chain TransactionProof struct.
+ * Total size: 256 bytes (64 + 128 + 64)
+ */
+export type TransactionProofStruct = {
+    /** G1 point A (64 bytes) */
+    proofA: number[];
+    /** G2 point B (128 bytes) */
+    proofB: number[];
+    /** G1 point C (64 bytes) */
+    proofC: number[];
+};
+/**
+ * Shape of a Groth16 proof produced by snarkjs.
+ */
+export type RawProof = {
+    pi_a: [string, string, string];
+    pi_b: [[string, string], [string, string], [string, string]];
+    pi_c: [string, string, string];
+    protocol: string;
+    curve: string;
+};
+/**
+ * Proof builder function type - takes circuit inputs and returns a raw snarkjs proof.
+ */
+export type TransactionProofBuilder = (inputs: TransactionCircuitInputs) => Promise<RawProof>;
+/**
+ * Compute the external data hash.
+ * Matches on-chain computation:
+ *   hash1 = Poseidon(recipient, relayer)
+ *   hash2 = Poseidon(fee, refund)
+ *   extDataHash = Poseidon(hash1, hash2, claimant)
+ */
+export declare function computeExtDataHash(extData: ExtData): Uint8Array;
+/**
+ * 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 declare function i64ToField(value: bigint): bigint;
+/**
+ * Prepare transaction circuit inputs from high-level parameters.
+ * This converts the SDK types into the format expected by the circuit.
+ */
+export declare function prepareTransactionInputs(params: {
+    inputUTXOs: [InputUTXO, InputUTXO];
+    outputUTXOs: [SerializedUTXO, SerializedUTXO];
+    root: Uint8Array;
+    publicAmount: bigint;
+    extData: ExtData;
+    mintAddress: PublicKey;
+}): TransactionCircuitInputs;
+/**
+ * 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 declare function packProofToBytes(proof: RawProof): Uint8Array;
+/**
+ * Encode a snarkjs proof into the TransactionProofStruct format expected by the on-chain program.
+ */
+export declare function encodeSnarkjsProofToTransactionProof(proof: RawProof): TransactionProofStruct;
+/**
+ * Convert TransactionCircuitInputs to the format expected by snarkjs.groth16.fullProve().
+ * All values are converted to strings (snarkjs expects string inputs for field elements).
+ */
+export declare function formatInputsForSnarkjs(inputs: TransactionCircuitInputs): Record<string, any>;
+/**
+ * Swap circuit inputs. Matches the signal shape declared by swap.circom's
+ * main component (see zk-circuits/swap.circom lines 208-238). Unlike the
+ * transaction circuit, the swap circuit distinguishes a "change" output
+ * (same mint as source) from a "dest" output (dest mint) and takes a
+ * swap-specific params hash and swapAmount alongside the usual inputs.
+ */
+export type SwapCircuitInputs = {
+    sourceRoot: Uint8Array;
+    swapParamsHash: Uint8Array;
+    extDataHash: Uint8Array;
+    sourceMint: PublicKey;
+    destMint: PublicKey;
+    inputNullifiers: [Uint8Array, Uint8Array];
+    changeCommitment: Uint8Array;
+    destCommitment: Uint8Array;
+    swapAmount: bigint;
+    inAmount: [bigint, bigint];
+    inPubkey: [bigint, bigint];
+    inBlinding: [bigint, bigint];
+    inPathIndex: [number, number];
+    inPathElements: [bigint[], bigint[]];
+    inPrivateKey: [bigint, bigint];
+    changeAmount: bigint;
+    changePubkey: bigint;
+    changeBlinding: bigint;
+    destAmount: bigint;
+    destPubkey: bigint;
+    destBlinding: bigint;
+    minAmountOut: bigint;
+    deadline: bigint;
+};
+/**
+ * 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 declare function formatSwapInputsForSnarkjs(inputs: SwapCircuitInputs): Record<string, any>;
+/**
+ * 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 declare function computeSwapParamsHash(sourceMint: PublicKey, destMint: PublicKey, minAmountOut: bigint, deadline: bigint, destAmount?: bigint): Uint8Array;
+/**
+ * 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 declare function computeSwapDataHash(swapData: Uint8Array | Buffer): Uint8Array;