@cloak.dev/sdk 0.1.8 → 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**: 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
+# 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
 
-### SDK Defaults (Recommended)
+The same SDK runs against a devnet or local deployment by pointing the three coordinates at it:
 
-- 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`.
+```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
+```
+
+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,240 +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";
+
+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,
+  },
+);
+```
 
-`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.
+`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`).
 
-### Node.js (with Keypair)
+### Withdraw (unshield)
 
-```typescript
-import { CloakSDK } from "@cloak.dev/sdk";
-import { Connection, Keypair, PublicKey } from "@solana/web3.js";
+```ts
+await fullWithdraw([note], recipientWallet, options);            // whole note
+await partialWithdraw([note], recipientWallet, amount, options); // amount out, change stays shielded
+```
 
-// Initialize connection and keypair
-const connection = new Connection("https://api.devnet.solana.com");
-const keypair = 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)).
 
-// Initialize SDK
-const sdk = new CloakSDK({
-  keypairBytes: keypair.secretKey,
-  network: "devnet",
-});
+### SPL pools (USDC, USDT)
 
-// 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);
+Same API with the pool mint on every note:
 
-// Withdraw to a recipient
-const withdrawResult = await sdk.withdraw(
-  connection,
-  depositResult.note,
-  new PublicKey("RECIPIENT_ADDRESS"),
-  { withdrawAll: true }
+```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 },
 );
-console.log("Withdrawn! TX:", withdrawResult.signature);
 ```
 
-### React/Next.js (with Wallet Adapter)
+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).
 
-```typescript
-import { CloakSDK } from "@cloak.dev/sdk";
-import { useWallet, useConnection } from "@solana/wallet-adapter-react";
-import { PublicKey } from "@solana/web3.js";
+### Shielded swap (SOL to USDC/USDT)
 
-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);
-  };
+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).
 
-  return <button onClick={handleDeposit}>Deposit 0.1 SOL</button>;
-}
+```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)
 ```
 
-## Core Methods
+`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.
 
-### Deposit
+#### Timed-out swaps
 
-Deposit SOL into the privacy pool:
+`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.deposit(connection, 100_000_000); // 0.1 SOL
-// Save the note securely - you need it to withdraw!
-console.log(result.note);
+```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);
+}
 ```
 
-### Withdraw
+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).
 
-Withdraw to a single recipient:
+## Recovery and discovery (viewing key)
 
-```typescript
-const result = await sdk.withdraw(
+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.
+
+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.
+
+```ts
+import { scanTransactions, fetchCommitments, type Utxo } from "@cloak.dev/sdk";
+
+const scan = await scanTransactions({
   connection,
-  note,
-  recipientPublicKey,
-  { withdrawAll: true }
-);
+  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
 ```
 
-### Send to Multiple Recipients
+`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.
+
+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.
 
-Send to up to 5 recipients:
+```ts
+import { PublicKey } from "@solana/web3.js";
 
-```typescript
-const result = await sdk.send(connection, note, [
-  { recipient: addr1, amount: 50_000_000 },
-  { recipient: addr2, amount: 47_000_000 },
-]);
+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
+`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).
 
-Swap SOL for SPL tokens:
+`toComplianceReport(scan)` and `formatComplianceCsv(report)` turn a scan into a report.
 
-```typescript
-const result = await sdk.swap(connection, note, recipientPublicKey, {
-  outputMint: "TOKEN_MINT_ADDRESS",
-  minOutputAmount: 1000000,
-});
+## 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)
-- **Variable Fee**: 0.3% of deposit amount
+## Fees and limits
 
-Use `getDistributableAmount()` to calculate the amount 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 deposited = 100_000_000; // 0.1 SOL
-const afterFees = getDistributableAmount(deposited); // ~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
 ```
 
-## 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;
-}
+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.
+
+| 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**: 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
+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
-import { CloakError } from "@cloak.dev/sdk";
+| 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,
+  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](docs/DEPOSIT-SIZE-NOTES.md) (deposit transaction size,
+confirmed-tree reads, supplemental lookup tables).
+
 ## Links
 
 - Website: [https://cloak.ag](https://cloak.ag)