Error handling

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

// Each merge is now your transaction: it returns, and you persist, before the next one starts.
let notes = [...inputUtxos];
while (notes.length > 2) {
  notes.sort((a, b) => (a.amount > b.amount ? 1 : a.amount < b.amount ? -1 : 0));
  const [small1, small2, ...rest] = notes;
  const merged = await createUtxo(small1.amount + small2.amount, small1.keypair, small1.mintAddress);
  const result = await transact(
    { inputUtxos: [small1, small2], outputUtxos: [merged], externalAmount: 0n },
    { connection, programId, relayUrl, walletPublicKey, signMessage },
  );
  // The merged note exists on chain now. Write it before the next round can fail.
  await saveNotes(result.outputUtxos.filter((utxo) => utxo.amount > 0n).map(serializeUtxo));
  notes = [result.outputUtxos[0], ...rest];
}

// Two notes left, so this call performs no merges and the exemption holds.
await fullWithdraw(notes, recipient, { connection, programId, relayUrl, walletPublicKey, signMessage });

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

let consolidated = false;
try {
  await fullWithdraw(inputUtxos, recipient, {
    connection,
    programId,
    relayUrl,
    walletPublicKey,
    signMessage,
    onProgress: (status) => {
      if (status.startsWith("Consolidating notes")) consolidated = true;
    },
  });
} catch (error) {
  if (consolidated) {
    // Some inputs are spent and one merged note is unreachable. Never retry with `inputUtxos`:
    // the first merge round preflights the nullifiers and throws `UtxoAlreadySpentError` (0x1020).
    const { spent, unspent } = await verifyUtxos(inputUtxos, connection, programId);
    // Anything without a commitment lands in `skipped`, so `spent` entries always have one.
    await dropNotes(spent.map((utxo) => utxo.commitment!));
    // Withdraw again from `unspent` only. Whatever `spent` totals went into a merged note you
    // cannot reach, unless the withdrawal itself landed and only its confirmation failed, so
    // check the recipient balance before writing that amount off.
  }
  throw error;
}

import { fullWithdraw, isRootNotFoundError, RootNotFoundError } from "@cloak.dev/sdk";

try {
  await fullWithdraw(inputUtxos, recipient, {
    connection,
    programId,
    relayUrl,
    depositorKeypair,
    walletPublicKey: depositorKeypair.address,
  });
  // With one or two inputs this leaves nothing shielded, so there is no change note to
  // persist here. With three or more, consolidation runs first and the exemption is off:
  // see "When fullWithdraw is not exempt". Every other flow has a change note either way.
} catch (error) {
  if (error instanceof RootNotFoundError || isRootNotFoundError(error)) {
    // Refresh proof inputs, then reconcile with verifyUtxos before retrying: a stale root on
    // the final withdrawal can follow consolidation rounds that already landed.
  }
}

import {
  addressFromPublicKey,
  isRootNotFoundError,
  partialWithdraw,
  RootNotFoundError,
  serializeUtxo,
} from "@cloak.dev/sdk";

try {
  const withdrawn = await partialWithdraw(inputUtxos, recipient, 10_000_000n, {
    connection,
    programId,
    relayUrl,
    walletPublicKey: addressFromPublicKey(publicKey!),
    signMessage: signMessage!,
  });
  // Success path: the remaining balance is here and nowhere else. Write it first.
  await saveNotes(
    withdrawn.outputUtxos.filter((utxo) => utxo.amount > 0n).map(serializeUtxo),
  );
} catch (error) {
  if (error instanceof RootNotFoundError || isRootNotFoundError(error)) {
    // Rebuild with fresh commitments/root and retry
  }
}

import {
  addressFromPublicKey,
  parseError,
  serializeUtxo,
  swapWithChange,
  type UserFriendlyError,
} from "@cloak.dev/sdk";

try {
  const swapped = await swapWithChange(
    inputUtxos,
    amountLamports,
    outputMint,
    recipientAta,
    minOutput,
    {
      connection,
      programId,
      relayUrl,
      depositorKeypair,
      walletPublicKey: depositorKeypair.address,
    },
  );
  // Success path, two writes. The change note is the remaining shielded balance.
  await saveNotes(
    swapped.outputUtxos.filter((utxo) => utxo.amount > 0n).map(serializeUtxo),
  );
  // `swapped.refund` reclaims the principal if the swap times out before it executes.
  // With `chainNoteViewingKeyNk` supplied it can be rebuilt later via `discoverSwapRefunds`,
  // so saving it is the fast path. Without one, `refund.derivedFromNk` is false and this
  // object is the only copy that will ever exist.
  await saveSwapRefund(swapped.swapStatePda, swapped.refund);
} catch (error) {
  const parsed: UserFriendlyError = parseError(error);
  // parsed.category: wallet | network | validation | service | transaction | unknown
  // parsed.recoverable: boolean
}

import {
  addressFromPublicKey,
  parseError,
  serializeUtxo,
  swapWithChange,
  type UserFriendlyError,
} from "@cloak.dev/sdk";

try {
  const swapped = await swapWithChange(
    inputUtxos,
    amountLamports,
    outputMint,
    recipientAta,
    minOutput,
    {
      connection,
      programId,
      relayUrl,
      walletPublicKey: addressFromPublicKey(publicKey!),
      signMessage: signMessage!,
    },
  );
  // Same two writes as the other tab: the change note, then the timeout refund secret.
  await saveNotes(
    swapped.outputUtxos.filter((utxo) => utxo.amount > 0n).map(serializeUtxo),
  );
  await saveSwapRefund(swapped.swapStatePda, swapped.refund);
} catch (error) {
  const parsed: UserFriendlyError = parseError(error);
  // parsed.category / parsed.recoverable
}