Solana Wallet-Aware Coding

tl;dr: pull solana-wallet-aware.mdc from awesome-cursorrules before any Solana code that touches private keys, signs transactions, or broadcasts swaps. Without these rules, models default to .env-stored keys and public-mempool broadcasts — both are catastrophic for trading bots.

What it does

This rule set configures Cursor to write Solana code that treats wallet security as a hard constraint, not an afterthought. It enforces three tiers of key custody (hot / warm / cold), isolates the signer in a subprocess with a minimal capability set, routes all swaps through Jito bundles to avoid public-mempool MEV, gates trades on a Pyth-vs-Jupiter oracle check, and refuses to move from simulation to live signing without an explicit user approval.

Sourced from PatrickJS/awesome-cursorrules — the community registry for .mdc Project Rules.

The rules

---
description: "Guidelines for writing Solana-native code with wallet-security awareness, isolated signer subprocesses, MEV defense, oracle gates, and transaction safety checks"
globs: **/*.{ts,tsx,js,jsx,py,rs}
alwaysApply: false
---

# Solana Wallet-Aware Coding

When writing Solana on-chain or off-chain code, apply these wallet-safety and transaction-safety rules.

## Wallet architecture

- 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).
- 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).
- Treat the hot wallet as burnable. Any key that ever touched a `.env` file on a dev machine is compromised forever.
- 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.

## MEV defense on Solana

- Never broadcast swaps to the public mempool. Always use Jito bundles with a per-bundle tip (start at 10k lamports, scale with expected profit).
- 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.
- Maintain an illiquidity blocklist: skip any token where the deepest pool has < $1M TVL (use GeckoTerminal or Birdeye API to check).
- For limit-style orders, prefer Jupiter's limit-order program (built-in MEV protection) over composing your own.

## Program-ID allowlist pattern

When 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.

## Transaction-safety invariants

Before signing ANY transaction:
- Deserialize + inspect every instruction. No opaque "signTransaction(bytes)" without parsing.
- Enforce a max SOL outflow per transaction AND per rolling 24h window (spend-cap circuit breaker).
- Require a freshness check on the blockhash (slot age < 150 or transaction will likely expire).
- Compute budget ≤ 200k CU default; require explicit opt-in for higher.

## Simulation gate

Do 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.

## Operational safety

- Keep deployment credentials, wallet keys, RPC credentials, and monitoring tokens out of source control.
- Add health checks for signer availability, stale blockhashes, RPC error rate, and transaction failure rate.
- Require an explicit manual approval path before raising spend caps, program allowlists, or compute-unit limits.

Installation

Drop the .mdc into .cursor/rules/ of your project:

mkdir -p .cursor/rules
curl -sL \
  https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/solana-wallet-aware.mdc \
  -o .cursor/rules/solana-wallet-aware.mdc

Cursor picks up files in .cursor/rules/ automatically. The rule has globs: **/*.{ts,tsx,js,jsx,py,rs} — it auto-attaches to any Solana-touching source file.

Why it helps

Without wallet-aware rules, models will:

• Suggest process.env.PRIVATE_KEY storage for the signer key (catastrophic if the dev machine is compromised)
• Broadcast swaps to the public mempool, exposing the bot to sandwich attacks and frontrunning
• Call signTransaction(bytes) on opaque base64, skipping instruction inspection and the allowlist check
• Skip the simulation gate and wire live signing into a bot that has not been fault-injection tested
• Skip blockhash freshness checks, producing transactions that expire before landing

These rules block the four most common Solana-trading failures that lose money on day one.

Gotchas

• These are Cursor .mdc rules, not a Claude Code CLAUDE.md file. For Claude Code, paraphrase into your project’s CLAUDE.md.
• The signer subprocess pattern assumes a Unix-like host. On Windows, swap the Unix socket for a named pipe; the rule body does not handle that for you.
• The 0.5% oracle-gate threshold is for liquid majors. For long-tail tokens, raise it to 1.5–2% or the gate will reject every trade.
• globs: **/*.{ts,tsx,js,jsx,py,rs} means the rule loads for any TypeScript, JavaScript, Python, or Rust file — not just Solana files. Tighten the glob to **/solana/** or **/programs/**/*.rs if the project is mixed-stack.
• The hot/warm/cold split assumes a single-asset AUM above $1k. For sub-$1k dev wallets, the tier model is overkill — use a single hardware wallet.

Related

• Toss-Style Design System — sibling safety/quality rule on animations
• JavaScript/TypeScript Code Quality — pairs well for the off-chain bot logic around the signer