Technical Decision-Making
Solana tech leads face high-stakes forks: Anchor vs Pinocchio, custodial vs non-custodial keys, upgradeable vs immutable programs. Good decisions frame options, score trade-offs explicitly, and commit with a documented owner and review date.
How to Use This List
- Use each decision template when two senior engineers disagree for more than one meeting
- Rank choices for your context - "Best" assumes production DeFi, not hackathon
- Record outcome in an ADR within 48 hours
- Set ADR review date when Agave or Anchor minor versions ship
Decision 1: Anchor vs Native (Pinocchio) for a New Program
Scenario: Greenfield program; team knows Anchor 0.32.1; CU budget may matter at scale.
| Rank | Choice | Approach |
|---|---|---|
| Best | Anchor | IDL, tests, constraints; ship in one sprint |
| 2nd | Pinocchio / native | CU-critical hot path after profiling proves need |
| 3rd | Steel | Lightweight when Anchor overhead too high but some ergonomics wanted |
Wrong choice: Native on day one to "avoid bloat" without CU data - doubles security review surface.
Why best is best: Anchor constraint macros encode Sealevel checks; audit firms recognize patterns; team velocity matters pre-PMF.
Decision 2: Upgradeable vs Immutable Program
Scenario: Launching lending vault with user deposits.
| Rank | Choice | Approach |
|---|---|---|
| Best | Upgradeable + multisig + pause | Patch bugs; drill rollback |
| 2nd | Immutable | Only after audits and no planned logic changes |
| 3rd | Upgradeable hot key | Never for production user funds |
Wrong choice: Immutable at launch "to look decentralized" - cannot patch exploit without migration.
Why best is best: Solana exploits move fast; multisig upgrade with verifiable builds balances trust and safety.
Decision 3: Client SDK - @solana/kit vs Legacy web3.js
Scenario: New Next.js dApp in 2026.
| Rank | Choice | Approach |
|---|---|---|
| Best | @solana/kit 7.0.0 | Typed RPC, codecs, tree-shakeable |
| 2nd | Anchor TS client | Heavy Anchor CPI from same repo |
| 3rd | web3.js v1 | Legacy maintenance only |
Wrong choice: New project on unmaintained patterns - migration cost hits at launch crunch.
Why best is best: Kit aligns with Agave 4.1.1 RPC and long-term Solana foundation direction.
Decision 4: RPC - Single Provider vs Multi
Scenario: Production wallet app; 10k DAU.
| Rank | Choice | Approach |
|---|---|---|
| Best | Primary write + secondary read failover | SWQoS on send path |
| 2nd | Single premium provider | Acceptable under 2k DAU with SLA |
| 3rd | Public RPC | Dev only |
Wrong choice: Public mainnet RPC for mint day - rate limits become your outage.
Why best is best: Landing and read availability dominate support tickets; failover is cheaper than incident MTTR.
Decision 5: Indexer - Build vs Buy
Scenario: Need history beyond RPC getSignaturesForAddress.
| Rank | Choice | Approach |
|---|---|---|
| Best | Managed indexer (Helius, etc.) | Ship product; SLAs |
| 2nd | Yellowstone gRPC self-host | Scale or custom parsing |
| 3rd | Poll RPC in cron | Prototype only |
Wrong choice: GPA loops in API route at scale - 429 your own production.
Why best is best: Engineering time better spent on program security than ops indexer unless core competency.
Decision 6: Testing - LiteSVM vs Test Validator
Scenario: CI for Anchor program PRs.
| Rank | Choice | Approach |
|---|---|---|
| Best | LiteSVM 0.6.x in CI | Fast, deterministic |
| 2nd | Surfpool 0.12.0 | Mainnet account clone scenarios |
| 3rd | solana-test-validator | Local manual debug |
Wrong choice: Devnet as CI gate - flaky and rate-limited.
Why best is best: Sub-second tests enable security regression on every PR.
FAQs
How many options per decision?
Three maximum in the decision doc; more causes fatigue.
Who makes the final call?
Tech lead or architect; PM input on user-visible trade-offs.
When revisit a decision?
ADR review date or material Agave/Anchor upgrade.
Disagree-and-commit?
Record dissent in ADR; supporter owns outcome metrics.
Spikes before deciding?
Time-box 2-3 days for CU or landing unknowns.
Community governance?
Token votes for protocol params; engineering ADRs for implementation.
Decision fatigue signs?
Same debate every sprint - missing ADR or unclear owner.
Junior engineer input?
Required in design review; decision owner still named senior.
Escalate when?
Irreversible + high funds risk + disagreement after two meetings.
Template location?
docs/adr/ in repo; link from architecture README.
Related
- Architecture Decision Records (ADRs) - document outcomes
- Running Design Reviews - facilitate debate
- Handling Technical Disagreements - de-escalation
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.