@cloak.dev/sdk 0.1.0

package/README.md

@@ -0,0 +1,268 @@
+# @cloak.dev/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 (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
+
+```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
+```
+
+**Note**: For swap functionality, you'll also need `@solana/spl-token`:
+```bash
+npm install @solana/spl-token
+```
+
+## Quick Start
+
+### Risk Quote Configuration (Recommended)
+
+- Default production flow: set `CLOAK_RELAY_URL` and let relay handle Range quoting.
+- Keep `RANGE_API_KEY` only in relay/service backend, not in SDK clients.
+- SDK auto-uses `${CLOAK_RELAY_URL}/range-quote` when `relayUrl` is provided.
+- SDK-side `rangeApiKey` exists only as a server-side fallback (no-relay scenarios).
+
+### Maintained Examples
+
+```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
+```
+
+`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.
+
+`example:fast-usdc-send` is the one-shot private send path for USDC recipients (deposit SOL, swap privately to USDC, deliver to recipient ATA).
+
+`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).
+
+`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.
+
+`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`.
+
+`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|...`.
+
+`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.
+
+### Node.js (with Keypair)
+
+```typescript
+import { CloakSDK } 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 */);
+
+// 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);
+```
+
+### 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";
+
+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);
+  };
+
+  return <button onClick={handleDeposit}>Deposit 0.1 SOL</button>;
+}
+```
+
+## 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.005 SOL (5,000,000 lamports)
+- **Variable Fee**: 0.3% of deposit amount
+
+Use `getDistributableAmount()` to calculate the amount 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
+```
+
+## 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.
+
+## 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
+```
+
+## Error Handling
+
+```typescript
+import { CloakError } from "@cloak.dev/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-ag/sdk](https://github.com/cloak-ag/sdk)
+
+## License
+
+Apache-2.0

package/dist/chunk-2SOX3JNO.js

@@ -0,0 +1,255 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/core/utxo.ts
+import { PublicKey } from "@solana/web3.js";
+import { buildPoseidon } from "circomlibjs";
+import { blake3 } from "@noble/hashes/blake3";
+var FIELD_MODULUS = BigInt("21888242871839275222246405745257275088548364400416034343698204186575808495617");
+var UTXO_KEY_DOMAIN = new TextEncoder().encode("cloak_utxo_priv_v1");
+var NATIVE_SOL_MINT = new PublicKey("So11111111111111111111111111111111111111112");
+var poseidonInstance = null;
+async function getPoseidon() {
+  if (!poseidonInstance) {
+    poseidonInstance = await buildPoseidon();
+  }
+  return poseidonInstance;
+}
+function randomFieldElement() {
+  const bytes = new Uint8Array(32);
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    crypto.getRandomValues(bytes);
+  } else {
+    const { randomBytes } = __require("crypto");
+    const nodeBytes = randomBytes(32);
+    for (let i = 0; i < 32; i++) {
+      bytes[i] = nodeBytes[i];
+    }
+  }
+  let value = BigInt(0);
+  for (let i = 0; i < 32; i++) {
+    value = value << BigInt(8) | BigInt(bytes[i]);
+  }
+  return value % (FIELD_MODULUS >> BigInt(4));
+}
+async function generateUtxoKeypair() {
+  const poseidon = await getPoseidon();
+  const privateKey = randomFieldElement();
+  const publicKeyHash = poseidon([privateKey, BigInt(0)]);
+  const publicKey = poseidon.F.toObject(publicKeyHash);
+  return { privateKey, publicKey };
+}
+async function deriveUtxoKeypairFromSpendKey(skSpend) {
+  if (!skSpend || !(skSpend instanceof Uint8Array) || skSpend.length !== 32) {
+    throw new Error("skSpend must be 32 bytes");
+  }
+  const preimage = new Uint8Array(UTXO_KEY_DOMAIN.length + skSpend.length);
+  preimage.set(UTXO_KEY_DOMAIN, 0);
+  preimage.set(skSpend, UTXO_KEY_DOMAIN.length);
+  const hash = blake3(preimage);
+  let value = BigInt(0);
+  for (let i = 0; i < 32; i++) {
+    value = value << BigInt(8) | BigInt(hash[i]);
+  }
+  const privateKey = value % (FIELD_MODULUS >> BigInt(4));
+  const publicKey = await derivePublicKey(privateKey);
+  return { privateKey, publicKey };
+}
+async function derivePublicKey(privateKey) {
+  const poseidon = await getPoseidon();
+  const hash = poseidon([privateKey, BigInt(0)]);
+  return poseidon.F.toObject(hash);
+}
+async function createUtxo(amount, keypair, mintAddress = NATIVE_SOL_MINT) {
+  const blinding = randomFieldElement();
+  const utxo = {
+    amount,
+    keypair,
+    blinding,
+    mintAddress
+  };
+  utxo.commitment = await computeCommitment(utxo);
+  return utxo;
+}
+async function createZeroUtxo(mintAddress = NATIVE_SOL_MINT, salt) {
+  const poseidon = await getPoseidon();
+  const effectiveSalt = salt ?? randomFieldElement();
+  const publicKeyHash = poseidon([effectiveSalt, BigInt(0)]);
+  const publicKey = poseidon.F.toObject(publicKeyHash);
+  const keypair = { privateKey: effectiveSalt, publicKey };
+  const utxo = {
+    amount: BigInt(0),
+    keypair,
+    blinding: BigInt(0),
+    mintAddress
+  };
+  utxo.commitment = await computeCommitment(utxo);
+  utxo.index = 0;
+  return utxo;
+}
+function pubkeyToFieldElement(pubkey) {
+  const bytes = pubkey.toBytes();
+  let value = BigInt(0);
+  for (let i = 0; i < 32; i++) {
+    value = value << BigInt(8) | BigInt(bytes[i]);
+  }
+  return value % FIELD_MODULUS;
+}
+async function computeCommitment(utxo) {
+  const poseidon = await getPoseidon();
+  const mintField = pubkeyToFieldElement(utxo.mintAddress);
+  const hash = poseidon([
+    utxo.amount,
+    utxo.keypair.publicKey,
+    utxo.blinding,
+    mintField
+  ]);
+  return poseidon.F.toObject(hash);
+}
+async function computeSignature(privateKey, commitment, pathIndex) {
+  const poseidon = await getPoseidon();
+  const hash = poseidon([privateKey, commitment, pathIndex]);
+  return poseidon.F.toObject(hash);
+}
+async function computeNullifier(utxo) {
+  if (utxo.index === void 0) {
+    throw new Error("UTXO must have an index to compute nullifier");
+  }
+  const poseidon = await getPoseidon();
+  const commitment = utxo.commitment ?? await computeCommitment(utxo);
+  const pathIndex = BigInt(utxo.index);
+  const signature = await computeSignature(
+    utxo.keypair.privateKey,
+    commitment,
+    pathIndex
+  );
+  const hash = poseidon([commitment, pathIndex, signature]);
+  return poseidon.F.toObject(hash);
+}
+function serializeUtxo(utxo) {
+  const buffer = new ArrayBuffer(128);
+  const view = new DataView(buffer);
+  const amountBytes = bigintToBytes(utxo.amount, 8);
+  for (let i = 0; i < 8; i++) {
+    view.setUint8(i, amountBytes[i]);
+  }
+  const privkeyBytes = bigintToBytes(utxo.keypair.privateKey, 32);
+  for (let i = 0; i < 32; i++) {
+    view.setUint8(8 + i, privkeyBytes[i]);
+  }
+  const blindingBytes = bigintToBytes(utxo.blinding, 32);
+  for (let i = 0; i < 32; i++) {
+    view.setUint8(40 + i, blindingBytes[i]);
+  }
+  const mintBytes = utxo.mintAddress.toBytes();
+  for (let i = 0; i < 32; i++) {
+    view.setUint8(72 + i, mintBytes[i]);
+  }
+  view.setUint32(104, utxo.index ?? 0, true);
+  return new Uint8Array(buffer);
+}
+async function deserializeUtxo(bytes) {
+  const view = new DataView(bytes.buffer, bytes.byteOffset);
+  const amountBytes = bytes.slice(0, 8);
+  const amount = bytesToBigint(amountBytes);
+  const privkeyBytes = bytes.slice(8, 40);
+  const privateKey = bytesToBigint(privkeyBytes);
+  const publicKey = await derivePublicKey(privateKey);
+  const blindingBytes = bytes.slice(40, 72);
+  const blinding = bytesToBigint(blindingBytes);
+  const mintBytes = bytes.slice(72, 104);
+  const mintAddress = new PublicKey(mintBytes);
+  const index = view.getUint32(104, true);
+  const utxo = {
+    amount,
+    keypair: { privateKey, publicKey },
+    blinding,
+    mintAddress,
+    index: index > 0 ? index : void 0
+  };
+  utxo.commitment = await computeCommitment(utxo);
+  return utxo;
+}
+function bigintToBytes(value, length) {
+  const result = new Uint8Array(length);
+  let remaining = value;
+  for (let i = 0; i < length; i++) {
+    result[i] = Number(remaining & BigInt(255));
+    remaining >>= BigInt(8);
+  }
+  return result;
+}
+function bytesToBigint(bytes) {
+  let result = BigInt(0);
+  for (let i = bytes.length - 1; i >= 0; i--) {
+    result = result << BigInt(8) | BigInt(bytes[i]);
+  }
+  return result;
+}
+function bigintToHex(value) {
+  return value.toString(16).padStart(64, "0");
+}
+function hexToBigint(hex) {
+  const cleanHex = hex.startsWith("0x") ? hex.slice(2) : hex;
+  return BigInt("0x" + cleanHex);
+}
+function bigintToBytes32(value) {
+  const result = new Uint8Array(32);
+  let remaining = value;
+  for (let i = 31; i >= 0; i--) {
+    result[i] = Number(remaining & BigInt(255));
+    remaining >>= BigInt(8);
+  }
+  return result;
+}
+async function utxoEquals(a, b) {
+  const commitmentA = a.commitment ?? await computeCommitment(a);
+  const commitmentB = b.commitment ?? await computeCommitment(b);
+  return commitmentA === commitmentB;
+}
+function sumUtxoAmounts(utxos) {
+  return utxos.reduce((sum, utxo) => sum + utxo.amount, BigInt(0));
+}
+function selectUtxos(available, targetAmount) {
+  const sorted = [...available].sort(
+    (a, b) => Number(b.amount - a.amount)
+  );
+  const selected = [];
+  let total = BigInt(0);
+  for (const utxo of sorted) {
+    if (total >= targetAmount) break;
+    selected.push(utxo);
+    total += utxo.amount;
+  }
+  if (total < targetAmount) {
+    return null;
+  }
+  return selected;
+}
+
+export {
+  __require,
+  NATIVE_SOL_MINT,
+  randomFieldElement,
+  generateUtxoKeypair,
+  deriveUtxoKeypairFromSpendKey,
+  derivePublicKey,
+  createUtxo,
+  createZeroUtxo,
+  pubkeyToFieldElement,
+  computeCommitment,
+  computeSignature,
+  computeNullifier,
+  serializeUtxo,
+  deserializeUtxo,
+  bigintToHex,
+  hexToBigint,
+  bigintToBytes32,
+  utxoEquals,
+  sumUtxoAmounts,
+  selectUtxos
+};