@veilo/sdk-core 0.1.17 → 0.3.3

package/README.md

@@ -1,35 +1,797 @@
-# @zkprivacysol/sdk-core
+# @veilo/sdk-core
 
-Tiny TypeScript SDK for the `privacy-pool` Anchor program.
+TypeScript SDK for the Veilo Privacy Pool Anchor program.
 
-This package wraps the on-chain program with a small set of ergonomic helpers for:
+This package provides a complete UTXO-based privacy protocol implementation on Solana with:
 
-- 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.)
+- **UTXO Model**: Full support for unspent transaction outputs with Poseidon commitments
+- **Multi-Tree Support**: Multiple concurrent Merkle trees for improved scalability
+- **ZK Proofs**: Integration with Circom circuits for private transactions
+- **Private Swaps**: Atomic cross-pool swaps via Jupiter (native SOL + SPL tokens)
+- **Note Encryption**: NaCl-based encrypted UTXO notes and blind mailbox delivery
+- **Event Scanning**: Reconstruct Merkle trees from on-chain events
+- **Poseidon Hashing**: BN254-curve compatible hashing using circomlibjs
+- **Relayer Support**: Built-in relayer infrastructure for private withdrawals and swaps
 
-> **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).
+> **Status:** Active development. The SDK supports full transaction privacy with ZK-SNARK proofs.
+> Proofs are generated off-chain and verified on-chain using Groth16.
 
 ---
 
-## 1. Install
+## 1. Installation
 
-From the monorepo root (or inside the package folder):
+```bash
+npm install @veilo/sdk-core
+```
+
+---
+
+## 2. Prerequisites
+
+- A running Solana validator (localnet/devnet/mainnet)
+- The `privacy-pool` program deployed to the network
+- A funded keypair
 
 ```bash
-cd packages/sdk-core
-npm install
+export ANCHOR_PROVIDER_URL=https://api.devnet.solana.com
+export ANCHOR_WALLET=$HOME/.config/solana/id.json
 ```
 
-If you publish it somewhere later:
+---
+
+## 3. Build
 
 ```bash
-npm install @zkprivacysol/sdk-core
+npm run build
+```
+
+---
+
+## 4. SDK API
+
+### 4.1 PDA Helpers
+
+```ts
+import {
+  getPoolPdas,
+  getNoteTreePda,
+  getGlobalConfigPda,
+  getNullifierMarkerPda,
+  getSwapExecutorPda,
+} from "@veilo/sdk-core";
+import { PublicKey } from "@solana/web3.js";
+
+const programId = new PublicKey(
+  "YourProgram1111111111111111111111111111111111",
+);
+const mintAddress = new PublicKey(
+  "So11111111111111111111111111111111111111112",
+);
+
+// Pool PDAs (config, vault, nullifiers)
+const { config, vault, nullifiers } = getPoolPdas(programId, mintAddress);
+
+// Note tree PDA for tree ID 0
+const noteTree = getNoteTreePda(programId, mintAddress, 0);
+
+// Global config PDA (one per program)
+const globalConfig = getGlobalConfigPda(programId);
+
+// Nullifier marker PDA (prevents double-spend)
+const nullifier = new Uint8Array(32);
+const marker = getNullifierMarkerPda(programId, mintAddress, nullifier);
+
+// Swap executor PDA (for cross-pool swaps)
+const relayerPubkey = new PublicKey("...");
+const executor = getSwapExecutorPda(
+  programId,
+  sourceMint,
+  destMint,
+  inputNullifier0, // Uint8Array[32]
+  relayerPubkey,
+);
+```
+
+**PDA seeds (v3):**
+
+| Account          | Seeds                                                               |
+| ---------------- | ------------------------------------------------------------------- |
+| Config           | `["privacy_config_v3", mint]`                                       |
+| Vault            | `["privacy_vault_v3", mint]`                                        |
+| Note Tree        | `["privacy_note_tree_v3", mint, tree_id]`                           |
+| Nullifiers       | `["privacy_nullifiers_v3", mint]`                                   |
+| Nullifier Marker | `["nullifier_v3", mint, nullifier]`                                 |
+| Global Config    | `["global_config_v1"]`                                              |
+| Swap Executor    | `["swap_executor_v1", source_mint, dest_mint, nullifier0, relayer]` |
+
+---
+
+### 4.2 Pool Initialization
+
+```ts
+import {
+  initializeGlobalConfig,
+  initializePool,
+  updatePoolConfig,
+  addMerkleTree,
+  getPoolConfig,
+  updateGlobalConfig,
+} from "@veilo/sdk-core";
+import { NATIVE_SOL_MINT, sol } from "@veilo/sdk-core/config";
+
+// Initialize global config (once per program)
+await initializeGlobalConfig({ program, admin: adminKeypair });
+
+// Update global config
+await updateGlobalConfig({
+  program,
+  admin: adminKeypair,
+  newAdmin: newAdminPubkey, // optional
+  paused: false, // optional
+});
+
+// Initialize a pool for native SOL
+await initializePool({
+  program,
+  payer: adminKeypair,
+  admin: adminKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  minDepositAmount: sol(0.1),
+  maxDepositAmount: sol(100),
+  minWithdrawAmount: sol(0.1),
+  maxWithdrawAmount: sol(100),
+  feeBps: 50, // 0.5%
+  feeErrorMarginBps: 10, // 0.1% margin
+  minWithdrawalFee: 1_000_000n,
+});
+
+// Add Merkle tree (tree ID 0)
+await addMerkleTree({
+  program,
+  payer: adminKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  treeId: 0,
+});
+
+// Update pool fee
+await updatePoolConfig({
+  program,
+  admin: adminKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  feeBps: 30,
+});
+
+// Read pool configuration
+const poolConfig = await getPoolConfig(program, NATIVE_SOL_MINT);
+console.log("TVL:", poolConfig.totalTvl, "  Fee:", poolConfig.feeBps, "bps");
+```
+
+---
+
+### 4.3 On-Chain Account Queries
+
+```ts
+import {
+  fetchPoolConfig,
+  checkNullifierSpent,
+  getTreeInfo,
+  getAllTreeInfo,
+  getBestTreeForDeposit,
+} from "@veilo/sdk-core";
+
+// Fetch decoded PrivacyConfig account
+const config = await fetchPoolConfig(program, NATIVE_SOL_MINT);
+
+// Check if a nullifier has been spent
+const spent = await checkNullifierSpent(program, NATIVE_SOL_MINT, nullifier);
+
+// Info for a single tree
+const info = await getTreeInfo(program, NATIVE_SOL_MINT, 0);
+// info = { treeId, leafCount, root, isFull }
+
+// Info for all trees in a pool
+const allInfo = await getAllTreeInfo(program, NATIVE_SOL_MINT);
+
+// Pick the best tree for depositing (least full with capacity)
+const best = await getBestTreeForDeposit(program, NATIVE_SOL_MINT);
+// best = { treeId, leafCount, root }
+```
+
+---
+
+### 4.4 UTXO Management
+
+```ts
+import {
+  generateKeypair,
+  keypairFromPrivateKey,
+  createUTXO,
+  createOwnedUTXO,
+  createOwnedZeroUTXO,
+  deriveNullifier,
+  type Keypair,
+  type UTXO,
+  type SerializedUTXO,
+  type InputUTXO,
+} from "@veilo/sdk-core";
+import { NATIVE_SOL_MINT } from "@veilo/sdk-core/config";
+import { pubkeyToField } from "@veilo/sdk-core";
+
+// Generate a random UTXO keypair
+const keypair: Keypair = generateKeypair();
+// keypair = { privateKey: bigint, publicKey: bigint }
+
+// Restore from private key
+const restored = keypairFromPrivateKey(privateKeyBigInt);
+
+// Create an owned UTXO (includes private key)
+const ownedUtxo: SerializedUTXO = createOwnedUTXO({
+  amount: 1_000_000_000n,
+  privateKey: keypair.privateKey,
+  mintAddress: NATIVE_SOL_MINT,
+});
+
+// Create a zero-value UTXO (for unused inputs/outputs)
+const zeroUtxo = createOwnedZeroUTXO(pubkeyToField(NATIVE_SOL_MINT), keypair);
+
+// Derive nullifier for spending
+const pathIndex = 0; // leaf index in Merkle tree
+const treeId = 0;
+const nullifier = deriveNullifier(
+  ownedUtxo.privateKey,
+  ownedUtxo.commitment,
+  pathIndex,
+  treeId,
+);
+```
+
+**UTXO commitment:** `Poseidon(amount, pubkey, blinding, mintAddress)`
+
+**Nullifier:** `Poseidon(privateKey, commitment, pathIndex, treeId)`
+
+---
+
+### 4.5 UTXO Encryption
+
+The SDK provides NaCl-based encryption for UTXO notes (relayer storage) and blind mailbox delivery (wallet-to-wallet).
+
+```ts
+import {
+  deriveEncryptionKeypair,
+  encryptUTXONote,
+  decryptUTXONote,
+  encryptBlindMailboxNote,
+  decryptBlindMailboxNote,
+  fetchAndDecryptNotes,
+  computeSignature,
+  inputUTXOToCircuitFormat,
+  type EncryptedNote,
+  type BlindMailboxNote,
+  type BlindMailboxNoteData,
+  type DecryptedNote,
+} from "@veilo/sdk-core";
+import { Keypair as SolanaKeypair } from "@solana/web3.js";
+
+// Derive a NaCl encryption keypair from a UTXO private key
+const encKeypair = deriveEncryptionKeypair(utxoKeypair.privateKey);
+// encKeypair = { publicKey: Uint8Array[32], secretKey: Uint8Array[32] }
+
+// Encrypt a UTXO note for relay storage
+const encryptedNote: EncryptedNote = encryptUTXONote(
+  serializedUtxo, // SerializedUTXO
+  encKeypair.publicKey, // NaCl public key (Uint8Array[32])
+);
+
+// Decrypt a UTXO note
+const decrypted: SerializedUTXO | null = decryptUTXONote(
+  encryptedNote,
+  encKeypair.secretKey, // NaCl secret key (Uint8Array[32])
+);
+
+// Blind mailbox: encrypt for a Solana wallet keypair
+const recipientKeypair = SolanaKeypair.generate();
+
+const mailboxNote: BlindMailboxNote = encryptBlindMailboxNote(
+  serializedUtxo,
+  recipientKeypair.publicKey.toBytes(), // ed25519 public key → X25519 DH
+);
+
+// Recipient decrypts using their Solana secret key (64-byte)
+const mailboxDecrypted: DecryptedNote | null = decryptBlindMailboxNote(
+  mailboxNote,
+  recipientKeypair.secretKey, // 64-byte Solana secret key
+);
+
+// Compute UTXO signature (used in circuit)
+const sig = computeSignature(utxoKeypair.privateKey, utxo.commitment);
+
+// Format an InputUTXO for snarkjs circuit
+const circuitFormat = inputUTXOToCircuitFormat(inputUtxo);
+```
+
+---
+
+### 4.6 Merkle Tree Operations
+
+```ts
+import { MerkleTree } from "@veilo/sdk-core";
+
+// Create a new Merkle tree (default depth: 22)
+const tree = new MerkleTree();
+
+// Insert commitments
+const index = tree.insert(ownedUtxo.commitment);
+
+// Current root
+const root = tree.root();
+
+// Merkle path for proof generation
+const path = tree.path(index);
+// path = { pathElements: Uint8Array[], pathIndices: number[] }
+
+// Total leaves inserted
+const count = tree.totalLeaves;
+```
+
+---
+
+### 4.7 Transaction Operations
+
+All transaction functions return `Promise<string>` (the transaction signature).
+
+#### Deposits
+
+```ts
+import { deposit, type DepositResult } from "@veilo/sdk-core";
+
+const result: DepositResult = await deposit({
+  program,
+  depositor: depositorKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  amount: 1_000_000_000n, // 1 SOL
+  recipientPubkey: pubkeyToField(depositorKeypair.publicKey), // bigint
+  tree,
+  proofBuilder,
+  treeId: 0,
+});
+// result = { outputUTXOs, leafIndices, root }
+```
+
+#### Withdrawals
+
+```ts
+import { withdraw, type WithdrawResult } from "@veilo/sdk-core";
+
+const result: WithdrawResult = await withdraw({
+  program,
+  relayer: relayerKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  amount: 900_000_000n, // 0.9 SOL
+  fee: 100_000_000n, // 0.1 SOL to relayer
+  inputs: [inputUtxo1, zeroInputUtxo],
+  outputs: [changeUtxo, zeroOutputUtxo],
+  recipient: recipientKeypair.publicKey,
+  tree,
+  proofBuilder,
+  treeId: 0,
+});
+```
+
+#### Private Transfers
+
+```ts
+import { privateTransfer, type TransferResult } from "@veilo/sdk-core";
+
+const result: TransferResult = await privateTransfer({
+  program,
+  relayer: relayerKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  inputs: [inputUtxo1, zeroInputUtxo],
+  outputs: [recipientUtxo, changeUtxo],
+  recipient: relayerKeypair.publicKey,
+  tree,
+  proofBuilder,
+  treeId: 0,
+});
+```
+
+#### Low-Level `transact`
+
+```ts
+import { transact } from "@veilo/sdk-core";
+
+const signature: string = await transact({
+  program,
+  relayer: relayerKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  inputTreeId: 0,
+  outputTreeId: 0,
+  root: tree.root(),
+  publicAmount: 0n,
+  inputNullifiers: [nullifier1, nullifier2],
+  outputCommitments: [output1.commitment, output2.commitment],
+  extData: { recipient, relayer: relayerPubkey, fee: 0n, refund: 0n },
+  proof,
+});
+```
+
+---
+
+### 4.8 Private Swaps
+
+Cross-pool private swaps via Jupiter/Raydium. For native SOL source pools the SDK automatically composes the required `fund_native_source` + `transact_swap` instructions into a single atomic transaction.
+
+```ts
+import {
+  transactSwap,
+  getSwapExecutorPda,
+  fundNativeSource,
+  type SwapParams,
+  type SwapProofStruct,
+} from "@veilo/sdk-core";
+
+// Execute a private swap (returns transaction signature)
+const signature: string = await transactSwap({
+  program,
+  relayer: relayerKeypair,
+  sourceMint, // NATIVE_SOL_MINT or SPL token mint
+  destMint,
+  sourceRoot: tree.root(),
+  sourceTreeId: 0,
+  destTreeId: 0,
+  inputNullifiers: [nullifier0, nullifier1],
+  outputCommitments: [changeCommitment, destCommitment],
+  proof, // SwapProofStruct
+  swapParams: {
+    minAmountOut: 950_000_000n,
+    deadline: BigInt(Math.floor(Date.now() / 1000) + 60),
+    sourceMint,
+    destMint,
+    destAmount: 950_000_000n,
+    swapDataHash: new Uint8Array(32), // SHA-256 of DEX ix bytes, or zeros
+  },
+  swapAmount: 1_000_000_000n,
+  swapData: jupiterInstructionBytes, // Buffer
+  extData: { recipient, relayer: relayerPubkey, fee, refund: 0n },
+  sourceVaultTokenAccount,
+  sourceMintAccount,
+  destVaultTokenAccount,
+  destMintAccount,
+  relayerTokenAccount,
+  swapProgram: JUPITER_PROGRAM_ID,
+  jupiterEventAuthority,
+});
+
+// Build the fund_native_source instruction standalone (advanced)
+const fundIx = await fundNativeSource({
+  program,
+  relayer: relayerKeypair,
+  sourceMint: NATIVE_SOL_MINT,
+  destMint,
+  inputNullifier0: nullifier0,
+  swapAmount: 1_000_000_000n,
+});
+// Returns TransactionInstruction — must be first ix in same tx as transact_swap
+```
+
+> **Note:** `transactSwap` handles the atomicity requirement automatically. Only use `fundNativeSource` directly if you are building transactions manually.
+
+---
+
+### 4.9 Event Scanning & Tree Reconstruction
+
+```ts
+import {
+  scanCommitmentEvents,
+  scanNullifierEvents,
+  buildTreeFromEvents,
+  type CommitmentEvent,
+  type NullifierSpentEvent,
+} from "@veilo/sdk-core";
+
+// Scan all commitment events for a mint (paginated by signature)
+const { events, latestSignature } = await scanCommitmentEvents({
+  program,
+  mintAddress: NATIVE_SOL_MINT,
+  treeId: 0,
+  beforeSignature: undefined, // or last known signature for pagination
+  limit: 1000,
+});
+// events: CommitmentEvent[]
+// CommitmentEvent = { commitment, leafIndex, newRoot, timestamp, mintAddress, treeId }
+
+// Scan spent nullifier events
+const { events: nullEvents } = await scanNullifierEvents({
+  program,
+  mintAddress: NATIVE_SOL_MINT,
+  beforeSignature: undefined,
+  limit: 1000,
+});
+// NullifierSpentEvent = { nullifier, mintAddress, treeId }
+
+// Reconstruct a Merkle tree from on-chain events
+const {
+  tree,
+  events: allEvents,
+  latestSignature: sig,
+} = await buildTreeFromEvents({
+  program,
+  mintAddress: NATIVE_SOL_MINT,
+  treeId: 0,
+});
+```
+
+---
+
+### 4.10 Proof Generation
+
+```ts
+import {
+  prepareTransactionInputs,
+  formatInputsForSnarkjs,
+  computeExtDataHash,
+  encodeSnarkjsProofToTransactionProof,
+  packProofToBytes,
+  computeSwapParamsHash,
+  computeSwapDataHash,
+  type ExtData,
+  type TransactionCircuitInputs,
+} from "@veilo/sdk-core";
+
+// Prepare inputs for the transaction circuit
+const circuitInputs: TransactionCircuitInputs = prepareTransactionInputs({
+  root: tree.root(),
+  publicAmount: 1_000_000_000n,
+  extData: { recipient, relayer: relayerPubkey, fee: 0n, refund: 0n },
+  mintAddress: NATIVE_SOL_MINT,
+  inputs: [input1, input2],
+  outputs: [output1, output2],
+  inputTreeId: 0,
+  outputTreeId: 0,
+});
+
+// Format for snarkjs (converts bigints / Uint8Arrays to strings)
+const snarkjsInputs = formatInputsForSnarkjs(circuitInputs);
+
+// After proof generation:
+// const { proof } = await snarkjs.groth16.fullProve(snarkjsInputs, wasmPath, zkeyPath);
+// const transactionProof = encodeSnarkjsProofToTransactionProof(proof);
+
+// Compute ext data hash (matches on-chain computation)
+const extDataHash = computeExtDataHash({
+  recipient,
+  relayer,
+  fee: 0n,
+  refund: 0n,
+});
+
+// Compute swap param/data hashes (for swap circuit inputs)
+const swapParamsHash = computeSwapParamsHash(swapParams);
+const swapDataHash = computeSwapDataHash(jupiterInstructionBytes);
+```
+
+---
+
+### 4.11 Fee Utilities
+
+```ts
+import {
+  computeWithdrawalFee,
+  computeSwapFee,
+  DEFAULT_FEE_BPS,
+} from "@veilo/sdk-core/config";
+
+// Compute protocol fee for a withdrawal
+const fee = computeWithdrawalFee(amount, feeBps, minWithdrawalFee);
+
+// Compute protocol fee for a swap
+const swapFee = computeSwapFee(swapAmount, feeBps);
+```
+
+---
+
+### 4.12 Relayer & Admin Management
+
+```ts
+import { addRelayer, setPaused } from "@veilo/sdk-core";
+
+// Authorise a new relayer for a pool
+await addRelayer({
+  program,
+  admin: adminKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  newRelayer: relayerPubkey,
+});
+
+// Pause or unpause a pool
+await setPaused({
+  program,
+  admin: adminKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  paused: true,
+});
+```
+
+---
+
+### 4.13 Poseidon Utilities
+
+```ts
+import {
+  initPoseidon,
+  poseidon1,
+  poseidon2,
+  poseidon3,
+  poseidon4,
+  pubkeyToField,
+  bytesToBigIntBE,
+  bigIntToBytesBE,
+  BN254_FR_MODULUS,
+} from "@veilo/sdk-core";
+
+// Must be called once before using hash functions
+await initPoseidon();
+
+const h1 = poseidon1(12345n);
+const h2 = poseidon2(12345n, 67890n);
+const h3 = poseidon3(12345n, 67890n, 11111n);
+const h4 = poseidon4(12345n, 67890n, 11111n, 22222n);
+
+// Convert a Solana PublicKey to a BN254 field element
+const field = pubkeyToField(NATIVE_SOL_MINT);
+
+// Byte ↔ bigint helpers (big-endian)
+const n = bytesToBigIntBE(bytes32);
+const b = bigIntToBytesBE(someField, 32);
+```
+
+---
+
+### 4.14 Error Utilities
+
+```ts
+import { parseOnChainError } from "@veilo/sdk-core";
+
+try {
+  await transactSwap({ ... });
+} catch (err) {
+  // Returns a human-readable error string from Anchor/program errors
+  const msg = parseOnChainError(err);
+  console.error("Swap failed:", msg);
+}
+```
+
+---
+
+## 5. Architecture
+
+### Transaction Model
+
+Veilo uses a UTXO privacy model inspired by Zcash and Tornado Cash Nova:
+
+- **Inputs**: 2 UTXOs (zero-value for deposits)
+- **Outputs**: 2 UTXOs (zero-value for withdrawals)
+- **Public Amount**: net pool change — positive = deposit, negative = withdrawal, zero = private transfer or swap
+
+Each transaction consumes 2 input UTXOs (Merkle proofs), creates 2 output UTXOs (commitments inserted to tree), and generates 2 nullifiers to prevent double-spend.
+
+### Swap Architecture
+
+Private swaps require two instructions in a **single atomic transaction**:
+
+1. `fund_native_source` — pre-funds the swap executor with SOL from the vault (native SOL pools only)
+2. `transact_swap` — verifies the ZK proof, spends input UTXOs, creates output UTXOs, and executes the DEX swap
+
+`transactSwap()` handles this automatically. The on-chain program validates atomicity via the instructions sysvar.
+
+### Privacy Guarantees
+
+- **Commitment hiding**: amount, owner, blinding are hidden via Poseidon
+- **Nullifier uniqueness**: each UTXO can only be spent once
+- **Unlinkability**: no public link between inputs and outputs
+- **ZK proofs**: Groth16 verified on-chain
+
+### Constants
+
+```ts
+import {
+  NATIVE_SOL_MINT, // PublicKey.default — native SOL pools
+  MERKLE_TREE_DEPTH, // 22
+  ROOT_HISTORY_SIZE, // 256
+  DEFAULT_FEE_BPS, // 50 (0.5%)
+  sol, // sol(1) === 1_000_000_000n
+} from "@veilo/sdk-core/config";
+```
+
+### Type Exports
+
+```ts
+import type {
+  // UTXO
+  Keypair,
+  UTXO,
+  SerializedUTXO,
+  InputUTXO,
+  // Encryption
+  EncryptedNote,
+  BlindMailboxNote,
+  BlindMailboxNoteData,
+  DecryptedNote,
+  // Proof
+  ExtData,
+  TransactionCircuitInputs,
+  TransactionProofStruct,
+  RawProof,
+  TransactionProofBuilder,
+  // Swap
+  SwapProofStruct,
+  SwapParams,
+  // Tree / events
+  MerklePath,
+  CircuitMerklePath,
+  TreeInfo,
+  CommitmentEvent,
+  NullifierSpentEvent,
+  // Results
+  DepositResult,
+  WithdrawResult,
+  TransferResult,
+  // Config
+  PoolInitConfig,
+  PrivacyConfigAccount,
+  GlobalConfigAccount,
+} from "@veilo/sdk-core";
+```
+
+---
+
+## 6. Development
+
+```bash
+# Run tests (requires devnet or local validator)
+npm test
+```
+
+---
+
+## 7. Resources
+
+- **Repository**: https://github.com/VeiloSolana/veilo-sdk
+- **Circomlibjs**: https://github.com/iden3/circomlibjs
+- **Poseidon Hash**: https://www.poseidon-hash.info/
+
+---
+
+## License
+
+ISC
+
+This package provides a complete UTXO-based privacy protocol implementation on Solana with:
+
+- **UTXO Model**: Full support for unspent transaction outputs with Poseidon commitments
+- **Multi-Tree Support**: Multiple concurrent Merkle trees for improved scalability
+- **ZK Proofs**: Integration with Circom circuits for private transactions
+- **Flexible Operations**: Deposits, withdrawals, and private transfers
+- **Poseidon Hashing**: BN254-curve compatible hashing using circomlibjs
+- **Merkle Trees**: Off-chain Merkle tree management with proof generation
+- **Relayer Support**: Built-in relayer infrastructure for private withdrawals
+
+> **Status:** Active development. The SDK supports full transaction privacy with ZK-SNARK proofs.  
+> Proofs are generated off-chain and verified on-chain using Groth16.
+
+---
+
+## 1. Installation
+
+```bash
+npm install @veilo/sdk-core
+```
+
+Or from source:
+
+```bash
+cd core-sdk
+npm install
 ```
 
 ---
@@ -38,20 +800,20 @@ npm install @zkprivacysol/sdk-core
 
 You need:
 
-- A running Solana validator (localnet recommended):
+- A running Solana validator (localnet/devnet/mainnet):
 
   ```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):
+- The `privacy-pool` program deployed to the network
+- The `privacy-pool` Anchor IDL available:
 
   ```text
-  ../../privacy-pool/target/idl/privacy_pool.json
+  idl/idl/privacy_pool.json
   ```
 
-- A funded keypair on that validator:
+- A funded keypair:
 
   ```bash
   solana config set --url http://127.0.0.1:8899
@@ -59,7 +821,7 @@ You need:
   solana airdrop 10
   ```
 
-Environment variables for tests:
+Environment variables:
 
 ```bash
 export ANCHOR_PROVIDER_URL=http://127.0.0.1:8899
@@ -68,372 +830,595 @@ export ANCHOR_WALLET=$HOME/.config/solana/id.json
 
 ---
 
-## 3. Build & Test
-
-From `packages/sdk-core`:
+## 3. Build
 
 ```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.
+## 4. SDK API
 
-- **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.
+### 4.1 PDA Helpers
 
-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`.
+```ts
+import {
+  getPoolPdas,
+  getNoteTreePda,
+  getGlobalConfigPda,
+  getNullifierMarkerPda,
+} from "@veilo/sdk-core";
+import { PublicKey } from "@solana/web3.js";
 
----
+const programId = new PublicKey(
+  "YourProgram1111111111111111111111111111111111",
+);
+const mintAddress = new PublicKey(
+  "So11111111111111111111111111111111111111112",
+); // Native SOL
 
-## 4. SDK Surface
+// Get pool PDAs
+const { config, vault, nullifiers } = getPoolPdas(programId, mintAddress);
 
-### 4.1 PDA helpers
+// Get note tree PDA for tree ID 0
+const noteTree = getNoteTreePda(programId, mintAddress, 0);
 
-```ts
-import { getPoolPdas } from "@zkprivacysol/sdk-core";
-import { PublicKey } from "@solana/web3.js";
+// Get global config
+const globalConfig = getGlobalConfigPda(programId);
 
-const programId = new PublicKey("YourProgram1111111111111111111111111111111111");
-const { config, vault, noteTree, nullifiers } = getPoolPdas(programId);
+// Get nullifier marker PDA
+const nullifier = new Uint8Array(32);
+const marker = getNullifierMarkerPda(programId, mintAddress, 0, nullifier);
 ```
 
-These must match the on-chain seeds (v3 layout):
+**PDA seeds (v3):**
 
-- `["privacy_config_v3"]`
-- `["privacy_vault_v3"]`
-- `["privacy_note_tree_v3"]`
-- `["privacy_nullifiers_v3"]`
+- Config: `["privacy_config_v3", mint_address]`
+- Vault: `["privacy_vault_v3", mint_address]`
+- Note Tree: `["privacy_note_tree_v3", mint_address, tree_id]`
+- Nullifiers: `["privacy_nullifiers_v3", mint_address]`
+- Nullifier Marker: `["privacy_nullifier_v3", mint_address, tree_id, nullifier]`
+- Global Config: `["global_config_v1"]`
 
 ---
 
-### 4.2 Pool init / configuration
+### 4.2 Pool Initialization
 
 ```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
-  });
-}
-```
+import {
+  initializeGlobalConfig,
+  initializePool,
+  updatePoolConfig,
+  addMerkleTree,
+  getPoolConfig,
+} from "@veilo/sdk-core";
+import { NATIVE_SOL_MINT, sol } from "@veilo/sdk-core/config";
+
+// Initialize global config (once per program)
+await initializeGlobalConfig({
+  program,
+  admin: adminKeypair,
+});
 
-This calls the on-chain `initialize` instruction and sets:
+// Initialize a pool for native SOL
+await initializePool({
+  program,
+  payer: adminKeypair,
+  admin: adminKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  minDepositAmount: sol(0.1), // 0.1 SOL
+  maxDepositAmount: sol(100), // 100 SOL
+  minWithdrawAmount: sol(0.1),
+  maxWithdrawAmount: sol(100),
+  feeBps: 50, // 0.5%
+  feeErrorMarginBps: 10, // 0.1% margin
+  minWithdrawalFee: 1_000_000n, // 0.001 SOL minimum
+});
 
-- fixed denominations (in lamports)
-- vault + note tree + nullifier set PDAs
-- fee in basis points
-- initial TVL = 0
+// Add first Merkle tree (tree ID 0)
+await addMerkleTree({
+  program,
+  payer: adminKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  treeId: 0,
+});
+
+// Update pool configuration
+await updatePoolConfig({
+  program,
+  admin: adminKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  feeBps: 30, // Change to 0.3%
+});
+
+// Read pool configuration
+const poolConfig = await getPoolConfig(program, NATIVE_SOL_MINT);
+console.log("TVL:", poolConfig.totalTvl);
+console.log("Fee:", poolConfig.feeBps, "bps");
+console.log("Num Trees:", poolConfig.numTrees);
+```
 
 ---
 
-### 4.3 Notes & commitments
+### 4.3 UTXO Management
 
-`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.
+The SDK uses a UTXO (Unspent Transaction Output) model with Poseidon commitments:
 
 ```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,
+  generateKeypair,
+  keypairFromPrivateKey,
+  createUTXO,
+  createOwnedUTXO,
+  createOwnedZeroUTXO,
+  deriveNullifier,
+  type Keypair,
+  type UTXO,
+  type SerializedUTXO,
+  type InputUTXO,
+} from "@veilo/sdk-core";
+import { NATIVE_SOL_MINT } from "@veilo/sdk-core/config";
+import { pubkeyToField } from "@veilo/sdk-core";
+
+// Generate a random keypair
+const keypair: Keypair = generateKeypair();
+// keypair = { privateKey: bigint, publicKey: bigint }
+
+// Restore keypair from private key
+const restored = keypairFromPrivateKey(privateKeyBigInt);
+
+// Create an owned UTXO (includes private key)
+const ownedUtxo: SerializedUTXO = createOwnedUTXO({
+  amount: 1_000_000_000n,
+  privateKey: keypair.privateKey,
+  mintAddress: NATIVE_SOL_MINT,
 });
 
-// 2. Encode deterministically
-const bytes = encodeNoteToBytes(note);
+// Create a zero UTXO (for unused inputs/outputs)
+const zeroUtxo = createOwnedZeroUTXO(pubkeyToField(NATIVE_SOL_MINT), keypair);
 
-// 3. Hash to a 32-byte commitment (placeholder)
-const commitment = commitNote(note);
+// Derive nullifier for spending
+const nullifier = deriveNullifier(
+  ownedUtxo.privateKey,
+  ownedUtxo.commitment,
+  0, // pathIndex in Merkle tree
+  0, // treeId
+);
+```
+
+**UTXO commitment formula:**
 
-// 4. Convenience combo
-const full = createNoteWithCommitment({
-  value: 1_000_000n,
-  owner,
-});
-// full.commitment is 32 bytes
+```
+commitment = Poseidon(amount, pubkey, blinding, mintAddress)
 ```
 
-Encoding layout:
+**Nullifier formula:**
 
-```text
-value (u64 LE, 8 bytes)
-|| owner pubkey (32 bytes)
-|| rho (32 bytes random)
-|| r   (32 bytes random)
+```
+nullifier = Poseidon(privateKey, commitment, pathIndex, treeId)
 ```
 
-Hash:
+---
+
+### 4.4 Merkle Tree Operations
 
 ```ts
-commitment = sha256(encodedBytes);
-```
+import { MerkleTree } from "@veilo/sdk-core";
 
-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]`.
+// Create a new Merkle tree (default depth: 20)
+const tree = new MerkleTree();
 
----
+// Insert commitments
+const index1 = tree.insert(ownedUtxo1.commitment);
+const index2 = tree.insert(ownedUtxo2.commitment);
 
-### 4.4 Merkle helpers (demo-only)
+// Get current root
+const root = tree.root();
 
-`src/merkle.ts` provides **very basic** Merkle helpers so callers can build roots off-chain. This is meant for demos/tests, not production.
+// Get Merkle path for proof generation
+const path = tree.path(index1);
+// path = { pathElements: Uint8Array[], pathIndices: number[] }
 
-Key functions:
+// Get number of leaves
+const numLeaves = tree.totalLeaves;
 
-```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
+// Custom tree depth
+const deepTree = new MerkleTree(25); // 25 levels
 ```
 
-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).
+The Merkle tree uses Poseidon hash for all internal nodes.
 
 ---
 
-### 4.5 Deposits
+### 4.5 Transaction Operations
 
-Low-level helper (you supply both commitment + Merkle root):
+The SDK supports three types of transactions:
+
+#### Deposits (publicAmount > 0)
 
 ```ts
-import * as anchor from "@coral-xyz/anchor";
-import { depositFixedSol } from "@zkprivacysol/sdk-core";
+import { deposit } from "@veilo/sdk-core";
 
-const provider = anchor.getProvider() as anchor.AnchorProvider;
-const wallet = provider.wallet as anchor.Wallet;
+// Create output UTXO
+const outputUtxo = createOwnedUTXO({
+  amount: 1_000_000_000n, // 1 SOL
+  mintAddress: pubkeyToField(NATIVE_SOL_MINT),
+  keypair: utxoKeypair,
+});
+
+// Zero inputs for deposit
+const input1 = createOwnedZeroUTXO(pubkeyToField(NATIVE_SOL_MINT), utxoKeypair);
+const input2 = createOwnedZeroUTXO(pubkeyToField(NATIVE_SOL_MINT), utxoKeypair);
+const output2 = createOwnedZeroUTXO(
+  pubkeyToField(NATIVE_SOL_MINT),
+  utxoKeypair,
+);
 
-await depositFixedSol({
+await deposit({
   program,
-  depositor: wallet,
-  denomIndex: 0,        // index into cfg.denoms
-  commitment,           // 32-byte note commitment
-  newRoot,              // 32-byte Merkle root (caller computed off-chain)
+  depositor: depositorKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  inputTreeId: 0,
+  outputTreeId: 0,
+  root: tree.root(),
+  publicAmount: 1_000_000_000n, // Positive = deposit
+  inputs: [input1, input2],
+  outputs: [outputUtxo, output2],
+  recipient: depositorKeypair.publicKey,
+  fee: 0n,
+  refund: 0n,
+  proof: mockProof,
 });
+
+// Insert outputs into tree
+tree.insert(outputUtxo.commitment);
+tree.insert(output2.commitment);
 ```
 
-High-level helper (with note creation, but you still feed a root):
+#### Withdrawals (publicAmount < 0)
 
 ```ts
-import * as anchor from "@coral-xyz/anchor";
-import { createNoteAndDeposit } from "@zkprivacysol/sdk-core";
-import { sol } from "@zkprivacysol/sdk-core/config";
+import { withdraw } from "@veilo/sdk-core";
+
+// Prepare input with Merkle path
+const input1: InputUTXO = {
+  ...ownedUtxo1,
+  pathIndex: 0,
+  pathElements: tree.path(0).pathElements,
+};
+
+const zeroInput2: InputUTXO = {
+  ...createOwnedZeroUTXO(pubkeyToField(NATIVE_SOL_MINT), utxoKeypair),
+  pathIndex: 0,
+  pathElements: tree.path(0).pathElements,
+};
+
+// Zero outputs
+const output1 = createOwnedZeroUTXO(
+  pubkeyToField(NATIVE_SOL_MINT),
+  utxoKeypair,
+);
+const output2 = createOwnedZeroUTXO(
+  pubkeyToField(NATIVE_SOL_MINT),
+  utxoKeypair,
+);
+
+await withdraw({
+  program,
+  relayer: relayerKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  inputTreeId: 0,
+  outputTreeId: 0,
+  root: tree.root(),
+  publicAmount: -900_000_000n, // Negative = withdrawal (0.9 SOL)
+  inputs: [input1, zeroInput2],
+  outputs: [output1, output2],
+  recipient: recipientKeypair.publicKey,
+  fee: 100_000_000n, // 0.1 SOL to relayer
+  refund: 0n,
+  proof,
+});
+```
 
-const provider = anchor.getProvider() as anchor.AnchorProvider;
-const wallet = provider.wallet as anchor.Wallet;
+#### Private Transfers (publicAmount = 0)
 
-const dummyRoot = new Uint8Array(32).fill(7); // replace with real Merkle root
+```ts
+import {
+  privateTransfer,
+  generateKeypair,
+  createOwnedUTXO,
+} from "@veilo/sdk-core";
+
+// Create new outputs for recipient
+const recipientKeypair = generateKeypair();
+const output1 = createOwnedUTXO({
+  amount: 1_000_000_000n,
+  privateKey: recipientKeypair.privateKey,
+  mintAddress: NATIVE_SOL_MINT,
+});
 
-const note = await createNoteAndDeposit({
+await privateTransfer({
   program,
-  depositor: wallet,
-  denomIndex: 0,
-  valueLamports: sol(1),
-  newRoot: dummyRoot,
+  relayer: relayerKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  inputTreeId: 0,
+  outputTreeId: 0,
+  root: tree.root(),
+  publicAmount: 0n, // Zero = private transfer
+  inputs: [input1, zeroInput2],
+  outputs: [output1, output2],
+  recipient: relayerKeypair.publicKey,
+  fee: 0n,
+  refund: 0n,
+  proof,
 });
 
-// note.commitment can later be used in your off-chain tree
+// Insert new outputs
+tree.insert(output1.commitment);
+tree.insert(output2.commitment);
 ```
 
-There’s also a higher-level helper that integrates directly with an in-memory `MerkleTree`:
+#### Low-Level Transaction Function
+
+For advanced use cases, use the unified `transact` function directly:
 
 ```ts
-import { createNoteDepositWithMerkle } from "@zkprivacysol/sdk-core";
-import { MerkleTree } from "@zkprivacysol/sdk-core/merkle";
+import { transact } from "@veilo/sdk-core";
 
-const tree = new MerkleTree();
+await transact({
+  program,
+  relayer: relayerKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  inputTreeId: 0,
+  outputTreeId: 0,
+  root: tree.root(),
+  publicAmount: 0n,
+  inputNullifiers: [nullifier1, nullifier2],
+  outputCommitments: [output1.commitment, output2.commitment],
+  extData: {
+    recipient: recipientPubkey,
+    relayer: relayerPubkey,
+    fee: 0n,
+    refund: 0n,
+  },
+  proof,
+});
+```
 
-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
-```
+### 4.6 Proof Generation
 
-On-chain, the `depositFixed` instruction:
+The SDK provides utilities for preparing circuit inputs:
 
-- moves SOL from `depositor` to the vault PDA,
-- updates TVL,
-- writes `new_root` into the on-chain note tree’s current root field.
+```ts
+import {
+  prepareTransactionInputs,
+  formatInputsForSnarkjs,
+  computeExtDataHash,
+  encodeSnarkjsProofToTransactionProof,
+  packProofToBytes,
+  type ExtData,
+  type TransactionCircuitInputs,
+} from "@veilo/sdk-core";
+
+// Prepare inputs for the circuit
+const circuitInputs: TransactionCircuitInputs = prepareTransactionInputs({
+  root: tree.root(),
+  publicAmount: 1_000_000_000n,
+  extData: {
+    recipient: recipientPubkey,
+    relayer: relayerPubkey,
+    fee: 0n,
+    refund: 0n,
+  },
+  mintAddress: NATIVE_SOL_MINT,
+  inputs: [input1, input2],
+  outputs: [output1, output2],
+  inputTreeId: 0,
+  outputTreeId: 0,
+});
 
----
+// Format for snarkjs (converts Uint8Array to string representations)
+const snarkjsInputs = formatInputsForSnarkjs(circuitInputs);
 
-### 4.6 Relayers & Withdrawals
+// Use with snarkjs to generate proof
+// const { proof, publicSignals } = await snarkjs.groth16.fullProve(
+//   snarkjsInputs,
+//   wasmPath,
+//   zkeyPath
+// );
 
-Add a relayer (admin-only):
+// Convert snarkjs proof to on-chain format
+// const transactionProof = encodeSnarkjsProofToTransactionProof(proof);
+```
 
-```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;
+### 4.7 Relayer Management
 
-const relayer = Keypair.generate();
+```ts
+import { addRelayer, setPaused } from "@veilo/sdk-core";
 
+// Add a relayer
 await addRelayer({
   program,
-  admin: wallet,
-  newRelayer: relayer.publicKey,
+  admin: adminKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  newRelayer: relayerPubkey,
+});
+
+// Pause/unpause the pool
+await setPaused({
+  program,
+  admin: adminKeypair,
+  mintAddress: NATIVE_SOL_MINT,
+  paused: true,
 });
 ```
 
-Withdraw via relayer (SDK-level helper):
+---
+
+### 4.8 Poseidon Utilities
 
 ```ts
-import { withdrawViaRelayer } from "@zkprivacysol/sdk-core";
-import { Keypair } from "@solana/web3.js";
+import {
+  initPoseidon,
+  poseidon1,
+  poseidon2,
+  poseidon3,
+  poseidon4,
+  pubkeyToField,
+} from "@veilo/sdk-core";
+
+// Initialize Poseidon (required once before using hash functions)
+await initPoseidon();
+
+// Hash functions
+const hash1 = poseidon1(12345n);
+const hash2 = poseidon2(12345n, 67890n);
+const hash3 = poseidon3(12345n, 67890n, 11111n);
+const hash4 = poseidon4(12345n, 67890n, 11111n, 22222n);
+
+// Convert Solana PublicKey to field element
+const fieldElement = pubkeyToField(NATIVE_SOL_MINT);
+```
 
-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
+## 5. Architecture
 
-// In the real world, `proof` will be zk-proof bytes coming from your prover.
-const proofBytes = new Uint8Array([]); // currently ignored by on-chain program
+### Transaction Model
 
-await withdrawViaRelayer({
-  program,
-  relayer,
-  recipient: recipient.publicKey,
-  denomIndex: 0,
-  root,
-  nullifier,
-  proof: proofBytes,
-});
-```
+Veilo uses a UTXO-based privacy model inspired by Zcash and Tornado Cash Nova:
 
-There is also a higher-level helper (`withdrawViaRelayerWithProof`) that takes:
+1. **Inputs**: 2 UTXOs (can be zero for deposits)
+2. **Outputs**: 2 UTXOs (can be zero for withdrawals)
+3. **Public Amount**: Net change (positive = deposit, negative = withdrawal, zero = private transfer)
 
-- `noteData` (serialized note),
-- `merklePath`,
-- `feeBps`,
-- a `builder: ProofBuilder` callback
+Each transaction:
 
-and lets you plug in your own proof generator. In practice, your **relayer service** will own that logic.
+- Consumes 2 input UTXOs (proven via Merkle paths)
+- Creates 2 output UTXOs (commitments added to tree)
+- Generates 2 nullifiers (prevents double-spending)
+- Optionally transfers funds in/out of the pool
 
-**Production pattern:**
+### Privacy Guarantees
 
-- 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.
+- **Commitment hiding**: Amount, owner, and blinding factor are hidden via Poseidon hash
+- **Nullifier uniqueness**: Each UTXO can only be spent once
+- **Unlinkability**: No public link between inputs and outputs
+- **Zero-knowledge proofs**: Transactions proven valid without revealing private data
 
-From the SDK’s perspective, `proof: Uint8Array` is **already-built**; this package doesn’t know how you generated it.
+### Multi-Tree Support
 
----
+The protocol supports multiple concurrent Merkle trees per pool:
+
+- Improves scalability by reducing tree depth
+- Allows parallel insertions
+- Each tree has independent state
+
+### Constants
+
+```ts
+import {
+  NATIVE_SOL_MINT, // PublicKey.default (all zeros) for native SOL
+  MERKLE_TREE_DEPTH, // 22 levels
+  ROOT_HISTORY_SIZE, // 256 historical roots
+  DEFAULT_FEE_BPS, // 50 (0.5%)
+  sol, // Helper: sol(1) = 1_000_000_000n lamports
+} from "@veilo/sdk-core/config";
+
+import { BN254_FR_MODULUS } from "@veilo/sdk-core";
+```
+
+### Type Exports
+
+The SDK exports the following types for TypeScript users:
 
-## 5. Environment & Localnet
+```ts
+import type {
+  // UTXO types
+  Keypair,
+  UTXO,
+  SerializedUTXO,
+  InputUTXO,
+
+  // Proof types
+  ExtData,
+  TransactionCircuitInputs,
+  TransactionProofStruct,
+  RawProof,
+  TransactionProofBuilder,
+
+  // Merkle types
+  MerklePath,
+  CircuitMerklePath,
+
+  // Config types
+  PoolInitConfig,
+  PrivacyConfigAccount,
+  GlobalConfigAccount,
+} from "@veilo/sdk-core";
+```
 
-To run the integration tests successfully, you should:
+### SPL Token Support
 
-1. Start local validator:
+The SDK supports both native SOL and SPL tokens:
 
-   ```bash
-   solana-test-validator
-   ```
+```ts
+import { PublicKey } from "@solana/web3.js";
+
+// For native SOL
+const solMint = NATIVE_SOL_MINT; // PublicKey.default
+
+// For SPL tokens
+const usdcMint = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
+
+// Initialize pool for SPL token
+await initializePool({
+  program,
+  payer: adminKeypair,
+  admin: adminKeypair,
+  mintAddress: usdcMint, // Use SPL token mint
+  minDepositAmount: 1_000_000n, // 1 USDC (6 decimals)
+  // ... other params
+});
+```
 
-2. Build & deploy the `privacy-pool` Anchor program in `packages/privacy-pool`:
+When using SPL tokens, the SDK automatically handles associated token accounts.
 
-   ```bash
-   cd packages/privacy-pool
-   anchor build
-   anchor deploy
-   ```
+---
 
-3. Ensure your CLI and wallet match the validator:
+## 6. Development
 
-   ```bash
-   solana config set --url http://127.0.0.1:8899
-   solana-keygen new --outfile ~/.config/solana/id.json
-   solana airdrop 10
-   ```
+### Environment Variables
 
-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
+```
 
-   ```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`:
+## 7. Limitations
 
-   ```bash
-   npm run build
-   npm test
-   ```
+- **Off-chain tree management**: Merkle trees must be maintained by relayers/clients
+- **Proof generation not included**: You must integrate your own circuit/prover
+- **Development status**: Active development, APIs may change
 
 ---
 
-## 6. Limitations & TODOs
+## 8. Resources
+
+- **Repository**: https://github.com/VeiloSolana/veilo-sdk
+- **Circomlibjs**: https://github.com/iden3/circomlibjs
+- **Poseidon Hash**: https://www.poseidon-hash.info/
+
+---
 
-- **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.
+## License
 
-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.
+ISC