@cloak.ag/sdk 1.0.0

package/README.md

@@ -0,0 +1,180 @@
+# @cloak.ag/sdk
+
+TypeScript SDK for the Cloak Protocol - Private transactions on Solana using zero-knowledge proofs.
+
+## 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
+- 🔐 **Type-Safe**: Full TypeScript support with comprehensive types
+- 🌐 **Cross-Platform**: Works in browser and Node.js
+- ⚡ **Simple API**: Easy-to-use high-level client
+
+## Installation
+
+```bash
+npm install @cloak.ag/sdk @solana/web3.js
+# or
+yarn add @cloak.ag/sdk @solana/web3.js
+# or
+pnpm add @cloak.ag/sdk @solana/web3.js
+```
+
+**Note**: For swap functionality, you'll also need `@solana/spl-token`:
+```bash
+npm install @solana/spl-token
+```
+
+## Quick Start
+
+```typescript
+import { CloakSDK, generateNote } from "@cloak.ag/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 */);
+
+// Initialize SDK
+const sdk = new CloakSDK({
+  keypairBytes: keypair.secretKey,
+  network: "devnet",
+});
+
+// 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);
+
+// Withdraw to a recipient
+const withdrawResult = await sdk.withdraw(
+  connection,
+  depositResult.note,
+  new PublicKey("RECIPIENT_ADDRESS"),
+  { withdrawAll: true }
+);
+console.log("Withdrawn! TX:", withdrawResult.signature);
+```
+
+## API Configuration
+
+The SDK connects to `https://api.cloak.ag` by default. You can override this:
+
+```typescript
+const sdk = new CloakSDK({
+  keypairBytes: keypair.secretKey,
+  network: "devnet",
+  indexerUrl: "http://localhost:3001", // Custom indexer
+  relayUrl: "http://localhost:3002",   // Custom relay
+});
+```
+
+Or use environment variables:
+- `CLOAK_INDEXER_URL` - Override indexer URL
+- `CLOAK_RELAY_URL` - Override relay URL
+
+## Core Methods
+
+### Deposit
+
+Deposit SOL into the privacy pool:
+
+```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);
+```
+
+### Withdraw
+
+Withdraw to a single recipient:
+
+```typescript
+const result = await sdk.withdraw(
+  connection,
+  note,
+  recipientPublicKey,
+  { withdrawAll: true }
+);
+```
+
+### Send to Multiple Recipients
+
+Send to up to 5 recipients:
+
+```typescript
+const result = await sdk.send(connection, note, [
+  { recipient: addr1, amount: 50_000_000 },
+  { recipient: addr2, amount: 47_000_000 },
+]);
+```
+
+### Swap
+
+Swap SOL for SPL tokens:
+
+```typescript
+const result = await sdk.swap(connection, note, recipientPublicKey, {
+  outputMint: "TOKEN_MINT_ADDRESS",
+  minOutputAmount: 1000000,
+});
+```
+
+## Fee Structure
+
+- **Fixed Fee**: 0.003 SOL (3,000,000 lamports)
+- **Variable Fee**: 0.5% of deposit amount
+
+Use `getDistributableAmount()` to calculate the amount after fees:
+
+```typescript
+import { getDistributableAmount } from "@cloak.ag/sdk";
+
+const deposited = 100_000_000; // 0.1 SOL
+const afterFees = getDistributableAmount(deposited); // ~97,000,000 lamports
+```
+
+## 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;
+}
+```
+
+**⚠️ Important**: Save your notes securely! Without the note, you cannot withdraw your funds.
+
+## Error Handling
+
+```typescript
+import { CloakError } from "@cloak.ag/sdk";
+
+try {
+  await sdk.withdraw(connection, note, recipient);
+} catch (error) {
+  if (error instanceof CloakError) {
+    console.log("Category:", error.category); // 'wallet', 'network', 'prover', etc.
+    console.log("Retryable:", error.retryable);
+  }
+}
+```
+
+## Links
+
+- Website: [https://cloak.ag](https://cloak.ag)
+- Documentation: [https://docs.cloak.ag](https://docs.cloak.ag)
+- GitHub: [https://github.com/cloak-labs/sdk](https://github.com/cloak-labs/sdk)
+
+## License
+
+Apache-2.0