UTXO Transactions

import {
  CLOAK_PROGRAM_ID,
  CLOAK_PRODUCTION_RELAY_URL,
  transact,
  createUtxo,
  createZeroUtxo,
  addressFromPublicKey,
  createCloakRpc,
  generateUtxoKeypair,
} 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!);
const { publicKey, signTransaction, signMessage } = useWallet();

// The adapter hands back a web3.js PublicKey; Cloak options take a Kit Address.
const walletAddress = addressFromPublicKey(publicKey!);

const programId = CLOAK_PROGRAM_ID;
const relayUrl = CLOAK_PRODUCTION_RELAY_URL;

const owner = await generateUtxoKeypair();
const output = await createUtxo(20_000_000n, owner);

const result = await transact(
  {
    inputUtxos: [await createZeroUtxo()],
    outputUtxos: [output],
    externalAmount: 20_000_000n,
    depositor: walletAddress,
  },
  {
    connection,
    programId,
    relayUrl,
    signTransaction: signTransaction!, // signs the deposit transaction itself
    signMessage: signMessage!,         // viewing-key registration, and the signed sender later
    depositorPublicKey: walletAddress,
    walletPublicKey: walletAddress,
  }
);

// The deposited note lives only in this result. Write it down first.
await persistOutputs(result.outputUtxos);

import {
  CLOAK_PROGRAM_ID,
  CLOAK_PRODUCTION_RELAY_URL,
  transact,
  createUtxo,
  createCloakRpc,
  generateUtxoKeypair,
  signerFromSecretKey,
} from "@cloak.dev/sdk";

/** The 64 raw secret-key bytes of the funding wallet, loaded however your service loads secrets. */
declare const secretKeyBytes: Uint8Array;

const connection = createCloakRpc(process.env.SOLANA_RPC_URL!);
const relayUrl = CLOAK_PRODUCTION_RELAY_URL;
const programId = CLOAK_PROGRAM_ID;
const depositorKeypair = await signerFromSecretKey(secretKeyBytes);

const owner = await generateUtxoKeypair();
const output = await createUtxo(20_000_000n, owner); // 0.02 SOL

const result = await transact(
  {
    inputUtxos: [],
    outputUtxos: [output],
    externalAmount: 20_000_000n,
  },
  {
    connection,
    programId,
    relayUrl,
    depositorKeypair,
  }
);

// The deposited note lives only in this result. Write it down first.
await persistOutputs(result.outputUtxos);

console.log(result.signature, result.commitmentIndices);

import { transfer, partialWithdraw, fullWithdraw } from "@cloak.dev/sdk";

const walletOptions = {
  connection,
  programId,
  relayUrl,
  walletPublicKey: walletAddress, // becomes the request's authenticated sender
  signMessage: signMessage!,   // signs the request preimage
};

const sent = await transfer(inputUtxos, recipientUtxoPublicKey, 30_000_000n, walletOptions);
await persistOutputs(sent.outputUtxos); // your change note is in here

const withdrawn = await partialWithdraw(inputUtxos, recipientWallet, 10_000_000n, walletOptions);
await persistOutputs(withdrawn.outputUtxos); // the remainder that stayed shielded

// With one or two input notes fullWithdraw leaves nothing shielded, so there is no change note.
// With three or more it merges on chain first, and a throw mid-merge strands a note no result
// ever returns: see "Withdrawing three or more notes consolidates first" above.
await fullWithdraw(inputUtxos, recipientWallet, walletOptions);

import { transfer, partialWithdraw, fullWithdraw } from "@cloak.dev/sdk";

const sent = await transfer(inputUtxos, recipientUtxoPublicKey, 30_000_000n, options);
await persistOutputs(sent.outputUtxos); // your change note is in here

const withdrawn = await partialWithdraw(inputUtxos, recipientWallet, 10_000_000n, options);
await persistOutputs(withdrawn.outputUtxos); // the remainder that stayed shielded

// With one or two input notes fullWithdraw leaves nothing shielded, so there is no change note.
// With three or more it merges on chain first, and a throw mid-merge strands a note no result
// ever returns: see "Withdrawing three or more notes consolidates first" above.
await fullWithdraw(inputUtxos, recipientWallet, options);

import { swapWithChange, type UtxoSwapResult } from "@cloak.dev/sdk";

/** Your wallet's chain-note viewing key, and your own durable write for the refund secret. */
declare const nk: string;
declare function saveSwapRefund(
  swapStatePda: string,
  refund: UtxoSwapResult["refund"],
): Promise<void>;

const swapped = await swapWithChange(
  inputUtxos,
  50_000_000n,
  outputMint,
  recipientAta,
  1_000_000n,
  {
    connection,
    programId,
    relayUrl,
    walletPublicKey: walletAddress,
    signMessage: signMessage!,
    maxWalletApprovals: 3, // default 5
    chainNoteViewingKeyNk: nk, // makes the refund below rebuildable from key material
  },
  walletAddress
);

await persistOutputs(swapped.outputUtxos); // the change note left by the swap
await saveSwapRefund(swapped.swapStatePda, swapped.refund); // reclaims a timed-out swap

import { swapWithChange, type UtxoSwapResult } from "@cloak.dev/sdk";

/** Your wallet's chain-note viewing key, and your own durable write for the refund secret. */
declare const nk: string;
declare function saveSwapRefund(
  swapStatePda: string,
  refund: UtxoSwapResult["refund"],
): Promise<void>;

const swapped = await swapWithChange(
  inputUtxos,
  50_000_000n, // swap amount (lamports)
  outputMint,
  recipientAta,
  1_000_000n, // min output
  {
    connection,
    programId,
    relayUrl,
    depositorKeypair,
    chainNoteViewingKeyNk: nk, // makes the refund below rebuildable from key material
  },
  recipientWallet
);

await persistOutputs(swapped.outputUtxos); // the change note left by the swap
await saveSwapRefund(swapped.swapStatePda, swapped.refund); // reclaims a timed-out swap