@cloak.dev/sdk 0.1.7 → 0.1.8

package/README.md

@@ -4,12 +4,12 @@ TypeScript SDK for the Cloak Protocol - Private transactions on Solana using zer
 
 ## Features
 
-- 🔒 **Private Transfers**: Shield, send, and reclaim SOL or SPL tokens via the UTXO model and zero-knowledge proofs
-- 🔁 **Shield-to-shield**: Move funds privately between UTXOs (`transfer`) without ever de-shielding
-- 💱 **Token Swaps**: Swap shielded SOL for SPL tokens via Jupiter (`swapUtxo`) — SOL → USDC, BRZ, etc.
-- 🔐 **Type-Safe**: Full TypeScript types; the `getConfig()` snapshot is structurally narrower than the constructor input so secrets cannot be re-exposed by accident
-- 🌐 **Cross-Platform**: Browser (wallet adapter) and Node.js (`Keypair`) modes
-- ⚡ **Functional API**: `transact` / `transfer` / `partialWithdraw` / `fullWithdraw` / `swapUtxo` — pass connection + program + relay + signer per call
+- 🔒 **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
 
 ## Installation
 
@@ -155,215 +155,146 @@ npm run test:examples
 ### Node.js (with Keypair)
 
 ```typescript
-import {
-  CLOAK_PROGRAM_ID,
-  NATIVE_SOL_MINT,
-  createUtxo,
-  createZeroUtxo,
-  fullWithdraw,
-  generateUtxoKeypair,
-  transact,
-} from "@cloak.dev/sdk";
+import { CloakSDK } from "@cloak.dev/sdk";
 import { Connection, Keypair, PublicKey } from "@solana/web3.js";
 
-const connection = new Connection("https://api.mainnet-beta.solana.com");
-const signer = Keypair.fromSecretKey(/* your secret key */);
+// Initialize connection and keypair
+const connection = new Connection("https://api.devnet.solana.com");
+const keypair = Keypair.fromSecretKey(/* your secret key */);
 
-// Generate a UTXO keypair (owner of the shielded balance)
-const owner = await generateUtxoKeypair();
-
-// Build a 0.01 SOL output UTXO and shield it
-const amountLamports = 10_000_000n;
-const output = await createUtxo(amountLamports, owner, NATIVE_SOL_MINT);
+// Initialize SDK
+const sdk = new CloakSDK({
+  keypairBytes: keypair.secretKey,
+  network: "devnet",
+});
 
-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("Deposit signature:", deposited.signature);
+// 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);
 
-// Reclaim the full balance to a public address
-const recipient = new PublicKey("RECIPIENT_ADDRESS");
-const withdrawn = await fullWithdraw(deposited.outputUtxos, recipient, {
+// Withdraw to a recipient
+const withdrawResult = await sdk.withdraw(
   connection,
-  programId: CLOAK_PROGRAM_ID,
-  relayUrl: "https://api.cloak.ag",
-  depositorKeypair: signer,
-  cachedMerkleTree: deposited.merkleTree,
-});
-console.log("Withdraw signature:", withdrawn.signature);
+  depositResult.note,
+  new PublicKey("RECIPIENT_ADDRESS"),
+  { withdrawAll: true }
+);
+console.log("Withdrawn! TX:", withdrawResult.signature);
 ```
 
 ### React/Next.js (with Wallet Adapter)
 
 ```typescript
-import {
-  CLOAK_PROGRAM_ID,
-  NATIVE_SOL_MINT,
-  createUtxo,
-  createZeroUtxo,
-  generateUtxoKeypair,
-  transact,
-} from "@cloak.dev/sdk";
-import { useConnection, useWallet } from "@solana/wallet-adapter-react";
-import { useCallback } from "react";
+import { CloakSDK } from "@cloak.dev/sdk";
+import { useWallet, useConnection } from "@solana/wallet-adapter-react";
+import { PublicKey } from "@solana/web3.js";
 
-export function DepositButton() {
+function PrivateTransfer() {
+  const { publicKey, signTransaction, sendTransaction } = useWallet();
   const { connection } = useConnection();
-  const wallet = useWallet();
 
-  const onClick = useCallback(async () => {
-    if (!wallet.publicKey || !wallet.signTransaction) return;
-
-    const owner = await generateUtxoKeypair();
-    const amount = 10_000_000n; // 0.01 SOL — SDK-enforced minimum
-    const output = await createUtxo(amount, owner, NATIVE_SOL_MINT);
-
-    const result = await transact(
-      {
-        inputUtxos: [await createZeroUtxo(NATIVE_SOL_MINT), await createZeroUtxo(NATIVE_SOL_MINT)],
-        outputUtxos: [output, await createZeroUtxo(NATIVE_SOL_MINT)],
-        externalAmount: amount,
-        depositor: wallet.publicKey,
-      },
-      {
-        connection,
-        programId: CLOAK_PROGRAM_ID,
-        relayUrl: "https://api.cloak.ag",
-        wallet: {
-          publicKey: wallet.publicKey,
-          signTransaction: wallet.signTransaction,
-        },
+  // 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),
       },
-    );
-    console.log("Deposited:", result.signature);
-  }, [connection, wallet]);
+    });
+  }, [publicKey, signTransaction, sendTransaction]);
 
-  return <button onClick={onClick}>Deposit 0.01 SOL</button>;
+  const handleDeposit = async () => {
+    const result = await sdk.deposit(connection, 100_000_000);
+    console.log("Deposited!", result.signature);
+  };
+
+  return <button onClick={handleDeposit}>Deposit 0.1 SOL</button>;
 }
 ```
 
-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.
+## Core Methods
 
-## Core Functions
+### Deposit
 
-### Deposit (`transact` with positive `externalAmount`)
+Deposit SOL into the privacy pool:
 
 ```typescript
-const result = await transact(
-  {
-    inputUtxos: [await createZeroUtxo(), await createZeroUtxo()],
-    outputUtxos: [outputUtxo, await createZeroUtxo()],
-    externalAmount: 10_000_000n, // positive = deposit
-    depositor: signer.publicKey,
-  },
-  { connection, programId: CLOAK_PROGRAM_ID, relayUrl: "https://api.cloak.ag", depositorKeypair: signer },
-);
-console.log("Leaf index:", result.commitmentIndices[0]);
-console.log("Output UTXO:", result.outputUtxos[0]);
+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);
 ```
 
 ### Withdraw
 
-```typescript
-import { fullWithdraw, partialWithdraw } from "@cloak.dev/sdk";
+Withdraw to a single recipient:
 
-// Reclaim everything in one or more input UTXOs to a public address.
-const result = await fullWithdraw(myUtxos, recipientPublicKey, {
-  connection,
-  programId: CLOAK_PROGRAM_ID,
-  relayUrl: "https://api.cloak.ag",
-  depositorKeypair: signer,
-});
-
-// Or withdraw a portion and keep the change shielded.
-const partial = await partialWithdraw(myUtxos, recipientPublicKey, 5_000_000n, {
+```typescript
+const result = await sdk.withdraw(
   connection,
-  programId: CLOAK_PROGRAM_ID,
-  relayUrl: "https://api.cloak.ag",
-  depositorKeypair: signer,
-});
+  note,
+  recipientPublicKey,
+  { withdrawAll: true }
+);
 ```
 
-### Shield-to-shield Transfer
+### Send to Multiple Recipients
 
-```typescript
-import { transfer } from "@cloak.dev/sdk";
+Send to up to 5 recipients:
 
-const result = await transfer(myUtxos, recipientUtxoPublicKey, amountLamports, {
-  connection,
-  programId: CLOAK_PROGRAM_ID,
-  relayUrl: "https://api.cloak.ag",
-  depositorKeypair: signer,
-});
+```typescript
+const result = await sdk.send(connection, note, [
+  { recipient: addr1, amount: 50_000_000 },
+  { recipient: addr2, amount: 47_000_000 },
+]);
 ```
 
-### Swap (SOL → SPL token)
+### Swap
+
+Swap SOL for SPL tokens:
 
 ```typescript
-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,
-  },
-);
+const result = await sdk.swap(connection, note, recipientPublicKey, {
+  outputMint: "TOKEN_MINT_ADDRESS",
+  minOutputAmount: 1000000,
+});
 ```
 
 ## Fee Structure
 
-- **Fixed Fee**: 0.005 SOL (5,000,000 lamports) on withdraw
-- **Variable Fee**: 0.3% of withdrawn amount
+- **Fixed Fee**: 0.005 SOL (5,000,000 lamports)
+- **Variable Fee**: 0.3% of deposit amount
 
-Use `getDistributableAmount()` to calculate the amount a recipient receives after fees:
+Use `getDistributableAmount()` to calculate the amount after fees:
 
 ```typescript
 import { getDistributableAmount } from "@cloak.dev/sdk";
 
-const withdrawing = 100_000_000; // 0.1 SOL
-const recipientReceives = getDistributableAmount(withdrawing); // ~94,700,000 lamports
+const deposited = 100_000_000; // 0.1 SOL
+const afterFees = getDistributableAmount(deposited); // ~94,700,000 lamports
 ```
 
-## UTXOs
+## Notes
 
-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:
+A **Cloak Note** is a cryptographic commitment representing a private amount of SOL:
 
 ```typescript
-interface Utxo {
-  amount: bigint;            // lamports for SOL, token units for SPL
-  keypair: UtxoKeypair;      // { privateKey, publicKey } — bigints
-  blinding: bigint;          // randomness
-  mintAddress: PublicKey;    // NATIVE_SOL_MINT for SOL
-  index?: number;            // leaf index in the Merkle tree (set after the UTXO is in-tree)
-  commitment?: bigint;
-  nullifier?: bigint;
+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;
 }
 ```
 
-**⚠️ 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).
+**⚠️ Important**: Save your notes securely! Without the note, you cannot withdraw your funds.
 
 ## Compliance Chain Scanning
 
@@ -403,31 +334,13 @@ sequenceDiagram
 ## Error Handling
 
 ```typescript
-import {
-  CloakError,
-  UtxoAlreadySpentError,
-  RootNotFoundError,
-  classifyRelayError,
-  fullWithdraw,
-  CLOAK_PROGRAM_ID,
-} from "@cloak.dev/sdk";
+import { CloakError } from "@cloak.dev/sdk";
 
 try {
-  await fullWithdraw(myUtxos, recipient, {
-    connection,
-    programId: CLOAK_PROGRAM_ID,
-    relayUrl: "https://api.cloak.ag",
-    depositorKeypair: signer,
-  });
+  await sdk.withdraw(connection, note, recipient);
 } catch (error) {
-  if (error instanceof UtxoAlreadySpentError) {
-    // Drop the spent UTXO from local storage; the structured error
-    // carries which nullifiers collided.
-    console.log("Spent nullifiers:", error.nullifiers);
-  } else if (error instanceof RootNotFoundError) {
-    // Relay/chain root mismatch; retry against a fresh tree.
-  } else if (error instanceof CloakError) {
-    console.log("Category:", error.category); // 'wallet' | 'network' | 'prover' | 'relay' | 'validation' | 'environment' | 'service' | 'indexer'
+  if (error instanceof CloakError) {
+    console.log("Category:", error.category); // 'wallet', 'network', 'prover', etc.
     console.log("Retryable:", error.retryable);
   }
 }