Clusters e Redes

A Solana executa vários clusters - blockchains independentes com conjuntos próprios de validadores, hashes de genesis e economia de tokens. Escolher o cluster certo mantém seu desenvolvimento seguro e previsível.

Receita

Cartão de receita de referência rápida - pronto para copiar.

# Apontar CLI para um cluster
solana config set --url devnet
solana config set --url https://api.mainnet-beta.solana.com
 
# Verificar cluster atual
solana config get
 
# Iniciar validador local Agave 4.1.1
solana-test-validator --reset

Quando usar:

Inicializar novo projeto na devnet com SOL de teste grátis
Executar testes de integração contra validador local
Implantar programa na mainnet-beta para produção
Depurar falhas de transação em ambiente isolado
Combinar URL de RPC ao cluster onde contas foram criadas

Exemplo Prático

#!/bin/bash
# devnet-workflow.sh - Solana CLI 3.0.10
 
set -e
 
# 1. Configurar devnet
solana config set --url devnet
echo "Cluster: $(solana config get | grep 'RPC URL')"
 
# 2. Criar carteira dev
solana-keygen new --no-bip39-passphrase -o ./dev-keypair.json --force
PUBKEY=$(solana-keygen pubkey ./dev-keypair.json)
echo "Wallet: $PUBKEY"
 
# 3. Financiar do faucet
solana airdrop 2 ./dev-keypair.json
solana balance ./dev-keypair.json
 
# 4. Verificar genesis corresponde à devnet
solana genesis-hash
# devnet genesis: EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG

import { createSolanaRpc } from "@solana/kit";
 
// URL de RPC deve corresponder ao cluster onde suas contas vivem
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"]);

O que isso demonstra:

CLI config set --url determina para onde todos os comandos subsequentes enviam transações
Airdrops funcionam só na devnet/testnet - não na mainnet-beta
Genesis hash identifica um cluster de forma única - RPC incompatível significa contas ausentes
Clientes RPC Kit são específicos de cluster - instancie um por ambiente

Aprofundamento

Como Funciona

Cada cluster tem seu próprio bloco genesis, conjunto de validadores e histórico de ledger
Transações assinadas para um cluster são inválidas em outro (blockhash recente diferente)
Program IDs podem diferir entre clusters se implantados separadamente
Endpoints RPC públicos têm rate limit; apps de produção usam providers dedicados

Clusters em Resumo

Cluster	Propósito	SOL	Airdrop	Estabilidade
devnet	Desenvolvimento de apps	Teste (sem valor)	Sim	Moderada
testnet	Testes de validador/protocolo	Teste	Sim	Menor
mainnet-beta	Produção	Valor real	Não	Maior
localnet	`solana-test-validator` local	Ilimitado local	N/A	Você controla

Opções de Validador Local

# Ledger fresco, portas padrão
solana-test-validator --reset
 
# Clonar programa mainnet para teste local
solana-test-validator --clone-upgradeable-program <PROGRAM_ID> --url mainnet-beta
 
# Apontar CLI para validador local
solana config set --url http://127.0.0.1:8899

Notas Rust

// Em testes, use LiteSVM 0.6.x ou Surfpool 0.12.0 para clusters locais programáticos
// Anchor test com Surfpool:
// [scripts]
// test = "npx surfpool run anchor test"

Erros Comuns

RPC errado para contas existentes - keypairs devnet têm saldo zero na mainnet. Correção: combine URL de RPC ao cluster onde contas foram criadas.
Usar chaves mainnet na devnet - seguro, mas o inverso é catastrófico. Correção: arquivos keypair separados por cluster; nunca airdrop na mainnet.
Program IDs hardcoded entre clusters - endereços implantados diferem por cluster. Correção: use config de ambiente ou declare_id! por deploy.
Rate limits de RPC público - airdrops devnet e leituras pesadas são limitadas. Correção: use provider RPC dedicado ou validador local para CI.
Instabilidade da testnet - quebra mais que devnet. Correção: use devnet para dev de app, testnet só para trabalho de validador.
Mismatch de genesis hash no CI - imagem de validador obsoleta vs cluster esperado. Correção: fixe Agave 4.1.1 e verifique genesis no setup de teste.

Alternativas

Alternativa	Use Quando	Não Use Quando
`solana-test-validator`	Controle local total, iteração rápida	Precisa de estado de programa mainnet
Surfpool 0.12.0	Testes de integração Anchor com fixtures	Experimentos CLI pontuais
LiteSVM 0.6.x	Testes unitários sem validador completo	Testar comportamento de nível de rede
Devnet	Sandbox público compartilhado	Load testing ou uptime garantido

FAQs

Qual a diferença entre devnet e testnet?

Devnet é para desenvolvedores de aplicativos. Testnet é para testes de validador e protocolo. Devnet é mais estável para trabalho diário de app.

Posso usar o mesmo keypair em todos os clusters?

Sim - keypairs são agnósticos de cluster. Mas estado de conta (saldos, programas) é por cluster.

Como obter SOL de teste na devnet?

solana airdrop 2

Limitado a alguns SOL por requisição. Use faucets web se rate-limited.

Qual URL de RPC usar para mainnet?

Pública: https://api.mainnet-beta.solana.com. Apps de produção devem usar provider dedicado (Helius, Triton, QuickNode, etc.).

Como verificar a qual cluster estou conectado?

solana genesis-hash
solana cluster-version

Localnet persiste estado entre reinícios?

Só se omitir --reset. Com --reset, o ledger começa fresco cada vez.

Posso clonar contas mainnet para localnet?

Sim, com solana-test-validator --clone <PUBKEY>. Útil para testar contra deploys reais de programa.

Por que transações falham após trocar de cluster?

Blockhashes recentes são específicos de cluster. Busque novo blockhash do RPC do cluster alvo.

SOL da devnet vale algo?

Não. Não tem valor de mercado e pode ser mintado livremente via airdrops.

Qual versão Agave roda nos clusters públicos?

Clusters públicos acompanham releases estáveis do Agave. Fixe ferramentas locais em Agave 4.1.1 para corresponder a esta documentação.

CI deve usar devnet ou localnet?

Localnet (Surfpool ou solana-test-validator) é mais rápido e livre de rate limits. Use devnet só para smoke tests de integração ocasionais.

Como explorers sabem qual cluster mostrar?

Passe ?cluster=devnet ou ?cluster=mainnet-beta na URL. Padrão é mainnet-beta.

Relacionado

Noções Básicas de Solana - primeiros passos na devnet
Carteiras e Explorers - fluxo devnet e faucets
Keypairs e Endereços - gestão de chaves por cluster

Versões da stack: Esta página foi escrita para 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 e LiteSVM 0.6.x.

Clusters e Redes

Receita

Cartão de receita de referência rápida - pronto para copiar.

# Apontar CLI para um cluster
solana config set --url devnet
solana config set --url https://api.mainnet-beta.solana.com
 
# Verificar cluster atual
solana config get
 
# Iniciar validador local Agave 4.1.1
solana-test-validator --reset

Quando usar:

Inicializar novo projeto na devnet com SOL de teste grátis
Executar testes de integração contra validador local
Implantar programa na mainnet-beta para produção
Depurar falhas de transação em ambiente isolado
Combinar URL de RPC ao cluster onde contas foram criadas

Exemplo Prático

#!/bin/bash
# devnet-workflow.sh - Solana CLI 3.0.10
 
set -e
 
# 1. Configurar devnet
solana config set --url devnet
echo "Cluster: $(solana config get | grep 'RPC URL')"
 
# 2. Criar carteira dev
solana-keygen new --no-bip39-passphrase -o ./dev-keypair.json --force
PUBKEY=$(solana-keygen pubkey ./dev-keypair.json)
echo "Wallet: $PUBKEY"
 
# 3. Financiar do faucet
solana airdrop 2 ./dev-keypair.json
solana balance ./dev-keypair.json
 
# 4. Verificar genesis corresponde à devnet
solana genesis-hash
# devnet genesis: EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG

import { createSolanaRpc } from "@solana/kit";
 
// URL de RPC deve corresponder ao cluster onde suas contas vivem
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"]);

O que isso demonstra:

CLI config set --url determina para onde todos os comandos subsequentes enviam transações
Airdrops funcionam só na devnet/testnet - não na mainnet-beta
Genesis hash identifica um cluster de forma única - RPC incompatível significa contas ausentes
Clientes RPC Kit são específicos de cluster - instancie um por ambiente

Aprofundamento

Como Funciona

Cada cluster tem seu próprio bloco genesis, conjunto de validadores e histórico de ledger
Transações assinadas para um cluster são inválidas em outro (blockhash recente diferente)
Program IDs podem diferir entre clusters se implantados separadamente
Endpoints RPC públicos têm rate limit; apps de produção usam providers dedicados

Clusters em Resumo

Cluster	Propósito	SOL	Airdrop	Estabilidade
devnet	Desenvolvimento de apps	Teste (sem valor)	Sim	Moderada
testnet	Testes de validador/protocolo	Teste	Sim	Menor
mainnet-beta	Produção	Valor real	Não	Maior
localnet	`solana-test-validator` local	Ilimitado local	N/A	Você controla

Opções de Validador Local

# Ledger fresco, portas padrão
solana-test-validator --reset
 
# Clonar programa mainnet para teste local
solana-test-validator --clone-upgradeable-program <PROGRAM_ID> --url mainnet-beta
 
# Apontar CLI para validador local
solana config set --url http://127.0.0.1:8899

Notas Rust

// Em testes, use LiteSVM 0.6.x ou Surfpool 0.12.0 para clusters locais programáticos
// Anchor test com Surfpool:
// [scripts]
// test = "npx surfpool run anchor test"

Erros Comuns

RPC errado para contas existentes - keypairs devnet têm saldo zero na mainnet. Correção: combine URL de RPC ao cluster onde contas foram criadas.
Usar chaves mainnet na devnet - seguro, mas o inverso é catastrófico. Correção: arquivos keypair separados por cluster; nunca airdrop na mainnet.
Program IDs hardcoded entre clusters - endereços implantados diferem por cluster. Correção: use config de ambiente ou declare_id! por deploy.
Rate limits de RPC público - airdrops devnet e leituras pesadas são limitadas. Correção: use provider RPC dedicado ou validador local para CI.
Instabilidade da testnet - quebra mais que devnet. Correção: use devnet para dev de app, testnet só para trabalho de validador.
Mismatch de genesis hash no CI - imagem de validador obsoleta vs cluster esperado. Correção: fixe Agave 4.1.1 e verifique genesis no setup de teste.

Alternativas

Alternativa	Use Quando	Não Use Quando
`solana-test-validator`	Controle local total, iteração rápida	Precisa de estado de programa mainnet
Surfpool 0.12.0	Testes de integração Anchor com fixtures	Experimentos CLI pontuais
LiteSVM 0.6.x	Testes unitários sem validador completo	Testar comportamento de nível de rede
Devnet	Sandbox público compartilhado	Load testing ou uptime garantido

FAQs

Qual a diferença entre devnet e testnet?

Devnet é para desenvolvedores de aplicativos. Testnet é para testes de validador e protocolo. Devnet é mais estável para trabalho diário de app.

Posso usar o mesmo keypair em todos os clusters?

Sim - keypairs são agnósticos de cluster. Mas estado de conta (saldos, programas) é por cluster.

Como obter SOL de teste na devnet?

solana airdrop 2

Limitado a alguns SOL por requisição. Use faucets web se rate-limited.

Qual URL de RPC usar para mainnet?

Pública: https://api.mainnet-beta.solana.com. Apps de produção devem usar provider dedicado (Helius, Triton, QuickNode, etc.).

Como verificar a qual cluster estou conectado?

solana genesis-hash
solana cluster-version

Localnet persiste estado entre reinícios?

Só se omitir --reset. Com --reset, o ledger começa fresco cada vez.

Posso clonar contas mainnet para localnet?

Sim, com solana-test-validator --clone <PUBKEY>. Útil para testar contra deploys reais de programa.

Por que transações falham após trocar de cluster?

Blockhashes recentes são específicos de cluster. Busque novo blockhash do RPC do cluster alvo.

SOL da devnet vale algo?

Não. Não tem valor de mercado e pode ser mintado livremente via airdrops.

Qual versão Agave roda nos clusters públicos?

Clusters públicos acompanham releases estáveis do Agave. Fixe ferramentas locais em Agave 4.1.1 para corresponder a esta documentação.

CI deve usar devnet ou localnet?

Localnet (Surfpool ou solana-test-validator) é mais rápido e livre de rate limits. Use devnet só para smoke tests de integração ocasionais.

Como explorers sabem qual cluster mostrar?

Passe ?cluster=devnet ou ?cluster=mainnet-beta na URL. Padrão é mainnet-beta.

Relacionado

Noções Básicas de Solana - primeiros passos na devnet
Carteiras e Explorers - fluxo devnet e faucets
Keypairs e Endereços - gestão de chaves por cluster

Versões da stack: Esta página foi escrita para 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 e LiteSVM 0.6.x.

Clusters e Redes

Buscar na documentação

Clusters e Redes