@cloak.dev/sdk 0.1.7 → 0.2.0

package/README.md

@@ -1,53 +1,81 @@
 # @cloak.dev/sdk
 
-TypeScript SDK for the Cloak Protocol - Private transactions on Solana using zero-knowledge proofs.
+TypeScript SDK for Cloak: shielded transactions on Solana. Shield SOL, USDC or USDT into a
+per-mint pool, send privately inside the pool, withdraw to any address, or swap shielded SOL to
+USDC/USDT with the output landing in a public token account. Groth16 proofs are generated
+client-side (snarkjs) and verified on-chain by the Cloak program.
 
-## Features
-
-- 🔒 **Private Transfers**: Shield, send, and reclaim SOL or SPL tokens via the UTXO model and zero-knowledge proofs
-- 🔁 **Shield-to-shield**: Move funds privately between UTXOs (`transfer`) without ever de-shielding
-- 💱 **Token Swaps**: Swap shielded SOL for SPL tokens via Jupiter (`swapUtxo`) — SOL → USDC, BRZ, etc.
-- 🔐 **Type-Safe**: Full TypeScript types; the `getConfig()` snapshot is structurally narrower than the constructor input so secrets cannot be re-exposed by accident
-- 🌐 **Cross-Platform**: Browser (wallet adapter) and Node.js (`Keypair`) modes
-- ⚡ **Functional API**: `transact` / `transfer` / `partialWithdraw` / `fullWithdraw` / `swapUtxo` — pass connection + program + relay + signer per call
+Version 0.2.0 targets the mainnet program deployed on 2026-08-24 and the ceremony-frozen
+`cloak-transaction-0.2.0` circuit bundle. See [Version and compatibility](#version-and-compatibility).
 
 ## Installation
 
 ```bash
 npm install @cloak.dev/sdk @solana/web3.js
-# or
-yarn add @cloak.dev/sdk @solana/web3.js
-# or
-pnpm add @cloak.dev/sdk @solana/web3.js
+# swaps and SPL pools also need:
+npm install @solana/spl-token
 ```
 
-**Note**: For swap functionality, you'll also need `@solana/spl-token`:
-```bash
-npm install @solana/spl-token
+Node >= 18. Ships ESM and CJS builds with type declarations. Runs in Node and in the browser
+(wallet-adapter signing); the on-chain Merkle-tree rebuild fallback is not available in browsers.
+
+## Networks
+
+### Mainnet (defaults)
+
+| Setting | Value |
+| --- | --- |
+| Program | `zh1eLd6rSphLejbFfJEneUwzHRfMKxgzrgkfwA6qRkW` (`CLOAK_PROGRAM_ID`) |
+| Relay | `https://api.cloak.ag`, passed as `relayUrl` or via `CLOAK_RELAY_URL` (see below) |
+| Circuits | `https://storage.googleapis.com/cloak-circuits/circuits/0.2.0` (the SDK default) |
+| Pools | WSOL (`NATIVE_SOL_MINT`), USDC `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`, USDT `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB` |
+| RPC | any mainnet RPC; use `new Connection(url, "confirmed")` |
+
+The relay URL is never defaulted. `transact` resolves it from the `relayUrl` option, then from
+`CLOAK_RELAY_URL`, and with neither set it throws before anything is signed or sent. This is
+deliberate: a script that forgets the option must not ship its proof to production. Name production
+explicitly:
+
+```ts
+relayUrl: "https://api.cloak.ag"
 ```
 
-## Quick Start
+Every flow needs it, deposits included: the SDK registers the wallet's viewing key through the relay
+before its first transaction (see [Recovery and discovery](#recovery-and-discovery-viewing-key)),
+deposits fetch the signed risk quote the program requires from `<relayUrl>/range-quote`, and sends,
+withdrawals and swaps are submitted through it. `enforceViewingKeyRegistration: false` skips only the
+registration step (the shipped examples set it on a local fork); it is not a no-relay mode.
+
+Do not expose `programId`, the relay URL or the circuits base as end-user input. Wallet adapters are
+the in-app signer; keypair files belong to scripts only.
+
+### Devnet and local
+
+The same SDK runs against a devnet or local deployment by pointing the three coordinates at it:
 
-### SDK Defaults (Recommended)
+```bash
+SOLANA_RPC_URL=https://api.devnet.solana.com   # or http://127.0.0.1:8899 for a local fork
+CLOAK_RELAY_URL=<relay serving that deployment>
+CLOAK_PROGRAM_ID=<program id of that deployment>   # examples read this; pass it as programId in your code
+```
 
-- Standard integrations should use SDK defaults for program, relay, and circuits.
-- Do not expose protocol-level config (`programId`, relay URL, circuits URL) as end-user input.
-- `transact`, `partialWithdraw`, and `fullWithdraw` already include stale-root retry handling.
-- For simple CLI sends, require only `SOLANA_RPC_URL` and `KEYPAIR_PATH`.
+The shipped examples default to a local fork (`http://127.0.0.1:8899`) with a local relay
+(`http://127.0.0.1:5500`); see [Examples](#examples).
 
-### Minimal Private SOL Send (Single File, Keypair)
+## Quick start: private SOL send (single file, keypair)
 
-Use this contract for one-shot scripts and AI-generated snippets.
+Shield from the signer, then unshield to the recipient. Use this shape for one-shot scripts.
 
 ```ts
 import { readFileSync } from "fs";
 import {
   CLOAK_PROGRAM_ID,
   NATIVE_SOL_MINT,
-  createUtxo,
+  createRecoverableDepositUtxo,
   createZeroUtxo,
   fullWithdraw,
   generateUtxoKeypair,
+  getNkFromUtxoPrivateKey,
   transact,
 } from "@cloak.dev/sdk";
 import { Connection, Keypair, PublicKey } from "@solana/web3.js";
@@ -59,45 +87,54 @@ async function main() {
   }
 
   const rpcUrl = process.env.SOLANA_RPC_URL;
+  const relayUrl = process.env.CLOAK_RELAY_URL;
   const keypairPath = process.env.KEYPAIR_PATH;
-  if (!rpcUrl || !keypairPath) {
-    throw new Error("Set SOLANA_RPC_URL and KEYPAIR_PATH");
+  if (!rpcUrl || !relayUrl || !keypairPath) {
+    throw new Error("Set SOLANA_RPC_URL, CLOAK_RELAY_URL and KEYPAIR_PATH");
   }
 
   const connection = new Connection(rpcUrl, "confirmed");
   const signer = Keypair.fromSecretKey(
     Uint8Array.from(JSON.parse(readFileSync(keypairPath, "utf8"))),
   );
-
   const recipient = new PublicKey(recipientArg);
-  const amountLamports = BigInt(lamportsArg);
+  const amount = BigInt(lamportsArg);
 
+  // The wallet's viewing base (nk). A real wallet derives it from its seed; a throwaway
+  // keypair keeps this script self-contained.
   const owner = await generateUtxoKeypair();
-  const output = await createUtxo(amountLamports, owner, NATIVE_SOL_MINT);
+  const nk = getNkFromUtxoPrivateKey(owner.privateKey);
 
+  // Shield. The note's keypair and blinding are derived from (nk, noteSalt) and the salt is
+  // published inside the nk-encrypted chain note, so a scan holding only nk can rebuild it.
+  const { utxo, noteSalt } = await createRecoverableDepositUtxo(amount, nk, NATIVE_SOL_MINT);
   const deposited = await transact(
     {
       inputUtxos: [await createZeroUtxo(NATIVE_SOL_MINT)],
-      outputUtxos: [output],
-      externalAmount: amountLamports,
+      outputUtxos: [utxo],
+      externalAmount: amount,
       depositor: signer.publicKey,
     },
     {
       connection,
       programId: CLOAK_PROGRAM_ID,
+      relayUrl,
       depositorKeypair: signer,
-      walletPublicKey: signer.publicKey,
-      enforceViewingKeyRegistration: false,
+      chainNoteViewingKeyNk: nk,
+      chainNoteSalt: noteSalt,
     },
   );
 
-  const withdrawn = await fullWithdraw(deposited.outputUtxos, recipient, {
+  // Unshield to the recipient. outputUtxos[0] is the deposited note ([1] is the zero pad).
+  // The program takes its fee here (0.005 SOL + 0.3%).
+  const withdrawn = await fullWithdraw([deposited.outputUtxos[0]], recipient, {
     connection,
     programId: CLOAK_PROGRAM_ID,
+    relayUrl,
     depositorKeypair: signer,
     walletPublicKey: signer.publicKey,
+    chainNoteViewingKeyNk: nk,
     cachedMerkleTree: deposited.merkleTree,
-    enforceViewingKeyRegistration: false,
   });
 
   console.log(withdrawn.signature);
@@ -112,327 +149,433 @@ main().catch((e) => {
 Run:
 
 ```bash
-SOLANA_RPC_URL="https://api.mainnet-beta.solana.com" \
+SOLANA_RPC_URL="https://<your mainnet rpc>" \
+CLOAK_RELAY_URL="https://api.cloak.ag" \
 KEYPAIR_PATH="/absolute/path/to/id.json" \
 npx tsx send-sol-private.ts <recipientPubkey> <lamports>
 ```
 
-Hard rules for minimal scripts:
+Rules for minimal scripts:
 
-- Use lamports from CLI (`<lamports>`) and keep transaction math in `bigint`.
-- Use `KEYPAIR_PATH`; do not ask for raw private key env vars.
-- Do not parse SOL decimals with float math (`parseFloat`, `AMOUNT_SOL`).
-- Keep `programId` fixed to `CLOAK_PROGRAM_ID` (no end-user override).
+- Take lamports from the CLI and keep all amount math in `bigint`; never parse SOL with float math.
+- `<lamports>` must be at least `MIN_DEPOSIT_LAMPORTS` (0.01 SOL) and the withdrawal must exceed
+  its fee (see [Fees and limits](#fees-and-limits)).
+- Use `KEYPAIR_PATH`; do not read raw private keys from the environment.
+- Keep `programId` fixed to `CLOAK_PROGRAM_ID`.
+- `transact`, `partialWithdraw` and `fullWithdraw` already retry on a stale Merkle root; do not
+  wrap them in your own retry loop.
 
-### Maintained Examples
+### Browser (wallet adapter)
 
-```bash
-npm run example:fast-send
-npm run example:fast-usdc-send
-npm run example:usdc-pool-transfer
-npm run example:swap
-npm run example:swap-recovery
-npm run example:swap-usdc
-npm run example:swap-brz
-npm run example:transfer
-npm run test:examples
+Replace `depositorKeypair` with the adapter's signers:
+
+```ts
+await transact(params, {
+  connection,
+  programId: CLOAK_PROGRAM_ID,
+  relayUrl,
+  signTransaction: (tx) => wallet.signTransaction(tx),
+  signMessage: (message) => wallet.signMessage(message), // signs the viewing-key registration challenge
+  depositorPublicKey: wallet.publicKey,
+  walletPublicKey: wallet.publicKey,
+  chainNoteViewingKeyNk: nk,
+  chainNoteSalt: noteSalt,
+});
 ```
 
-`example:transfer` runs deposit -> shield-to-shield transfer (`public_amount=0`) -> recipient withdraw verification and prints stable `FULL_SIG|transfer|deposit|...`, `FULL_SIG|transfer|tx|...`, and `COMMITMENT_INDICES|transfer|[...]` markers.
+`signTransaction` must accept both a legacy `Transaction` and a `VersionedTransaction` (v0 with
+address lookup tables); deposits use either depending on the path taken. `signMessage` is required
+unless `enforceViewingKeyRegistration: false` is set; without it the call fails with
+"Viewing key registration is mandatory: signMessage (wallet) or depositorKeypair is required."
 
-`example:fast-usdc-send` is the one-shot private send path for USDC recipients (deposit SOL, swap privately to USDC, deliver to recipient ATA).
+## The UTXO model
 
-`example:usdc-pool-transfer` is the mint-scoped USDC pool transfer path (User A deposits USDC into Cloak USDC pool, sends shielded USDC to User B, and User B spends the received shielded note).
+- A shielded balance is a set of notes (`Utxo`): `{ amount, keypair, blinding, mintAddress, index?, commitment? }`.
+  Amounts are `bigint` in base units (lamports, or 10^-6 for USDC/USDT).
+- Every transaction is 2-in / 2-out. Pad unused slots with `createZeroUtxo(mint)`.
+- `externalAmount > 0` is a deposit (funds enter from `depositor`), `< 0` is a withdrawal to
+  `recipient`, `0` is a private send inside the pool.
+- Pools are per mint. All inputs and outputs of one transaction live in the same pool;
+  `NATIVE_SOL_MINT` is the SOL pool.
+- `TransactResult.outputUtxos` are the notes you can spend next (leaf `index` set). Persist them
+  with `serializeUtxo` / `deserializeUtxo`. Pass `result.merkleTree` as `cachedMerkleTree` to the
+  next call to skip re-fetching commitments.
+- The Merkle tree is read at `confirmed`, so a note is spendable as soon as its deposit is confirmed.
 
-`example:swap-usdc` is the canonical Nora swap evidence path (SOL -> USDC) and prints quote/route details, `FULL_SIG|swap-usdc|transact_swap|...`, `FULL_SIG|swap-usdc|swap_completed|...`, and `RECIPIENT_USDC_BALANCE|...` markers.
+Entry points: `transact` (general), `transfer`, `partialWithdraw`, `fullWithdraw`,
+`swapUtxo` / `swapWithChange`.
 
-`example:swap-recovery` focuses on pending/timeout behavior. It submits a swap, tracks `swap_phase` + `slots_remaining` from relay `/status`, and can optionally call `close_timed_out` (`AUTO_CLOSE_TIMED_OUT=1`) once `can_recover=true`.
+### Private send (shield-to-shield)
 
-`example:swap-brz` first attempts BRZ (`FtgGSFADXBtroxq8VCausXRr2of47QBf5AS1NtZCu4GD`) and automatically falls back to USDC if BRZ routing is unavailable. It always emits `QUOTE_ROUTE|...`, `SWAP_OUTPUT_MINT|...`, and (when fallback happens) `BRZ_FALLBACK_TO|...`.
+```ts
+import { deriveViewingKeyFromNk, transfer } from "@cloak.dev/sdk";
 
-`test:examples` runs all maintained examples in `CLOAK_EXAMPLE_DRY_RUN=1` mode so CI/local checks validate script wiring without requiring funded wallets or live RPC execution.
+const result = await transfer(
+  [myNote],                 // inputs to spend (same pool)
+  recipientUtxoPublicKey,   // bigint: the recipient's UTXO public key
+  amount,
+  {
+    connection,
+    programId: CLOAK_PROGRAM_ID,
+    relayUrl,
+    depositorKeypair: signer,
+    walletPublicKey: signer.publicKey,
+    chainNoteViewingKeyNk: myNk,
+    // The recipient's X25519 viewing public key. With it the recipient can discover the note
+    // from chain with their own key (scanRecipientDeliveryNotes). Without it the note is still
+    // valid but must be handed over out of band.
+    recipientViewingPublicKey: deriveViewingKeyFromNk(recipientNk).publicKey,
+    cachedMerkleTree: previous.merkleTree,
+  },
+);
+```
 
-### Node.js (with Keypair)
+`transfer` builds the recipient note as output 0 and returns the change (owned by the input's
+keypair) as output 1. Calling `transact` directly with `externalAmount: 0n` does the same; keep the
+recipient note at `outputUtxos[0]`, which is the one the delivery carrier is built for.
+The recipient shares two values with the sender: their UTXO public key (`UtxoKeypair.publicKey`)
+and their viewing public key (`deriveViewingKeyFromNk(nk).publicKey`).
 
-```typescript
-import {
-  CLOAK_PROGRAM_ID,
-  NATIVE_SOL_MINT,
-  createUtxo,
-  createZeroUtxo,
-  fullWithdraw,
-  generateUtxoKeypair,
-  transact,
-} from "@cloak.dev/sdk";
-import { Connection, Keypair, PublicKey } from "@solana/web3.js";
+### Withdraw (unshield)
+
+```ts
+await fullWithdraw([note], recipientWallet, options);            // whole note
+await partialWithdraw([note], recipientWallet, amount, options); // amount out, change stays shielded
+```
 
-const connection = new Connection("https://api.mainnet-beta.solana.com");
-const signer = Keypair.fromSecretKey(/* your secret key */);
+For SPL pools the recipient receives tokens in their associated token account. The program charges
+its fee on the withdrawn amount ([Fees and limits](#fees-and-limits)).
 
-// Generate a UTXO keypair (owner of the shielded balance)
-const owner = await generateUtxoKeypair();
+### SPL pools (USDC, USDT)
 
-// Build a 0.01 SOL output UTXO and shield it
-const amountLamports = 10_000_000n;
-const output = await createUtxo(amountLamports, owner, NATIVE_SOL_MINT);
+Same API with the pool mint on every note:
 
-const deposited = await transact(
-  {
-    inputUtxos: [await createZeroUtxo(NATIVE_SOL_MINT), await createZeroUtxo(NATIVE_SOL_MINT)],
-    outputUtxos: [output, await createZeroUtxo(NATIVE_SOL_MINT)],
-    externalAmount: amountLamports, // positive = deposit
-    depositor: signer.publicKey,
-  },
+```ts
+const usdc = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
+const { utxo, noteSalt } = await createRecoverableDepositUtxo(2_000_000n, nk, usdc); // 2.00 USDC
+await transact(
+  { inputUtxos: [await createZeroUtxo(usdc)], outputUtxos: [utxo], externalAmount: 2_000_000n, depositor: signer.publicKey },
+  { connection, programId: CLOAK_PROGRAM_ID, relayUrl, depositorKeypair: signer, chainNoteViewingKeyNk: nk, chainNoteSalt: noteSalt },
+);
+```
+
+Minimum SPL deposit is 1.00 token. SOL deposits fit in a single v0 packet with the production
+lookup table; SPL deposits currently still create a small supplemental lookup table
+(about 0.0056 SOL rent, reclaimable by the depositor). Details: [docs/DEPOSIT-SIZE-NOTES.md](docs/DEPOSIT-SIZE-NOTES.md).
+
+### Shielded swap (SOL to USDC/USDT)
+
+Spends shielded SOL and delivers the output token to a public associated token account, routed
+through Jupiter. Swap input is SOL only (the pool is wSOL-locked).
+
+```ts
+import { swapWithChange } from "@cloak.dev/sdk";
+import { getAssociatedTokenAddressSync } from "@solana/spl-token";
+
+const recipientAta = getAssociatedTokenAddressSync(usdc, recipientWallet);
+
+const swap = await swapWithChange(
+  [solNote],
+  swapAmount,        // lamports leaving the pool; the program's fee is taken from this
+  usdc,
+  recipientAta,
+  minOutputAmount,   // proof-bound floor; quote the fee-adjusted amount and use the quote's threshold
   {
     connection,
     programId: CLOAK_PROGRAM_ID,
-    relayUrl: "https://api.cloak.ag",
+    relayUrl,
     depositorKeypair: signer,
+    walletPublicKey: signer.publicKey,
+    chainNoteViewingKeyNk: nk,
+    swapSlippageBps: 100,
   },
+  recipientWallet,   // required on mainnet: the wallet the swap's risk quote is issued for
 );
-console.log("Deposit signature:", deposited.signature);
 
-// Reclaim the full balance to a public address
-const recipient = new PublicKey("RECIPIENT_ADDRESS");
-const withdrawn = await fullWithdraw(deposited.outputUtxos, recipient, {
-  connection,
-  programId: CLOAK_PROGRAM_ID,
-  relayUrl: "https://api.cloak.ag",
-  depositorKeypair: signer,
-  cachedMerkleTree: deposited.merkleTree,
-});
-console.log("Withdraw signature:", withdrawn.signature);
+swap.signature;  // the executed swap; swapWithChange resolves only once execution has completed
+swap.refund;     // persist: the refund-fallback secret (see below)
 ```
 
-### React/Next.js (with Wallet Adapter)
+`swapUtxo` is the lower-level form taking `UtxoSwapParams` and an explicit change note. Quote the
+amount after the protocol fee (`swapAmount - calculateFeeBigint(swapAmount)` for SOL) so
+`minOutputAmount` is achievable. `outputMint`, `recipientAta` and `minOutputAmount` are bound into
+the proof and cannot be changed after it is generated.
 
-```typescript
-import {
-  CLOAK_PROGRAM_ID,
-  NATIVE_SOL_MINT,
-  createUtxo,
-  createZeroUtxo,
-  generateUtxoKeypair,
-  transact,
-} from "@cloak.dev/sdk";
-import { useConnection, useWallet } from "@solana/wallet-adapter-react";
-import { useCallback } from "react";
-
-export function DepositButton() {
-  const { connection } = useConnection();
-  const wallet = useWallet();
-
-  const onClick = useCallback(async () => {
-    if (!wallet.publicKey || !wallet.signTransaction) return;
-
-    const owner = await generateUtxoKeypair();
-    const amount = 10_000_000n; // 0.01 SOL — SDK-enforced minimum
-    const output = await createUtxo(amount, owner, NATIVE_SOL_MINT);
-
-    const result = await transact(
-      {
-        inputUtxos: [await createZeroUtxo(NATIVE_SOL_MINT), await createZeroUtxo(NATIVE_SOL_MINT)],
-        outputUtxos: [output, await createZeroUtxo(NATIVE_SOL_MINT)],
-        externalAmount: amount,
-        depositor: wallet.publicKey,
-      },
-      {
-        connection,
-        programId: CLOAK_PROGRAM_ID,
-        relayUrl: "https://api.cloak.ag",
-        wallet: {
-          publicKey: wallet.publicKey,
-          signTransaction: wallet.signTransaction,
-        },
-      },
-    );
-    console.log("Deposited:", result.signature);
-  }, [connection, wallet]);
-
-  return <button onClick={onClick}>Deposit 0.01 SOL</button>;
+#### Timed-out swaps
+
+`swapWithChange` polls the swap status and throws if the swap is refunded, cancelled or fails, or if
+polling runs out (`swapStatusMaxAttempts` x `swapStatusDelayMs`, default 60 x 2 s); the result above
+exists only for a completed swap. On a timeout the program returns the principal, net of the swap
+fee, to the SOL pool as a refund note, which is spent through the normal withdraw path. When the
+swap was submitted with `chainNoteViewingKeyNk` (`swap.refund.derivedFromNk === true`) that note is
+discoverable from the key alone:
+
+```ts
+import { discoverSwapRefunds, fullWithdraw, NATIVE_SOL_MINT, type Utxo } from "@cloak.dev/sdk";
+
+const refunds = await discoverSwapRefunds(connection, CLOAK_PROGRAM_ID, nk); // DiscoveredSwapRefund[]
+for (const refund of refunds) {
+  const note: Utxo = {
+    amount: refund.amount,          // principal net of the swap fee
+    keypair: refund.keypair,
+    blinding: refund.blinding,
+    mintAddress: NATIVE_SOL_MINT,
+    commitment: refund.commitment,
+    index: Number(refund.leafIndex),
+  };
+  await fullWithdraw([note], recipientWallet, options);
 }
 ```
 
-The `CloakSDK` class is kept as a thin config + read-only chain helper
-(`getPublicKey`, `getCurrentRoot`, `getMerkleProof`, `getTransactionStatus`,
-`importWalletKeys`, `exportWalletKeys`, `getConfig`). All transaction-emitting
-calls use the standalone helpers above.
+Swaps that executed leave no refund note, and an empty result only says that none of the scanned
+leaves derive from this `nk`. A swap submitted without `chainNoteViewingKeyNk` has `swap.refund`
+(hex `privateKey`, `publicKey`, `blinding`) as the only copy of its secret; rebuild the note from it
+with the on-chain `SwapState.sol_amount` as the amount and
+`computeSwapRefundCommitment(amount, publicKey, blinding)` as the commitment, then look up the leaf
+index as in [Recovery and discovery](#recovery-and-discovery-viewing-key).
 
-## Core Functions
+## Recovery and discovery (viewing key)
 
-### Deposit (`transact` with positive `externalAmount`)
-
-```typescript
-const result = await transact(
-  {
-    inputUtxos: [await createZeroUtxo(), await createZeroUtxo()],
-    outputUtxos: [outputUtxo, await createZeroUtxo()],
-    externalAmount: 10_000_000n, // positive = deposit
-    depositor: signer.publicKey,
-  },
-  { connection, programId: CLOAK_PROGRAM_ID, relayUrl: "https://api.cloak.ag", depositorKeypair: signer },
-);
-console.log("Leaf index:", result.commitmentIndices[0]);
-console.log("Output UTXO:", result.outputUtxos[0]);
-```
+The viewing base `nk` is derived from the wallet's spend key (`getNkFromUtxoPrivateKey(privateKey)`
+or `expandSpendKey(skSpend).nsk`). It decrypts the chain notes the SDK attaches to transactions and
+opens notes delivered by other people's private sends. Recoverable deposit notes and swap refund
+notes also derive their secrets from it, which is what makes key-only recovery possible, so store
+it with the same care as the spend key.
 
-### Withdraw
+Before a wallet's first transaction the SDK registers `nk` with the relay for compliance scanning:
+it requests a challenge from `<relayUrl>/viewing-key/challenge`, signs it with `signMessage` (wallet)
+or `depositorKeypair`, and posts `nk` with the signature to `<relayUrl>/viewing-key/register`.
+Nothing viewing-key related is written on-chain. The step is on by default;
+`enforceViewingKeyRegistration: false` disables it.
 
-```typescript
-import { fullWithdraw, partialWithdraw } from "@cloak.dev/sdk";
+```ts
+import { scanTransactions, fetchCommitments, type Utxo } from "@cloak.dev/sdk";
 
-// Reclaim everything in one or more input UTXOs to a public address.
-const result = await fullWithdraw(myUtxos, recipientPublicKey, {
+const scan = await scanTransactions({
   connection,
   programId: CLOAK_PROGRAM_ID,
-  relayUrl: "https://api.cloak.ag",
-  depositorKeypair: signer,
+  viewingKeyNk: nk,
+  ownerUtxoPublicKey: owner.publicKey, // authenticates delivered notes' commitments
+  deliveryMints: [NATIVE_SOL_MINT],
+  untilSignature: lastScan?.lastSignature, // incremental scans
 });
 
-// Or withdraw a portion and keep the change shielded.
-const partial = await partialWithdraw(myUtxos, recipientPublicKey, 5_000_000n, {
-  connection,
-  programId: CLOAK_PROGRAM_ID,
-  relayUrl: "https://api.cloak.ag",
-  depositorKeypair: signer,
-});
+scan.recoveredDepositNotes; // own deposits built with createRecoverableDepositUtxo, in spendable form
+scan.deliveredNotes;        // notes sent to this wallet (amount + blinding; the keypair is your own)
+scan.transactions;          // history rows for compliance reporting
 ```
 
-### Shield-to-shield Transfer
+`scanRecipientDeliveryNotes` returns only the delivered notes. Deposit recovery applies to deposits
+built with `createRecoverableDepositUtxo` (the default in the examples); a deposit built with
+`createUtxo` has a random blinding that is written nowhere and appears as history only.
 
-```typescript
-import { transfer } from "@cloak.dev/sdk";
+A recovered or delivered note needs its leaf index before it can be spent. Look it up by commitment.
+The two record types differ: `RecoveredDepositNoteRecord` carries the note's own `keypair`, a
+`bigint` `commitment` and a `PublicKey` `mintAddress`; `DeliveredNote` carries a hex `commitment`,
+a base58 `mint` (set only when the scan was given `ownerUtxoPublicKey`) and no keypair, because the
+keypair is yours.
 
-const result = await transfer(myUtxos, recipientUtxoPublicKey, amountLamports, {
-  connection,
-  programId: CLOAK_PROGRAM_ID,
-  relayUrl: "https://api.cloak.ag",
-  depositorKeypair: signer,
-});
+```ts
+import { PublicKey } from "@solana/web3.js";
+
+const entries = await fetchCommitments(relayUrl, { mint: NATIVE_SOL_MINT });
+const indexOf = (commitment: bigint) =>
+  entries.find((e) => BigInt("0x" + e.commitment.replace(/^0x/, "")) === commitment)?.index;
+
+// Own deposit recovered from nk
+const recovered = scan.recoveredDepositNotes[0];
+const ownNote: Utxo = {
+  amount: recovered.amount,
+  keypair: recovered.keypair,
+  blinding: recovered.blinding,
+  mintAddress: recovered.mintAddress,
+  commitment: recovered.commitment,
+  index: indexOf(recovered.commitment),
+};
+
+// Note delivered by someone else's private send
+const delivered = scan.deliveredNotes[0];
+if (!delivered.commitmentVerified || !delivered.mint) {
+  throw new Error("scan with ownerUtxoPublicKey to authenticate delivered notes");
+}
+const deliveredCommitment = BigInt("0x" + delivered.commitment);
+const deliveredNote: Utxo = {
+  amount: delivered.amount,
+  keypair: owner,                            // the UtxoKeypair whose publicKey the sender used
+  blinding: delivered.blinding,
+  mintAddress: new PublicKey(delivered.mint),
+  commitment: deliveredCommitment,
+  index: indexOf(deliveredCommitment),
+};
 ```
 
-### Swap (SOL → SPL token)
+`discoverSwapRefunds(connection, programId, nk)` returns `DiscoveredSwapRefund` records (`keypair`,
+`blinding`, `amount`, `commitment`, `leafIndex: bigint`); build the `Utxo` from one as shown under
+[Timed-out swaps](#timed-out-swaps).
 
-```typescript
-import { swapUtxo } from "@cloak.dev/sdk";
+`toComplianceReport(scan)` and `formatComplianceCsv(report)` turn a scan into a report.
 
-const result = await swapUtxo(
-  {
-    inputUtxos: myUtxos,
-    swapAmount: 10_000_000n,
-    outputMint: new PublicKey("TOKEN_MINT_ADDRESS"),
-    recipientAta: recipientTokenAccount,
-    minOutputAmount: 1_000_000n,
-  },
-  {
-    connection,
-    programId: CLOAK_PROGRAM_ID,
-    relayUrl: "https://api.cloak.ag",
-    depositorKeypair: signer,
-  },
-);
+## Nullifiers and spent checks
+
+Two exports share a name and are not interchangeable:
+
+- `computeUtxoNullifier(utxo)` is the circuit's scheme: `Poseidon(commitment, index, signature)`.
+  This is the value the program records when a note is spent. Use it for spent checks.
+- `computeNullifier(skSpend, leafIndex)` is `Poseidon(sk0, sk1, leafIndex)` from the legacy
+  `withdraw_regular` circuit. It does not match anything the 0.2.0 program stores.
+
+Prefer the helpers, which use the UTXO scheme:
+
+```ts
+import { verifyUtxos, preflightNullifiers } from "@cloak.dev/sdk";
+
+const { spent } = await verifyUtxos(notes, connection, CLOAK_PROGRAM_ID);
+await preflightNullifiers(notes, connection, CLOAK_PROGRAM_ID); // throws UtxoAlreadySpentError
 ```
 
-## Fee Structure
+`transact` runs the preflight itself before generating a proof.
 
-- **Fixed Fee**: 0.005 SOL (5,000,000 lamports) on withdraw
-- **Variable Fee**: 0.3% of withdrawn amount
+## Fees and limits
 
-Use `getDistributableAmount()` to calculate the amount a recipient receives after fees:
+Fees are collected on-chain by the program from each pool's `PoolConfig` account
+(`["pool_config", mint]`). They apply to withdrawals and swaps, on the amount leaving the pool.
+Deposits and private sends carry no protocol fee.
 
-```typescript
-import { getDistributableAmount } from "@cloak.dev/sdk";
+| Pool | Fixed fee | Rate | Minimum deposit |
+| --- | --- | --- | --- |
+| SOL | 0.005 SOL | 0.3% | 0.01 SOL |
+| USDC | 0.45 USDC | 0.3% | 1.00 USDC |
+| USDT | 0.45 USDT | 0.3% | 1.00 USDT |
 
-const withdrawing = 100_000_000; // 0.1 SOL
-const recipientReceives = getDistributableAmount(withdrawing); // ~94,700,000 lamports
+A withdrawal or swap must exceed its fee or the program rejects it; deposits below the minimum are
+rejected with `DepositTooSmall`.
+
+`utils/fees.ts` mirrors the SOL pool for estimates in the UI:
+
+```ts
+import { calculateFeeBigint, getDistributableAmount, isWithdrawAmountSufficient } from "@cloak.dev/sdk";
+
+calculateFeeBigint(1_000_000_000n);      // 8_000_000n  (0.005 SOL + 0.3% of 1 SOL)
+getDistributableAmount(100_000_000);     // 94_700_000  (0.1 SOL withdrawal, net to recipient)
+isWithdrawAmountSufficient(6_000_000n);  // true: 0.006 SOL covers the 0.005018 SOL fee
 ```
 
-## UTXOs
+For USDC/USDT compute `450_000n + amount * 3n / 1000n`. Treat these as estimates: the deployed
+`PoolConfig` is the source of truth. Solana transaction fees and, for SPL deposits, the supplemental
+lookup-table rent are separate.
 
-A **UTXO** is a cryptographic commitment over `(amount, ownerPubkey, blinding, mintAddress)`. Each `transact` call consumes up to 2 input UTXOs and produces up to 2 outputs:
+## Circuit artifacts
 
-```typescript
-interface Utxo {
-  amount: bigint;            // lamports for SOL, token units for SPL
-  keypair: UtxoKeypair;      // { privateKey, publicKey } — bigints
-  blinding: bigint;          // randomness
-  mintAddress: PublicKey;    // NATIVE_SOL_MINT for SOL
-  index?: number;            // leaf index in the Merkle tree (set after the UTXO is in-tree)
-  commitment?: bigint;
-  nullifier?: bigint;
-}
+Proving uses the `transaction` circuit from bundle `cloak-transaction-0.2.0` (multi-party ceremony,
+6 contributors plus a public final beacon; 42,672 constraints, 9 public inputs). The verifying key is
+embedded in the program.
+
+| Artifact | SHA-256 |
+| --- | --- |
+| `transaction_js/transaction.wasm` | `02ec02e954ae3932827ad9de51afa597ca95569aa97fec8410879c937a58aa2b` |
+| `transaction_final.zkey` | `9da7db8cb1370fc497d36a0365f1f107ab0b0c13ca66fa9f0287e5f96ee68d25` |
+| `transaction.vkey.json` | `deb40e7b94eae17db2975d23dcf26c26db2a36a4f02d14a25830dee3e88fb93c` |
+
+The SDK downloads the artifacts once per process from
+`DEFAULT_TRANSACTION_CIRCUITS_URL` (`https://storage.googleapis.com/cloak-circuits/circuits/0.2.0`),
+hashes them, and refuses to prove if any digest differs from the pinned values. No configuration is
+needed for mainnet.
+
+To serve the artifacts yourself (a mirror or a local directory containing
+`transaction_js/transaction.wasm` and `transaction_final.zkey` with the same digests):
+
+```ts
+import { resolveCircuitsBase, setCircuitsPath } from "@cloak.dev/sdk";
+
+// explicit argument, else CLOAK_CIRCUITS_PATH / CLOAK_CIRCUITS, else the pinned default
+setCircuitsPath(resolveCircuitsBase());
 ```
 
-**⚠️ Important**: persist the spend `privateKey`, `blinding`, `amount`, `index`, and `mintAddress` for every output UTXO — those are the only inputs you need to spend it later. The SDK ships `LocalStorageAdapter` for browser wallet keys; UTXO persistence is the consumer's responsibility (see `lib/utxo-manager.ts` patterns in cloak-ag/web for a reference implementation).
-
-## Compliance Chain Scanning
-
-Cloak supports a viewing-key commitment flow for compliance and self-discovery:
-
-- The viewing key itself is never written on-chain.
-- Only `viewing_key_commitment = SHA256(viewing_key_public)` is stored on-chain.
-- A scanner recomputes this commitment from `viewing_key_public` and matches program transactions.
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant U as User Wallet + SDK
-    participant R as Relay
-    participant C as Cloak Program (Solana)
-    participant S as Scanner
-
-    U->>U: Generate (vk_priv, vk_pub)
-    U->>U: vkc = SHA256(vk_pub)
-    U->>R: Register vk_priv (signed)
-    U->>R: POST /transact + metadata_bundle + viewing_key_commitment=vkc
-    R->>C: Submit instruction [proof|public_inputs|vkc]
-    C-->>R: Confirm tx signature
-    R-->>U: Return signature
-
-    S->>S: Compute target_vkc from vk_pub
-    S->>C: Fetch recent program txs
-    S->>S: Decode ix data, extract vkc bytes, filter target_vkc
-    alt Relay enrichment enabled
-      S->>R: POST /admin/compliance/decrypt (admin signed)
-      R-->>S: Decrypted metadata rows (amount/recipient/type)
-      S->>S: Join on commitment + public_amount hints
-    end
-    S-->>U: Matching transactions
+Never write the artifact URL out by hand: the version segment and the digests are declared together
+in `src/config/circuit-release.ts` so they cannot drift.
+
+## Version and compatibility
+
+- SDK 0.2.0 pairs with the mainnet program at `zh1eLd6rSphLejbFfJEneUwzHRfMKxgzrgkfwA6qRkW`
+  (deployed 2026-08-24) and the 0.2.0 circuit bundle. All flows in this README were exercised on
+  mainnet on 2026-08-25: deposit, private send and withdraw on SOL, USDC and USDT; swaps SOL to
+  USDC and USDT; viewing-key discovery followed by a spend; keypair-only deposit recovery.
+- Proofs generated with the 0.1.x circuits are rejected by the mainnet program. SDK 0.1.x builds
+  (which ship the 0.1.0 bundle) are not usable against it; upgrade to 0.2.0.
+- The note-based `CloakSDK` class (`deposit` / `withdraw` / `send` / `swap` on `CloakNote`) targets
+  the pre-0.2.0 instruction layout and the unpublished 0.1.0 `withdraw_*` circuits. It is still
+  exported but does not work against the current program. Use the UTXO API above.
+
+## Examples
+
+```bash
+npm run example:fast-send          # deposit SOL, withdraw to a recipient
+npm run example:transfer           # deposit, private send, recipient withdraw
+npm run example:fast-usdc-send     # deposit SOL, swap to USDC, deposit USDC, withdraw USDC
+npm run example:usdc-pool-transfer # USDC pool: A deposits, sends to B, B spends
+npm run example:swap               # SOL -> USDC swap with interactive route retry
+npm run example:swap-usdc          # same, with the canonical swap markers
+npm run example:swap-brz           # BRZ with automatic USDC fallback
+npm run example:swap-recovery      # pending / timed-out swap handling
+npm run example:history-scan       # every flow, then full and incremental viewing-key scans
+npm run test:examples              # dry-run all of the above (no wallet, no RPC)
 ```
 
-## Error Handling
+Environment read by the examples:
 
-```typescript
+| Variable | Default |
+| --- | --- |
+| `SOLANA_RPC_URL` | `http://127.0.0.1:8899` (local fork) |
+| `CLOAK_RELAY_URL` | `http://127.0.0.1:5500` (local relay) |
+| `CLOAK_PROGRAM_ID` | `CLOAK_PROGRAM_ID` |
+| `CLOAK_CIRCUITS_PATH` | the pinned 0.2.0 bundle |
+| `CLOAK_ALT_ADDRESSES` | unset; the production lookup tables are resolved automatically |
+
+The examples fund throwaway keypairs from `~/.config/solana/id.json` and print stable
+`FULL_SIG|<example>|<step>|<signature>` markers. They import `@cloak.ag/sdk`, which
+`tsconfig.json` maps to `src/index.ts`; outside this repo import `@cloak.dev/sdk`.
+
+## Error handling
+
+```ts
 import {
   CloakError,
   UtxoAlreadySpentError,
-  RootNotFoundError,
-  classifyRelayError,
-  fullWithdraw,
-  CLOAK_PROGRAM_ID,
+  SanctionsQuoteError,
+  RelayInternalError,
+  SettlementVerificationError,
 } from "@cloak.dev/sdk";
 
 try {
-  await fullWithdraw(myUtxos, recipient, {
-    connection,
-    programId: CLOAK_PROGRAM_ID,
-    relayUrl: "https://api.cloak.ag",
-    depositorKeypair: signer,
-  });
+  await fullWithdraw([note], recipient, options);
 } catch (error) {
   if (error instanceof UtxoAlreadySpentError) {
-    // Drop the spent UTXO from local storage; the structured error
-    // carries which nullifiers collided.
-    console.log("Spent nullifiers:", error.nullifiers);
-  } else if (error instanceof RootNotFoundError) {
-    // Relay/chain root mismatch; retry against a fresh tree.
+    // the note was spent elsewhere; rescan
+  } else if (error instanceof SettlementVerificationError) {
+    // error.outcome tells whether it is safe to retry; error.signature is what to look up
   } else if (error instanceof CloakError) {
-    console.log("Category:", error.category); // 'wallet' | 'network' | 'prover' | 'relay' | 'validation' | 'environment' | 'service' | 'indexer'
-    console.log("Retryable:", error.retryable);
+    console.log(error.category, error.retryable);
   }
 }
 ```
 
+Catch the typed errors instead of matching message strings. `confirmTransactSettlement` re-checks a
+signature from chain state when an outcome was reported as unknown.
+
+## Development
+
+```bash
+npm install
+npm run lint           # tsc --noEmit
+npm test               # jest
+npm run build          # tsup -> dist/
+npm run verify:dist    # dist is byte-identical to a fresh build
+npm run test:examples  # dry-run the examples
+```
+
+Notes: [docs/DEPOSIT-SIZE-NOTES.md](docs/DEPOSIT-SIZE-NOTES.md) (deposit transaction size,
+confirmed-tree reads, supplemental lookup tables).
+
 ## Links
 
 - Website: [https://cloak.ag](https://cloak.ag)