Shielded transfers

sum(inputs) = sum(outputs) + public_amount

inputs:  [ Alice's 0.10 note ]                 → nullified
outputs: [ Bob's 0.06 note, Alice's 0.04 change ]
public_amount = 0        # 0.10 = 0.06 + 0.04 + 0  ✓  nothing leaves the pool

import {
  CLOAK_PRODUCTION_RELAY_URL,
  CLOAK_PROGRAM_ID,
  NATIVE_SOL_MINT,
  createUtxo,
  createZeroUtxo,
  deriveViewingKeyFromNk,
  generateUtxoKeypair,
  getNkFromUtxoPrivateKey,
  scanRecipientDeliveryNotes,
  serializeUtxo,
  transact,
  transfer,
  fullWithdraw,
  createCloakRpc,
  signerFromSecretKey,
  type Utxo,
} from "@cloak.dev/sdk";
import { writeFileSync } from "node:fs";

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

// The SDK persists nothing for you. `serializeUtxo` is the 128-byte encoding of one
// note (amount, private key, blinding, mint, index) that `deserializeUtxo` reads back;
// nothing else can. A file is the simplest durable store there is. Treat these bytes
// as key material: whoever holds them can spend the note.
const keepNote = (name: string, utxo: Utxo) =>
  writeFileSync(`${name}.note`, serializeUtxo(utxo));

// Solana wallets. Each side's own wallet authenticates that side's request.
const aliceWallet = await signerFromSecretKey(
  Uint8Array.from(JSON.parse(process.env.ALICE_SECRET_KEY!)),
);
const bobWallet = await signerFromSecretKey(
  Uint8Array.from(JSON.parse(process.env.BOB_SECRET_KEY!)),
);

// ── Recipient (Bob), once ────────────────────────────────────────────
// Bob has a Cloak keypair and shares TWO public values with the sender.
const bob = await generateUtxoKeypair();
const bobNk = getNkFromUtxoPrivateKey(bob.privateKey);   // stays with Bob, never shared
const bobPubkey = bob.publicKey;                          // ← handoff #1a: Bob → Alice
const bobViewingPublicKey = deriveViewingKeyFromNk(bobNk).publicKey; // ← handoff #1b: Bob → Alice

// ── Sender (Alice): where `aliceNote` comes from ─────────────────────
// A note exists only because someone deposited. `alice` is Alice's Cloak keypair;
// `aliceWallet` is her Solana wallet, and it is the wallet that authenticates
// every request she makes. This deposit shields 0.10 SOL to her Cloak key.
const alice = await generateUtxoKeypair();
const aliceNk = getNkFromUtxoPrivateKey(alice.privateKey);   // Alice's OWN nk

const deposit = await transact(
  {
    inputUtxos: [await createZeroUtxo(NATIVE_SOL_MINT)],   // 2-in circuit: pad with a zero note
    outputUtxos: [await createUtxo(100_000_000n, alice, NATIVE_SOL_MINT)],
    externalAmount: 100_000_000n,           // 0.10 SOL flowing INTO the pool
    depositor: aliceWallet.address,
  },
  {
    connection, programId, relayUrl,
    depositorKeypair: aliceWallet,
    walletPublicKey: aliceWallet.address,
    chainNoteViewingKeyNk: aliceNk,
  },
);
const [aliceNote] = deposit.outputUtxos;   // ← the 0.10 note, with its leaf index attached
keepNote(`alice-deposit-${deposit.signature}`, aliceNote);  // crash here and it is gone

// ── Sender (Alice) sends ─────────────────────────────────────────────
// Alice moves 0.06 SOL of that note to Bob. externalAmount is 0 this time, so
// nothing leaves the pool, only ownership. Her 0.04 change comes back on
// `outputUtxos`, and that is the only copy of it: see the note below.
const sent = await transfer(
  [aliceNote],              // input note(s) Alice owns
  bobPubkey,                // recipient's Cloak pubkey — NOT a Solana wallet
  60_000_000n,             // 0.06 SOL
  {
    connection, programId, relayUrl,
    depositorKeypair: aliceWallet,          // server signer; a browser passes signMessage instead
    walletPublicKey: aliceWallet.address, // the authenticated sender, either way
    chainNoteViewingKeyNk: aliceNk,         // Alice's OWN nk
    recipientViewingPublicKey: bobViewingPublicKey,  // opt in to recipient discovery
    cachedMerkleTree: deposit.merkleTree,   // the deposit already built the tree; reuse it
  },
);

// Bank Alice's 0.04 change BEFORE anything reports success. `transfer` puts Bob's
// note at output 0 and Alice's change at output 1; a zero amount there means the
// input was consumed exactly and there is no change. The change note's blinding is
// fresh randomness that reaches no chain, so these bytes are its only copy and
// dropping them makes 0.04 SOL unspendable by Alice, by Bob and by anyone else.
const aliceChange = sent.outputUtxos[1];
if (aliceChange && aliceChange.amount > 0n) {
  keepNote(`alice-change-${sent.signature}`, aliceChange);
}

// ── Recipient (Bob) discovers and claims ─────────────────────────────
// Bob scans with nothing but his own keys and finds the note Alice sent him.
const { notes } = await scanRecipientDeliveryNotes({
  connection,
  programId,
  viewingKeyNk: bobNk,
  ownerUtxoPublicKey: bob.publicKey,   // authenticates the carrier's declared commitment
});
const delivered = notes.find((n) => n.commitmentVerified && n.amount === 60_000_000n);
if (!delivered) throw new Error("no delivered note found");

const claimable = {
  amount: delivered.amount,
  blinding: delivered.blinding,
  keypair: bob,
  mintAddress: NATIVE_SOL_MINT,
};
await fullWithdraw([claimable], bobWallet.address, {   // ← funds land at bobWallet (any address)
  connection, programId, relayUrl,
  depositorKeypair: bobWallet,            // Bob's OWN wallet authenticates his withdrawal
  walletPublicKey: bobWallet.address,   // never a service key: this is the screened sender
  chainNoteViewingKeyNk: bobNk,           // Bob's OWN nk
});

import {
  CLOAK_PRODUCTION_RELAY_URL,
  CLOAK_PROGRAM_ID,
  NATIVE_SOL_MINT,
  UtxoWallet,
  explainRelayAuthRejection,
  getNkFromUtxoPrivateKey,
  addressFromPublicKey,
  createCloakRpc,
  selectUtxos,
  transfer,
  type UtxoKeypair,
} from "@cloak.dev/sdk";
import { useWallet } from "@solana/wallet-adapter-react";

const connection = createCloakRpc(process.env.NEXT_PUBLIC_SOLANA_RPC_URL!);
const programId = CLOAK_PROGRAM_ID;
const relayUrl = CLOAK_PRODUCTION_RELAY_URL;
const NOTES_KEY = "myapp.cloak.notes";

const { publicKey, signMessage } = useWallet();

// `wallet` is the note set restored with UtxoWallet.deserialize on mount, and
// `alice` is the Cloak keypair stored beside it. Neither comes from the SDK.
async function sendToBob(
  wallet: UtxoWallet,
  alice: UtxoKeypair,
  bobPubkey: bigint,
  bobViewingPublicKey: Uint8Array,
) {
  // Not every adapter implements signMessage. Check before you offer the action.
  if (!publicKey || !signMessage) {
    throw new Error("Connect a wallet that supports message signing.");
  }

  const inputs = selectUtxos(wallet.getUnspentUtxos(NATIVE_SOL_MINT), 60_000_000n);
  if (!inputs) throw new Error("insufficient shielded balance");   // null, not a throw
  if (inputs.length > 2) throw new Error("consolidate first");     // transfer will not

  try {
    const result = await transfer(inputs, bobPubkey, 60_000_000n, {
      connection, programId, relayUrl,

      // ── replaces depositorKeypair: the user's own wallet signs the request ──
      // The adapter gives a web3.js PublicKey; Cloak options take a Kit Address.
      walletPublicKey: addressFromPublicKey(publicKey), // the request's authenticated sender
      signMessage,                  // returns the 64-byte ed25519 detached signature
      // ───────────────────────────────────────────────────────────────────────

      chainNoteViewingKeyNk: getNkFromUtxoPrivateKey(alice.privateKey), // Alice's OWN nk
      recipientViewingPublicKey: bobViewingPublicKey, // opt in to recipient discovery
    });

    // Bank the change before you render "sent". This is its only copy: output 0 is
    // Bob's note, output 1 is Alice's change, and its blinding reaches no chain.
    for (const spent of inputs) wallet.markSpent(spent, spent.mintAddress);
    for (const utxo of result.outputUtxos) wallet.addUtxo(utxo, utxo.mintAddress);
    window.localStorage.setItem(NOTES_KEY, wallet.serialize());
  } catch (error) {
    const hint = explainRelayAuthRejection(String(error));
    throw hint ? new Error(hint, { cause: error }) : error;
  }
}