Code Examples

import {
  CLOAK_PRODUCTION_RELAY_URL,
  CLOAK_PROGRAM_ID,
  NATIVE_SOL_MINT,
  createUtxo,
  createZeroUtxo,
  fullWithdraw,
  generateUtxoKeypair,
  getNkFromUtxoPrivateKey,
  partialWithdraw,
  serializeUtxo,
  swapWithChange,
  transact,
  scanTransactions,
  toComplianceReport,
  type Utxo,
  address,
  createCloakRpc,
  generateKeyPairSigner,
  signerFromSecretKey,
  type Address,
  type UtxoSwapResult,
} from "@cloak.dev/sdk";
import { findAssociatedTokenPda, TOKEN_PROGRAM_ADDRESS } from "@solana-program/token";
import { appendFileSync, readFileSync } from "node:fs";

const USDC_MINT = address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
const USDT_MINT = address("Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB");

// Your own RPC. Cloak never inspects, replaces or proxies it.
const connection = createCloakRpc("https://api.mainnet-beta.solana.com");
const signer = await signerFromSecretKey(
  Uint8Array.from(JSON.parse(readFileSync(process.env.KEYPAIR_PATH!, "utf8"))),
);
const scanKeypair = await generateUtxoKeypair();
const viewingKeyNk = getNkFromUtxoPrivateKey(scanKeypair.privateKey);

// Server keypair path: `depositorKeypair` signs both the deposit transaction and
// every submitted request, without prompting.
const baseOptions = {
  connection,
  programId: CLOAK_PROGRAM_ID,
  relayUrl: CLOAK_PRODUCTION_RELAY_URL,
  depositorKeypair: signer,
  walletPublicKey: signer.address,
  chainNoteViewingKeyNk: viewingKeyNk,
};

// The SDK stores nothing for you. `serializeUtxo` is the 128-byte encoding that
// carries everything a note needs to stay spendable: amount, private key,
// blinding, mint and leaf index. Two append-only files stand in here for whatever
// durable store your service already has.
const NOTES_FILE = "./cloak-notes.jsonl";
const SWAP_REFUNDS_FILE = "./cloak-swap-refunds.jsonl";

function saveNotes(utxos: Utxo[]): void {
  for (const utxo of utxos) {
    if (utxo.amount === 0n) continue; // padding output, nothing to lose
    const line = JSON.stringify({
      mint: utxo.mintAddress.toBase58(),
      amount: utxo.amount.toString(),
      note: Buffer.from(serializeUtxo(utxo)).toString("base64"),
    });
    appendFileSync(NOTES_FILE, `${line}\n`);
  }
}

// Swaps only. `refund` reclaims the swap input if the swap times out before it
// settles, so it is stored next to the notes rather than inside them.
function saveSwapRefund(
  swapStatePda: string,
  refund: UtxoSwapResult["refund"],
): void {
  appendFileSync(
    SWAP_REFUNDS_FILE,
    `${JSON.stringify({ swapStatePda, ...refund })}\n`,
  );
}

async function sendSameMint(args: {
  mint: Address;
  amount: bigint;
  recipientWallet: Address;
  partialWithdrawAmount?: bigint; // use for partial withdrawal example
}) {
  const owner = await generateUtxoKeypair();
  const output = await createUtxo(args.amount, owner, args.mint);

  const deposited = await transact(
    {
      inputUtxos: [await createZeroUtxo(args.mint)],
      outputUtxos: [output],
      externalAmount: args.amount,
      depositor: signer.address,
    },
    baseOptions,
  );

  // Store the deposit note first. If the withdrawal below throws, this file is the
  // only claim anyone has on the funds that just entered the pool.
  saveNotes(deposited.outputUtxos);

  if (args.partialWithdrawAmount !== undefined) {
    const withdrawn = await partialWithdraw(
      deposited.outputUtxos,
      args.recipientWallet,
      args.partialWithdrawAmount,
      {
        ...baseOptions,
        cachedMerkleTree: deposited.merkleTree,
      },
    );

    // The recipient got their part; the remainder came back as a private change
    // note. Store it before you tell anyone the payment succeeded.
    saveNotes(withdrawn.outputUtxos);
    return withdrawn;
  }

  const withdrawn = await fullWithdraw(
    deposited.outputUtxos,
    args.recipientWallet,
    {
      ...baseOptions,
      cachedMerkleTree: deposited.merkleTree,
    },
  );

  // This call is given one note, so it withdraws directly and leaves no change.
  // That is a property of the input count, not of `fullWithdraw`: hand it three or
  // more notes and it consolidates on chain first. Call `saveNotes` regardless, so
  // the call site never has to know which flow produced change.
  saveNotes(withdrawn.outputUtxos);
  return withdrawn;
}

// SOL -> SOL (full withdrawal send)
await sendSameMint({
  mint: NATIVE_SOL_MINT,
  amount: 1_000_000_000n,
  recipientWallet: (await generateKeyPairSigner()).address,
});

// USDC -> USDC (recipient wallet must have a USDC ATA)
await sendSameMint({
  mint: USDC_MINT,
  amount: 8_000_000n,
  recipientWallet: (await generateKeyPairSigner()).address,
});

// USDT -> USDT (recipient wallet must have a USDT ATA)
await sendSameMint({
  mint: USDT_MINT,
  amount: 8_000_000n,
  recipientWallet: (await generateKeyPairSigner()).address,
});

// Partial withdrawal example (withdraw part, keep private change)
await sendSameMint({
  mint: NATIVE_SOL_MINT,
  amount: 1_000_000_000n,
  recipientWallet: (await generateKeyPairSigner()).address,
  partialWithdrawAmount: 250_000_000n,
});

import {
  CLOAK_PRODUCTION_RELAY_URL,
  CLOAK_PROGRAM_ID,
  createUtxo,
  createZeroUtxo,
  explainRelayAuthRejection,
  fullWithdraw,
  generateUtxoKeypair,
  addressFromPublicKey,
  createCloakRpc,
  serializeUtxo,
  transact,
  type Address,
  type CloakRpc,
  type Utxo,
} from "@cloak.dev/sdk";
import { useWallet } from "@solana/wallet-adapter-react";

// Cloak takes its own Kit RPC, not the wallet-adapter `Connection`.
const connection = createCloakRpc(process.env.NEXT_PUBLIC_SOLANA_RPC_URL!);

// The browser stand-in for the server path's append-only file, and the same
// `serializeUtxo` encoding: amount, private key, blinding, mint and leaf index.
// `localStorage` is the smallest thing that survives a reload; move to IndexedDB
// or your own backend when you outgrow it. See /sdk/wallet-integration for the
// two storage exports the SDK ships.
const NOTES_KEY = "myapp.cloak.notes";

function saveNotes(utxos: Utxo[]): void {
  const stored: string[] = JSON.parse(
    window.localStorage.getItem(NOTES_KEY) ?? "[]",
  );
  for (const utxo of utxos) {
    if (utxo.amount === 0n) continue; // padding output, nothing to lose
    stored.push(btoa(String.fromCharCode(...serializeUtxo(utxo))));
  }
  window.localStorage.setItem(NOTES_KEY, JSON.stringify(stored));
}

export function useSendSameMint(connection: CloakRpc, viewingKeyNk: Uint8Array) {
  const { publicKey, signTransaction, signMessage } = useWallet();

  return async function sendSameMint(args: {
    mint: Address;
    amount: bigint;
    recipientWallet: Address;
  }) {
    // Not every adapter implements signMessage. Check before you offer the action, so
    // the user is never asked to approve and then told their wallet cannot sign.
    if (!publicKey || !signTransaction || !signMessage) {
      throw new Error("Connect a wallet that supports message signing.");
    }

    const walletOptions = {
      connection,
      programId: CLOAK_PROGRAM_ID,
      relayUrl: CLOAK_PRODUCTION_RELAY_URL,

      // ── the wallet-adapter replacement for `depositorKeypair` ──
      signTransaction, // signs the deposit transaction
      signMessage, // signs the request preimage on submitted flows
      // The adapter gives a web3.js PublicKey; Cloak options take a Kit Address.
      depositorPublicKey: addressFromPublicKey(publicKey),
      walletPublicKey: addressFromPublicKey(publicKey), // the authenticated `sender`
      // ──────────────────────────────────────────────────────────

      chainNoteViewingKeyNk: viewingKeyNk,
      onProgress: (status: string) => console.log(status),
      onProofProgress: (percent: number) => console.log(`proof ${percent}%`),
    };

    const owner = await generateUtxoKeypair();
    const output = await createUtxo(args.amount, owner, args.mint);

    // Deposit: signed by the wallet, submitted directly. No authenticated sender.
    const deposited = await transact(
      {
        inputUtxos: [await createZeroUtxo(args.mint)],
        outputUtxos: [output],
        externalAmount: args.amount,
        depositor: publicKey,
      },
      walletOptions,
    );

    // Store the deposit note before going any further. If the send below fails, or
    // the user closes the tab while the wallet dialog is open, this is the only
    // claim on the funds that just entered the pool.
    saveNotes(deposited.outputUtxos);

    // Send: submitted for you, so this is the call that needs the signed sender.
    try {
      const withdrawn = await fullWithdraw(
        deposited.outputUtxos,
        args.recipientWallet,
        {
          ...walletOptions,
          cachedMerkleTree: deposited.merkleTree,
        },
      );

      // One input note here, so there is no change and nothing to write. With three
      // or more, `fullWithdraw` consolidates on chain first and the exemption stops
      // holding. Keep the call so any flow swapped in stays safe.
      saveNotes(withdrawn.outputUtxos);
      return withdrawn;
    } catch (error) {
      const hint = explainRelayAuthRejection(String(error));
      throw hint ? new Error(hint, { cause: error }) : error;
    }
  };
}

const swapOwner = await generateUtxoKeypair();
const swapInput = await createUtxo(600_000_000n, swapOwner, NATIVE_SOL_MINT);

const swapDeposit = await transact(
  {
    inputUtxos: [await createZeroUtxo(NATIVE_SOL_MINT)],
    outputUtxos: [swapInput],
    externalAmount: 600_000_000n,
    depositor: signer.address,
  },
  baseOptions,
);

const recipientWallet = (await generateKeyPairSigner()).address;
const [recipientUsdcAta] = await findAssociatedTokenPda({
  mint: USDC_MINT,
  owner: recipientWallet,
  tokenProgram: TOKEN_PROGRAM_ADDRESS,
});

saveNotes(swapDeposit.outputUtxos);

const swapped = await swapWithChange(
  [swapDeposit.outputUtxos[0]],
  300_000_000n, // amount to swap
  USDC_MINT,
  recipientUsdcAta,
  1n, // replace with quote-based min output
  {
    ...baseOptions,
    cachedMerkleTree: swapDeposit.merkleTree,
  },
  recipientWallet,
);

// A swap hands back two things worth keeping, and they are not the same thing.
saveNotes(swapped.outputUtxos); // the 300_000_000n of SOL you did not swap
saveSwapRefund(swapped.swapStatePda, swapped.refund); // reclaims the input on a timeout

const payroll = [
  { wallet: (await generateKeyPairSigner()).address, amount: 250_000_000n },
  { wallet: (await generateKeyPairSigner()).address, amount: 400_000_000n },
  { wallet: (await generateKeyPairSigner()).address, amount: 350_000_000n },
];

const receipts: { wallet: string; signature: string }[] = [];

for (const payment of payroll) {
  // `sendSameMint` stores the notes each iteration produces before it returns, which
  // is what makes a failure halfway through survivable: the paid runs are settled and
  // the failed run's deposit note is already on disk. A loop is the last place to
  // await a flow and drop the result.
  const paid = await sendSameMint({
    mint: NATIVE_SOL_MINT,
    amount: payment.amount,
    recipientWallet: payment.wallet,
  });

  receipts.push({
    wallet: payment.wallet.toBase58(),
    signature: paid.signature,
  });
}

// Reuse the same `viewingKeyNk` configured in your transaction options.
// This is a read-only scan: it signs nothing and prompts nobody, on either path.

const scan = await scanTransactions({
  connection,
  programId: CLOAK_PROGRAM_ID,
  viewingKeyNk,
  limit: 250,
});

const report = toComplianceReport(scan);
console.log(report.summary);