/safe-solana-builder

name: safe-solana-builder
description: >
  Use this skill whenever the user wants to write, scaffold, or build a Solana smart contract
  or program from scratch. Triggers on: "write a Solana program", "create a smart contract",
  "build an anchor program", "write a native Rust Solana program", "scaffold a Solana program",
  "help me write a program that does X on Solana", or any request to produce production-grade
  on-chain Solana code. This skill enforces Frank Castle's security best practices and pitfall
  avoidance guidelines automatically — giving every program a first layer of protection before
  it ever reaches an auditor. Always use this skill — even for simple programs — whenever
  Solana program code is the primary deliverable.

Safe Solana Builder — by Frank Castle

You are writing production-grade Solana programs. Security is not an afterthought — it is baked into every line. Every program produced by this skill ships with a full project scaffold, a test file skeleton, and a security checklist.

What This Skill Enforces

This skill systematically addresses the following vulnerability classes derived from real Solana protocol audits:

• **Protocol-specific vulnerabilities** — oracle manipulation, fee bypass, slippage attacks, LP preprocessing gaps
• **Logic flaws & edge cases** — dust DoS, time-unit mismatches, pre/post-fee inconsistencies, type narrowing
• **Access control & authorization bugs** — missing signer checks, frontrunnable initialization, namespace capture, inbound transfer auth, post-expiry flows
• **State management errors** — coupled-field resets, counter drift, vested/unvested balance separation, rollback safety
• **Lifecycle & state machine integrity** — absorbing terminal states, canonical transition matrices, paired time-gate divergence, user-param reachability constraints
• **PDA-related issues** — zombie accounts, seed collisions, canonical bump enforcement, lifecycle closure
• **Reward accounting exploits** — rounding gaps in partial unstake, dual-path reward debt bypass, retroactive rate application, dead share price, inflation/first-depositor attack, fee-on-transfer delta errors, rewards sourced from principal
• **Vault & pool architecture** — missing withdrawal paths on PDA-controlled vaults, spendable-vs-reserved balance confusion, backing invariant violations
• **Slippage & fee ordering** — slippage on net (not gross) amount, fee base must match executed amount, unambiguous gross/fee/net naming
• **AMM / bonding-curve safety** — completion-threshold capping, post-cap slippage recheck, terminal-state solvency, reserve layer alignment
• **Config management** — every write-path validation, tri-state patch semantics, partial-update corruption, cross-field invariant enforcement, atomic commit
• **Withdraw & drain safety** — cumulative caps for partial withdrawals, liability settlement before residual extraction, exact-remainder accounting after partial drains
• **Token-2022 extension validation** — PermanentDelegate seizure, uncontrolled FreezeAuthority, TransferHook CPI forwarding, ConfidentialTransfer compatibility
• **Treasury & fee recipient hygiene** — sweepable authority requirement, config-time ATA validation
• **Admin key security** — two-step rotation pattern, timelock recommendations for Critical programs
• **BPF runtime limits** — 4096-byte stack frame DoS, Box<> mitigation for large account types
• **Panic safety** — no `unwrap()`/`expect()` on user-controlled `Option`/`Result` paths; always return typed errors
• **Input validation & metadata hygiene** — non-empty required fields, explicit length bounds, URI scheme allowlists for user-supplied strings

---

Step 1 — Ask the Framework Question

If the user has not already specified, ask exactly this (and nothing else):

> "Should I write this in **Native Rust**, **Anchor**, or **Pinocchio**?"

**Pinocchio** is Anza's zero-dependency, zero-copy framework — 88–95% CU reduction vs. Anchor. Best for high-throughput programs (DEXs, orderbooks, vaults). It is unaudited — flag this in the checklist for Critical programs.

Wait for the answer before proceeding.

---

Step 1b — Ask the Testing Question

Immediately after the framework is chosen, ask:

> "Should I use **LiteSVM** for testing (fast, in-process, no validator required), or the default testing approach for your framework?"

Present the options clearly:

| Option | Best For | |---|---| | **LiteSVM** | Fast unit/integration tests, CI pipelines, time-lock testing, CU profiling, account injection from devnet | | **Framework default** | Anchor: TypeScript with `@coral-xyz/anchor`; Native: `solana-program-test` async harness |

Wait for the answer before proceeding to Step 2.

---

Step 2 — Load Your Reference Files

Once **both** the framework and testing approach are chosen, read the following files **before writing a single line of code**:

1. **Always read first (both files):**

• `references/shared-base.md` — Core security rules, pitfall patterns, and best practices for ALL Solana programs. Sections 1–20 cover foundational security; sections 21–31 cover vulnerability-derived rules from real protocol audits (reward accounting, vault architecture, Token-2022 extension validation, admin key rotation, BPF stack frame limits, lifecycle state machine integrity, slippage/fee ordering, bonding-curve AMM safety, initialization/namespace capture, config management, withdraw/drain safety, and treasury sweepability).

2. **Then read the framework-specific file:**

• Native Rust → `references/native-rust.md`
• Anchor → `references/anchor.md`
• Pinocchio → `references/pinocchio.md`

→ Framework-specific patterns, constraints, additional pitfalls, and common build/tooling errors.

3. **If LiteSVM was chosen for testing, also read:**

• `references/litesvm.md`

→ Test structure patterns, sysvar control, token setup, account inspection, CU profiling, and the LiteSVM security test checklist.

4. **Check for a relevant exa