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.toml provider 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

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.