@veilo/sdk-core 0.4.0 → 0.6.0

package/README.md

@@ -1,1463 +1,669 @@
 # @veilo/sdk-core
 
-TypeScript SDK for the Veilo Privacy Pool Anchor program.
+Build private payments and swaps on Solana with Veilo.
 
-This package provides a complete UTXO-based privacy protocol implementation on Solana with:
+The SDK gives TypeScript applications a safe, typed way to:
 
-- **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
+- shield SOL or SPL tokens into Veilo;
+- withdraw, privately transfer, or privately swap shielded funds;
+- open and manage private positions, Jupiter perps, and predictions;
+- work with Veilo's relayer without handling its encryption protocol yourself;
+- add partner-powered private sends and swaps through the Cloak API.
 
-> **Status:** Active development. The SDK supports full transaction privacy with ZK-SNARK proofs.
-> Proofs are generated off-chain and verified on-chain using Groth16.
+It works with both ESM and CommonJS and includes TypeScript declarations.
 
----
+> **Project status:** Active development. Test integrations on Devnet before using
+> them with real funds.
 
-## 1. Installation
+## Install
 
 ```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
+Install `snarkjs` only if your application generates proofs locally:
 
 ```bash
-export ANCHOR_PROVIDER_URL=https://api.devnet.solana.com
-export ANCHOR_WALLET=$HOME/.config/solana/id.json
+npm install snarkjs
 ```
 
----
-
-## 3. Build
-
-```bash
-npm run build
-```
+You will also need:
 
----
+- a Solana RPC connection;
+- a connected wallet when a user must sign;
+- the Veilo circuit `.wasm` and `.zkey` files for local proof generation;
+- an API key only for partner services such as Cloak or Jupiter Predictions.
 
-## 4. SDK API
+## Choose an integration
 
-### 4.1 PDA Helpers
+| What you want to build | Start with | Who signs? |
+| --- | --- | --- |
+| Let any wallet shield funds into Veilo | `shield()` | The user's wallet |
+| Add private transfers or swaps to a partner app | `VeiloCloakClient` | The user's wallet |
+| Build a full Veilo wallet experience | Managed relayer helpers | The relayer for private spends |
+| Manage proofs, notes, trees, and transactions yourself | Transaction helpers | Your application or relayer |
 
-```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",
-);
+For most third-party deposit integrations, `shield()` is the best starting
+point. For a managed private send or swap flow, use Cloak.
 
-// Pool PDAs (config, vault, nullifiers)
-const { config, vault, nullifiers } = getPoolPdas(programId, mintAddress);
+## Quick start: shield funds
 
-// 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
+`shield()` creates an unsigned transaction. Your application asks the user's
+wallet to sign it, submits it, and then finalizes the new private note.
 
 ```ts
+import { Connection } from "@solana/web3.js";
 import {
-  initializeGlobalConfig,
-  initializePool,
-  updatePoolConfig,
-  addMerkleTree,
-  getPoolConfig,
-  updateGlobalConfig,
+  createTransactionProver,
+  finalizeShield,
+  resolveShieldOwner,
+  shield,
 } 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 });
+const connection = new Connection(process.env.SOLANA_RPC_URL!, "confirmed");
 
-// 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,
+// `wallet` is any connected Solana wallet with `publicKey` and
+// `signTransaction` methods.
+const owner = await resolveShieldOwner({ username: "alice" });
+const prover = createTransactionProver({
+  wasmPath: "/circuits/transaction.wasm",
+  zkeyPath: "/circuits/transaction_final.zkey",
 });
 
-// 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,
+const result = await shield({
+  connection,
+  amount: 1_000_000_000n, // 1 SOL in lamports
+  owner,
+  signer: { publicKey: wallet.publicKey },
+  prover,
 });
 
-// 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
-);
+const signed = await wallet.signTransaction(result.transaction);
+const signature = await connection.sendRawTransaction(signed.serialize());
 
-// Recipient decrypts using their Solana secret key (64-byte)
-const mailboxDecrypted: DecryptedNote | null = decryptBlindMailboxNote(
-  mailboxNote,
-  recipientKeypair.secretKey, // 64-byte Solana secret key
+const confirmation = await connection.confirmTransaction(
+  {
+    signature,
+    blockhash: result.blockhash,
+    lastValidBlockHeight: result.lastValidBlockHeight,
+  },
+  "confirmed",
 );
 
-// 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";
+if (confirmation.value.err) {
+  throw new Error("Shield transaction failed");
+}
 
-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,
+const finalized = await finalizeShield({
+  connection,
+  signature,
+  note: result.note,
+  owner,
 });
-```
-
-#### 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, claimant },
-  proof,
-});
+console.log("Private note created at leaf", finalized.leafIndex);
 ```
 
----
-
-#### Wallet-agnostic shielding
-
-`shield()` builds an unsigned v0 deposit transaction for any Solana wallet to
-sign. The signer funds the deposit, while the resulting private note can belong
-to a different Veilo user. The SDK never receives a wallet secret key and never
-broadcasts on the caller's behalf.
+To shield an SPL token, pass its mint:
 
 ```ts
-import {
-  createTransactionProver,
-  resolveShieldOwner,
-  shield,
-} from "@veilo/sdk-core";
-
-const owner = await resolveShieldOwner({ username: "alice" });
 const result = await shield({
   connection,
-  amount: 5_000_000n,
-  mint: USDC_MINT,
+  mint: usdcMint,
+  amount: 5_000_000n, // 5 USDC when the mint has 6 decimals
   owner,
   signer: { publicKey: wallet.publicKey },
-  prover: createTransactionProver({ wasmPath, zkeyPath }),
+  prover,
 });
-
-const signed = await wallet.signTransaction(result.transaction);
-const signature = await connection.sendRawTransaction(signed.serialize());
 ```
 
-Use `rebuild()` if the blockhash or deadline expires, and call
-`finalizeShield()` after confirmation to obtain the authoritative Merkle leaf
-index. See [SHIELD_INTEGRATION.md](./SHIELD_INTEGRATION.md) for the complete
-build → sign → submit → finalize flow, retry rules, owner-key invariant, and
-fee/rent requirements.
-
----
+Keep `result.note` private. It contains the information needed to recover the
+shielded funds. `finalizeShield()` gives you the authoritative leaf index after
+the transaction lands.
 
-### 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.
+If the blockhash expires before submission, reuse the proof with `rebuild()`:
 
 ```ts
-import {
-  transactSwap,
-  getSwapExecutorPda,
-  fundNativeSource,
-  type SwapParams,
-  type SwapProofStruct,
-} from "@veilo/sdk-core";
+import { rebuild } 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, claimant },
-  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
+const refreshed = await rebuild(result, { connection });
 ```
 
-> **Note:** `transactSwap` handles the atomicity requirement automatically. Only use `fundNativeSource` directly if you are building transactions manually.
+A stale Merkle root needs a new call to `shield()` because it requires a new
+proof.
 
----
+## Cloak Partner API
 
-### 4.9 Event Scanning & Tree Reconstruction
+Cloak is the simplest route for partner applications that want a private send
+or cross-asset private swap. The SDK handles request types, API authentication,
+transaction decoding, polling, and structured errors. It never signs for the
+user.
+
+Keep your Cloak API key on a trusted server. Do not include it in a browser or
+mobile bundle.
+
+### Create an order on your server
 
 ```ts
-import {
-  scanCommitmentEvents,
-  scanNullifierEvents,
-  buildTreeFromEvents,
-  type CommitmentEvent,
-  type NullifierSpentEvent,
-} from "@veilo/sdk-core";
+import { VeiloCloakClient } from "@veilo/sdk-core/cloak";
 
-// 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,
+const cloak = new VeiloCloakClient({
+  apiKey: process.env.VEILO_CLOAK_KEY!,
 });
-// 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,
+// The production API defaults to https://api.veilo.network/.
+const { quote } = await cloak.getQuote({
+  amount: "100000000", // raw token units
+  sourceAssetId: "veilo-usdc",
+  destinationAssetId: "veilo-usdc",
+  senderAddress,
+  recipientAddress,
+  mode: "exact_in",
 });
-// 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,
-});
+const { order } = await cloak.createOrder(
+  {
+    quote, // return the complete quote without changing it
+    senderAddress,
+    recipientAddress,
+  },
+  { idempotencyKey: crypto.randomUUID() },
+);
 ```
 
----
+For a cross-asset swap, use a different `destinationAssetId` and optionally add
+`slippageBps` to the quote request. Use `listTokens()` to discover supported
+asset IDs and their current limits.
 
-### 4.10 Proof Generation
+You can override the API address for another environment. Both the origin and
+the full Cloak path are accepted:
 
 ```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, claimant },
-  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,
-  claimant,
+new VeiloCloakClient({
+  baseUrl: "https://api.veilo.network/", // `/cloak/v1` also works here
+  apiKey: process.env.VEILO_CLOAK_KEY!,
 });
-
-// Compute swap param/data hashes (for swap circuit inputs)
-const swapParamsHash = computeSwapParamsHash(swapParams);
-const swapDataHash = computeSwapDataHash(jupiterInstructionBytes);
 ```
 
----
+### Sign in the user's application
 
-### 4.11 Fee Utilities
+Send the returned `order` to the user's application, then deserialize and sign
+its transaction:
 
 ```ts
-import {
-  computeWithdrawalFee,
-  computeSwapFee,
-  DEFAULT_FEE_BPS,
-} from "@veilo/sdk-core/config";
+import { deserializeCloakTransaction } from "@veilo/sdk-core/cloak";
 
-// Compute protocol fee for a withdrawal
-const fee = computeWithdrawalFee(amount, feeBps, minWithdrawalFee);
-
-// Compute protocol fee for a swap
-const swapFee = computeSwapFee(swapAmount, feeBps);
+const transaction = deserializeCloakTransaction(order);
+const signed = await wallet.signTransaction(transaction);
+const signature = await connection.sendRawTransaction(signed.serialize());
+await connection.confirmTransaction(signature, "confirmed");
 ```
 
----
-
-### 4.12 Relayer & Admin Management
+Send the signature back to your server. The deposit notification is optional,
+but it can reduce processing latency:
 
 ```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,
+await cloak.notifyDeposit({
+  trackingId: order.trackingId,
+  txSignature: signature,
 });
 
-// Pause or unpause a pool
-await setPaused({
-  program,
-  admin: adminKeypair,
-  mintAddress: NATIVE_SOL_MINT,
-  paused: true,
+const finalStatus = await cloak.waitForFinalStatus(order.trackingId, {
+  intervalMs: 3_000,
+  timeoutMs: 20 * 60_000,
 });
+
+console.log(finalStatus.status);
 ```
 
----
+If an unfunded order's transaction expires, call
+`refreshTransaction(order.trackingId)` and ask the user to sign the refreshed
+transaction.
 
-### 4.13 Poseidon Utilities
+## Full private wallet flows
 
-```ts
-import {
-  initPoseidon,
-  poseidon1,
-  poseidon2,
-  poseidon3,
-  poseidon4,
-  pubkeyToField,
-  bytesToBigIntBE,
-  bigIntToBytesBE,
-  BN254_FR_MODULUS,
-} from "@veilo/sdk-core";
+The SDK supports all Veilo privacy-pool operations. Pick the highest-level API
+that fits your application:
 
-// 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);
+| Operation | Managed relayer call | Direct SDK helper |
+| --- | --- | --- |
+| Deposit | Not required | `shield()` or `deposit()` |
+| Withdraw | `submitWithdraw()` | `withdraw()` |
+| Private transfer | `submitPrivateTransfer()` | `privateTransfer()` |
+| Private swap | `submitPrivateSwap()` | `buildPrivateSwapInstructions()` or `transactSwap()` |
 
-// Convert a Solana PublicKey to a BN254 field element
-const field = pubkeyToField(NATIVE_SOL_MINT);
+### Use the managed relayer helpers
 
-// Byte ↔ bigint helpers (big-endian)
-const n = bytesToBigIntBE(bytes32);
-const b = bigIntToBytesBE(someField, 32);
-```
-
----
-
-### 4.14 Error Utilities
+The SDK owns Veilo's production relayer URL, encryption key, request encryption,
+and safe retry behavior. Applications call typed functions directly; there is
+no relayer client or URL to configure.
 
 ```ts
-import { parseOnChainError } from "@veilo/sdk-core";
+import {
+  submitWithdraw,
+  type WithdrawRequest,
+} from "@veilo/sdk-core/relayer";
 
-try {
-  await transactSwap({ ... });
-} catch (err) {
-  // Returns a human-readable error string from Anchor/program errors
-  const msg = parseOnChainError(err);
-  console.error("Swap failed:", msg);
+async function submitWithdrawal(request: WithdrawRequest) {
+  return submitWithdraw(request);
 }
 ```
 
----
-
-## 5. Architecture
-
-### Transaction Model
+The same focused entry point provides account authentication, encrypted note
+storage, Merkle tree reads, private transfers, private swaps, and these product
+flows:
 
-Veilo uses a UTXO privacy model inspired by Zcash and Tornado Cash Nova:
+| Product | Relayer helpers |
+| --- | --- |
+| Private positions | `submitOpenPosition()`, `submitClosePosition()`, `submitMergePositions()` |
+| Jupiter perps | `submitJperpOpen()`, `submitJperpClose()`, TP/SL, cancellation, recovery, and reissue helpers |
+| Jupiter predictions | `submitPredictionOpen()` and `submitPredictionReissue()` |
 
-- **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
+#### Submission always targets Veilo's relayer
 
-Each transaction consumes 2 input UTXOs (Merkle proofs), creates 2 output UTXOs (commitments inserted to tree), and generates 2 nullifiers to prevent double-spend.
+Every helper above submits to Veilo's relayer. There is no `baseUrl` option, no
+client to construct, and no supported way to redirect submission. That is
+deliberate, for two independent reasons:
 
-### Swap Architecture
+1. **The program requires it.** The privacy pool checks the submitting relayer
+   against an on-chain allowlist on every spend. Deposits (`public_amount > 0`)
+   are permissionless — which is why `shield()` and `deposit()` work with any
+   wallet — but withdrawals, transfers, swaps, positions, perps, and predictions
+   all fail with `RelayerNotAllowed` unless the transaction is signed by a
+   whitelisted relayer. Pointing the SDK at a different host would produce a
+   well-formed request that cannot land on chain.
+2. **These requests carry spending keys.** `TransactNote.privateKey`, and the
+   `claimantSecretKey` on position close and merge, *are* the spend authority for
+   the funds involved (see [A private note is valuable secret
+   data](#a-private-note-is-valuable-secret-data)). A configurable submission
+   target would be a configurable destination for user funds.
 
-Private swaps require two instructions in a **single atomic transaction**:
+Running your own relayer is a whitelisting conversation rather than a
+configuration flag — see [Support](#support). Reaching past the package's
+`exports` map to import internal modules is unsupported and not covered by
+semver.
 
-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";
-```
+### Spend status and private balance
 
-### Type Exports
+Nothing in a note says whether it has been spent — a note is yours until its
+nullifier is published. So a balance is always two steps, and the SDK gives you
+both:
 
 ```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";
-```
+import { getPrivateBalance, checkNullifiersSpent } from "@veilo/sdk-core";
 
----
-
-## 6. Development
-
-```bash
-# Run tests (requires devnet or local validator)
-npm test
+const { total, byMint, unspent, spent } = await getPrivateBalance(myNotes);
 ```
 
----
-
-## 7. Resources
-
-- **Repository**: https://github.com/VeiloSolana/veilo-sdk
-- **Circomlibjs**: https://github.com/iden3/circomlibjs
-- **Poseidon Hash**: https://www.poseidon-hash.info/
-
----
-
-## License
+Each note needs an `amount`, a 64-character hex `nullifier`, and optionally a
+`mint` to group by. `getPrivateBalance` asks the relayer which nullifiers are
+spent, then sums what is left; `unspent` and `spent` hand back your own note
+objects, so you can render from them directly.
 
-ISC
+`checkNullifiersSpent(nullifiers)` is the same question on its own. It
+deduplicates, splits into the server's 200-per-request batches, issues them
+concurrently, and returns a `Set` for membership testing. It also lower-cases
+input: the endpoint validates case-insensitively but answers in lower case, so
+upper-case hex would otherwise never match and every note would read as unspent.
 
-This package provides a complete UTXO-based privacy protocol implementation on Solana with:
+To compute a balance without the relayer — from a chain scan of nullifier
+events, or a local cache — supply the answer yourself:
 
-- **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
+```ts
+await getPrivateBalance(myNotes, { resolveSpent: async (ns) => mySpentSet(ns) });
 ```
 
----
-
-## 2. Prerequisites
+Amounts stay `bigint` end to end. A `number` amount above `Number.MAX_SAFE_INTEGER`
+is rejected rather than silently rounded, and a malformed nullifier throws
+instead of counting as unspent — either would overstate a balance.
 
-You need:
+### Choosing notes to spend
 
-- A running Solana validator (localnet/devnet/mainnet):
+Two rules govern this, and both are easy to get wrong:
 
-  ```bash
-  solana-test-validator
-  ```
+- the transaction circuit is **2-in-2-out**, so one transaction spends at most
+  two notes;
+- notes are only co-spendable inside the **same Merkle tree**, and the tree is
+  derived from the mint.
 
-- The `privacy-pool` program deployed to the network
-- The `privacy-pool` Anchor IDL available:
-
-  ```text
-  idl/idl/privacy_pool.json
-  ```
-
-- A funded keypair:
-
-  ```bash
-  solana config set --url http://127.0.0.1:8899
-  solana-keygen new --outfile ~/.config/solana/id.json
-  solana airdrop 10
-  ```
-
-Environment variables:
+```ts
+import { selectNotesForAmount, canonicalTreeId } from "@veilo/sdk-core";
 
-```bash
-export ANCHOR_PROVIDER_URL=http://127.0.0.1:8899
-export ANCHOR_WALLET=$HOME/.config/solana/id.json
+const selection = selectNotesForAmount(unspentNotes, amountRaw, { mint });
+if (!selection.ok) throw new Error(selection.message); // NO_NOTES | INSUFFICIENT_FUNDS
+if (selection.requiresMerge) {
+  // more than two inputs — combine them before proving
+}
 ```
 
----
+It searches each tree independently and returns the best result: the smallest
+single note that covers the amount, else the pair with the least change (found
+by a two-pointer scan, not an all-pairs search), else the largest notes greedily
+with `requiresMerge` set. A failure reports `available`, the largest total
+reachable within one tree.
 
-## 3. Build
+`canonicalTreeId(mint)` derives a note's tree the way the relayer does. **Derive
+it; never trust a stored `treeId`.** Change notes are written with the on-chain
+shard index while deposits and synced notes carry the mint-derived id — for
+native SOL both are 0 so the difference hides, but for SPL tokens they diverge
+and co-spending across the two fails at proof time as a commitment mismatch.
 
-```bash
-npm run build
-```
+### Private product keys and recovery
 
----
-
-## 4. SDK API
-
-### 4.1 PDA Helpers
+Private positions, perps, and predictions use deterministic client-held keys.
+The SDK provides the exact derivations used by Veilo's wallet, extension,
+relayer, and program tests. Keep the spending key and claimant secret on the
+user's device; send claimant secrets only inside the SDK's encrypted relayer
+requests.
 
 ```ts
 import {
-  getPoolPdas,
-  getNoteTreePda,
-  getGlobalConfigPda,
-  getNullifierMarkerPda,
+  derivePositionKeyBundle,
+  deriveSpendingKeyWithSigner,
+  encodeClaimantSecretKey,
+  initPoseidon,
+  submitOpenPosition,
 } from "@veilo/sdk-core";
-import { PublicKey } from "@solana/web3.js";
 
-const programId = new PublicKey(
-  "YourProgram1111111111111111111111111111111111",
+await initPoseidon();
+const spendingKey = await deriveSpendingKeyWithSigner(
+  (message) => wallet.signMessage(message),
 );
-const mintAddress = new PublicKey(
-  "So11111111111111111111111111111111111111112",
-); // Native SOL
-
-// Get pool PDAs
-const { config, vault, nullifiers } = getPoolPdas(programId, mintAddress);
-
-// Get note tree PDA for tree ID 0
-const noteTree = getNoteTreePda(programId, mintAddress, 0);
+const positionKeys = derivePositionKeyBundle(spendingKey, nextPositionIndex);
 
-// Get global config
-const globalConfig = getGlobalConfigPda(programId);
+await submitOpenPosition({
+  // Select private source notes in your wallet before calling the relayer.
+  notes,
+  sourceMintAddress,
+  destMintAddress,
+  swapAmountRaw,
+  slippageBps: 50,
+  userPublicKey: wallet.publicKey.toBase58(),
+  veiloPublicKey,
+  position: positionKeys.position,
+});
 
-// Get nullifier marker PDA
-const nullifier = new Uint8Array(32);
-const marker = getNullifierMarkerPda(programId, mintAddress, 0, nullifier);
+// Persist the returned position data and `nextPositionIndex`. Re-derive the
+// same claimant later when closing or merging the position.
+const claimantSecretKey = encodeClaimantSecretKey(positionKeys.claimant);
 ```
 
-**PDA seeds (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"]`
-
----
+Use `deriveJperpKeyBundle()` and `getJperpMarketPayload()` for private perps.
+Use `derivePredictionKeyBundle()` for private predictions. Lower-level key
+derivations are also exported when an application needs them individually. The
+PDA helpers in each focused entry point support on-chain recovery scans on a
+fresh device.
 
-### 4.2 Pool Initialization
+Predictions have one additional step: Jupiter returns an unsigned order,
+close, or claim transaction. The SDK exposes that API without taking custody
+of signing:
 
 ```ts
-import * as anchor from "@coral-xyz/anchor";
 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,
-});
+  JupiterPredictionClient,
+  deserializePredictionTransaction,
+} from "@veilo/sdk-core/predictions";
 
-// 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
+const predictions = new JupiterPredictionClient({ apiKey: jupiterApiKey });
+const order = await predictions.placeOrder({
+  ownerPubkey: ephemeral.publicKey.toBase58(),
+  marketId,
+  isYes: true,
+  isBuy: true,
+  depositAmount: "5000000",
+  depositMint: usdcMint,
 });
-
-// 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);
+const transaction = deserializePredictionTransaction(order);
+// Ask the deterministic ephemeral wallet to sign, then submit and confirm it.
 ```
 
----
+The SDK deliberately does not own application storage or choose which notes to
+spend. Persist indexes and returned product records only after the corresponding
+transaction is confirmed.
 
-### 4.3 UTXO Management
+### Use the direct helpers
 
-The SDK uses a UTXO (Unspent Transaction Output) model with Poseidon commitments:
+Direct helpers are intended for applications that already maintain Veilo note
+and Merkle tree state and can generate proofs.
 
 ```ts
 import {
-  generateKeypair,
-  keypairFromPrivateKey,
-  createUTXO,
-  createOwnedUTXO,
-  createOwnedZeroUTXO,
-  deriveNullifier,
-  type Keypair,
-  type UTXO,
-  type SerializedUTXO,
-  type InputUTXO,
+  NATIVE_SOL_MINT,
+  createTransactionProver,
+  createVeiloProgram,
+  deposit,
 } 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);
+const program = createVeiloProgram(connection, anchorWallet);
+const proofBuilder = createTransactionProver({
+  wasmPath: "/circuits/transaction.wasm",
+  zkeyPath: "/circuits/transaction_final.zkey",
+});
 
-// Create an owned UTXO (includes private key)
-const ownedUtxo: SerializedUTXO = createOwnedUTXO({
-  amount: 1_000_000_000n,
-  privateKey: keypair.privateKey,
+const built = await deposit({
+  program,
+  depositor: { publicKey: wallet.publicKey },
   mintAddress: NATIVE_SOL_MINT,
+  amount: 1_000_000_000n,
+  recipientPubkey: veiloOwnerPublicKey,
+  noteRecipientWallet: wallet.publicKey,
+  tree,
+  proofBuilder,
+  treeId: 0,
 });
 
-// Create a zero UTXO (for unused inputs/outputs)
-const zeroUtxo = createOwnedZeroUTXO(pubkeyToField(NATIVE_SOL_MINT), keypair);
-
-// Derive nullifier for spending
-const nullifier = deriveNullifier(
-  ownedUtxo.privateKey,
-  ownedUtxo.commitment,
-  0, // pathIndex in Merkle tree
-  0, // treeId
-);
-```
-
-**UTXO commitment formula:**
-
-```
-commitment = Poseidon(amount, pubkey, blinding, mintAddress)
-```
-
-**Nullifier formula:**
+const signed = await wallet.signTransaction(built.transaction);
+const signature = await connection.sendRawTransaction(signed.serialize());
+await connection.confirmTransaction(signature, "confirmed");
 
+// Update the local tree only after on-chain confirmation.
+const receipt = built.commit();
 ```
-nullifier = Poseidon(privateKey, commitment, pathIndex, treeId)
-```
-
----
 
-### 4.4 Merkle Tree Operations
+`withdraw()` and `privateTransfer()` accept two spendable input notes, build the
+proof, submit through the supplied relayer signer, and return the resulting
+change or output notes. Important rules are enforced by the SDK:
 
-```ts
-import { MerkleTree } from "@veilo/sdk-core";
+- withdrawal amounts must be positive and fit within the selected notes;
+- private-transfer outputs must equal the total input amount;
+- direct private transfers use a zero public fee;
+- note-recipient wallet keys should be supplied so new notes remain recoverable.
 
-// 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);
-
-// Get current root
-const root = tree.root();
-
-// Get Merkle path for proof generation
-const path = tree.path(index1);
-// path = { pathElements: Uint8Array[], pathIndices: number[] }
-
-// Get number of leaves
-const numLeaves = tree.totalLeaves;
-
-// Custom tree depth
-const deepTree = new MerkleTree(25); // 25 levels
-```
+Private swaps normally use Jupiter versioned transactions and address lookup
+tables. Use `buildPrivateSwapInstructions()` to add Veilo's atomic instructions
+to the exact Jupiter route. Preserve Jupiter's account order and duplicate
+accounts. `transactSwap()` is available when a legacy transaction is sufficient.
 
-The Merkle tree uses Poseidon hash for all internal nodes.
+The low-level `transact()` and `buildRawTransactInstruction()` exports are for
+custom transaction composition. Most applications should use the helpers above.
 
----
+## Important concepts
 
-### 4.5 Transaction Operations
+### Amounts use base units
 
-The SDK supports three types of transactions:
-
-#### Deposits (publicAmount > 0)
+Amounts are `bigint` values or decimal strings in the token's smallest unit:
 
 ```ts
-import { deposit } from "@veilo/sdk-core";
-
-// 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 deposit({
-  program,
-  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,
-});
+import { sol } from "@veilo/sdk-core/config";
 
-// Insert outputs into tree
-tree.insert(outputUtxo.commitment);
-tree.insert(output2.commitment);
+const oneSol = sol(1);       // 1_000_000_000n lamports
+const fiveUsdc = 5_000_000n; // 5 USDC for a 6-decimal mint
 ```
 
-#### Withdrawals (publicAmount < 0)
+Avoid JavaScript floating-point values for token arithmetic.
 
-```ts
-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,
-);
+### A private note is valuable secret data
 
-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,
-});
-```
+A note contains the information needed to locate and spend private funds. Store
+it encrypted, never log it, and never send its unencrypted contents to an
+analytics or application server.
 
-#### Private Transfers (publicAmount = 0)
+For shielding, prefer `resolveShieldOwner()`. It obtains the spending and note
+viewing keys as a matched pair. Supplying unrelated keys can create a note that
+the recipient cannot discover.
 
-```ts
-import {
-  privateTransfer,
-  generateKeypair,
-  createOwnedUTXO,
-} from "@veilo/sdk-core";
+### Confirmation comes before local state updates
 
-// Create new outputs for recipient
-const recipientKeypair = generateKeypair();
-const output1 = createOwnedUTXO({
-  amount: 1_000_000_000n,
-  privateKey: recipientKeypair.privateKey,
-  mintAddress: NATIVE_SOL_MINT,
-});
+Do not mark notes as spent, insert commitments into a local tree, or persist a
+predicted leaf index until the transaction is confirmed. Use `finalizeShield()`
+for shields and call a deposit's `commit()` callback only after confirmation.
 
-await privateTransfer({
-  program,
-  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,
-});
+### Proof files are separate
 
-// Insert new outputs
-tree.insert(output1.commitment);
-tree.insert(output2.commitment);
-```
+Circuit `.wasm` and `.zkey` files are intentionally not bundled with the npm
+package because they are large — `files` ships `dist/` only. Provide local
+paths, byte arrays, or hosted URLs to `createTransactionProver()` and
+`createSwapProver()`.
 
-#### Low-Level Transaction Function
+Both arguments are optional. Omit them and the prover resolves artifacts from
+disk on first use, first hit wins:
 
-For advanced use cases, use the unified `transact` function directly:
+1. `$VEILO_CIRCUITS_DIR`
+2. `<package>/circuits` — populated by `npm run copy:circuits`
+3. `<cwd>/circuits`
+4. `<cwd>/node_modules/@veilo/sdk-core/circuits`
 
 ```ts
-import { transact } from "@veilo/sdk-core";
-
-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,
-    claimant: claimantPubkey,
-  },
-  proof,
-});
+const prover = createTransactionProver();            // resolved from disk
+const prover = createTransactionProver({ wasmPath, zkeyPath }); // explicit
 ```
 
----
+`resolveCircuitArtifacts("transaction" | "swap")` performs that lookup on its
+own if you want the paths. Resolution is **Node-only and lazy** — it imports
+`node:fs` inside the call so browser bundles can still import this module, and
+there is nothing to resolve in a browser anyway. Browser builds must pass
+`CircuitArtifacts` explicitly. A miss throws with every path it tried.
 
-### 4.6 Proof Generation
+## Error handling
 
-The SDK provides utilities for preparing circuit inputs:
+Shield and Cloak errors include stable fields that applications can use to show
+useful recovery actions.
 
 ```ts
 import {
-  prepareTransactionInputs,
-  formatInputsForSnarkjs,
-  computeExtDataHash,
-  encodeSnarkjsProofToTransactionProof,
-  packProofToBytes,
-  type ExtData,
-  type TransactionCircuitInputs,
+  CloakApiError,
+  mapShieldError,
 } 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,
-    claimant: claimantPubkey,
-  },
-  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);
-
-// Use with snarkjs to generate proof
-// const { proof, publicSignals } = await snarkjs.groth16.fullProve(
-//   snarkjsInputs,
-//   wasmPath,
-//   zkeyPath
-// );
-
-// Convert snarkjs proof to on-chain format
-// const transactionProof = encodeSnarkjsProofToTransactionProof(proof);
+try {
+  // Build or submit a Veilo operation.
+} catch (error) {
+  if (error instanceof CloakApiError) {
+    console.error(error.code, error.status, error.message);
+  } else {
+    const shieldError = mapShieldError(error);
+    console.error(shieldError.code, shieldError.message);
+    // retryable is `rebuild`, `reshield`, or `none`.
+    console.log(shieldError.retryable);
+  }
+}
 ```
 
----
+When handling Cloak separately, `CloakApiError` also exposes actionable values
+such as `min`, `max`, `field`, `maxBps`, and `retryAfter` when the API returns
+them.
 
-### 4.7 Relayer Management
+## Package entry points
 
-```ts
-import { addRelayer, setPaused } from "@veilo/sdk-core";
-
-// Add a relayer
-await addRelayer({
-  program,
-  admin: adminKeypair,
-  mintAddress: NATIVE_SOL_MINT,
-  newRelayer: relayerPubkey,
-});
-
-// Pause/unpause the pool
-await setPaused({
-  program,
-  admin: adminKeypair,
-  mintAddress: NATIVE_SOL_MINT,
-  paused: true,
-});
-```
-
----
-
-### 4.8 Poseidon Utilities
+Import from the package root for convenience or use a focused entry point:
 
 ```ts
-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);
+import { shield } from "@veilo/sdk-core";
+import { getPoolPdas } from "@veilo/sdk-core/accounts";
+import { createUTXO } from "@veilo/sdk-core/notes";
+import { deposit, withdraw } from "@veilo/sdk-core/transactions";
+import { submitWithdraw } from "@veilo/sdk-core/relayer";
+import { VeiloCloakClient } from "@veilo/sdk-core/cloak";
+import { derivePositionKeyBundle } from "@veilo/sdk-core/positions";
+import { getJperpMarketPayload } from "@veilo/sdk-core/perps";
+import { JupiterPredictionClient } from "@veilo/sdk-core/predictions";
 ```
 
----
-
-## 5. Architecture
-
-### Transaction Model
-
-Veilo uses a UTXO-based privacy model inspired by Zcash and Tornado Cash Nova:
+Available focused entry points:
 
-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)
+- `@veilo/sdk-core/accounts`
+- `@veilo/sdk-core/cloak`
+- `@veilo/sdk-core/config`
+- `@veilo/sdk-core/idl`
+- `@veilo/sdk-core/identity`
+- `@veilo/sdk-core/notes`
+- `@veilo/sdk-core/perps`
+- `@veilo/sdk-core/positions`
+- `@veilo/sdk-core/predictions`
+- `@veilo/sdk-core/poseidon`
+- `@veilo/sdk-core/proof`
+- `@veilo/sdk-core/prover`
+- `@veilo/sdk-core/relayer`
+- `@veilo/sdk-core/shield`
+- `@veilo/sdk-core/transactions`
 
-Each transaction:
+## Advanced building blocks
 
-- 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
+The root package also exports tools for teams building their own Veilo wallet
+or relayer:
 
-### Privacy Guarantees
+- account and PDA queries;
+- UTXO creation, ownership, encryption, and recovery;
+- Merkle tree reconstruction from on-chain events;
+- transaction and swap witness preparation;
+- Poseidon hashing helpers;
+- pool initialization and administration;
+- raw IDL-correct transaction instruction builders.
 
-- **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
+These APIs are fully typed. Use their TypeScript definitions as the source of
+truth for required inputs.
 
-### Multi-Tree Support
+### Historical IDLs and commitment recovery
 
-The protocol supports multiple concurrent Merkle trees per pool:
-
-- Improves scalability by reducing tree depth
-- Allows parallel insertions
-- Each tree has independent state
-
-### Constants
+The SDK includes the current, legacy, and legacy-2 privacy-pool IDLs used by the
+relayer. Event scans automatically try the historical layouts, so applications
+can rebuild trees across program upgrades.
 
 ```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:
-
-```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,
+  PRIVACY_POOL_IDLS,
+  buildTreeFromEvents,
+  resolveCommitmentEvents,
 } from "@veilo/sdk-core";
 ```
 
-### SPL Token Support
-
-The SDK supports both native SOL and SPL tokens:
-
-```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
-});
-```
-
-When using SPL tokens, the SDK automatically handles associated token accounts.
+`buildTreeFromEvents()` includes Veilo's protected historical repairs by
+default and rejects gaps that would produce an incorrect root. When a confirmed
+instruction appended commitments without emitting `CommitmentEvent`, use
+`resolveCommitmentEvents()` with the expected commitments and current local
+tree. It prefers emitted metadata and computes only the missing entries.
 
----
+For the deployed eventless `open_position` path, use
+`recoverEventlessOpenPositionEvents()`. It decodes both commitments from the
+instruction and reads the authoritative global position-tree leaf index from
+the program-owned PositionPDA. `buildGlobalPositionTreeFromEvents()` mirrors
+the relayer's all-mint position-tree reconstruction.
 
-## 6. Development
-
-### Environment Variables
+## Development
 
 ```bash
-export ANCHOR_PROVIDER_URL=http://127.0.0.1:8899
-export ANCHOR_WALLET=$HOME/.config/solana/id.json
-```
-
----
+# Build CommonJS, ESM, and declaration outputs
+npm run build
 
-## 7. Limitations
+# Run deterministic unit and proof tests
+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
+# Run opt-in live Devnet integration tests
+npm run test:integration
 
----
+# Check module boundaries for dependency cycles
+npm run check:cycles
+```
 
-## 8. Resources
+## Support
 
-- **Repository**: https://github.com/VeiloSolana/veilo-sdk
-- **Circomlibjs**: https://github.com/iden3/circomlibjs
-- **Poseidon Hash**: https://www.poseidon-hash.info/
+- [Repository](https://github.com/VeiloSolana/veilo-sdk)
+- [Issue tracker](https://github.com/VeiloSolana/veilo-sdk/issues)
 
----
+When reporting a problem, include the SDK version, runtime, Solana cluster, and
+the error's `code` and `status` or `programCode` where available. Never include
+private notes, wallet secret keys, API keys, or authentication tokens.
 
 ## License
 
-ISC
+[ISC](./LICENSE)