solana-program-upgrade
Atualize um programa Solana em produção e migre seus dados de conta on-chain com segurança — versionamento, migração lazy realloc, simulação em fork, higiene de autoridade de upgrade e rollback. Este é o passo mais catastrófico do ciclo de vida no desenvolvimento Solana, tornado sobrevivível.
Complemento de
solana-dev-skill. Aquela habilidade cobre os fundamentos de Anchor/Pinocchio/testes. Esta habilidade cuida apenas do ciclo de vida de upgrade + migração — recorra a ela quando um programa já estiver implantado e precisar mudar.
Regras de ouro (a espinha dorsal da segurança)
- Nunca altere o layout de uma conta ativa sem uma tag de versão + caminho de migração.
Contas antigas são bytes brutos; novo código lendo-as com uma struct alterada ->
AccountDidNotDeserializeou corrupção silenciosa. O discriminador de 8 bytes controla o tipo, não a versão. - Simule contra o estado real clonado da mainnet antes da mainnet. Sempre execute o upgrade exato + migração em um fork primeiro e difira os bytes das contas. Sem exceções.
- Multisig para a autoridade de upgrade. Uma única chave ativa que pode substituir toda a lógica do programa é um vetor de rug/comprometimento. Mova-a para Squads v4.
- Migrações de dados on-chain geralmente são apenas para frente. Projete-as aditivamente e retomáveis; não presuma que pode reverter dados.
- Mantenha o
.soanterior. Você sempre pode reverter o código rapidamente, mesmo quando os dados não podem ser revertidos. - Padrão para devnet/localnet/fork. Nunca mire na mainnet automaticamente em nenhum exemplo.
O fluxo de trabalho de upgrade
Siga em ordem. Cada etapa leva a um arquivo específico para aprofundamento.
- Difere o esquema - compare structs
#[account]antigas vs novas. Identifique mudanças aditivas vs quebra (reordenar/remover/alterar tipo = quebra). - Escolha uma estratégia - crank eager vs migração lazy no toque vs copiar para nova conta ->
migration-strategies.md. - Escreva structs versionadas - adicione uma tag de versão, ramifique com base na versão armazenada ->
account-versioning.md. - Implemente a migração -
reallocmanual (linha de base portátil) ->realloc-migration.md; ou o tipoMigrationdo Anchor se sua versão o tiver ->anchor-migration-type.md. - Simule em um fork - clone contas reais, execute o upgrade, difira bytes, afirme idempotência ->
fork-simulation.md. - Proteja a autoridade - verifique/mova para multisig Squads antes de tocar na mainnet ->
upgrade-authority.md. - Implante o binário - fluxo de buffer,
extendse maior, IDL,--final->program-deploy-upgrade.md. - Verifique e mantenha um plano de rollback - confirme que as contas desserializam; retenha o
.soanterior e um caminho de recuperação de meia-migração ->rollback-recovery.md.
Tabela de roteamento
Encontre a linha que corresponde à situação e leia aquele arquivo.
| Sintoma / tarefa | Leia |
|---|---|
AccountDidNotDeserialize / incompatibilidade de tamanho / valores errados após um upgrade | account-versioning.md, depois realloc-migration.md |
Adicionou/removeu/reordenou/alterou tipo de um campo em uma struct #[account] | account-versioning.md |
| "Como versiono minha conta para poder alterá-la depois?" | account-versioning.md |
| Precisa aumentar/diminuir uma conta existente no lugar | realloc-migration.md |
| Migração lazy "migrar no toque" vs migração única eager | realloc-migration.md, migration-strategies.md |
realloc::zero armadilha de bytes obsoletos / direção de recarga de aluguel | realloc-migration.md |
| Limite de crescimento realloc de 10 KB por instrução, crescimentos grandes | realloc-migration.md |
Quer o novo tipo Migration<'info, From, To> do Anchor | anchor-migration-type.md |
Erros AccountAlreadyMigrated / AccountNotMigrated | anchor-migration-type.md |
| Escolher entre eager vs lazy vs copiar para nova conta | migration-strategies.md |
| Migrar um grande conjunto de contas (ex.: dezenas de milhares) de forma barata | migration-strategies.md |
| Migração batch/crank/keeper, paginação, rastreamento de progresso | migration-strategies.md |
| Realloc no lugar impossível (encolhendo além dos dados, mudança de tipo) | migration-strategies.md |
| Reimplantando / atualizando o binário do programa | program-deploy-upgrade.md |
Fluxo solana program write-buffer / deploy --buffer | program-deploy-upgrade.md |
Novo .so é maior que o implantado (solana program extend) | program-deploy-upgrade.md |
Atualizando o IDL (anchor idl upgrade) | program-deploy-upgrade.md |
| Implantação no lugar vs novo id do programa (efeito em PDAs/contas) | program-deploy-upgrade.md |
| Quem controla o programa? Chave única vs multisig | upgrade-authority.md |
| Mover autoridade de upgrade para um multisig Squads v4 | upgrade-authority.md |
set-upgrade-authority, timelock, gerenciamento de chaves | upgrade-authority.md |
Tornar o programa imutável (--final) e o que isso custa | upgrade-authority.md |
| Testar o upgrade antes da mainnet / clonar estado real | fork-simulation.md |
| Fork da mainnet Surfpool; difir bytes de contas antes/depois | fork-simulation.md |
| Testes unitários LiteSVM / Mollusk para a instrução de migração | fork-simulation.md |
| Provar que a migração é idempotente (executar duas vezes = sem efeito) | fork-simulation.md |
| Upgrade deu errado - recuperar o código antigo rapidamente | rollback-recovery.md |
| Conjunto de contas meio migrado; retomar com segurança | rollback-recovery.md |
| Pausar / guarda de migração / flag de emergência | rollback-recovery.md |
| Programa nativo / Pinocchio (sem açúcar Anchor) | realloc-migration.md, account-versioning.md |
| Links e documentos oficiais (verifique a versão atual) | resources.md |
Ferramentas complementares
- Comandos:
/plan-upgrade(diff de esquema -> plano de migração + relatório de risco),/simulate-upgrade(fork, clonar, executar, diff),/check-upgrade-authority(auditar chave única vs multisig). - Agentes:
program-migration-architect(projetar a migração a partir de um diff de esquema),migration-qa-engineer(escrever testes de fork/LiteSVM, verificar sem corrupção). - Regra:
account-layout-guarddispara automaticamente em edições de structs#[account]/state.rse exige um aumento de versão + caminho de migração.
Contrato de precisão
Toda flag de CLI, constraint Anchor, crate e tipo de conta nos arquivos roteados deve ser real e verificável. Quando em dúvida, verifique contra as versões instaladas (anchor --version, solana --version, o changelog do Anchor) - nunca invente. Trate o tipo Migration como possivelmente não lançado; o padrão realloc manual é o padrão portátil.