@cloak.dev/sdk 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -0,0 +1,173 @@
+# Changelog
+
+All notable changes to `@cloak.dev/sdk` are documented here. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.6] — 2026-04-27
+
+### Removed (BREAKING)
+
+- **`CloakSDK.deposit / privateTransfer / withdraw / send / swap`** —
+  these methods built a legacy `[discriminator: 1, amount: u64,
+  commitment: 32]` deposit instruction. The deployed shield-pool program
+  has repurposed discriminator `1` to `TransactSwap` (which requires
+  `>= 8` accounts), so every external invocation hit `0x1063
+  MissingAccounts` at ~112 CU. Reported by the cloak-squads hackathon
+  team on 2026-04-26.
+- **`createDepositInstruction` / `validateDepositParams` /
+  `DepositInstructionParams`** — the disc-1 instruction builder and its
+  validators.
+- **`CloakNote` model and helpers** — `generateNote`, `parseNote`,
+  `exportNote`, `findNoteByCommitment`, `filterNotesByNetwork`,
+  `filterWithdrawableNotes`, `isWithdrawable`, `updateNoteWithDeposit`,
+  `getRecipientAmount`, `generateNoteFromWallet`. The OLD
+  `withdraw_regular.circom` model used a 3-input
+  `Poseidon(amount, r0, r1, pk_spend)` commitment that is incompatible
+  with the deployed `transaction.circom` UTXO circuit (4-input
+  `Poseidon(amount, pubkey, blinding, mintAddress)`).
+- **`CloakSDK.loadNotes / saveNote / findNote / getTransactionMetadata`**
+  and the `StorageAdapter.notes*` methods. The adapter is now keys-only.
+- **Encrypted-note helpers** — `prepareEncryptedOutput`,
+  `prepareEncryptedOutputForRecipient`, `encodeNoteSimple` (legacy
+  `CloakNote`-based variants).
+- **Pending-operations helpers** — `savePendingDeposit`/`Withdrawal`
+  and friends, plus `PendingDeposit` / `PendingWithdrawal` types.
+- **Legacy proof generation** — `src/utils/proof-generation.ts`
+  (`generateWithdrawRegularProof`, `generateWithdrawSwapProof`,
+  `verifyCircuitIntegrity`, `verifyAllCircuits`,
+  `areCircuitsAvailable`, `getDefaultCircuitsPath`,
+  `EXPECTED_CIRCUIT_HASHES`, `DEFAULT_CIRCUITS_URL`).
+- **Legacy bigint hash helpers** in `src/utils/crypto.ts` —
+  `computeCommitment` (3-arg), `generateCommitmentAsync`,
+  `computeNullifier{,Async,Sync}`, `computeOutputsHash{,Async,Sync,FromLimbs}`,
+  `computeSwapOutputsHash{,Async,Sync}`. The UTXO-model
+  `computeCommitment(utxo)` / `computeNullifier(utxo)` live in
+  `core/utxo` and are re-exported as `computeUtxoCommitment` /
+  `computeUtxoNullifier`.
+- **OLD types** in `src/core/types.ts` — `CloakNote`, `Transfer`,
+  `MaxLengthArray`, `TransferResult`, `DepositResult`, `DepositOptions`,
+  `TransferOptions`, `WithdrawOptions`, `DepositStatus`, `SwapOptions`,
+  `SwapParams`, `SwapResult`. Plus `proofTimeout` (was unused on the
+  snapshot).
+- **`withdraw_regular_final.zkey`** — the ~10 MB legacy circuit asset.
+
+### Changed (BREAKING)
+
+- **`CloakConfig` is now a snapshot-only type.** It is the structurally
+  narrow value returned by `CloakSDK.getConfig()`: exactly seven
+  fields — `network`, `cloakKeys`, `programId`, `poolAddress`,
+  `merkleTreeAddress`, `treasuryAddress`, `debug`. The constructor
+  input is the new exported `CloakSDKOptions` interface (which still
+  accepts `keypairBytes`, `wallet`, and `storage` — they are consumed
+  into private SDK state and are *never* persisted on the snapshot).
+  `sdk.getConfig().keypairBytes` is now a `TS2339` compile-time error.
+- `CloakConfig.cloakKeys` is now typed as `CloakKeyPair | undefined`
+  (was `any`).
+- `LocalStorageAdapter` constructor signature is `(keysKey?: string)`;
+  the second `notesKey` parameter is gone.
+- `CloakSDK` constructor now throws `CloakError(_, "validation", false)`
+  instead of plain `Error` when no signer is provided; `getPublicKey()`
+  throws `CloakError(_, "wallet", false)` when neither keypair nor
+  wallet adapter is configured. Consumers' `parseError()` /
+  `classifyRelayError()` flows now handle these uniformly.
+
+### Added
+
+- **`LocalStorageAdapter` auto-purges legacy plaintext secrets.** On
+  the first construction in any browser origin, the adapter removes the
+  pre-0.1.6 `cloak_notes` localStorage entry (which contained `r`
+  randomness and `sk_spend` hex in plaintext) and writes a sentinel at
+  `cloak_purged_v0_1_5` so subsequent constructions skip the work.
+  Closes the upgrade-time security gap without requiring consumers to
+  call any helper. Consumers using a non-default legacy key can still
+  call `LocalStorageAdapter.purgeLegacyNoteStorage(customKey)`
+  explicitly.
+- `LocalStorageAdapter.LEGACY_PURGE_SENTINEL_KEY` and
+  `LocalStorageAdapter.LEGACY_NOTES_KEY` static constants for callers
+  that want to inspect / reset the purge state.
+- `LocalStorageAdapter.runLegacyPurgeOnce()` static helper for callers
+  that want to force the auto-purge before the first adapter
+  instantiation (e.g. during an upgrade boot sequence).
+
+### Security
+
+- `getConfig()` no longer leaks `keypairBytes`. The constructor
+  consumed the secret bytes into a `Keypair` and used to spread the
+  whole input onto `this.config`; `getConfig()`'s shallow-copy return
+  exposed the original `Uint8Array` by reference. `this.config` is now
+  built explicitly without `keypairBytes`/`wallet`/`storage`, and the
+  type system enforces the asymmetry (see "Changed" above).
+- `LocalStorageAdapter` upgrade-time auto-purge (see "Added") removes
+  the now-unredeemable plaintext secrets that pre-0.1.6 versions left
+  in browser localStorage.
+
+### Migration guide
+
+The supported flow for transaction emission is the functional UTXO API.
+
+```ts
+import {
+  transact,
+  fullWithdraw,
+  partialWithdraw,
+  transfer,
+  swapUtxo,
+  createUtxo,
+  createZeroUtxo,
+  generateUtxoKeypair,
+  CLOAK_PROGRAM_ID,
+  NATIVE_SOL_MINT,
+} from "@cloak.dev/sdk";
+import { Connection, Keypair } from "@solana/web3.js";
+
+const connection = new Connection("https://api.mainnet-beta.solana.com");
+const signer = Keypair.fromSecretKey(/* ... */);
+
+// Deposit (positive externalAmount).
+const owner = await generateUtxoKeypair();
+const output = await createUtxo(10_000_000n, owner, NATIVE_SOL_MINT);
+const deposited = await transact(
+  {
+    inputUtxos: [
+      await createZeroUtxo(NATIVE_SOL_MINT),
+      await createZeroUtxo(NATIVE_SOL_MINT),
+    ],
+    outputUtxos: [output, await createZeroUtxo(NATIVE_SOL_MINT)],
+    externalAmount: 10_000_000n,
+    depositor: signer.publicKey,
+  },
+  {
+    connection,
+    programId: CLOAK_PROGRAM_ID,
+    relayUrl: "https://api.cloak.ag",
+    depositorKeypair: signer,
+  },
+);
+
+// Reclaim to a public address.
+await fullWithdraw(deposited.outputUtxos, signer.publicKey, {
+  connection,
+  programId: CLOAK_PROGRAM_ID,
+  relayUrl: "https://api.cloak.ag",
+  depositorKeypair: signer,
+  cachedMerkleTree: deposited.merkleTree,
+});
+```
+
+The `CloakSDK` class is retained as a thin config + read-only helper
+(`getPublicKey`, `getCurrentRoot`, `getMerkleProof`,
+`getTransactionStatus`, `importWalletKeys`, `exportWalletKeys`,
+`getConfig`). Construction is unchanged for new fields.
+
+### Verification
+
+- Mainnet end-to-end smoke (deposit + withdraw cycle) on the patched
+  SDK: deposit signature
+  `5iGmrMYoSucYJ5PzEo5BCWioqTof4KNfjowq14ZYrbQACicaP2tJdJfRUy2CctsQLyNu6xpYXn8gYBg3EefsmXrv`
+  (slot 416038846, leaf 318); withdraw signature
+  `37A4T1KNiZLkmRvLAtui5ZN2VCmzjsZMzzGNwMosFA2UM1NGn7kP28p5APTvKRb51rNaLmWF42TJqK9GSZM5xCxn`
+  (slot 416055377). Net delta on the test wallet matches the expected
+  fee schedule (0.005 fixed + 0.3% var).
+
+[0.1.6]: https://github.com/cloak-ag/sdk/pull/11

package/README.md

@@ -4,12 +4,12 @@ TypeScript SDK for the Cloak Protocol - Private transactions on Solana using zer
 
 ## 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
+- 🔒 **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
 
 ## Installation
 
@@ -155,146 +155,215 @@ npm run test:examples
 ### Node.js (with Keypair)
 
 ```typescript
-import { CloakSDK } from "@cloak.dev/sdk";
+import {
+  CLOAK_PROGRAM_ID,
+  NATIVE_SOL_MINT,
+  createUtxo,
+  createZeroUtxo,
+  fullWithdraw,
+  generateUtxoKeypair,
+  transact,
+} from "@cloak.dev/sdk";
 import { Connection, Keypair, PublicKey } from "@solana/web3.js";
 
-// Initialize connection and keypair
-const connection = new Connection("https://api.devnet.solana.com");
-const keypair = Keypair.fromSecretKey(/* your secret key */);
+const connection = new Connection("https://api.mainnet-beta.solana.com");
+const signer = Keypair.fromSecretKey(/* your secret key */);
 
-// Initialize SDK
-const sdk = new CloakSDK({
-  keypairBytes: keypair.secretKey,
-  network: "devnet",
-});
+// Generate a UTXO keypair (owner of the shielded balance)
+const owner = await generateUtxoKeypair();
 
-// 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);
+// Build a 0.01 SOL output UTXO and shield it
+const amountLamports = 10_000_000n;
+const output = await createUtxo(amountLamports, owner, NATIVE_SOL_MINT);
 
-// Withdraw to a recipient
-const withdrawResult = await sdk.withdraw(
-  connection,
-  depositResult.note,
-  new PublicKey("RECIPIENT_ADDRESS"),
-  { withdrawAll: true }
+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,
+  },
+  {
+    connection,
+    programId: CLOAK_PROGRAM_ID,
+    relayUrl: "https://api.cloak.ag",
+    depositorKeypair: signer,
+  },
 );
-console.log("Withdrawn! TX:", withdrawResult.signature);
+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);
 ```
 
 ### React/Next.js (with Wallet Adapter)
 
 ```typescript
-import { CloakSDK } from "@cloak.dev/sdk";
-import { useWallet, useConnection } from "@solana/wallet-adapter-react";
-import { PublicKey } from "@solana/web3.js";
+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";
 
-function PrivateTransfer() {
-  const { publicKey, signTransaction, sendTransaction } = useWallet();
+export function DepositButton() {
   const { connection } = useConnection();
+  const wallet = useWallet();
 
-  // 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 onClick = useCallback(async () => {
+    if (!wallet.publicKey || !wallet.signTransaction) return;
 
-  const handleDeposit = async () => {
-    const result = await sdk.deposit(connection, 100_000_000);
-    console.log("Deposited!", result.signature);
-  };
+    const owner = await generateUtxoKeypair();
+    const amount = 10_000_000n; // 0.01 SOL — SDK-enforced minimum
+    const output = await createUtxo(amount, owner, NATIVE_SOL_MINT);
 
-  return <button onClick={handleDeposit}>Deposit 0.1 SOL</button>;
+    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>;
 }
 ```
 
-## Core Methods
+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.
 
-### Deposit
+## Core Functions
 
-Deposit SOL into the privacy pool:
+### Deposit (`transact` with positive `externalAmount`)
 
 ```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);
+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]);
 ```
 
 ### Withdraw
 
-Withdraw to a single recipient:
-
 ```typescript
-const result = await sdk.withdraw(
+import { fullWithdraw, partialWithdraw } from "@cloak.dev/sdk";
+
+// Reclaim everything in one or more input UTXOs to a public address.
+const result = await fullWithdraw(myUtxos, recipientPublicKey, {
   connection,
-  note,
-  recipientPublicKey,
-  { withdrawAll: true }
-);
-```
+  programId: CLOAK_PROGRAM_ID,
+  relayUrl: "https://api.cloak.ag",
+  depositorKeypair: signer,
+});
 
-### Send to Multiple Recipients
+// 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,
+});
+```
 
-Send to up to 5 recipients:
+### Shield-to-shield Transfer
 
 ```typescript
-const result = await sdk.send(connection, note, [
-  { recipient: addr1, amount: 50_000_000 },
-  { recipient: addr2, amount: 47_000_000 },
-]);
-```
+import { transfer } from "@cloak.dev/sdk";
 
-### Swap
+const result = await transfer(myUtxos, recipientUtxoPublicKey, amountLamports, {
+  connection,
+  programId: CLOAK_PROGRAM_ID,
+  relayUrl: "https://api.cloak.ag",
+  depositorKeypair: signer,
+});
+```
 
-Swap SOL for SPL tokens:
+### Swap (SOL → SPL token)
 
 ```typescript
-const result = await sdk.swap(connection, note, recipientPublicKey, {
-  outputMint: "TOKEN_MINT_ADDRESS",
-  minOutputAmount: 1000000,
-});
+import { swapUtxo } from "@cloak.dev/sdk";
+
+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,
+  },
+);
 ```
 
 ## Fee Structure
 
-- **Fixed Fee**: 0.005 SOL (5,000,000 lamports)
-- **Variable Fee**: 0.3% of deposit amount
+- **Fixed Fee**: 0.005 SOL (5,000,000 lamports) on withdraw
+- **Variable Fee**: 0.3% of withdrawn amount
 
-Use `getDistributableAmount()` to calculate the amount after fees:
+Use `getDistributableAmount()` to calculate the amount a recipient receives after fees:
 
 ```typescript
 import { getDistributableAmount } from "@cloak.dev/sdk";
 
-const deposited = 100_000_000; // 0.1 SOL
-const afterFees = getDistributableAmount(deposited); // ~94,700,000 lamports
+const withdrawing = 100_000_000; // 0.1 SOL
+const recipientReceives = getDistributableAmount(withdrawing); // ~94,700,000 lamports
 ```
 
-## Notes
+## UTXOs
 
-A **Cloak Note** is a cryptographic commitment representing a private amount of SOL:
+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:
 
 ```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;
+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;
 }
 ```
 
-**⚠️ Important**: Save your notes securely! Without the note, you cannot withdraw your funds.
+**⚠️ 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
 
@@ -334,13 +403,31 @@ sequenceDiagram
 ## Error Handling
 
 ```typescript
-import { CloakError } from "@cloak.dev/sdk";
+import {
+  CloakError,
+  UtxoAlreadySpentError,
+  RootNotFoundError,
+  classifyRelayError,
+  fullWithdraw,
+  CLOAK_PROGRAM_ID,
+} from "@cloak.dev/sdk";
 
 try {
-  await sdk.withdraw(connection, note, recipient);
+  await fullWithdraw(myUtxos, recipient, {
+    connection,
+    programId: CLOAK_PROGRAM_ID,
+    relayUrl: "https://api.cloak.ag",
+    depositorKeypair: signer,
+  });
 } catch (error) {
-  if (error instanceof CloakError) {
-    console.log("Category:", error.category); // 'wallet', 'network', 'prover', etc.
+  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.
+  } else if (error instanceof CloakError) {
+    console.log("Category:", error.category); // 'wallet' | 'network' | 'prover' | 'relay' | 'validation' | 'environment' | 'service' | 'indexer'
     console.log("Retryable:", error.retryable);
   }
 }