@veilo/sdk-core 0.1.17 → 0.4.0

package/dist/esm/index.d.ts

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

package/dist/esm/index.js

@@ -0,0 +1,29 @@
+// Core client functions
+export * from "./client.js";
+// UTXO types and functions (replaces note.ts)
+export * from "./utxo.js";
+// Configuration constants and types
+export * from "./config.js";
+// Merkle tree implementation
+export * from "./merkle.js";
+// Proof types and helpers
+export * from "./proof.js";
+// On-chain event scanning and tree reconstruction
+export * from "./events.js";
+// Program factory and IDL
+export { createVeiloProgram, createReadonlyVeiloProgram, PRIVACY_POOL_IDL, PRIVACY_POOL_PROGRAM_ID, } from "./program.js";
+// Wallet-agnostic shielding — build an unsigned deposit for any external wallet
+export * from "./shield/index.js";
+// Proof generation (requires snarkjs peer dependency)
+export { createTransactionProver, verifyProof } from "./prover.js";
+// Compact note ciphers — the on-chain payload that makes notes recoverable
+// from chain data alone, without any relayer involvement.
+export * from "./compactNote.js";
+// Cross-platform CSPRNG (no node:crypto import — safe in browser bundles)
+export { randomBytes, randomBytes32 } from "./random.js";
+// Relayer API client
+export * from "./relayer.js";
+// RPC retry / resilience
+export { withRpcRetry, DEFAULT_RPC_RETRY } from "./retry.js";
+// Poseidon hash functions
+export { initPoseidon, getPoseidon, BN254_FR_MODULUS, bytesToBigIntBE, bigIntToBytesBE, frToBigInt, poseidon1, poseidon2, poseidon3, poseidon4, pubkeyToField, } from "./poseidon.js";

package/dist/esm/merkle.d.ts

@@ -0,0 +1,77 @@
+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;
+}
+/**
+ * The Poseidon zero chain: `z[0] = 0`, `z[i+1] = Poseidon(z[i], z[i])`.
+ *
+ * This is the `zeroes` array a `MerkleTree` builds in its constructor, without
+ * the tree. Deposits need a Merkle path for their dummy inputs, but the circuit
+ * disables the path check when a input amount is zero (`enabled <== 1 - IsZero(amount)`
+ * in transaction.circom), so the values are never constrained — only their
+ * count is.
+ *
+ * Allocating a full depth-22 `MerkleTree` for this costs ~130 MB and several
+ * seconds. This costs 22 hashes. Any deposit-shaped transaction should use it.
+ */
+export declare function poseidonZeroChain(depth?: number): Uint8Array[];

package/dist/esm/merkle.js

@@ -0,0 +1,151 @@
+import { BN254_FR_MODULUS, bytesToBigIntBE, bigIntToBytesBE, getPoseidon, frToBigInt, } from "./poseidon.js";
+// 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),
+        };
+    }
+}
+/**
+ * The Poseidon zero chain: `z[0] = 0`, `z[i+1] = Poseidon(z[i], z[i])`.
+ *
+ * This is the `zeroes` array a `MerkleTree` builds in its constructor, without
+ * the tree. Deposits need a Merkle path for their dummy inputs, but the circuit
+ * disables the path check when a input amount is zero (`enabled <== 1 - IsZero(amount)`
+ * in transaction.circom), so the values are never constrained — only their
+ * count is.
+ *
+ * Allocating a full depth-22 `MerkleTree` for this costs ~130 MB and several
+ * seconds. This costs 22 hashes. Any deposit-shaped transaction should use it.
+ */
+export function poseidonZeroChain(depth = 22) {
+    const zeroes = [];
+    let zero = bigIntToBytesBE(0n);
+    zeroes.push(zero);
+    for (let level = 1; level <= depth; level++) {
+        zero = hashPair(zero, zero);
+        zeroes.push(zero);
+    }
+    return zeroes;
+}

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/esm/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/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.d.ts

@@ -0,0 +1,37 @@
+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;
+/**
+ * Create a `Program` for reading on-chain accounts, with no wallet.
+ *
+ * The shield path never signs, so requiring a `Wallet` just to decode a
+ * `MerkleTreeAccount` would force integrators to invent a dummy one. This is
+ * safe for `program.account.*.fetch` and the coders; anything that would submit
+ * a transaction will fail, which is the intent.
+ */
+export declare function createReadonlyVeiloProgram(connection: Connection, opts?: {
+    commitment?: "processed" | "confirmed" | "finalized";
+}): Program;

package/dist/esm/program.js

@@ -0,0 +1,53 @@
+import { Program, AnchorProvider } from "@coral-xyz/anchor";
+import { PublicKey } from "@solana/web3.js";
+import IDL_JSON from "./idl/privacy_pool.js";
+// 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);
+}
+/**
+ * Create a `Program` for reading on-chain accounts, with no wallet.
+ *
+ * The shield path never signs, so requiring a `Wallet` just to decode a
+ * `MerkleTreeAccount` would force integrators to invent a dummy one. This is
+ * safe for `program.account.*.fetch` and the coders; anything that would submit
+ * a transaction will fail, which is the intent.
+ */
+export function createReadonlyVeiloProgram(connection, opts) {
+    const provider = new AnchorProvider(connection, 
+    // No signing surface: reads only.
+    {
+        publicKey: PublicKey.default,
+        signTransaction: () => {
+            throw new Error("createReadonlyVeiloProgram: this program cannot sign");
+        },
+        signAllTransactions: () => {
+            throw new Error("createReadonlyVeiloProgram: this program cannot sign");
+        },
+    }, { commitment: opts?.commitment ?? "confirmed" });
+    return new Program(PRIVACY_POOL_IDL, provider);
+}

package/dist/esm/proof.d.ts

@@ -0,0 +1,183 @@
+import { PublicKey } from "@solana/web3.js";
+import { SerializedUTXO, InputUTXO } from "./utxo.js";
+/**
+ * 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;