@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 (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

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:

npm install @solana/spl-token

Quick Start

Node.js (with Keypair)

import { CloakSDK } 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);

React/Next.js (with Wallet Adapter)

import { CloakSDK } from "@cloak.ag/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:

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:

const result = await sdk.withdraw(
  connection,
  note,
  recipientPublicKey,
  { withdrawAll: true }
);

Send to Multiple Recipients

Send to up to 5 recipients:

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:

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:

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:

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

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
• Documentation: https://docs.cloak.ag
• GitHub: https://github.com/cloak-ag/sdk

License

Apache-2.0