{"filename":"solana-wallet-aware.mdc","content":"---\ndescription: \"Guidelines for writing Solana-native code with wallet-security awareness, isolated signer subprocesses, MEV defense, oracle gates, and transaction safety checks\"\nglobs: **/*.{ts,tsx,js,jsx,py,rs}\nalwaysApply: false\n---\n# Solana Wallet-Aware Coding\n\nWhen writing Solana on-chain or off-chain code, apply these wallet-safety and transaction-safety rules.\n\n## Wallet architecture\n\n- Never store a raw private key in `.env`, config files, or source. Encrypt with a passphrase-derived key (HKDF-SHA256 + AES-256-GCM, or `eth-account`'s scrypt V3 keystore, or `libsodium`'s sealed-box).\n- Use a three-tier wallet split at $1k+ scale: **hot** (bot-signing, ≤10% of AUM), **warm** (manual-top-up buffer on founder phone, ~30%), **cold** (hardware wallet or Squads 2-of-2 multisig, ~60%, untouchable ≥6 months).\n- Treat the hot wallet as burnable. Any key that ever touched a `.env` file on a dev machine is compromised forever.\n- Isolate the signer in a subprocess with only two capabilities: (a) receive a pre-built transaction over a local Unix socket / stdin, (b) return a signature. No network access, no program-scope escalation, explicit allowlist of program IDs.\n\n## MEV defense on Solana\n\n- Never broadcast swaps to the public mempool. Always use Jito bundles with a per-bundle tip (start at 10k lamports, scale with expected profit).\n- Add an oracle gate: reject a trade if Jupiter's quoted price is > 0.5% off Pyth's spot price. Update threshold dynamically with 1-minute realized volatility.\n- Maintain an illiquidity blocklist: skip any token where the deepest pool has < $1M TVL (use GeckoTerminal or Birdeye API to check).\n- For limit-style orders, prefer Jupiter's limit-order program (built-in MEV protection) over composing your own.\n\n## Program-ID allowlist pattern\n\nWhen building a signer, hard-code the list of program IDs your bot may invoke. Reject any transaction whose instructions touch a program outside the allowlist. At minimum for a Solana trading bot:\n\n```\nconst ALLOWED_PROGRAMS = new Set([\n  \"JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4\",  // Jupiter v6\n  \"opnb2LAfJYbRMAHHvqjCwQxanZn7ReEHp1k81EohpZb\",  // OpenBook v2\n  \"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA\",  // SPL Token\n  \"ComputeBudget111111111111111111111111111111\",  // Compute budget\n  // add your DEX IDs here — NEVER include unknown programs\n]);\n```\n\n## Transaction-safety invariants\n\nBefore signing ANY transaction:\n- Deserialize + inspect every instruction. No opaque \"signTransaction(bytes)\" without parsing.\n- Enforce a max SOL outflow per transaction AND per rolling 24h window (spend-cap circuit breaker).\n- Require a freshness check on the blockhash (slot age < 150 or transaction will likely expire).\n- Compute budget ≤ 200k CU default; require explicit opt-in for higher.\n\n## Simulation gate\n\nDo not move wallet-automation code from simulation to live signing until the user has explicitly approved it and the implementation has passed fault-injection tests for signer failure, RPC failure, stale blockhashes, rejected allowlist entries, and spend-cap enforcement.\n\n## Operational safety\n\n- Keep deployment credentials, wallet keys, RPC credentials, and monitoring tokens out of source control.\n- Add health checks for signer availability, stale blockhashes, RPC error rate, and transaction failure rate.\n- Require an explicit manual approval path before raising spend caps, program allowlists, or compute-unit limits.\n"}