@cloak.dev/sdk 0.1.8 → 0.2.1

package/README.md

@@ -1,53 +1,104 @@
 # @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**: Send SOL privately using zero-knowledge proofs
-- 👥 **Multi-Recipient**: Support for 1-5 recipients in a single transaction
-- 💱 **Token Swaps**: Swap SOL for SPL tokens privately (SOL → USDC, etc.)
-- 🔐 **Type-Safe**: Full TypeScript support with comprehensive types
-- 🌐 **Cross-Platform**: Works in browser (React, Next.js) and Node.js
-- ⚡ **Simple API**: Easy-to-use high-level client with wallet adapter support
+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
+npm install @cloak.dev/sdk@^0.2.0 @solana/web3.js
+# swaps and SPL pools also need:
+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`) |
+| Cloak endpoint | `https://api.cloak.ag` — pinned into the build, not configurable (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 endpoint is fixed when the SDK is built and cannot be changed by a consumer. A published build
+carries `RELAY_ORIGIN_ALLOWLIST` as a compiled-in constant, every request is checked against it
+before it leaves the process, and there is no option, environment variable, or bundler define that
+moves it. Name it by importing the constant rather than typing a host:
+
+```ts
+import { CLOAK_PRODUCTION_RELAY_URL } from "@cloak.dev/sdk";
+
+relayUrl: CLOAK_PRODUCTION_RELAY_URL
 ```
 
-**Note**: For swap functionality, you'll also need `@solana/spl-token`:
+It is still never defaulted: omitting the option throws before anything is signed or sent, so a
+script that forgets it cannot ship its proof anywhere. `relayUrl: ""` means the opposite — no
+endpoint at all, so a deposit is signed and submitted by the caller.
+
+A build pinned somewhere else is made by editing source and rebuilding, which is also what makes a
+published build unrepointable:
+
 ```bash
-npm install @solana/spl-token
+# in a checkout of this repo
+$ $EDITOR src/config/relay.ts     # replace the RELAY_ORIGIN_ALLOWLIST entry, do not append
+$ npm run build                   # only needed by consumers that import dist/
 ```
 
-## Quick Start
+The same edit unlocks the second half of the lock: a build pinned to a non-local origin refuses to
+run against an RPC served by the local machine, and a build pinned to a local origin does not. One
+constant, both behaviours.
 
-### SDK Defaults (Recommended)
+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 (some of the shipped examples set it on a local fork); it is not a no-relay mode.
 
-- 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`.
+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.
 
-### Minimal Private SOL Send (Single File, Keypair)
+### Devnet and local
 
-Use this contract for one-shot scripts and AI-generated snippets.
+The same SDK runs against a devnet or local deployment by pointing the three coordinates at it:
+
+```bash
+SOLANA_RPC_URL=https://api.devnet.solana.com   # or http://127.0.0.1:8899 for a local fork
+CLOAK_RELAY_URL=<endpoint serving that deployment>  # read by examples/ and scripts/, NOT by the SDK
+CLOAK_PROGRAM_ID=<program id of that deployment>   # examples read this; pass it as programId in your code
+```
+
+`CLOAK_RELAY_URL` configures the shipped examples and scripts, which pass its value as `relayUrl`.
+The SDK itself does not read it: the endpoint a build may talk to comes from `src/config/relay.ts`,
+so pointing at a devnet or local deployment means editing that file in a checkout and building it.
+
+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).
+
+## Quick start: private SOL send (single file, keypair)
+
+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 +110,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,245 +172,553 @@ 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).
+A deposit is signed by the wallet and goes straight to chain. A private send, a withdrawal and a
+swap are submitted for you, and each one carries an authenticated sender — so those three need
+`signMessage` and `walletPublicKey` even when `enforceViewingKeyRegistration` is off:
 
-`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).
+```ts
+// Private send (externalAmount 0) from a wallet adapter. Same for fullWithdraw / partialWithdraw
+// (externalAmount < 0) and swapUtxo / swapWithChange.
+await transact(
+  { inputUtxos, outputUtxos, externalAmount: BigInt(0) },
+  {
+    connection,
+    programId: CLOAK_PROGRAM_ID,
+    relayUrl,
+    signMessage: (message) => wallet.signMessage(message),
+    walletPublicKey: wallet.publicKey, // becomes the authenticated sender
+    chainNoteViewingKeyNk: nk,
+  },
+);
+```
 
-`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.
+`signMessage` must return the raw 64-byte ed25519 detached signature over the bytes it is given;
+adapters that re-encode or wrap the result are rejected by name. `walletPublicKey` must be the end
+user's own wallet — it is the identity the transaction is authenticated as. Passing neither a
+`depositorKeypair` nor both of these fails immediately, before any proof is generated.
 
-`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`.
+`depositorKeypair`, `walletPublicKey` and `depositorPublicKey` are three names for the SAME end
+user. That one key is the request's authenticated sender, the key screened for sanctions, and the
+wallet a viewing key is registered against, so setting two of the names to two different keys would
+screen one person and authenticate another. Passing two different wallets is refused at the call.
 
-`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|...`.
+### The approval window
 
-`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.
+The request's timestamp is stamped when the bytes are built, because it is part of what the wallet
+signs, and the relay accepts a first-use request for 300 seconds from that moment. An approval left
+sitting in a hardware wallet past that window cannot be rescued by re-stamping it, so the SDK stops
+there and says so instead of shipping a request that can only come back as a 401. Retry the
+operation and approve the prompt when it appears.
 
-### Node.js (with Keypair)
+`auth_issued_at` comes from the machine's own clock, and the relay rejects anything more than 30
+seconds ahead of its own. A user whose clock is fast cannot authenticate at all until it is
+corrected; `explainRelayAuthRejection` turns that rejection, and the rest of the relay's 401s, into
+a sentence that names the cause. The SDK applies it to its own relay errors already.
 
-```typescript
-import { CloakSDK } from "@cloak.dev/sdk";
-import { Connection, Keypair, PublicKey } from "@solana/web3.js";
+A private send or withdrawal signs exactly ONCE: every network retry re-POSTs the same signed
+bytes, so the user sees one prompt. A swap re-proves on every retry, so each retry needs its own
+approval; `maxWalletApprovals` (default 5) bounds how many times one swap may interrupt the user,
+independently of `maxRootRetries`. A `depositorKeypair` signs silently and is unaffected.
 
-// Initialize connection and keypair
-const connection = new Connection("https://api.devnet.solana.com");
-const keypair = Keypair.fromSecretKey(/* your secret key */);
+### Authenticating a call you build yourself
 
-// Initialize SDK
-const sdk = new CloakSDK({
-  keypairBytes: keypair.secretKey,
-  network: "devnet",
-});
+To authenticate a call you build yourself (a swap retry that posts only `retry_request_id`, for
+example), use the exported primitives rather than re-deriving the scheme:
 
-// Deposit SOL into the privacy pool
-const depositResult = await sdk.deposit(connection, 100_000_000); // 0.1 SOL
-console.log("Deposited! Leaf index:", depositResult.leafIndex);
+```ts
+import { buildRelayAuthPreimage, TRANSACT_SWAP_AUTH_FIELDS } from "@cloak.dev/sdk";
 
-// Withdraw to a recipient
-const withdrawResult = await sdk.withdraw(
-  connection,
-  depositResult.note,
-  new PublicKey("RECIPIENT_ADDRESS"),
-  { withdrawAll: true }
+const body = { retry_request_id: requestId, slippage_bps: 500 };
+const preimage = buildRelayAuthPreimage(
+  "/transact_swap",
+  CLOAK_PROGRAM_ID,
+  body,
+  wallet.publicKey,
+  undefined,
+  TRANSACT_SWAP_AUTH_FIELDS,
 );
-console.log("Withdrawn! TX:", withdrawResult.signature);
+const signature = await wallet.signMessage(preimage.message);
+
+const payload = {
+  ...body,
+  sender: preimage.sender,
+  auth_issued_at: preimage.auth_issued_at,
+  auth_nonce: preimage.auth_nonce,
+  auth_signature: Buffer.from(signature).toString("base64"),
+};
 ```
 
-### React/Next.js (with Wallet Adapter)
+Reuse one `preimage` for every retry of the same logical request; rebuilding it produces a new
+nonce and a new request.
+
+`slippage_bps` in that snippet is not decoration. Every other field in both lists is optional on
+the relay side, so omitting one and signing it as `null` matches what the relay signs. `slippage_bps`
+is the exception: it is not optional, and a request that omits it is read by the relay as **500**.
+Omit it and you sign `null` while the relay signs `500`, the digests differ, and the answer is a 401
+that points at nothing. Set it explicitly, to the same value the body carries. The SDK's own swap
+path always does; a hand-built body that leaves it out is refused before it is signed.
+
+`canonicalJson` is exported for the same reason, and it is the SDK's half of a byte-for-byte
+agreement with one Rust function over one fixed schema: ASCII keys over strings, small unsigned
+integers, booleans, nulls, arrays and plain objects. Amounts travel as decimal strings, not numbers,
+because JavaScript and `serde_json` do not spell every number the same way. Anything outside that
+schema that could serialize differently on the two sides is refused rather than silently signed.
+
+## The UTXO model
+
+- 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; `transact` pads unused slots with zero notes for you.
+  `createZeroUtxo(mint)` is exported if you want to pass them explicitly.
+- `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.
+
+Entry points: `transact` (general), `transfer`, `partialWithdraw`, `fullWithdraw`,
+`swapUtxo` / `swapWithChange`.
+
+### Private send (shield-to-shield)
 
-```typescript
-import { CloakSDK } from "@cloak.dev/sdk";
-import { useWallet, useConnection } from "@solana/wallet-adapter-react";
-import { PublicKey } from "@solana/web3.js";
+```ts
+import { deriveViewingKeyFromNk, transfer } from "@cloak.dev/sdk";
 
-function PrivateTransfer() {
-  const { publicKey, signTransaction, sendTransaction } = useWallet();
-  const { connection } = useConnection();
-
-  // Initialize SDK with wallet adapter
-  const sdk = useMemo(() => {
-    if (!publicKey) return null;
-    return new CloakSDK({
-      network: "devnet",
-      wallet: {
-        publicKey,
-        signTransaction: (tx) => signTransaction!(tx),
-        sendTransaction: (tx, conn, opts) => sendTransaction(tx, conn, opts),
-      },
-    });
-  }, [publicKey, signTransaction, sendTransaction]);
-
-  const handleDeposit = async () => {
-    const result = await sdk.deposit(connection, 100_000_000);
-    console.log("Deposited!", result.signature);
-  };
+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,
+  },
+);
+```
 
-  return <button onClick={handleDeposit}>Deposit 0.1 SOL</button>;
-}
+`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`).
+
+### Withdraw (unshield)
+
+```ts
+await fullWithdraw([note], recipientWallet, options);            // whole note
+await partialWithdraw([note], recipientWallet, amount, options); // amount out, change stays shielded
 ```
 
-## Core Methods
+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)).
 
-### Deposit
+### SPL pools (USDC, USDT)
 
-Deposit SOL into the privacy pool:
+Same API with the pool mint on every note:
 
-```typescript
-const result = await sdk.deposit(connection, 100_000_000); // 0.1 SOL
-// Save the note securely - you need it to withdraw!
-console.log(result.note);
+```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 },
+);
 ```
 
-### Withdraw
+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).
 
-Withdraw to a single recipient:
+### Shielded swap (SOL to USDC/USDT)
 
-```typescript
-const result = await sdk.withdraw(
-  connection,
-  note,
-  recipientPublicKey,
-  { withdrawAll: true }
+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,
+    depositorKeypair: signer,
+    walletPublicKey: signer.publicKey,
+    chainNoteViewingKeyNk: nk,
+    swapSlippageBps: 100,
+  },
+  recipientWallet,   // required on mainnet: the wallet the swap's risk quote is issued for
 );
+
+swap.signature;  // the executed swap; swapWithChange resolves only once execution has completed
+swap.refund;     // persist: the refund-fallback secret (see below)
 ```
 
-### Send to Multiple Recipients
+`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.
+
+#### Timed-out swaps
 
-Send to up to 5 recipients:
+`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:
 
-```typescript
-const result = await sdk.send(connection, note, [
-  { recipient: addr1, amount: 50_000_000 },
-  { recipient: addr2, amount: 47_000_000 },
-]);
+```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);
+}
 ```
 
-### Swap
+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).
+
+## Recovery and discovery (viewing key)
+
+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.
 
-Swap SOL for SPL tokens:
+Before a wallet's first transaction the SDK registers `nk` with the relay for compliance scanning:
+it signs a one-time challenge with `signMessage` (wallet) or `depositorKeypair` and submits `nk`
+with that signature. Nothing viewing-key related is written on-chain. The step is on by default;
+`enforceViewingKeyRegistration: false` disables it. `registerViewingKey(relayUrl, userPubkey, nk,
+signMessage)` performs the same registration on its own.
 
-```typescript
-const result = await sdk.swap(connection, note, recipientPublicKey, {
-  outputMint: "TOKEN_MINT_ADDRESS",
-  minOutputAmount: 1000000,
+```ts
+import { scanTransactions, fetchCommitments, type Utxo } from "@cloak.dev/sdk";
+
+const scan = await scanTransactions({
+  connection,
+  programId: CLOAK_PROGRAM_ID,
+  viewingKeyNk: nk,
+  ownerUtxoPublicKey: owner.publicKey, // authenticates delivered notes' commitments
+  deliveryMints: [NATIVE_SOL_MINT],
+  untilSignature: lastScan?.lastSignature, // incremental scans
 });
+
+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
+```
+
+`scanRecipientDeliveryNotes` does the delivery sweep alone, returning `{ notes, rpcCalls }`
+instead of a full scan result. 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.
+
+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.
+
+```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),
+};
 ```
 
-## Fee Structure
+`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).
 
-- **Fixed Fee**: 0.005 SOL (5,000,000 lamports)
-- **Variable Fee**: 0.3% of deposit amount
+`toComplianceReport(scan)` and `formatComplianceCsv(report)` turn a scan into a report.
 
-Use `getDistributableAmount()` to calculate the amount after fees:
+## Nullifiers and spent checks
 
-```typescript
-import { getDistributableAmount } from "@cloak.dev/sdk";
+The nullifier export is `computeUtxoNullifier(utxo)`, the circuit's scheme:
+`Poseidon(commitment, index, signature)`. This is the value the program records when a note is
+spent, so it is what a spent check compares against. It is async and requires `utxo.index` to be
+set.
 
-const deposited = 100_000_000; // 0.1 SOL
-const afterFees = getDistributableAmount(deposited); // ~94,700,000 lamports
+Prefer the helpers, which derive the nullifier and check the on-chain PDA for you:
+
+```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
 ```
 
-## Notes
-
-A **Cloak Note** is a cryptographic commitment representing a private amount of SOL:
-
-```typescript
-interface CloakNote {
-  version: string;
-  amount: number;          // Amount in lamports
-  commitment: string;      // Commitment hash
-  sk_spend: string;        // Spending key (keep secret!)
-  r: string;               // Randomness
-  timestamp: number;
-  network: Network;
-  leafIndex?: number;      // Set after deposit
-  depositSignature?: string;
-}
+`transact` runs the preflight itself before generating a proof.
+
+## Fees and limits
+
+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.
+
+| 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 |
+
+A withdrawal or swap must exceed its fee or the program rejects it; deposits below the minimum are
+rejected with `DepositTooSmall`.
+
+`shared/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
 ```
 
-**⚠️ Important**: Save your notes securely! Without the note, you cannot withdraw your funds.
-
-## 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
+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.
+
+## Circuit artifacts
+
+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, so the SDK never fetches it; for the record, the exported
+`transaction.vkey.json` from the same ceremony is SHA-256
+`deb40e7b94eae17db2975d23dcf26c26db2a36a4f02d14a25830dee3e88fb93c`.
+
+| Artifact | SHA-256 |
+| --- | --- |
+| `transaction_js/transaction.wasm` | `02ec02e954ae3932827ad9de51afa597ca95569aa97fec8410879c937a58aa2b` |
+| `transaction_final.zkey` | `9da7db8cb1370fc497d36a0365f1f107ab0b0c13ca66fa9f0287e5f96ee68d25` |
+
+The SDK downloads both 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 load the artifacts from a local directory instead (an air-gapped machine, a React Native bundle,
+or the ceremony output — the directory must contain `transaction_js/transaction.wasm` and
+`transaction_final.zkey` with the same digests):
+
+```ts
+import { resolveCircuitsBase, setCircuitsPath } from "@cloak.dev/sdk";
+
+// explicit argument, else the pinned default; no environment variable is consulted
+setCircuitsPath(resolveCircuitsBase());
+setCircuitsPath("/opt/cloak/ceremony-0.2.0"); // or a local directory you control
+```
+
+Never write the artifact URL out by hand: the version segment and the digests are declared together
+in `src/proving/circuits.ts` so they cannot drift.
+
+Where the artifacts may be read from is fixed when the SDK is built. `transaction.wasm` is the
+witness generator, so it is handed your spend key, your note secrets, the amounts and the recipient
+— a mirror on another host is therefore not accepted, and the SHA-256 check over the bytes cannot be
+switched off by any option or environment variable. A local directory is accepted (nothing leaves
+the machine, and the digest check still decides whether the bytes are usable); an `http(s)` base
+must be the bundle base this build pins. To point a build somewhere else, edit
+`RELAY_ORIGIN_ALLOWLIST` in `src/config/relay.ts` and rebuild — the one edit that also unlocks the
+relay endpoint and the localhost-RPC check.
+
+## 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 is removed in 0.2.0. It targeted the pre-0.2.0 instruction layout
+  and the unpublished 0.1.0 `withdraw_*` circuits, so it could not work against the current program.
+  Use the UTXO API above: `transact`, `transfer`, `partialWithdraw`, `fullWithdraw`, `swapUtxo`.
+
+## Examples
+
+```bash
+# SOL pool
+npm run example:deposit            # move lamports into the shielded SOL pool
+npm run example:private-send       # shield-to-shield send the recipient can discover
+npm run example:withdraw           # partial withdraw, then full withdraw of the change
+npm run example:swap               # SOL to USDC through Jupiter
+
+# SPL pools (USDC, USDT). There is no SPL swap: swap input is wSOL-locked.
+npm run example:spl-deposit
+npm run example:spl-private-send
+npm run example:spl-withdraw
+
+# Not pool specific
+npm run example:viewing-keys       # derive a viewing key, register it, read your history
+
+# Swap variants
+npm run example:swap-usdc          # same swap, with the canonical swap markers
+npm run example:swap-brz           # BRZ with automatic USDC fallback
+
+npm run test:examples              # dry-run all eight (no wallet, no RPC)
 ```
 
-## Error Handling
+Examples log by default. Set `CLOAK_DEBUG=0` to silence them.
+
+Environment read by the examples:
+
+| Variable | Default |
+| --- | --- |
+| `SOLANA_RPC_URL` | `http://127.0.0.1:8899` (local fork) |
+| `CLOAK_RELAY_URL` | `http://127.0.0.1:5500` (local endpoint) — read by the examples, not by the SDK; it must name an origin the SDK build is pinned to |
+| `CLOAK_PROGRAM_ID` | `CLOAK_PROGRAM_ID` |
+| `CLOAK_ALT_ADDRESSES` | unset; the production lookup tables are resolved automatically |
 
-```typescript
-import { CloakError } from "@cloak.dev/sdk";
+The examples fund throwaway keypairs from `~/.config/solana/id.json` and print stable
+`FULL_SIG|<example>|<step>|<signature>` markers. They import `@cloak.dev/sdk`, the published
+package name; inside this repo `tsconfig.json` maps that specifier to `src/index.ts` so the
+examples run against source.
+
+## Error handling
+
+```ts
+import {
+  CloakError,
+  UtxoAlreadySpentError,
+  SanctionsQuoteError,
+  RelayInternalError,
+  SettlementVerificationError,
+} from "@cloak.dev/sdk";
 
 try {
-  await sdk.withdraw(connection, note, recipient);
+  await fullWithdraw([note], recipient, options);
 } catch (error) {
-  if (error instanceof CloakError) {
-    console.log("Category:", error.category); // 'wallet', 'network', 'prover', etc.
-    console.log("Retryable:", error.retryable);
+  if (error instanceof UtxoAlreadySpentError) {
+    // 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(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` (deposit transaction size, confirmed-tree reads,
+supplemental lookup tables), `docs/transact-split.md` (how `flows/transact.ts` is split),
+`docs/cleanup-plan.md` (the root/scripts/examples cleanup this repo is executing).
+
 ## Links
 
 - Website: [https://cloak.ag](https://cloak.ag)
 - Documentation: [https://docs.cloak.ag](https://docs.cloak.ag)
-- GitHub: [https://github.com/cloak-ag/sdk](https://github.com/cloak-ag/sdk)
 
 ## License