@veilo/sdk-core 0.1.17

package/src/client.ts

@@ -0,0 +1,352 @@
+import * as anchor from "@coral-xyz/anchor";
+import { Program, BN, Idl } from "@coral-xyz/anchor";
+import { PublicKey, SystemProgram, Keypair } from "@solana/web3.js";
+
+import {
+  ProofBuilder,
+  WithdrawCircuitInputs,
+  WithdrawProofStruct,
+  deriveNullifier,
+  encodeSnarkjsProofToWithdrawProof,
+} from "./proof";
+
+import {
+  createNoteWithCommitment,
+  EncryptedNotePlaintext,
+  encryptNote,
+  SerializedNote,
+} from "./note";
+
+import { MerklePath, MerkleTree } from "./merkle";
+import { randomBytes } from "crypto";
+
+// -----------------------------------------------------------------------------
+// Types
+// -----------------------------------------------------------------------------
+
+export type NoteAndMerkleData = {
+  note: SerializedNote;
+  leafIndex: number;
+  root: Uint8Array;
+  merklePath: MerklePath;
+};
+
+// -----------------------------------------------------------------------------
+// High-level deposit helper (off-chain Merkle is just for zk / demos)
+// -----------------------------------------------------------------------------
+
+/**
+ * High-level helper:
+ *  - Creates a random note + commitment
+ *  - Inserts the commitment into an *off-chain* Merkle tree (your zk tree)
+ *  - Calls on-chain `depositFixed` with the commitment
+ *  - Returns note + index + Merkle path (+ off-chain root)
+ *
+ * The on-chain program *also* keeps its own rolling 32-byte root, but that is
+ * intentionally minimal and independent from this off-chain tree. For a real
+ * zk circuit you’d want both to share the same hash function.
+ */
+export async function createNoteDepositWithMerkle<T extends Idl>(params: {
+  program: Program<T>;
+  depositor: anchor.Wallet;
+  denomIndex: number;
+  valueLamports: bigint;
+  tree: MerkleTree;
+}): Promise<NoteAndMerkleData> {
+  const { program, depositor, denomIndex, valueLamports, tree } = params;
+
+  const note = createNoteWithCommitment({
+    value: valueLamports,
+    owner: depositor.publicKey,
+  });
+
+  // Maintain your off-chain mirror (for proofs)
+  const { index, root } = tree.insert(note.commitment);
+  const merklePath = tree.getPath(index);
+
+  // Call low-level deposit with just the commitment
+  await depositFixedSol({
+    program,
+    depositor,
+    denomIndex,
+    commitment: note.commitment,
+    note,
+  });
+
+  return {
+    note,
+    leafIndex: index,
+    root,
+    merklePath,
+  };
+}
+
+// -----------------------------------------------------------------------------
+// PDA helpers (v3 seeds)
+// -----------------------------------------------------------------------------
+
+export function getPoolPdas(programId: PublicKey, commitmentSeed?: Uint8Array) {
+  const [config] = PublicKey.findProgramAddressSync(
+    [Buffer.from("privacy_config_v3")],
+    programId
+  );
+  const [vault] = PublicKey.findProgramAddressSync(
+    [Buffer.from("privacy_vault_v3")],
+    programId
+  );
+  const [noteTree] = PublicKey.findProgramAddressSync(
+    [Buffer.from("privacy_note_tree_v3")],
+    programId
+  );
+  const [nullifiers] = PublicKey.findProgramAddressSync(
+    [Buffer.from("privacy_nullifiers_v3")],
+    programId
+  );
+
+  const [noteHint] = PublicKey.findProgramAddressSync(
+    [Buffer.from("privacy_note_hint_v3"), commitmentSeed ?? Buffer.alloc(0)],
+    programId
+  );
+
+  return { config, vault, noteTree, nullifiers, noteHint };
+}
+
+// -----------------------------------------------------------------------------
+// Pool initialization
+// -----------------------------------------------------------------------------
+
+export async function initializePool<T extends Idl>(params: {
+  program: Program<T>;
+  admin: anchor.Wallet;
+  denomsLamports: (bigint | number)[];
+  feeBps: number; // 0–10000
+}) {
+  const { program, admin, denomsLamports, feeBps } = params;
+  const { config, vault, noteTree, nullifiers } = getPoolPdas(
+    program.programId
+  );
+
+  await (program.methods as any)
+    .initialize(
+      denomsLamports.map((d) => new BN(d.toString())),
+      feeBps
+    )
+    .accounts({
+      config,
+      vault,
+      noteTree,
+      nullifiers,
+      admin: admin.publicKey,
+      systemProgram: SystemProgram.programId,
+    } as any)
+    .rpc();
+}
+
+// -----------------------------------------------------------------------------
+// Deposit helpers
+// -----------------------------------------------------------------------------
+
+export type DepositNoteResult = {
+  commitment: Uint8Array; // 32 bytes
+};
+
+/**
+ * Low-level deposit helper.
+ * Expects a 32-byte commitment; on-chain NoteTree keeps a rolling 32-byte root.
+ */
+export async function depositFixedSol<T extends Idl>(params: {
+  program: Program<T>;
+  depositor: anchor.Wallet;
+  denomIndex: number;
+  commitment: Uint8Array; // 32
+  note: SerializedNote;
+}) {
+  const { program, depositor, denomIndex, commitment, note } = params;
+  const { config, vault, noteTree, noteHint } = getPoolPdas(
+    program.programId,
+    commitment
+  );
+
+  if (commitment.length !== 32) {
+    throw new Error("commitment must be 32 bytes");
+  }
+
+  const notePlain: EncryptedNotePlaintext = {
+    secret: randomBytes(32),
+    nullifier: deriveNullifier(note),
+    denomIndex: 0,
+  };
+
+  const sharedKey = randomBytes(32); // derive from recipient pubkey in real wallet
+  const encryptedNote = encryptNote(notePlain, sharedKey);
+
+  await (program.methods as any)
+    .depositFixed(
+      denomIndex,
+      Array.from(commitment) // [u8;32]
+    )
+    .accounts({
+      config,
+      vault,
+      noteTree,
+      noteHint,
+      depositor: depositor.publicKey,
+      systemProgram: SystemProgram.programId,
+    } as any)
+    .rpc();
+}
+
+/**
+ * Convenience: build a random Note off-chain, commit it, and call deposit.
+ */
+export async function createNoteAndDeposit<T extends Idl>(params: {
+  program: Program<T>;
+  depositor: anchor.Wallet;
+  denomIndex: number;
+  valueLamports: bigint;
+}) {
+  const { program, depositor, denomIndex, valueLamports } = params;
+
+  const note = createNoteWithCommitment({
+    value: valueLamports,
+    owner: depositor.publicKey,
+  });
+
+  await depositFixedSol({
+    program,
+    depositor,
+    denomIndex,
+    commitment: note.commitment,
+    note,
+  });
+
+  return note;
+}
+
+// -----------------------------------------------------------------------------
+// Relayers & Withdrawals
+// -----------------------------------------------------------------------------
+
+export async function addRelayer<T extends Idl>(params: {
+  program: Program<T>;
+  admin: anchor.Wallet;
+  newRelayer: PublicKey;
+}) {
+  const { program, admin, newRelayer } = params;
+  const { config } = getPoolPdas(program.programId);
+
+  await (program.methods as any)
+    .addRelayer(newRelayer)
+    .accounts({
+      config,
+      admin: admin.publicKey,
+    } as any)
+    .rpc();
+}
+
+/**
+ * Low-level withdraw:
+ *  - Expects the **already packed** WithdrawProofStruct
+ *    (matching Rust `WithdrawProof` fields).
+ */
+export async function withdrawViaRelayer<T extends Idl>(params: {
+  program: Program<T>;
+  relayer: Keypair;
+  recipient: PublicKey;
+  denomIndex: number;
+  root: Uint8Array; // 32 bytes
+  nullifier: Uint8Array; // 32 bytes
+  proof: WithdrawProofStruct;
+}) {
+  const { program, relayer, recipient, denomIndex, root, nullifier, proof } =
+    params;
+  const { config, vault, noteTree, nullifiers } = getPoolPdas(
+    program.programId
+  );
+
+  if (root.length !== 32) throw new Error("root must be 32 bytes");
+  if (nullifier.length !== 32) throw new Error("nullifier must be 32 bytes");
+
+  await (program.methods as any)
+    .withdraw(
+      Array.from(root),
+      Array.from(nullifier),
+      denomIndex,
+      recipient,
+      proof // <- Anchor / IDL maps this to WithdrawProof { proof_a, proof_b, proof_c }
+    )
+    .accounts({
+      config,
+      vault,
+      noteTree,
+      nullifiers,
+      relayer: relayer.publicKey,
+      recipient,
+      systemProgram: SystemProgram.programId,
+    } as any)
+    .signers([relayer])
+    .rpc();
+}
+
+/**
+ * High-level withdraw:
+ *  - Takes note + Merkle path + denom + fee info
+ *  - Uses a pluggable ProofBuilder (snarkjs.groth16) to create a RawProof
+ *  - Encodes RawProof into WithdrawProofStruct
+ *  - Calls the low-level withdrawViaRelayer
+ *
+ * In production, you'd typically call a relayer HTTP API instead, and let it
+ * build/verify the proof server-side. But this is handy for tools / tests.
+ */
+export async function withdrawViaRelayerWithProof<T extends Idl>(params: {
+  program: Program<T>;
+  relayer: Keypair;
+  recipient: PublicKey;
+  denomIndex: number;
+  feeBps: number;
+  root: Uint8Array;
+  nullifier: Uint8Array;
+  noteData: SerializedNote;
+  merklePath: MerklePath;
+  builder: ProofBuilder; // must produce a valid snarkjs Groth16 proof
+}) {
+  const {
+    program,
+    relayer,
+    recipient,
+    denomIndex,
+    feeBps,
+    root,
+    nullifier,
+    noteData,
+    merklePath,
+    builder,
+  } = params;
+
+  const inputs: WithdrawCircuitInputs = {
+    root,
+    note: noteData,
+    merklePath,
+    nullifier,
+    denomIndex,
+    recipient,
+    relayer: relayer.publicKey,
+    feeBps,
+  };
+
+  // Build snarkjs proof off-chain
+  const rawProof = await builder(inputs);
+
+  // Pack into the struct expected by the on-chain Rust program
+  const withdrawProof = encodeSnarkjsProofToWithdrawProof(rawProof);
+
+  await withdrawViaRelayer({
+    program,
+    relayer,
+    recipient,
+    denomIndex,
+    root,
+    nullifier,
+    proof: withdrawProof,
+  });
+}

package/src/config.ts

@@ -0,0 +1,13 @@
+// config.ts
+import { LAMPORTS_PER_SOL } from "@solana/web3.js";
+
+export const DEFAULT_FEE_BPS = 50; // 0.5%
+
+export function sol(n: number): bigint {
+	return BigInt(n) * BigInt(LAMPORTS_PER_SOL);
+}
+
+export type PoolInitConfig = {
+	denomsSol: number[]; // [1, 5] etc
+	feeBps?: number;
+};

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./client";
+export * from "./note";
+export * from "./config";
+export * from "./merkle";
+export * from "./proof";
+export { initPoseidon } from "./poseidon";

package/src/merkle.ts

@@ -0,0 +1,178 @@
+// sdk-core/src/merkle.ts
+import {
+	BN254_FR_MODULUS,
+	bytesToBigIntBE,
+	bigIntToBytesBE,
+} from "./note";
+import {
+	getPoseidon,
+	frToBigInt,
+} from "./poseidon";
+
+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[];
+};
+
+export type Bytes32 = Uint8Array;
+
+// Poseidon-based hash of two 32-byte field elements.
+function hashPair(left: Bytes32, right: Bytes32): Bytes32 {
+	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 {
+	readonly depth: number;
+	readonly zeroes: Uint8Array[];
+	readonly layers: Uint8Array[][];
+	nextIndex: number;
+
+	constructor(depth = 16) {
+		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: Uint8Array[] = new Array(size);
+			for (let i = 0; i < size; i++) {
+				arr[i] = this.zeroes[level];
+			}
+			this.layers.push(arr);
+		}
+
+		this.nextIndex = 0;
+	}
+
+	get capacity(): number {
+		return 1 << this.depth;
+	}
+
+	get root(): Uint8Array {
+		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: Uint8Array): { index: number; root: Uint8Array } {
+		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: number): MerklePath {
+		if (index < 0 || index >= this.capacity) {
+			throw new Error("index out of range");
+		}
+
+		const path: Uint8Array[] = [];
+		const indices: number[] = [];
+
+		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 };
+	}
+}