Requirements to Technical Specs

Product asks arrive as "users should stake and earn yield." Engineering ships account layouts, CPI graphs, and wallet flows. A good spec bridges the gap with testable acceptance criteria before anyone writes Anchor handlers.

Recipe

Quick-reference recipe card - copy-paste ready.

## Feature: Stake SOL for pool shares
 
### User story
As a holder, I deposit SOL to receive pool tokens representing share.
 
### On-chain
- Accounts: PoolConfig PDA, UserPosition PDA, vault SOL account
- Instructions: deposit, withdraw
- CPIs: System Program transfer only
 
### Acceptance
- [ ] LiteSVM: deposit 1 SOL -> mint 1e9 share units
- [ ] Simulation fails if pool paused
- [ ] Client shows confirmed before success toast

When to reach for this:

• Sprint planning for new protocol feature
• Product proposes token utility change
• Auditor needs feature scope document
• Translating community governance proposal to engineering

Working Example

## Spec: SPL reward claim (v1)
 
**In scope**
- Claim accrued rewards to user ATA
- Read-only preview via RPC simulate
 
**Out of scope**
- Auto-compound (v2 RFC)
- Governance vote to change emission rate
 
**Security**
- Only position owner may claim
- Rewards vault PDA signs transfer via seeds
 
**UX**
- Wallet signs one tx; show CU estimate
- Error map: Paused, NothingToClaim, InsufficientRent

What this demonstrates:

• Explicit out-of-scope prevents mid-sprint surprises
• Security bullets become review checklist
• UX error mapping ties program ErrorCode to copy

Deep Dive

Spec Layers

Gotchas

• Vague "support NFTs" - cNFT vs Metaplex vs Core differ 10x in effort. Fix: Name standard and scale.
• No failure cases - Only happy path acceptance. Fix: Attacker and edge cases per instruction.
• Tokenomics hand-wavy - "Community decides" without authority. Fix: Multisig vs governance program spelled out.
• Spec without RPC impact - GPA-heavy feature melts infra. Fix: Read path and indexer noted.
• Changing spec without version bump - Client and program drift. Fix: Spec version in ticket title.

Alternatives

FAQs

Related

• Running Design Reviews - spec to RFC
• Estimation & Risk - sizing from spec
• Stakeholder Communication - sharing progress

Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.

3730363230327c3532336f6967637c6f692e73656469756765646f63