Localnet vs Devnet Workflow
A step-by-step workflow to choose localnet (solana-test-validator), devnet, Surfpool, or mainnet for a given development task.
How to Use This Workflow
- Start at Step 1 for each new feature or test plan.
- Record the chosen cluster in your PR description and
Anchor.tomlprovider block. - Revisit when integration scope changes (e.g., adding mainnet CPI).
- Default to localnet for CI; devnet for shared demos unless this tree says otherwise.
Step 1: Do you need mainnet-realistic state?
If yes - live pool reserves, oracle prices, or production program versions - go to Step 2. If no - you control all accounts and programs - go to Step 5.
Step 2: Is a small --clone set enough?
If yes - clone specific pubkeys into solana-test-validator - use localnet with clones (Cloning Mainnet Accounts).
If no - broad DeFi graph or frequent state refresh needed - go to Step 3.
Step 3: Do you need persistent fork simulation?
If yes - use Surfpool 0.12.0 for mainnet-fork simulate loops (Surfpool). If no - go to Step 4.
Step 4: Can you test on devnet with deployed counterparts?
If yes - use devnet with public programs and faucet funding. If no - return to Step 2 and expand clone list or adopt Surfpool.
Step 5: Is the work program-only unit/integration testing?
If yes - use localnet with anchor test and fixtures (Loading Programs & Fixtures).
If no - client wallet demos or multi-team sharing needed - go to Step 6.
Step 6: Do teammates need the same deployed program ID between laptops?
If yes - devnet deploy with documented program ID in README. If no - each engineer uses localnet deploy with local IDs or synced keypair files.
Step 7: Is CI reliability the primary concern?
If yes - localnet in GitHub Actions with --reset and committed fixtures - avoid devnet rate limits.
If no - optional nightly devnet smoke job is acceptable.
Step 8: Are you testing transaction landing under congestion?
If yes - devnet is weak signal; use devnet + priority fees for basic checks, then mainnet small probes with real SOL (Setting Priority Fees). If no - stay on localnet/devnet from prior steps.
Step 9: Do you need public wallet demos (Phantom, etc.)?
If yes - devnet with stable RPC URL and funded demo wallet.
If no - localnet works with wallet adapters pointed at localhost:8899.
Step 10: Will users spend real money in this test?
If yes - stop - use mainnet with minimal amounts and finalized confirmation only. If no - never use mainnet for this task; return to chosen localnet/devnet path.
Step 11: Document the decision
Record cluster URL, program IDs, fixture versions, and toolchain pins (Agave 4.1.1) in the PR for reproducibility.
FAQs
Why not always use devnet?
Rate limits, shared unstable state, and slower iteration hurt daily program development - localnet is faster and deterministic.
Why not always use localnet?
It lacks live network effects, peer validators, and realistic congestion - devnet/mainnet probes still matter before launch.
Where does LiteSVM fit?
Below this workflow for Rust unit tests - no RPC cluster required (LiteSVM).
Can I switch clusters mid-feature?
Yes - start local, graduate to devnet for wallet demos, then mainnet probes - update solana config and env vars each time.
What RPC URL for local Phantom?
http://127.0.0.1:8899 with wallet custom RPC - not all wallets support localhost cleanly; devnet may be easier for demos.
Related
- Local Dev Basics - local loop intro
- solana-test-validator - localnet how-to
- Surfpool - fork option
- RPC Providers - devnet/mainnet RPC quality
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.