Wallet integration

npm install @cloak.dev/sdk@0.2.5 @solana/kit @solana/wallet-adapter-react @solana/web3.js

npm install @solana/wallet-adapter-react-ui @solana/wallet-adapter-wallets

import { serializeUtxo, transact } from "@cloak.dev/sdk";

const result = await transact(params, {
  connection,
  programId,
  relayUrl,
  signTransaction, // wallet adapter signer, for the deposit transaction
  signMessage, // wallet adapter message signer, authenticates submitted requests
  depositorPublicKey, // wallet public key
  walletPublicKey: depositorPublicKey, // same key; becomes the authenticated sender
  riskOracleQueue, // if required by deployment
  riskQuoteUrl, // absolute URL on this build's allowlist (if needed)
  addressLookupTableAccounts,
});

// `result.outputUtxos` is the money this deposit created, and the SDK stores none of it.
// Write the bytes down before you report success. Zero-amount outputs are circuit
// padding, so drop them. `persistNotes` is your own storage, not the SDK's: it has
// none, and it must have committed before it resolves.
// See "Where your notes live between sessions" below.
await persistNotes(
  result.outputUtxos.filter((utxo) => utxo.amount > 0n).map(serializeUtxo),
);

import {
  CLOAK_PRODUCTION_RELAY_URL,
  CLOAK_PROGRAM_ID,
  NATIVE_SOL_MINT,
  createUtxo,
  createZeroUtxo,
  fullWithdraw,
  generateUtxoKeypair,
  isRootNotFoundError,
  serializeUtxo,
  address,
  createCloakRpc,
  transact,
  type Address,
} from "@cloak.dev/sdk";

// Your own durable store. The SDK ships nothing that plays this role.
declare function saveNoteBytes(bytes: Uint8Array): Promise<void>;

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

async function sendWithWalletAdapter({
  walletPublicKey,
  signTransaction,
  signMessage,
  recipientAddress,
  amountLamports,
}: {
  // A Kit Address. From a wallet adapter: addressFromPublicKey(wallet.publicKey).
  walletPublicKey: Address;
  signTransaction: (tx: any) => Promise<any>;
  signMessage: (msg: Uint8Array) => Promise<Uint8Array>;
  recipientAddress: string;
  amountLamports: bigint;
}) {
  const owner = await generateUtxoKeypair();
  const output = await createUtxo(amountLamports, owner, NATIVE_SOL_MINT);

  const deposited = await transact(
    {
      inputUtxos: [await createZeroUtxo(NATIVE_SOL_MINT)],
      outputUtxos: [output],
      externalAmount: amountLamports,
      depositor: walletPublicKey,
    },
    {
      connection,
      programId,
      relayUrl,
      signTransaction,
      signMessage,
      depositorPublicKey: walletPublicKey,
      walletPublicKey,
      onProgress: (status) => console.log("deposit", status),
      onProofProgress: (percent) => console.log("deposit proof", percent),
    },
  );

  // Persist before the withdrawal. The retry loop below can prompt the wallet three
  // times, and a tab closed at any of them leaves this note as the only claim on the
  // deposited funds. `saveNoteBytes` is your own storage, not an SDK export.
  await saveNoteBytes(serializeUtxo(deposited.outputUtxos[0]));

  const recipient = address(recipientAddress);
  let withdrawResult: Awaited<ReturnType<typeof fullWithdraw>> | undefined;

  for (let attempt = 1; attempt <= 3; attempt += 1) {
    try {
      withdrawResult = await fullWithdraw(deposited.outputUtxos, recipient, {
        connection,
        programId,
        relayUrl,
        walletPublicKey,
        signMessage,
        cachedMerkleTree: deposited.merkleTree,
        onProgress: (status) => console.log("withdraw", status),
        onProofProgress: (percent) => console.log("withdraw proof", percent),
      });
      break;
    } catch (error) {
      if (!isRootNotFoundError(error) || attempt === 3) throw error;
      await new Promise((resolve) => setTimeout(resolve, 1_500));
    }
  }

  if (!withdrawResult) throw new Error("withdraw did not produce a result");

  return {
    depositSignature: deposited.signature,
    withdrawSignature: withdrawResult.signature,
  };
}

import {
  createUtxo,
  serializeUtxo,
  transact,
  type TransactOptions,
  type Utxo,
} from "@cloak.dev/sdk";

// One deliberate merge round, in place of one round the withdrawal would have run
// for you. The difference is that the secret exists in your storage first.
async function mergeTwo(a: Utxo, b: Utxo, options: TransactOptions) {
  const merged = await createUtxo(a.amount + b.amount, a.keypair, a.mintAddress);

  // Write it down before submitting. Only `index` is still missing at this point,
  // and `index` is recoverable from chain state; `blinding` is not.
  await persistNotes([serializeUtxo(merged)]);

  const result = await transact(
    { inputUtxos: [a, b], outputUtxos: [merged], externalAmount: 0n },
    options,
  );

  // On success, replace the provisional copy with the one carrying the leaf index.
  await persistNotes(
    result.outputUtxos.filter((utxo) => utxo.amount > 0n).map(serializeUtxo),
  );
  return result;
}

import {
  LocalStorageAdapter,
  UtxoWallet,
  type CloakKeyPair,
} from "@cloak.dev/sdk";

const NOTES_KEY = "myapp.cloak.notes";
const storage = new LocalStorageAdapter();

function loadWallet(): UtxoWallet {
  const saved = window.localStorage.getItem(NOTES_KEY);
  return saved ? UtxoWallet.deserialize(saved) : new UtxoWallet();
}

function saveWallet(wallet: UtxoWallet): void {
  window.localStorage.setItem(NOTES_KEY, wallet.serialize());
}

// Key material has a ready-made home on the adapter.
async function loadKeys(): Promise<CloakKeyPair | null> {
  return await storage.loadKeys();
}

import { transact } from "@cloak.dev/sdk";

const wallet = loadWallet();

const result = await transact(params, options);

for (const utxo of result.outputUtxos) {
  wallet.addUtxo(utxo, utxo.mintAddress);
}
saveWallet(wallet); // before any "done" is shown

// On a spend, the inputs stop being yours.
for (const spent of inputUtxos) {
  wallet.markSpent(spent, spent.mintAddress);
}
for (const utxo of result.outputUtxos) {
  wallet.addUtxo(utxo, utxo.mintAddress);
}
saveWallet(wallet);

import { NATIVE_SOL_MINT, selectUtxos, transfer } from "@cloak.dev/sdk";

const available = wallet.getUnspentUtxos(NATIVE_SOL_MINT); // WalletUtxo[], extends Utxo
const selected = selectUtxos(available, 30_000_000n);

if (!selected) throw new Error("insufficient shielded balance");
if (selected.length > 2) throw new Error("consolidate before sending");

const sent = await transfer(selected, recipientUtxoPublicKey, 30_000_000n, walletOptions);

// The inputs are spent and your change is in `sent.outputUtxos`. Record both, and save,
// before you report the send as done.
for (const spent of selected) {
  wallet.markSpent(spent, spent.mintAddress);
}
for (const utxo of sent.outputUtxos) {
  wallet.addUtxo(utxo, utxo.mintAddress);
}
saveWallet(wallet);

import { createRecoverableDepositUtxo, transact } from "@cloak.dev/sdk";

const { utxo, noteSalt } = await createRecoverableDepositUtxo(20_000_000n, nk);

const deposit = await transact(
  { inputUtxos: [], outputUtxos: [utxo], externalAmount: 20_000_000n },
  { ...options, chainNoteViewingKeyNk: nk, chainNoteSalt: noteSalt },
);

// Recoverable is the fallback, not the plan. `deposit.outputUtxos` comes back with the leaf
// index already filled in, so persist it now and keep the scan as a repair tool.
for (const out of deposit.outputUtxos) {
  wallet.addUtxo(out, out.mintAddress);
}
saveWallet(wallet);