Implantação e Atualizações em Detalhe

Enviar um programa Solana não é "carregar um binário e ir embora". É um ciclo de vida: escolher uma identidade de programa, financiar o aluguel para armazenamento de bytecode, preparar o ELF através do carregador atualizável, provar o que você enviou, decidir quem pode alterá-lo mais tarde e planejar o que acontece quando uma versão falha.

Esta página é o mapa conceitual para a seção. Use-a para posicionar o fluxo de implantação, o carregador atualizável, atualizações, imutabilidade, autoridade controlada por governança, compilações verificáveis e rollbacks em um único contínuo antes de seguir as páginas de receitas focadas.

Resumo

Nas ferramentas modernas do Solana (Agave 4.1.1 / Solana CLI 3.0.10), os programas são quase sempre carregados com o BPF Upgradeable Loader. Esse modelo divide as responsabilidades:

• Uma conta de programa no ID do programa é o endereço estável e executável que os clientes chamam.
• Uma conta de dados do programa contém os bytes ELF (SBF) e a chave pública da autoridade de atualização (ou nenhuma).
• Uma conta de buffer prepara uploads em várias etapas para que grandes implantações possam ser retomadas e o aluguel possa ser recuperado em caso de falha.

Implantação cria (ou preenche) essas contas a partir de um .so compilado. Atualização reutiliza o mesmo ID de programa e substitui o ELF sob controle da autoridade. Imutável significa que a autoridade foi permanentemente removida, então nenhuma atualização adicional pode ser bem-sucedida. Controlado por governança significa que a autoridade é uma multisig ou um cofre DAO, não uma chave de laptop de desenvolvedor. Compilações verificáveis fecham a lacuna de confiança entre o código-fonte público e os bytes na cadeia. Rollback é operacional: reimplementar um artefato previamente atestado e revalidar o hash.

O estado da conta que seu programa possui (PDAs, cofres, configurações) é separado do bytecode do programa. Atualizar o código não reescreve os layouts de dados do usuário para você. Compatibilidade e migração são sua responsabilidade.

Fundamentos

O que "implantação" significa no Solana

Implantação é o processo de colocar bytecode executável na cadeia para que o runtime possa invocar seu programa quando uma transação lista seu ID de programa. Clientes como Anchor 0.32.1, Solana CLI e @solana/kit 7.0.0 visam os mesmos contratos de carregador: financiar contas, escrever bytes, marcar como executável, registrar quem pode atualizar.

Ao contrário das implantações de servidor tradicionais, não há sessão SSH nem gerenciador de processos oculto. O artefato é público, a autoridade está na cadeia e cada mudança futura é outra transação assinada (ou uma parada abrupta se a autoridade for removida).

ID do programa é identidade do produto

O ID do programa é a chave pública do par de chaves do programa (ou o endereço que você passa com --program-id). Ele deve corresponder a declare_id! (Anchor) ou ao endereço codificado de seus clientes. Alterar o ID do programa é uma nova implantação: clientes, exploradores e derivações de PDA que incluem o ID do programa se movem. Prefira atualizações com o mesmo ID quando a lógica mudar e o estado deve permanecer sob endereços existentes.

O modelo de conta do carregador atualizável

solana program show <PROGRAM_ID> é a ferramenta de inspeção do dia um: comprimento dos dados, autoridade, endereço do ProgramData e último slot de implantação. Trate essa saída como o plano de controle para operações de lançamento.

A autoridade de atualização é a verdadeira fronteira de segurança

Quem puder assinar como autoridade de atualização pode substituir a lógica de produção para todos os usuários desse ID de programa. Isso é mais forte do que uma implantação de site e mais próximo do root em um binário compartilhado. Hot wallets são aceitáveis para localnet e devnet inicial. Antes de TVL significativa ou dependência pública, mova a autoridade para um detentor controlado (tipicamente um multisig Squads ou um caminho de execução DAO) ou revogue-a deliberadamente.

Perder a chave de autoridade sem um caminho de recuperação congela as atualizações para sempre. Isso pode ser intencional (imutabilidade) ou acidental (falha operacional). Projete para o resultado que você deseja.

Fixações de toolchain para este guia

Trate as versões como um contrato de equipe. Este guia assume Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 e @solana/kit 7.0.0. Fixe CLI, ferramentas de plataforma e Anchor como você fixa Cargo.lock. Toolchains incompatíveis são uma causa comum de incompatibilidades de hash "compilou na minha máquina" sob solana-verify.

Mecânicas

Pense nas operações de lançamento como um único pipeline com alguns ramais opcionais no final: compilar, preparar, pousar, verificar, e então manter atualizável (com ou sem governança), congelar ou preparar para rollback.

Pipeline de implantação e atualização de ponta a ponta

  Fonte (Rust / Anchor 0.32.1)
           |
           | cargo build-sbf / anchor build
           | opcional: solana-verify build (reproduzível)
           v
  Artefato: target/deploy/my_program.so
  Identidade: par de chaves do programa / declare_id!
           |
           | solana program write-buffer (buffer explícito opcional)
           | ou solana program deploy / anchor deploy
           v
  +---------------------------+
  |  Upgradeable Loader       |
  |  buffer <- blocos ELF     |
  |  ProgramData <- buffer    |
  |  programa conta links     |
  +---------------------------+
           |
           | autoridade assina deploy/upgrade
           v
  Executável na cadeia no PROGRAM_ID
           |
           | solana-verify get-program-hash
           | solana program show
           v
  Atestado: {commit, hash, program_id, cluster}
           |
           +--> manter autoridade (dev / caminho rápido)
           +--> transferir autoridade (Squads / DAO)
           +--> definir autoridade --final (imutável)
           |
           | se lançamento ruim e ainda atualizável:
           v
  Reimplementar o último .so conhecido como bom (rollback)

1. Compilar o artefato

anchor build envolve cargo build-sbf e emite IDL mais target/deploy/*.so para espaços de trabalho Anchor. Crates nativos usam a toolchain SBF diretamente. Compile na pilha Agave/CLI fixada para que o ELF corresponda ao que os validadores esperam.

Para candidatos a lançamento, prefira um caminho reproduzível (solana-verify build em um contêiner controlado) em vez de apenas um binário de host de desenvolvedor. Compilações de host são aceitáveis para iteração; são evidências fracas para atestado de mainnet.

2. Primeira implantação

solana program deploy path/to/program.so --program-id <keypair> financia o aluguel para ProgramData proporcional ao tamanho do bytecode, escreve através de um caminho de buffer nos bastidores quando necessário e define o implantador (ou a autoridade configurada) como autoridade de atualização por padrão.

anchor deploy faz o mesmo dentro da configuração do espaço de trabalho (cluster e carteira Anchor.toml). Sempre confirme o cluster com solana config get antes da mainnet. Use --dry-run quando precisar de uma prévia de custo.

Falhas no meio da implantação deixam aluguel de buffer para trás. Feche buffers abandonados ou retome de um endereço de buffer conhecido. Detalhes e receitas estão em Implantando Programas e Noções Básicas de Implantação.

3. Atualização (mesmo ID de programa)

Atualização não é um opcode mágico separado para equipes de produto: você implanta um novo .so visando o ID de programa existente enquanto detém a autoridade de atualização. O carregador substitui o conteúdo do ProgramData; o endereço da conta do programa permanece fixo. Os clientes continuam chamando a mesma chave pública. Novas transações executam o novo ELF após o pouso da atualização.

Atualizações seguras são um processo, não um sinalizador CLI:

1. Marque o commit e arquive o .so + hash.
2. Execute todos os testes (anchor test, negativos, caminhos de migração).
3. Ensaie na devnet com o mesmo pipeline.
4. Verifique o hash pós-implantação.
5. Execute a mainnet via governança se a autoridade for controlada.
6. Monitore e mantenha o artefato anterior pronto.

Quebras de layout de estado são o clássico assassino silencioso. Se as contas ganharem campos ou mudarem de significado, envie layouts versionados e instruções de migração. Veja Atualizações de Programa.

4. Compilações verificáveis fecham a lacuna código-fonte-para-cadeia

Usuários e auditores não devem confiar em um tweet de que "este é o código". solana-verify reconstrói sob um ambiente controlado, calcula o hash do executável e compara com os dados do programa na cadeia via RPC.

Evidência mínima de lançamento:

Controle o CI para que os trabalhos de implantação enviem apenas o artefato verificado. Após a implantação, recupere o hash do programa. A correspondência local antes do upload não é suficiente se o arquivo errado foi passado para program deploy.

5. Atualizações controladas por governança

Transferir a autoridade de atualização para um multisig Squads (ou um cofre controlado por DAO) transforma a mudança de bytecode em uma proposta: memo, hash, links de CI, notas de risco e assinaturas M-de-N. Timelocks dão à comunidade tempo para reagir antes da execução.

Divisão típica:

Nunca deixe uma autoridade de hot-wallet "oculta" para emergências enquanto anuncia segurança multisig. Exploradores e program show revelarão a autoridade real. Veja Atualizações Controladas por Governança.

6. Tornando programas imutáveis

solana program set-upgrade-authority <PROGRAM_ID> --final remove a autoridade permanentemente. Depois disso, nenhuma instrução de atualização pode alterar o ELF. A confiança na estabilidade do código aumenta; a capacidade de corrigir bugs críticos sem um novo ID de programa cai para zero.

Imutabilidade é uma decisão de produto com consequências operacionais:

• Faça isso apenas após auditoria, período de teste e atestado de hash verificado.
• Planeje antecipadamente ferramentas de migração se um bug futuro exigir um novo programa e movimentação de estado.
• Prefira --final executado por multisig para que um único laptop comprometido não possa congelar o artefato errado.

Detalhe da receita: Tornando Programas Imutáveis.

7. Rollbacks e resposta a incidentes

O runtime não mantém uma pilha de ELFs anteriores para desfazer com um clique. Rollback significa:

1. Detectar e conter (pausar fluxos de UI arriscados, se necessário).
2. Despejar os bytes atuais na cadeia para análise forense (solana program dump).
3. Reimplementar o último .so conhecido como bom sob o mesmo ID de programa (se ainda atualizável).
4. Verificar o hash e testar os caminhos críticos.
5. Comunicar o slot, a assinatura, o impacto e os próximos passos.

Se o programa já for imutável, "rollback" se torna migrar usuários e liquidez para um novo ID de programa, o que é muito mais caro. Arquive todos os artefatos de lançamento e hashes no CI para que o rollback seja possível. Padrões completos de runbook: Rollbacks e Resposta a Incidentes.

Avançado

Atualização com mesmo ID vs migração de novo programa

Feature flags não substituem atualizações quando o bug está no código enviado. Eles apenas reduzem a frequência com que você toca no bytecode para superfícies opcionais.

O aluguel escala com o tamanho do ProgramData (aproximadamente o tamanho do .so). Feche buffers abandonados para que implantações falhas não deixem aluguel preso. Taxas de prioridade ajudam a pousar sob congestionamento, mas são secundárias ao aluguel para programas grandes.

Ciclo de vida da autoridade que você pode defender em uma auditoria

1. Implante com a autoridade da equipe na devnet; itere rapidamente.
2. Bloqueie a autoridade da mainnet para multisig antes do TVL.
3. Exija hash verificável + evidência de devnet em cada proposta.
4. Arquive artefatos para rollback.
5. Opcionalmente, revogue a autoridade após um longo período estável se a imutabilidade for a promessa do produto.

Auditores verificam program show, histórico de propostas e hashes publicados. Alinhe o marketing com o estado real da autoridade.

Clientes, monitoramento e desvio

Atualizações mantêm o ID do programa, mas podem quebrar suposições de IDL. Fixe IDLs de clientes e tipos gerados por Codama/kit para a versão implantada. Coordene cortes quando os layouts de instrução mudarem. @solana/kit 7.0.0 não altera a semântica do carregador; a higiene de lançamento é operacional.

Observe atualizações inesperadas ou mudanças de autoridade, desvio de hash da última atestação, picos de erro após um slot de implantação e governança travada durante incidentes. Monitoramento sem artefatos retidos ainda deixa o rollback cego.

Conceitos Errôneos Comuns

Conceito Errado: Implantação é única; atualizações são casos especiais raros.
A maioria dos sistemas de produção permanece atualizável por meses. Projete autoridade e verificação desde o primeiro dia.

Conceito Errado: A conta do programa contém todo o bytecode sozinha.
ProgramData contém ELF e autoridade. A conta do programa é o identificador executável estável.

Conceito Errado: Multisig torna as atualizações automaticamente seguras.
Eleva a barra para mudança unilateral. Testes, compilações verificáveis e ensaio na devnet ainda importam. Os signatários podem aprovar uma proposta ruim.

Conceito Errado: Compilações verificáveis são apenas marketing para código aberto.
Eles também impedem que você implante o artefato errado e fornecem aos respondedores de incidentes a verdade fundamental para bytes na cadeia.

Conceito Errado: Programas imutáveis ainda podem ser corrigidos pela equipe original.
--final é final no carregador. Depois disso, você precisa de um novo programa e migração (a menos que você tenha divulgado um design de indireção).

Conceito Errado: Uma tag Git sozinha garante o rollback.
Arquive o .so de lançamento e o hash (ou prove uma reconstrução reproduzível dessa tag). Git sem o binário não é um pacote de rollback.

Conceito Errado: Atualizar código migra dados da conta.
Apenas suas instruções migram o estado. Novos layouts em contas antigas podem quebrar caminhos ou ler fundos incorretamente.

Conceito Errado: Implantação na devnet prova a execução da governança na mainnet.
Devnet prova bytecode e testes rápidos. UX de multisig, limites e timelocks ainda precisam de ensaio.

Conceito Errado: Uma chave de emergência oculta é inofensiva.
Se ela permanecer como autoridade de atualização, ela é o modelo de segurança.

FAQs