# Cloak Documentation

This file is the canonical index for AI coding agents integrating with Cloak. Integrations are built
on the TypeScript SDK `@cloak.dev/sdk`, in the browser, in Node, and in server-side scripts alike.

## AI Entrypoints

- [AI integration](/ai-tools/ai-integration): Read order and one-shot prompt templates.
- [LLM full export](/llms-full.txt): Single-file context pack for AI agents.
- [TypeScript SDK LLM reference](/sdk/llms.txt): Exhaustive `@cloak.dev/sdk` contract map and runtime invariants.
- [Well-known alias](/.well-known/llms.txt): Compatibility path for tools that probe `.well-known`.

## Documentation

### Getting Started

- [Platform Overview](/platform/overview): How Cloak fits together across SDK, programs, and circuits.
- [Cloak SDK](/sdk/introduction): Overview of `@cloak.dev/sdk`, shared runtime values, and where to start.

### Platform

- [Platform Components](/platform/components): Runtime boundaries for each subsystem.
- [Transaction Flows](/platform/transaction-flows): Deposit, transfer, withdraw, and swap lifecycle details.
- [Viewing Keys and Compliance](/architecture/viewing-keys-compliance): Key model, registration lifecycle, history behavior.

### TypeScript SDK (`@cloak.dev/sdk`)

- [Quickstart](/sdk/quickstart): Minimal mainnet setup with SOL send and withdraw examples.
- [Request authentication](/sdk/request-authentication): Signing the sender for private sends, withdrawals and swaps, from a wallet adapter or a server keypair.
- [Code Examples](/sdk/examples): Production-style snippets for common integration flows.
- [Solana Kit integration](/sdk/kit-integration): Integrate Cloak SDK in Kit-standardized codebases.
- [Core concepts](/sdk/core-concepts): UTXO model, fee semantics, viewing-key behavior, root retries.
- [UTXO Transactions](/sdk/utxo-transactions): Primary production APIs (`transact`, `fullWithdraw`, `swapWithChange`).
- [Batch signing](/sdk/batch-signing): `transactBatch` — N private spends behind one wallet approval, the coordinator for calls you already drive, and the 64-item limit.
- [Bridging in (SDK)](/sdk/bridge): SDK surface for cross-chain USDC in — deriving the one-time receiving address, quote assessment, client-side deposit-address verification, discovery and cleanup.
- [Shielded transfers](/sdk/shielded-transfers): Shielded-to-shielded sends — the two hand-offs a recipient needs, opt-in recipient discovery via `recipientViewingPublicKey`, and claiming with `scanRecipientDeliveryNotes`.
- [Wallet integration](/sdk/wallet-integration): wallet-adapter wiring, the two signing callbacks, secure signing patterns, and where a user's notes live between sessions: persisting `result.outputUtxos`, the `UtxoWallet` vs `StorageAdapter` split, and what is and is not recoverable once that storage is gone.
- [Error handling](/sdk/error-handling): Retry categories and diagnostics strategy.
- [API reference](/sdk/api-reference): Public exports and key type signatures.
- [TypeScript SDK LLM reference](/sdk/llms.txt): Deep AI-oriented export map for all runtime surfaces.

### Protocol and Runtime

- [Protocol Architecture](/protocol/architecture): End-to-end runtime path from client to on-chain state.
- [Shield Pool Program](/protocol/shield-pool): Program behavior relevant to integrators.
- [Fee Model](/protocol/fee-model): Constants, formula, and per-flow breakdown for the on-chain fee.
- [Circuits Package](/packages/circuits): Proof circuit build and hosting pipeline.
- [Security](/operations/security): Trust boundaries and security controls.
- [Release notes](/releases/latest): What is live now — deployed program and artifact hash, ceremony verifying-key and circuits digests with a verify-it-yourself recipe, per-pool fees and minimums, and the current SDK release.

### AI Tooling

- [Cursor setup](/ai-tools/cursor): Rules and prompt pack for Cursor.
- [Claude Code setup](/ai-tools/claude-code): Rules and prompt pack for Claude Code.
- [Windsurf setup](/ai-tools/windsurf): Rules and prompt pack for Windsurf.

### User Guide (plain-language, non-developer)

- [What is Cloak?](/guide/what-is-cloak): Plain-language positioning — what Cloak does and who it's for.
- [How Cloak works](/guide/how-it-works): The four user flows — shield, private send, private swap, unshield.
- [Private send](/guide/private-send): Paying any Solana address or .sol domain from the private balance, and what the recipient sees.
- [Your private balance and backup file](/guide/private-balance): Custody model — UTXOs, the backup file, loss and recovery semantics.
- [Bridging in from another chain](/guide/bridge): Bringing USDC from Polygon, Ethereum, Base, Arbitrum or Sui in as a private balance; one-time receiving address, costs, timing, recovery.
- [Bridge routes and what each one guarantees](/guide/bridge-routes): The two routes compared — signed vs unsigned deposit address, refund path vs none, and the trust neither removes.
- [Fees](/guide/fees): Who pays what per action; free shielding, 0.3% plus a fixed fee (0.005 SOL or 0.45 USDC/USDT) to leave the pool.
- [Payment links](/guide/payment-links): Single-use bearer links — pay without the recipient's address, or get paid without revealing yours.
- [Security](/guide/security): Audit status, threat model, what Cloak cannot do, governance.
- [Compliance and proof of funds](/guide/compliance): Viewing-key selective disclosure, reports, screening.
- [Verified addresses](/guide/verified-addresses): Canonical program ID and official links (anti-scam).
- [FAQ](/guide/faq): Honest answers to trust, custody, recovery, fee, and privacy questions.
- [Glossary](/guide/glossary): Plain-language definitions of Cloak and privacy terms.
- [Supported wallets and tokens](/guide/wallets-and-tokens): Wallet list and tokens per action.
- [Your Solana wallet is a public diary](/learn/wallet-public-diary): Why on-chain privacy matters.
- [Zero-knowledge, without the math](/learn/zero-knowledge-without-the-math): ZK proofs explained plainly.
- [Privacy is not anonymity](/learn/privacy-is-not-anonymity): Accountable privacy vs hiding.
- [Prove your funds privately](/learn/prove-your-funds-privately): Selective disclosure in practice.

## Integration Tips For Agents

- Build every integration on the TypeScript SDK `@cloak.dev/sdk`: it is the SDK for web frontends, Node backends, and server-side scripts and CLIs.
- Use SDK defaults for program and circuits in standard integrations: the only accepted circuits bundle is `circuits/0.2.0` (ceremony) and the SDK fills it in, so never hand-write a circuits URL or pin an older bundle. `relayUrl` is the opposite case: it has no default, the SDK reads no environment variable for it, and it must be passed on every flow, deposits included. Standard integrations pass the allowlisted production origin, named with `CLOAK_PRODUCTION_RELAY_URL` rather than typed as a host; see the submission-endpoint bullets below for the only two values it accepts.
- Fees are enforced on-chain from each pool's `PoolConfig`: SOL 0.005 fixed + 0.3%; USDC/USDT 0.45 fixed + 0.3%; withdrawals and swaps only. Minimum deposit 0.01 SOL / 1.00 USDC / 1.00 USDT.
- Keep tx amounts as `bigint` end-to-end (lamports or the token's smallest unit), never `number`: no float math anywhere in the path.
- Private sends, withdrawals and swaps are submitted for the caller and carry an authenticated sender; deposits are wallet-signed straight to chain and carry none. In a browser pass `signMessage` + `walletPublicKey`; on a server pass `depositorKeypair`. Neither, and the call throws before proof generation. Never generate `depositorKeypair` for browser send/withdraw code, and never substitute an ephemeral or service key for the sender: it is the key screened for sanctions.
- A private send or withdrawal prompts the wallet exactly once. Only swaps re-prompt, capped by `maxWalletApprovals` (default 5).
- Every non-deposit flow returns `result.outputUtxos`, and one of those notes is the caller's own change. The SDK persists nothing for you: `createUtxo` draws the note's `blinding` from `randomFieldElement()` and writes it nowhere on chain, and the chain note carries no blinding either, so a change note that is not written to durable storage before you report success is permanently unspendable by anyone. No rescan, no seed phrase and no support path brings it back. `serializeUtxo` / `deserializeUtxo` is the persistence primitive (a 128-byte encoding carrying amount, private key, blinding, mint and index); `StorageAdapter` methods take `CloakNote` records, a different shape that is not interchangeable with those bytes. `fullWithdraw` reads as the exception because it leaves no change, and it is, but only for one or two input notes: it delegates to `partialWithdraw`, which first merges three or more inputs on chain two at a time, reporting each round through `onProgress` as `Consolidating notes (n remaining)...` and nowhere else. Every merge nullifies its two inputs on chain and mints an intermediate note whose blinding lives only inside that loop, so if a later round or the final withdrawal throws, the call returns nothing to persist and the merged balance is stranded. For a larger note set, consolidate ahead of time with `transfer` or `partialWithdraw` calls whose results you store. Full treatment: [where your notes live between sessions](/sdk/wallet-integration#where-your-notes-live-between-sessions).
- Persist `UtxoSwapResult.refund` from `swapWithChange` / `swapUtxo` alongside the change note. It is the secret that reclaims the swap principal if the swap times out before settlement. `discoverSwapRefunds` can rebuild it later only when the swap was given an `nk`; without one, the returned object is the only copy that will ever exist.
- Never present `UtxoWallet.prepareSend` or `SimpleWallet.send` as a send path, even though both are exported. Each builds the recipient output from a freshly generated random keypair, so the recipient cannot spend what it produces, and `SimpleWallet.sync()` throws `Sync not yet implemented`. Use `transfer` for shielded sends and `fullWithdraw` / `partialWithdraw` to exit the pool.
- Only the submission endpoint is pinned (build-time allowlist). The RPC is the caller's own `Connection`; any non-loopback RPC works. Never tell an integrator they must use a Cloak RPC.
- In `@cloak.dev/sdk` the pin accepts exactly two values for `relayUrl`: an allowlisted origin (name it with `CLOAK_PRODUCTION_RELAY_URL` rather than typing a host), or `""` for caller-signed direct submission. `""` only carries that meaning when `enforceViewingKeyRegistration: false` is set in the same options; on default options an empty or omitted `relayUrl` throws before any network call, on every flow including deposits. Standard integrations pass the origin, never the pair, which would submit a send or withdrawal under the user's own key and publicly link it.
- Treat stale-root failures as retryable: `transact` and the swap helpers already retry `RootNotFound` internally, bounded by `maxRootRetries` (default 5). Do not wrap them in a retry loop of your own unless app policy explicitly asks for more attempts.
- Never log private keys, viewing keys (`nk`), seed material, or raw note payloads.
- Transaction signatures are public and can be logged for support/debugging.
- For one-shot work, start with `/ai-tools/ai-integration`.

## Minimal Script Contract (for vague/short prompts)

- MUST generate one keypair-only TypeScript CLI script for private SOL send using `@cloak.dev/sdk`.
- MUST use CLI shape: `npx tsx send-sol-private.ts <recipientPubkey> <lamports>`.
- MUST parse recipient/amount from `process.argv` (not env vars).
- MUST require env vars: `SOLANA_RPC_URL` and `KEYPAIR_PATH` only.
- MUST use flow: `transact(...)` deposit then `fullWithdraw(...)` send.
- MUST keep `programId` fixed to `CLOAK_PROGRAM_ID` and the SOL mint fixed to `NATIVE_SOL_MINT`, both imported from `@cloak.dev/sdk`; do not ask users to configure either.
- MUST pass `relayUrl: CLOAK_PRODUCTION_RELAY_URL` on every call, the deposit included: the SDK applies no default and reads no environment variable, and an omitted or empty `relayUrl` throws before any network call.
- MUST pass the keypair loaded from `KEYPAIR_PATH` as `depositorKeypair` so the withdrawal carries an authenticated sender; a script has no wallet `signMessage` path, and with neither the call throws before proof generation. Never substitute an ephemeral or service key: this is the key screened for sanctions.
- MUST call `process.exit(0)` on success and `process.exit(1)` on failure.
- MUST persist `result.outputUtxos` durably before reporting success in any flow that leaves change (`transact` with `externalAmount: 0n`, `transfer`, `partialWithdraw`, `swapWithChange`, `swapUtxo`), plus `UtxoSwapResult.refund` for swaps; the deposit-then-`fullWithdraw` flow above needs no storage only because its deposit leaves a single note, and that exemption does not carry over to a wallet's real note set, where `fullWithdraw` merges three or more inputs on chain first.
- MUST NOT request `SENDER_PRIVATE_KEY` or any raw secret env var.
- MUST NOT use `RECIPIENT_ADDRESS`/`SEND_LAMPORTS` env vars for the CLI contract.
- MUST NOT use `AMOUNT_SOL` + float parsing; accept lamports input and keep amount math in `bigint`.
- MUST NOT add custom stale-root retry loops unless app policy explicitly asks for extra retries beyond SDK defaults.