Clusters | Solana — BizFirstAI

Vocabulary: Solana calls its environments clusters, not "networks" — this node keeps that vocabulary rather than relabeling it to match other chains' node config.

Cluster	RPC URL (well-known default)	Use For
`mainnet-beta`	`https://api.mainnet-beta.solana.com`	Default cluster. Production. Real SOL, real fees on any write operation.
`devnet`	`https://api.devnet.solana.com`	Free faucet SOL available (`solana airdrop`) — safe for development and CI.
`testnet`	`https://api.testnet.solana.com`	Validator/dApp stress-testing cluster; less commonly used for app development than devnet.

Devnet faucet: Solana provides a public devnet faucet for free SOL, so you can exercise every write operation on this node end to end without spending real funds. Point cluster at devnet while developing, even though the app-wide DefaultCluster may be mainnet-beta.

Commitment Levels

Each cluster entry also sets a Commitment, controlling how finalized the state returned by a read (or required before a write is considered confirmed) must be:

Level	Meaning
`processed`	The most recent block the validator has processed — may still be skipped/rolled back.
`confirmed`	Default. A supermajority of the cluster has voted on the block — the practical safe default for most workflows.
`finalized`	Maximum lockout reached — effectively immutable. Slower to observe, strongest guarantee.

An unrecognized or omitted Commitment value silently falls back to confirmed rather than erroring.

How Cluster Selection Works

Each operation call may include a cluster config key.
If set, the node resolves that cluster's connection config from Solana:Clusters.
If the name isn't explicitly configured but matches a well-known name (mainnet-beta, devnet, testnet), the node still resolves it using the public default endpoint above.
If unset, the node uses whatever Solana:DefaultCluster points to.
If the resolved cluster name is neither explicitly configured nor well-known, the node throws SolanaClusterNotConfiguredException rather than silently falling back.
IRpcClient instances are cached per cluster for the process lifetime — the first call to a cluster pays any vault-resolution cost; subsequent calls reuse the cached client.

Adding a Custom Cluster

Add any additional entry under Solana:Clusters — the key becomes the value workflows pass in the cluster field. This also covers pointing at a local solana-test-validator:

"Solana": {
  "DefaultCluster": "devnet",
  "Clusters": {
    "devnet":      { "RpcUrl": "https://api.devnet.solana.com", "Commitment": "confirmed" },
    "local":       { "RpcUrl": "http://localhost:8899", "Commitment": "processed" },
    "helius-mainnet": { "RpcUrlCredentialID": 4821, "Commitment": "confirmed" }
  }
}

No code change or redeploy of the node itself is required — this is a pure configuration addition.

Plaintext RPC warning: If a resolved RPC URL doesn't use HTTPS and isn't a recognized localhost address (localhost, 127.0.0.1, ::1, host.docker.internal), the node logs a warning that signed transactions and wallet addresses will be transmitted in plaintext. Confirm any non-HTTPS endpoint really is a local dev validator before using it for signing operations.

Paid RPC providers: Set RpcUrlCredentialID instead of RpcUrl to point a cluster at a SERVICE_URL-type vault credential — useful for providers like Helius, QuickNode, or Triton whose endpoint URL embeds an API key that shouldn't live in plain appsettings. The URL is resolved once per cluster and cached in-memory for the process lifetime.