--- name: cloak description: Private onchain actions for AI agents on Solana. Use this skill whenever an agent needs to pay, receive, swap, or call a program WITHOUT linking the action to its main wallet or revealing its transaction history. Routes actions through the Cloak shielded pool (zk-SNARK proofs, relayer submission, stealth receive addresses). version: 0.3.0 homepage: https://usecloak.pro allowed-tools: Bash(cloak:*) --- # Cloak — Privacy Route for AI Agents Cloak sits between an agent and Solana: ``` AI Agent → Cloak Privacy Route → Solana ``` Instead of signing transactions directly from one long-lived wallet (which links every action together), the agent shields funds into a zero-knowledge pool once, then spends from it. Each outgoing action appears onchain from a fresh, unlinked address, submitted by a relayer. Each incoming payment lands on a one-time stealth address. Observers cannot connect the agent's actions to each other or to its identity. **Use this skill when** the user asks for privacy, unlinkability, "don't dox my wallet", stealth payments, or when the agent's operating policy says onchain actions must not be attributable to a shared treasury. **Do not use this skill** for actions that must be publicly attributable (e.g. a DAO vote that needs to come from a known address), or when the user explicitly wants a public transaction. --- ## Quick start ```bash # 1. Install the CLI (bundles a local WASM prover) npm i -g @cloak/cli # or: cargo install cloak-cli # 2. Point it at a network and your existing agent keypair cloak init --keypair ~/.config/solana/id.json # 3. Shield funds into the private pool (public → private, one time) cloak shield 1.5 SOL # 4. Act privately cloak pay 7xKX...9fQ 25 USDC ``` `cloak init` derives a **spending key** and a **viewing key** from the agent's existing Solana keypair. No new seed phrase. Keys live in `~/.cloak/` with `0600` permissions. --- ## Mental model | Term | Meaning | |---|---| | **Shield** | Move public funds into the pool. This is the *only* public link to the agent's wallet. Do it in round amounts, in advance, not immediately before a private action. | | **Note** | A private UTXO inside the pool. Only the spending key can spend it. | | **Proof** | A zk-SNARK, generated locally, proving "I own an unspent note of ≥ X" without revealing which note. 1–3 s on commodity hardware. | | **Relayer** | A third party that submits the proven transaction and pays network fees. Cannot move funds. It is reimbursed exactly the network fee, which is a public input to the proof and is taken from the note. | | **Stealth address** | A one-time Solana address derived from the agent's viewing key. Each payer gets a different one. | | **Viewing key** | Read-only key that reveals the agent's history. Share with an auditor/operator if selective disclosure is required. Never share the spending key. | --- ## Commands Every command accepts `--json` and returns a single JSON object on stdout. Exit code `0` = success, `1` = user/input error, `2` = network/relayer error (retryable), `3` = proof failure. ### `cloak balance` Private balance across all unspent notes. ```bash cloak balance --json # {"ok":true,"balances":{"SOL":"0.9000","USDC":"140.00"},"notes":3,"network":"mainnet-beta"} ``` ### `cloak shield ` Public → private deposit. Signs with the agent's normal keypair. **Public onchain.** ```bash cloak shield 2 SOL --json # {"ok":true,"sig":"4Gw...Cua7","note":"n_8f2c...","amount":"2","token":"SOL"} ``` Guidance: shield larger, round amounts ahead of time. Shielding `25.00 USDC` and paying `25.00 USDC` two minutes later is a timing/amount correlation leak. ### `cloak pay [--memo ]` Private → public send. Recipient sees funds arriving from a fresh relayer-submitted address with no history. ```bash cloak pay 7xKX...9fQ 25 USDC --json # {"ok":true,"sig":"9Lm...Q2vD","from":"fresh","fee":{"network":"0.000012 SOL"},"proof_ms":1810} ``` `--memo` is encrypted to the recipient's viewing key if they are a Cloak user; otherwise it is dropped (never posted in plaintext). ### `cloak receive [--stealth] [--label ]` Generate a one-time address to give to a payer. Funds sent there are auto-detected by the local scanner and become notes. ```bash cloak receive --stealth --label "invoice-2291" --json # {"ok":true,"address":"3Ff...kP1","expires":null,"label":"invoice-2291"} ``` Give **a different stealth address to every payer**. Reusing one links those payers together. ### `cloak swap [--slippage ]` Private swap routed via Jupiter from inside the pool. Output returns as a new note. No pre-trade wallet is exposed, so there is no sandwichable intent. ```bash cloak swap SOL USDC 2.5 --slippage 50 --json # {"ok":true,"sig":"Ht7...a9Xe","in":"2.5 SOL","out":"410.94 USDC","route":"jupiter","fee":{"protocol":"0.0075 SOL","network":"0.000012 SOL"},"proof_ms":2140} ``` Swaps carry a 0.3% protocol fee on the input amount (the only protocol fee Cloak charges). It is taken inside the pool and 100% of it is used to buy and burn CLOAK. Quote the net output to the user; `out` is already net of the fee. ### `cloak call --program --ix [--accounts ] [--fund ]` Execute an arbitrary program instruction from an **ephemeral session key** funded from the pool. The program sees a throwaway signer. ```bash cloak call --program Stake11111111111111111111111111111111111111 \ --ix "AQAAAA..." --fund 0.5 SOL --json # {"ok":true,"sig":"Bq2...m8Zd","signer":"ephemeral","swept":true} ``` Any leftover balance on the session key is swept back into the pool after execution (`swept: true`). If sweep fails, the response includes `"leftover"` and the key path so it can be recovered. ### `cloak unshield [--to
]` Private → public withdrawal to the agent's own wallet or any address. **This re-links funds to a public address.** Use only when a public balance is genuinely required. ### `cloak viewkey export [--to ]` / `cloak viewkey import ` Export the read-only viewing key for an auditor or operator, or import one to scan on behalf of another agent. ### `cloak history [--since ]` Local, private ledger of everything this agent has done through Cloak. Never leaves the machine. ### `cloak status` Network, relayer health, prover version, pending notes, anonymity set size, and fee-vault balances pending buyback. --- ## Operating rules for agents 1. **Shield ahead of time, in round amounts.** Never shield-then-spend in the same task if avoidable. 2. **One stealth address per counterparty.** Call `cloak receive --stealth` every time; never cache and reuse. 3. **Never `unshield` back to the origin wallet** unless the user explicitly asks. It undoes the privacy. 4. **Never print, log, or send the spending key** (`~/.cloak/spend.key`). Viewing keys may be shared only when the user explicitly authorises disclosure. 5. **Prefer `cloak swap` over `unshield` + public DEX trade.** 6. **Check `cloak balance` before spending.** If insufficient, ask the user whether to shield more — do not silently shield, because shielding is a public transaction from their wallet. 7. **Respect exit codes.** Exit `2` (relayer/network) → retry up to 3× with backoff. Exit `3` (proof) → do not retry; report the `error` field verbatim. Exit `1` → fix the input. 8. **Report what the counterparty can see.** After a `pay`, tell the user: "Recipient sees X from a fresh address; no link to your wallet." --- ## Failure modes | `error` code | Meaning | Agent action | |---|---|---| | `INSUFFICIENT_NOTES` | No combination of notes covers amount + fees | Report balance; ask user before shielding | | `RELAYER_UNAVAILABLE` | All relayers down or rate-limited | Retry with backoff; `cloak status` for detail | | `PROOF_FAILED` | Local prover error (usually stale Merkle root) | Run `cloak sync` once, then retry once | | `SLIPPAGE_EXCEEDED` | Swap quote moved beyond `--slippage` | Re-quote; ask user if > 1% | | `RECIPIENT_INVALID` | Not a valid Solana address / stealth address | Fix input | | `KEY_LOCKED` | Spending key requires unlock | Ask user to run `cloak unlock` interactively; never handle the passphrase yourself | --- ## What Cloak does NOT hide Be honest with the user about the boundaries: - **The shield transaction is public.** Anyone can see that the agent's wallet deposited N SOL into the Cloak pool. They cannot see what happened after. - **Amounts on exit are visible** to the recipient (they receive them). Amount correlation across shield/pay is the main heuristic attack — hence round amounts and time gaps. - **Anonymity set size matters.** Check `cloak status` → `anonymity_set` before making privacy claims to the user; a small set for a given token weakens the guarantee. - **Cloak does not hide the agent's IP** from the relayer. Run the CLI behind a proxy/Tor if network-level privacy is needed. --- ## Networks | Network | Program ID | |---|---| | Solana mainnet-beta | `CLoak1111111111111111111111111111111111111` | `cloak init` targets mainnet-beta by default. Pass `--network devnet` only for local testing against the devnet deployment. ## Fees | Action | Fee | |---|---| | `shield`, `unshield`, `pay`, `call` | Network fee only, reimbursed to the relayer from the shielded balance | | `receive` | None | | `swap` | Network fee + 0.3% protocol fee on the input amount | The network fee is estimated from recent compute usage with a single 1.25× buffer, included in the proof as a public input, and paid to the relayer by the program after verification. Relayers cannot charge more than the proven amount. There is no percentage fee on payments. 100% of the swap protocol fee is used to buy CLOAK on the open market and burn it. Holding CLOAK is not required to use Cloak and gives no discount. Full detail: https://usecloak.pro/tokenomics.md --- ## Example: agent pays an API invoice privately User: *"Pay the 12 USDC Helius invoice, but don't let them see our treasury."* ```bash cloak balance --json # USDC: 140.00 → sufficient cloak pay HeL1us...invoice 12 USDC --memo "inv-4471" --json # {"ok":true,"sig":"...","from":"fresh","fee":{...}} ``` Agent reports: "Paid 12 USDC to Helius (sig …). They see a payment from a fresh address; nothing links it to the treasury wallet. Network fee 0.000012 SOL. Remaining private balance: 128.00 USDC." --- ## Links - Site: https://usecloak.pro - This file: https://usecloak.pro/skill.md - Machine-readable index: https://usecloak.pro/llms.txt - Fees and tokenomics: https://usecloak.pro/tokenomics.md