Clusters & Networks

Q: What RPC URL should I use for mainnet?

Public: https://api.mainnet-beta.solana.com. Production apps should use a dedicated provider (Helius, Triton, QuickNode, etc.).

Q: Does localnet persist state between restarts?

Only if you omit --reset. With --reset, the ledger starts fresh each time.

Q: Can I clone mainnet accounts to localnet?

Yes, with solana-test-validator --clone . Useful for testing against real program deployments.

Q: Should CI use devnet or localnet?

Localnet (Surfpool or solana-test-validator) is faster and free of rate limits. Use devnet only for occasional integration smoke tests.

Solana runs multiple clusters - independent blockchains with their own validator sets, genesis hashes, and token economics. Picking the right cluster keeps your development safe and predictable.

Recipe

Quick-reference recipe card - copy-paste ready.

# Point CLI at a cluster
solana config set --url devnet
solana config set --url https://api.mainnet-beta.solana.com
 
# Verify current cluster
solana config get
 
# Start a local Agave 4.1.1 validator
solana-test-validator --reset

When to reach for this:

Bootstrapping a new project on devnet with free test SOL
Running integration tests against a local validator
Deploying a program to mainnet-beta for production
Debugging transaction failures in an isolated environment
Matching your RPC URL to the cluster where accounts were created

Working Example

#!/bin/bash
# devnet-workflow.sh - Solana CLI 3.0.10
 
set -e
 
# 1. Configure devnet
solana config set --url devnet
echo "Cluster: $(solana config get | grep 'RPC URL')"
 
# 2. Create a dev wallet
solana-keygen new --no-bip39-passphrase -o ./dev-keypair.json --force
PUBKEY=$(solana-keygen pubkey ./dev-keypair.json)
echo "Wallet: $PUBKEY"
 
# 3. Fund from faucet
solana airdrop 2 ./dev-keypair.json
solana balance ./dev-keypair.json
 
# 4. Verify genesis matches devnet
solana genesis-hash
# devnet genesis: EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG

import { createSolanaRpc } from "@solana/kit";
 
// RPC URL must match the cluster where your accounts live
const devnet = createSolanaRpc("https://api.devnet.solana.com");
const mainnet = createSolanaRpc("https://api.mainnet-beta.solana.com");
 
const { value: version } = await devnet.getVersion().send();
console.log("Agave version:", version["solana-core"]);

What this demonstrates:

CLI config set --url determines where all subsequent commands send transactions
Airdrops only work on devnet/testnet - not mainnet-beta
Genesis hash uniquely identifies a cluster - mismatched RPC means missing accounts
Kit RPC clients are cluster-specific - instantiate one per environment

Deep Dive

How It Works

Each cluster has its own genesis block, validator set, and ledger history
Transactions signed for one cluster are invalid on another (different recent blockhash)
Program IDs can differ across clusters if deployed separately
Public RPC endpoints are rate-limited; production apps use dedicated providers

Clusters at a Glance

Cluster	Purpose	SOL	Airdrop	Stability
devnet	App development	Test (no value)	Yes	Moderate
testnet	Validator/protocol testing	Test	Yes	Lower
mainnet-beta	Production	Real value	No	Highest
localnet	Local `solana-test-validator`	Unlimited local	N/A	You control it

Local Validator Options

# Fresh ledger, default ports
solana-test-validator --reset
 
# Clone a mainnet program for local testing
solana-test-validator --clone-upgradeable-program <PROGRAM_ID> --url mainnet-beta
 
# Point CLI at local validator
solana config set --url http://127.0.0.1:8899

Rust Notes

// In tests, use LiteSVM 0.6.x or Surfpool 0.12.0 for programmatic local clusters
// Anchor test with Surfpool:
// [scripts]
// test = "npx surfpool run anchor test"

Gotchas

Wrong RPC for existing accounts - devnet keypairs have zero balance on mainnet. Fix: match RPC URL to where accounts were created.
Using mainnet keys on devnet - safe, but reverse is catastrophic. Fix: use separate keypair files per cluster; never airdrop on mainnet.
Hardcoded program IDs across clusters - deployed addresses differ per cluster. Fix: use environment config or declare_id! per deployment.
Public RPC rate limits - devnet airdrops and heavy reads get throttled. Fix: use a dedicated RPC provider or local validator for CI.
Testnet instability - breaks more often than devnet. Fix: use devnet for app dev, testnet only for validator work.
Genesis hash mismatch in CI - stale validator image vs expected cluster. Fix: pin Agave 4.1.1 and verify genesis in test setup.

Alternatives

Alternative	Use When	Don't Use When
`solana-test-validator`	Full local control, fast iteration	You need mainnet program state
Surfpool 0.12.0	Anchor integration tests with fixtures	One-off CLI experiments
LiteSVM 0.6.x	Unit tests without a full validator	Testing network-level behavior
Devnet	Shared public sandbox	Load testing or guaranteed uptime

FAQs

What is the difference between devnet and testnet?

Devnet is for application developers. Testnet is for validator and protocol testing. Devnet is more stable for day-to-day app work.

Can I use the same keypair on all clusters?

Yes - keypairs are cluster-agnostic. But account state (balances, programs) is per-cluster.

How do I get test SOL on devnet?

solana airdrop 2

Limited to a few SOL per request. Use web faucets if rate-limited.

What RPC URL should I use for mainnet?

Public: https://api.mainnet-beta.solana.com. Production apps should use a dedicated provider (Helius, Triton, QuickNode, etc.).

How do I verify which cluster I am connected to?

solana genesis-hash
solana cluster-version

Does localnet persist state between restarts?

Only if you omit --reset. With --reset, the ledger starts fresh each time.

Can I clone mainnet accounts to localnet?

Yes, with solana-test-validator --clone <PUBKEY>. Useful for testing against real program deployments.

Why do my transactions fail after switching clusters?

Recent blockhashes are cluster-specific. Fetch a new blockhash from the target cluster's RPC.

Is devnet SOL worth anything?

No. It has no market value and can be minted freely via airdrops.

What Agave version runs on public clusters?

Public clusters track stable Agave releases. Pin your local tooling to Agave 4.1.1 to match this documentation.

Should CI use devnet or localnet?

Localnet (Surfpool or solana-test-validator) is faster and free of rate limits. Use devnet only for occasional integration smoke tests.

How do explorers know which cluster to show?

Pass ?cluster=devnet or ?cluster=mainnet-beta in the URL. Default is mainnet-beta.

Solana Basics - first steps on devnet
Wallets & Explorers - devnet workflow and faucets
Keypairs & Addresses - per-cluster key management

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.

Recipe

Quick-reference recipe card - copy-paste ready.

# Point CLI at a cluster
solana config set --url devnet
solana config set --url https://api.mainnet-beta.solana.com
 
# Verify current cluster
solana config get
 
# Start a local Agave 4.1.1 validator
solana-test-validator --reset

When to reach for this:

Bootstrapping a new project on devnet with free test SOL
Running integration tests against a local validator
Deploying a program to mainnet-beta for production
Debugging transaction failures in an isolated environment
Matching your RPC URL to the cluster where accounts were created

Working Example

#!/bin/bash
# devnet-workflow.sh - Solana CLI 3.0.10
 
set -e
 
# 1. Configure devnet
solana config set --url devnet
echo "Cluster: $(solana config get | grep 'RPC URL')"
 
# 2. Create a dev wallet
solana-keygen new --no-bip39-passphrase -o ./dev-keypair.json --force
PUBKEY=$(solana-keygen pubkey ./dev-keypair.json)
echo "Wallet: $PUBKEY"
 
# 3. Fund from faucet
solana airdrop 2 ./dev-keypair.json
solana balance ./dev-keypair.json
 
# 4. Verify genesis matches devnet
solana genesis-hash
# devnet genesis: EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG

import { createSolanaRpc } from "@solana/kit";
 
// RPC URL must match the cluster where your accounts live
const devnet = createSolanaRpc("https://api.devnet.solana.com");
const mainnet = createSolanaRpc("https://api.mainnet-beta.solana.com");
 
const { value: version } = await devnet.getVersion().send();
console.log("Agave version:", version["solana-core"]);

What this demonstrates:

CLI config set --url determines where all subsequent commands send transactions
Airdrops only work on devnet/testnet - not mainnet-beta
Genesis hash uniquely identifies a cluster - mismatched RPC means missing accounts
Kit RPC clients are cluster-specific - instantiate one per environment

Deep Dive

How It Works

Each cluster has its own genesis block, validator set, and ledger history
Transactions signed for one cluster are invalid on another (different recent blockhash)
Program IDs can differ across clusters if deployed separately
Public RPC endpoints are rate-limited; production apps use dedicated providers

Clusters at a Glance

Cluster	Purpose	SOL	Airdrop	Stability
devnet	App development	Test (no value)	Yes	Moderate
testnet	Validator/protocol testing	Test	Yes	Lower
mainnet-beta	Production	Real value	No	Highest
localnet	Local `solana-test-validator`	Unlimited local	N/A	You control it

Local Validator Options

# Fresh ledger, default ports
solana-test-validator --reset
 
# Clone a mainnet program for local testing
solana-test-validator --clone-upgradeable-program <PROGRAM_ID> --url mainnet-beta
 
# Point CLI at local validator
solana config set --url http://127.0.0.1:8899

Rust Notes

// In tests, use LiteSVM 0.6.x or Surfpool 0.12.0 for programmatic local clusters
// Anchor test with Surfpool:
// [scripts]
// test = "npx surfpool run anchor test"

Gotchas

Wrong RPC for existing accounts - devnet keypairs have zero balance on mainnet. Fix: match RPC URL to where accounts were created.
Using mainnet keys on devnet - safe, but reverse is catastrophic. Fix: use separate keypair files per cluster; never airdrop on mainnet.
Hardcoded program IDs across clusters - deployed addresses differ per cluster. Fix: use environment config or declare_id! per deployment.
Public RPC rate limits - devnet airdrops and heavy reads get throttled. Fix: use a dedicated RPC provider or local validator for CI.
Testnet instability - breaks more often than devnet. Fix: use devnet for app dev, testnet only for validator work.
Genesis hash mismatch in CI - stale validator image vs expected cluster. Fix: pin Agave 4.1.1 and verify genesis in test setup.

Alternatives

Alternative	Use When	Don't Use When
`solana-test-validator`	Full local control, fast iteration	You need mainnet program state
Surfpool 0.12.0	Anchor integration tests with fixtures	One-off CLI experiments
LiteSVM 0.6.x	Unit tests without a full validator	Testing network-level behavior
Devnet	Shared public sandbox	Load testing or guaranteed uptime

FAQs

What is the difference between devnet and testnet?

Devnet is for application developers. Testnet is for validator and protocol testing. Devnet is more stable for day-to-day app work.

Can I use the same keypair on all clusters?

Yes - keypairs are cluster-agnostic. But account state (balances, programs) is per-cluster.

How do I get test SOL on devnet?

solana airdrop 2

Limited to a few SOL per request. Use web faucets if rate-limited.

What RPC URL should I use for mainnet?

Public: https://api.mainnet-beta.solana.com. Production apps should use a dedicated provider (Helius, Triton, QuickNode, etc.).

How do I verify which cluster I am connected to?

solana genesis-hash
solana cluster-version

Does localnet persist state between restarts?

Only if you omit --reset. With --reset, the ledger starts fresh each time.

Can I clone mainnet accounts to localnet?

Yes, with solana-test-validator --clone <PUBKEY>. Useful for testing against real program deployments.

Why do my transactions fail after switching clusters?

Recent blockhashes are cluster-specific. Fetch a new blockhash from the target cluster's RPC.

Is devnet SOL worth anything?

No. It has no market value and can be minted freely via airdrops.

What Agave version runs on public clusters?

Public clusters track stable Agave releases. Pin your local tooling to Agave 4.1.1 to match this documentation.

Should CI use devnet or localnet?

Localnet (Surfpool or solana-test-validator) is faster and free of rate limits. Use devnet only for occasional integration smoke tests.

How do explorers know which cluster to show?

Pass ?cluster=devnet or ?cluster=mainnet-beta in the URL. Default is mainnet-beta.

Solana Basics - first steps on devnet
Wallets & Explorers - devnet workflow and faucets
Keypairs & Addresses - per-cluster key management

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.

Clusters & Networks

Search Documentation

Clusters & Networks