Implantando Programas
Implante programas sBPF compilados com solana program deploy, gerencie contas buffer e controle upgrade authority pela CLI.
Receita
Card de receita de referência rápida - pronto para copiar e colar.
cargo build-sbf
solana program deploy target/deploy/my_program.so
solana program show <PROGRAM_ID>
solana program set-upgrade-authority <PROGRAM_ID> --new-upgrade-authority <AUTH>Quando usar:
- Primeiro deploy de programa Anchor ou nativo em devnet/mainnet.
- Upgrade de programa existente com novo artefato
.so. - Transferir upgrade authority para multisig ou DAO.
- Escrever program ID em
Anchor.toml/declare_id!após keygen.
Exemplo Funcional
cd my_anchor_program
anchor build
# Artifact: target/deploy/my_anchor_program.so
solana config set --url devnet
solana airdrop 2
# Deploy with explicit program keypair (first deploy)
solana program deploy \
target/deploy/my_anchor_program.so \
--program-id target/deploy/my_anchor_program-keypair.json
PROGRAM_ID=$(solana-keygen pubkey target/deploy/my_anchor_program-keypair.json)
solana program show "$PROGRAM_ID"O que isso demonstra:
cargo build-sbf/anchor buildproduz o.soconsumido pelo deploy.- Keypair do programa determina o endereço on-chain do program ID.
program showconfirma loader, conta programdata e authority.
Aprofundamento
Como Funciona
- BPF Loader v3 upgradeable armazena bytecode em conta programdata.
- Transações de deploy fazem upload de ELF em chunks para buffer, depois finalizam em programdata.
- Pubkey de upgrade authority pode submeter novos upgrades ou ser definida como
none(imutável). - Deploy custa lamports para armazenamento programdata isento de rent proporcional ao tamanho do
.so.
Comandos de Deploy
| Comando | Propósito |
|---|---|
program deploy | Upload e ativação (ou upgrade) de bytecode |
program write-buffer | Upload apenas para buffer |
program deploy --buffer | Finalizar de buffer existente |
program close | Recuperar lamports do buffer (authority necessária) |
program set-upgrade-authority | Transferir ou revogar direitos de upgrade |
Notas bash
# Show deploy cost estimate
solana program deploy my_program.so --dry-run 2>&1 | grep -i cost
# Immutable program: revoke upgrade authority
solana program set-upgrade-authority <PROGRAM_ID> --finalErros Comuns
- Mismatch de program ID -
declare_id!não corresponde ao keypair implantado. Correção: alinheAnchor.tomlelib.rscomsolana-keygen pubkeydo keypair de deploy. - SOL insuficiente para rent - programas grandes precisam mais lamports que airdrop pequeno. Correção: financie deployer com SOL suficiente para rent programdata mais fees.
- Deploy de builds debug -
.sonão otimizado desperdiça CU e rent. Correção:cargo build-sbf --release/anchor build. - Upgrade authority perdida - definir authority na key errada trava upgrades. Correção: transfira para multisig deliberadamente; teste em devnet primeiro.
- Deploy em cluster errado - program ID devnet em config mainnet. Correção:
solana config getantes de todo deploy.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
anchor deploy | Workspace Anchor com IDs scriptados | Programas nativos raw sem Anchor |
solana program write-buffer + finalize separado | CI divide upload e ativação | Loops dev local simples |
Pipeline solana-verify | Deploys verificáveis reproduzíveis | Testes devnet descartáveis rápidos |
| Surfpool / validator local | Simulação pré-mainnet | Release de produção |
FAQs
Onde está o arquivo .so após anchor build?
target/deploy/<crate_name>.so mais -keypair.json correspondente para o program ID.
Quanto SOL custa deploy?
Rent para programdata escala com tamanho do bytecode mais fees de transação. Execute deploy em devnet e leia lamports cobrados em solana confirm -v.
Posso fazer upgrade sem redeploy do program ID?
Sim - submeta novo .so no mesmo program ID enquanto detém upgrade authority.
O que faz --final em set-upgrade-authority?
Remove upgrade authority permanentemente - programa torna-se imutável.
O que é conta buffer?
Conta temporária guardando chunks ELF uploadados antes de ativação em programdata.
Posso deploy com hardware wallet?
Possível com signers compatíveis, mas a maioria dos times usa hot deploy key em devnet e authority multisig na mainnet.
Por que deploy falhou com account already in use?
Frequentemente buffer parcial ou deploy concorrente. Feche buffers obsoletos ou espere txs em voo limparem.
Como verificar hash do binário implantado?
solana program dump <ID> out.so e compare SHA256 com artefato de build, ou use solana-verify para builds reproduzíveis.
Deploy funciona em localnet?
Sim - inicie solana-test-validator e implante em http://127.0.0.1:8899.
Quem paga fees de deploy?
Fee payer na transação de deploy - geralmente seu keypair CLI configurado.
Relacionado
- Construindo Programas (cargo build-sbf) - compile antes do deploy
- Inspecionando Contas e Programas - inspeção pós-deploy
- Builds Verificáveis (solana-verify) - artefatos reproduzíveis
- solana-test-validator - alvo de deploy local
Versões do 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.