@veilo/sdk-core 0.1.17

package/README.md

@@ -0,0 +1,439 @@
+# @zkprivacysol/sdk-core
+
+Tiny TypeScript SDK for the `privacy-pool` Anchor program.
+
+This package wraps the on-chain program with a small set of ergonomic helpers for:
+
+- Deriving PDAs (`config`, `vault`, `note_tree`, `nullifiers`)
+- Initializing the pool with fixed SOL denominations
+- Depositing using a note commitment + **off-chain Merkle root**
+- Withdrawing via an authorized relayer (with fee + TVL accounting)
+- Building simple Merkle roots off-chain (for demo / testing)
+- Handling note commitments (`createRandomNote`, `commitNote`, etc.)
+
+> **Status:** internal/dev SDK. No production guarantees.  
+> ZK verification is expected to happen **off-chain in a relayer service**.  
+> On-chain, `proof: Vec<u8>` is treated as opaque bytes (hook for a future verifier).
+
+---
+
+## 1. Install
+
+From the monorepo root (or inside the package folder):
+
+```bash
+cd packages/sdk-core
+npm install
+```
+
+If you publish it somewhere later:
+
+```bash
+npm install @zkprivacysol/sdk-core
+```
+
+---
+
+## 2. Prerequisites
+
+You need:
+
+- A running Solana validator (localnet recommended):
+
+  ```bash
+  solana-test-validator
+  ```
+
+- The `privacy-pool` program built and deployed to that validator.
+- The `privacy-pool` Anchor IDL available (the SDK tests load it from):
+
+  ```text
+  ../../privacy-pool/target/idl/privacy_pool.json
+  ```
+
+- A funded keypair on that validator:
+
+  ```bash
+  solana config set --url http://127.0.0.1:8899
+  solana-keygen new --outfile ~/.config/solana/id.json
+  solana airdrop 10
+  ```
+
+Environment variables for tests:
+
+```bash
+export ANCHOR_PROVIDER_URL=http://127.0.0.1:8899
+export ANCHOR_WALLET=$HOME/.config/solana/id.json
+```
+
+---
+
+## 3. Build & Test
+
+From `packages/sdk-core`:
+
+```bash
+# Typecheck & build to dist/
+npm run build
+
+# Run unit + integration tests
+npm test
+```
+
+What the tests do:
+
+- **Unit tests (`note.test.ts`)**
+    - `createRandomNote` / `encodeNoteToBytes` / `commitNote` / `createNoteWithCommitment`
+    - Ensures 32-byte commitments, deterministic encoding, etc.
+
+- **Integration test (`sdk.integration.test.ts`)**
+    - Loads the `privacy-pool` IDL from `privacy-pool/target/idl/privacy_pool.json`
+    - Constructs an Anchor `Program` with a provider from `ANCHOR_PROVIDER_URL` / `ANCHOR_WALLET`
+    - Runs end-to-end flow:
+        1. `initializePool` (configures denoms + fee)
+        2. `createNoteAndDeposit` (creates note, commits it, calls on-chain `depositFixed` and updates the Merkle root)
+        3. `addRelayer`
+        4. `withdrawViaRelayer` (using a Merkle root that actually contains the note + a demo nullifier, empty proof)
+        5. Asserts vault TVL decreased, recipient gained funds, relayer received fee.
+
+The integration test uses an **empty proof** for now; in a real deployment your **relayer** would generate and verify a Groth16/Plonk proof off-chain, then pass the proof bytes into `withdraw`.
+
+---
+
+## 4. SDK Surface
+
+### 4.1 PDA helpers
+
+```ts
+import { getPoolPdas } from "@zkprivacysol/sdk-core";
+import { PublicKey } from "@solana/web3.js";
+
+const programId = new PublicKey("YourProgram1111111111111111111111111111111111");
+const { config, vault, noteTree, nullifiers } = getPoolPdas(programId);
+```
+
+These must match the on-chain seeds (v3 layout):
+
+- `["privacy_config_v3"]`
+- `["privacy_vault_v3"]`
+- `["privacy_note_tree_v3"]`
+- `["privacy_nullifiers_v3"]`
+
+---
+
+### 4.2 Pool init / configuration
+
+```ts
+import * as anchor from "@coral-xyz/anchor";
+import { initializePool } from "@zkprivacysol/sdk-core";
+import { sol } from "@zkprivacysol/sdk-core/config";
+import type { Program, Idl } from "@coral-xyz/anchor";
+
+async function initPool(program: Program<Idl>, adminWallet: anchor.Wallet) {
+  await initializePool({
+    program,
+    admin: adminWallet,
+    denomsLamports: [sol(1), sol(5)], // 1 SOL & 5 SOL
+    feeBps: 50,                       // 0.5% fee
+  });
+}
+```
+
+This calls the on-chain `initialize` instruction and sets:
+
+- fixed denominations (in lamports)
+- vault + note tree + nullifier set PDAs
+- fee in basis points
+- initial TVL = 0
+
+---
+
+### 4.3 Notes & commitments
+
+`src/note.ts` is a small “note” helper module. It **does not** implement real zk-friendly Poseidon hashing yet; it’s just using SHA-256 to get 32-byte commitments that the on-chain program treats as opaque.
+
+```ts
+import {
+  createRandomNote,
+  encodeNoteToBytes,
+  commitNote,
+  createNoteWithCommitment,
+} from "@zkprivacysol/sdk-core/note";
+import { Keypair } from "@solana/web3.js";
+
+const owner = Keypair.generate().publicKey;
+
+// 1. Create a note
+const note = createRandomNote({
+  value: 1_000_000n, // lamports
+  owner,
+});
+
+// 2. Encode deterministically
+const bytes = encodeNoteToBytes(note);
+
+// 3. Hash to a 32-byte commitment (placeholder)
+const commitment = commitNote(note);
+
+// 4. Convenience combo
+const full = createNoteWithCommitment({
+  value: 1_000_000n,
+  owner,
+});
+// full.commitment is 32 bytes
+```
+
+Encoding layout:
+
+```text
+value (u64 LE, 8 bytes)
+|| owner pubkey (32 bytes)
+|| rho (32 bytes random)
+|| r   (32 bytes random)
+```
+
+Hash:
+
+```ts
+commitment = sha256(encodedBytes);
+```
+
+Later, a real implementation should swap this out for the exact hash function used inside the zk circuit (Poseidon/Rescue/etc.). The on-chain program just sees `[u8; 32]`.
+
+---
+
+### 4.4 Merkle helpers (demo-only)
+
+`src/merkle.ts` provides **very basic** Merkle helpers so callers can build roots off-chain. This is meant for demos/tests, not production.
+
+Key functions:
+
+```ts
+import {
+  merkleLeafFromCommitment,
+  merkleHashPair,
+  merkleRootFromLeaves,
+  MerkleTree,
+} from "@zkprivacysol/sdk-core/merkle";
+
+// Stateless helpers
+const leaf = merkleLeafFromCommitment(commitment);
+const parent = merkleHashPair(left, right);
+const root = merkleRootFromLeaves([leaf1, leaf2, leaf3]);
+
+// Simple incremental tree (toy)
+const tree = new MerkleTree();
+const { index, root: newRoot } = tree.insert(commitment);
+const path = tree.getPath(index); // Merkle path for proofs
+```
+
+Notes:
+
+- Uses SHA-256 under the hood, returning `Uint8Array` of length 32.
+- Pads with a “zero node” derived from hashing the all-zero leaf repeatedly up the tree.
+- This is intentionally “toy” to keep the SDK usable while the real circuit/Merkle design is still in flux.
+- On-chain, the program only stores the **latest Merkle root** in the `NoteTree` account (v3 layout exposes a `currentRoot` field).
+
+---
+
+### 4.5 Deposits
+
+Low-level helper (you supply both commitment + Merkle root):
+
+```ts
+import * as anchor from "@coral-xyz/anchor";
+import { depositFixedSol } from "@zkprivacysol/sdk-core";
+
+const provider = anchor.getProvider() as anchor.AnchorProvider;
+const wallet = provider.wallet as anchor.Wallet;
+
+await depositFixedSol({
+  program,
+  depositor: wallet,
+  denomIndex: 0,        // index into cfg.denoms
+  commitment,           // 32-byte note commitment
+  newRoot,              // 32-byte Merkle root (caller computed off-chain)
+});
+```
+
+High-level helper (with note creation, but you still feed a root):
+
+```ts
+import * as anchor from "@coral-xyz/anchor";
+import { createNoteAndDeposit } from "@zkprivacysol/sdk-core";
+import { sol } from "@zkprivacysol/sdk-core/config";
+
+const provider = anchor.getProvider() as anchor.AnchorProvider;
+const wallet = provider.wallet as anchor.Wallet;
+
+const dummyRoot = new Uint8Array(32).fill(7); // replace with real Merkle root
+
+const note = await createNoteAndDeposit({
+  program,
+  depositor: wallet,
+  denomIndex: 0,
+  valueLamports: sol(1),
+  newRoot: dummyRoot,
+});
+
+// note.commitment can later be used in your off-chain tree
+```
+
+There’s also a higher-level helper that integrates directly with an in-memory `MerkleTree`:
+
+```ts
+import { createNoteDepositWithMerkle } from "@zkprivacysol/sdk-core";
+import { MerkleTree } from "@zkprivacysol/sdk-core/merkle";
+
+const tree = new MerkleTree();
+
+const { note, leafIndex, root, merklePath } =
+  await createNoteDepositWithMerkle({
+    program,
+    depositor: wallet,
+    denomIndex: 0,
+    valueLamports: sol(1),
+    tree,
+  });
+
+// `root` is what got written to the on-chain NoteTree
+// `merklePath` can be used as witness for the zk circuit
+```
+
+On-chain, the `depositFixed` instruction:
+
+- moves SOL from `depositor` to the vault PDA,
+- updates TVL,
+- writes `new_root` into the on-chain note tree’s current root field.
+
+---
+
+### 4.6 Relayers & Withdrawals
+
+Add a relayer (admin-only):
+
+```ts
+import * as anchor from "@coral-xyz/anchor";
+import { addRelayer } from "@zkprivacysol/sdk-core";
+import { Keypair } from "@solana/web3.js";
+
+const provider = anchor.getProvider() as anchor.AnchorProvider;
+const wallet = provider.wallet as anchor.Wallet;
+
+const relayer = Keypair.generate();
+
+await addRelayer({
+  program,
+  admin: wallet,
+  newRelayer: relayer.publicKey,
+});
+```
+
+Withdraw via relayer (SDK-level helper):
+
+```ts
+import { withdrawViaRelayer } from "@zkprivacysol/sdk-core";
+import { Keypair } from "@solana/web3.js";
+
+const relayer = Keypair.generate();
+const recipient = Keypair.generate();
+
+const root = /* 32-byte Merkle root containing the note */;
+const nullifier = new Uint8Array(32).fill(3); // demo only
+
+// In the real world, `proof` will be zk-proof bytes coming from your prover.
+const proofBytes = new Uint8Array([]); // currently ignored by on-chain program
+
+await withdrawViaRelayer({
+  program,
+  relayer,
+  recipient: recipient.publicKey,
+  denomIndex: 0,
+  root,
+  nullifier,
+  proof: proofBytes,
+});
+```
+
+There is also a higher-level helper (`withdrawViaRelayerWithProof`) that takes:
+
+- `noteData` (serialized note),
+- `merklePath`,
+- `feeBps`,
+- a `builder: ProofBuilder` callback
+
+and lets you plug in your own proof generator. In practice, your **relayer service** will own that logic.
+
+**Production pattern:**
+
+- A **backend relayer service** (see `packages/relayer` or similar) owns:
+    - the proving key / circuits,
+    - a mirror view of the Merkle tree and nullifier set,
+    - a funded relayer keypair.
+- The front-end sends a withdraw request to that service:
+    - `root`, `nullifier`, `denomIndex`, `recipient`, plus any private witness data.
+- The relayer:
+    1. Builds & verifies the zk proof off-chain.
+    2. Packs it into bytes (e.g. via a `packProofToBytes` helper).
+    3. Calls the on-chain `withdraw` via Anchor, using the same program/PDAs as the SDK.
+
+From the SDK’s perspective, `proof: Uint8Array` is **already-built**; this package doesn’t know how you generated it.
+
+---
+
+## 5. Environment & Localnet
+
+To run the integration tests successfully, you should:
+
+1. Start local validator:
+
+   ```bash
+   solana-test-validator
+   ```
+
+2. Build & deploy the `privacy-pool` Anchor program in `packages/privacy-pool`:
+
+   ```bash
+   cd packages/privacy-pool
+   anchor build
+   anchor deploy
+   ```
+
+3. Ensure your CLI and wallet match the validator:
+
+   ```bash
+   solana config set --url http://127.0.0.1:8899
+   solana-keygen new --outfile ~/.config/solana/id.json
+   solana airdrop 10
+   ```
+
+4. Export env vars (or inject via `npm test` script):
+
+   ```bash
+   export ANCHOR_PROVIDER_URL=http://127.0.0.1:8899
+   export ANCHOR_WALLET=$HOME/.config/solana/id.json
+   ```
+
+5. Then from `packages/sdk-core`:
+
+   ```bash
+   npm run build
+   npm test
+   ```
+
+---
+
+## 6. Limitations & TODOs
+
+- **Merkle tree is minimal.**
+    - Toy implementation, primarily for demos/tests.
+    - No persisted tree; you’re expected to maintain state in your own service.
+- **On-chain NoteTree only stores the latest root.**
+    - Historical roots/nullifiers must be mirrored off-chain.
+- **Proofs are relayer-only.**
+    - SDK does **not** generate Groth16/Plonk proofs.
+    - On-chain program currently only sees `Vec<u8>` and does not verify it yet.
+- **API is still evolving.**
+    - Types, exports, and function signatures may change as the circuit + relayer design solidifies.
+
+This SDK is meant as a thin, hackable layer around the Anchor program while the core privacy design (circuit, proof system, Merkle layout, relayer flow) is being explored.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@veilo/sdk-core",
+  "version": "0.1.17",
+  "description": "Tiny TypeScript SDK for the `privacy-pool` Anchor program.",
+  "homepage": "https://github.com/ZKSOLDev/core-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/ZKSOLDev/core-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZKSOLDev/core-sdk.git"
+  },
+  "license": "ISC",
+  "author": "",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "directories": {
+    "test": "tests"
+  },
+  "scripts": {
+    "build": "rm -rf dist/ && tsc -p tsconfig.json",
+    "test": "ANCHOR_PROVIDER_URL=http://127.0.0.1:8899 ANCHOR_WALLET=$HOME/.config/solana/id.json rm -rf dist/ && tsc -p test-tsconfig.json && mocha -t 1000000 \"dist/tests/**/*.js\""
+  },
+  "dependencies": {
+    "@coral-xyz/anchor": "^0.30.0",
+    "@noble/hashes": "^1.8.0",
+    "@solana/spl-token": "^0.4.6",
+    "@solana/web3.js": "^1.95.0",
+    "circomlibjs": "^0.1.7",
+    "mocha": "^11.7.5",
+    "tweetnacl": "^1.0.3"
+  },
+  "devDependencies": {
+    "@types/circomlibjs": "^0.1.6",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^24.10.1",
+    "chai": "^6.2.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}