Request authentication

import {
  CLOAK_PROGRAM_ID,
  CLOAK_PRODUCTION_RELAY_URL,
  explainRelayAuthRejection,
  serializeUtxo,
  transfer,
  addressFromPublicKey,
  type CloakRpc,
  type Utxo,
} from "@cloak.dev/sdk";
import { useWallet } from "@solana/wallet-adapter-react";

// `persistNotes` is your own storage, not the SDK's: it has none. It must have
// committed the bytes before it resolves.
export function usePrivateSend(
  connection: CloakRpc, // from createCloakRpc(rpcUrl)
  persistNotes: (noteBytes: Uint8Array[]) => Promise<void>,
) {
  const { publicKey, signMessage } = useWallet();

  // `recipientPubkey` is the recipient's Cloak pubkey, not a Solana wallet address.
  return async function send(notes: Utxo[], recipientPubkey: bigint, amount: bigint) {
    // Not every adapter implements signMessage. Check before you offer the action,
    // so the user is never asked to prove and then told their wallet cannot sign.
    if (!publicKey || !signMessage) {
      throw new Error("Connect a wallet that supports message signing.");
    }

    try {
      const result = await transfer(notes, recipientPubkey, amount, {
        connection,
        programId: CLOAK_PROGRAM_ID,
        relayUrl: CLOAK_PRODUCTION_RELAY_URL,

        // ── the two options that authenticate the request ──
        walletPublicKey: addressFromPublicKey(publicKey), // the request's `sender`
        signMessage,               // signs the request preimage
        // ──────────────────────────────────────────────────

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

      // Bank the outputs BEFORE you return, and before any UI says "sent". The
      // sender's change note is in here and these bytes are its only copy.
      // Zero-amount outputs are circuit padding, so drop them.
      await persistNotes(
        result.outputUtxos.filter((utxo) => utxo.amount > 0n).map(serializeUtxo),
      );

      return result;
    } catch (error) {
      const hint = explainRelayAuthRejection(String(error));
      throw hint ? new Error(hint, { cause: error }) : error;
    }
  };
}

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

// `notes` is one or two notes here, which is the shape that returns nothing to store.
// Three or more makes this call merge on chain first; merge those yourself instead.
await fullWithdraw(notes, recipient, {
  connection,
  programId: CLOAK_PROGRAM_ID,
  relayUrl: CLOAK_PRODUCTION_RELAY_URL,
  depositorKeypair: signer,
  walletPublicKey: signer.address,
});

Cloak private send requires an authenticated sender, and no signer was provided. Pass either
`depositorKeypair` (a local Keypair) or `signMessage` together with `walletPublicKey` (a browser
wallet adapter). The sender must be the end user's own wallet. Checked before proof generation, so
nothing has been computed or submitted yet.

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

try {
  // fullWithdraw over one or two notes is used here because that shape is the one
  // that returns no change note to bank. Every other flow on this page, and
  // fullWithdraw over three or more notes, produces secrets you must persist first.
  await fullWithdraw(notes, recipient, options);
} catch (error) {
  const hint = explainRelayAuthRejection(String(error));
  // hint, when non-null, is user-facing prose: "This computer's clock is more than
  // 30 seconds ahead...", "The request was signed more than 300 seconds before it
  // arrived...", "The request body changed after it was signed..."
  showError(hint ?? "Something went wrong. Please try again.");
}

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

const swap = await swapWithChange(inputUtxos, amount, outputMint, recipientAta, minOutput, {
  connection,
  programId,
  relayUrl,
  walletPublicKey: addressFromPublicKey(publicKey),
  signMessage,
  chainNoteViewingKeyNk: nk,  // the user's own nk; see the refund note below
  maxWalletApprovals: 3,      // default 5, floored at 1
});

// A swap returns TWO things you must keep, and this call is the last moment
// either exists. Store both before you report success.
await persistNotes(
  swap.outputUtxos.filter((utxo) => utxo.amount > 0n).map(serializeUtxo), // the change note
);
await persistSwapRefund(swap.swapStatePda, swap.refund); // reclaims a timed-out swap

import {
  addressFromPublicKey,
  messageSignerFromCallback,
  submitTransactToRelay,
  type RelayAuthSigner,
} from "@cloak.dev/sdk";

// Since 0.2.5 `RelayAuthSigner` is a Kit signer (`MessageSigner | TransactionSigner`),
// not a `{ walletPublicKey, signMessage }` pair. Build one from the adapter:
const relayAuthSigner: RelayAuthSigner = messageSignerFromCallback(
  addressFromPublicKey(publicKey), // the end user's real wallet, never an ephemeral key
  signMessage,
);

const result = await submitTransactToRelay({
  relayUrl,
  requestBody, // the exact body you will POST
  programId,
  relayAuthSigner,
  settlement: { connection, programId, mint, inputNullifiers },
  canRetryStaleRoot: false,
});
// result.kind: "submitted" | "stale-root" | "failed"

import { TRANSACT_AUTH_FIELDS, buildRelayAuthPreimage } from "@cloak.dev/sdk";

// `auth_signature` is base64. Do this without `Buffer`: it is a Node global, so a
// browser bundle fails to compile against it and throws `Buffer is not defined` at
// runtime unless you have polyfilled it. `btoa` is present in browsers and in Node.
const toBase64 = (bytes: Uint8Array) =>
  btoa(String.fromCharCode(...Array.from(bytes)));

const preimage = buildRelayAuthPreimage(
  "/transact",          // the exact path you POST to
  programId,
  requestBody,
  publicKey,            // the end user's wallet, becomes `sender`
  undefined,            // issued-at seconds; omit to stamp now
  TRANSACT_AUTH_FIELDS, // use TRANSACT_SWAP_AUTH_FIELDS for a swap body
);

const signature = await signMessage(preimage.message);

await fetch(`${relayUrl}/transact`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    ...requestBody,
    sender: preimage.sender,
    auth_issued_at: preimage.auth_issued_at,
    auth_nonce: preimage.auth_nonce,
    auth_signature: toBase64(signature),
  }),
});

CLOAK_RELAY_REQUEST_AUTH_V1
<endpoint>
<program id, base58>
<auth_nonce>
<auth_issued_at>
<sha256 hex of canonicalJson(signed view)>

https://storage.googleapis.com/cloak-circuits/circuits/0.2.0/transaction_js/transaction.wasm    3.2 MB
https://storage.googleapis.com/cloak-circuits/circuits/0.2.0/transaction_final.zkey            19.7 MB

import { getCircuitsPath, verifyAllCircuits } from "@cloak.dev/sdk";

// Fire and forget on mount. The first proof then finds the bytes already loaded.
void verifyAllCircuits(getCircuitsPath());