builderz-solana-dapp-scaffold: Instructions file for Claude Code

Solana Development Rules

This file configures AI coding assistants for Solana program development. Follow these rules to produce secure, optimized, and correct code.

Modern Tooling (2025)

USE THESE - NOT OUTDATED ALTERNATIVES:

Category	Modern (Use This)	Outdated (Avoid)
Program SDK	pinocchio, solana-program 2.x	solana-program 1.x
Framework	Anchor 0.32+, Steel	Anchor < 0.30
Unit Testing	Mollusk, LiteSVM	solana-program-test alone
Local Dev	Surfpool	solana-test-validator alone
Client SDK	@solana/kit (web3.js 2.0)	@solana/web3.js 1.x
Fuzz Testing	Trident	None

Stack Configuration

Uncomment and configure based on your project:

# Framework: anchor | native | pinocchio | steel
# Client: typescript (@solana/kit) | rust | python
# Testing: mollusk | litesvm | trident | bankrun
# Local: surfpool | solana-test-validator

---

Critical Rules

NEVER

1. NEVER use deprecated crates:

   • solana-program < 2.0 → use solana-program 2.x or pinocchio
   • solana-sdk < 2.0 → use solana-sdk 2.x
   • spl-token < 5.0 → use spl-token 5.x or spl-token-2022
   • @solana/web3.js 1.x → use @solana/kit (web3.js 2.0)

2. NEVER deploy to mainnet without explicit user confirmation - always ask first

3. NEVER use unchecked arithmetic:

   // WRONG
   let total = amount_a + amount_b;
   
   // CORRECT
   let total = amount_a.checked_add(amount_b).ok_or(ErrorCode::Overflow)?;
   

4. NEVER skip account validation - every account must be validated for owner, signer status, and PDA derivation

5. NEVER hardcode keypairs, private keys, or RPC endpoints

6. NEVER use unwrap() in on-chain program code - use proper error handling

7. NEVER assume account data layout - always deserialize explicitly

ALWAYS

1. ALWAYS verify account ownership before reading/writing:

   if *account.owner != expected_program_id {
       return Err(ProgramError::IncorrectProgramId);
   }