solana-program-upgrade
Mettez à niveau un programme Solana en production et migrez ses données de comptes on-chain en toute sécurité - versioning, migration paresseuse par realloc, simulation fork, hygiène d'autorité de mise à niveau et rollback. C'est l'étape la plus catastrophique du cycle de vie Solana, rendue viable.
Complément de
solana-dev-skill. Cette compétence gère les bases Anchor/Pinocchio/test en environnement vierge. Celle-ci ne gère que le cycle de mise à niveau + migration - à utiliser une fois qu'un programme est déjà déployé et doit évoluer.
Règles d'or (l'épine dorsale de la sécurité)
- Ne jamais modifier la disposition d'un compte en production sans une balise de version + un chemin de migration.
Les anciens comptes sont des octets bruts ; un nouveau code les lisant avec une structure modifiée ->
AccountDidNotDeserializeou corruption silencieuse. Le discriminateur de 8 octets verrouille le type, pas la version. - Simulez contre l'état réel cloné du mainnet avant le mainnet. Exécutez toujours la mise à niveau et la migration exactes sur un fork d'abord et différenciez les octets des comptes. Aucune exception.
- Utilisez un multisig pour l'autorité de mise à niveau. Une seule clé à chaud capable de remplacer toute la logique du programme est un vecteur de rug/compréomission. Déplacez-la sur Squads v4.
- Les migrations de données on-chain sont généralement en avant uniquement. Concevez-les de manière additive et reprenable ; ne supposez pas que vous pouvez annuler les données.
- Conservez le
.soprécédent. Vous pouvez toujours revenir rapidement en arrière sur le code même si les données ne peuvent pas être annulées. - Par défaut, utilisez devnet/localnet/fork. Ne ciblez jamais automatiquement le mainnet dans un exemple.
Le workflow de mise à niveau
Suivez dans l'ordre. Chaque étape renvoie vers un fichier ciblé pour approfondir.
- Comparez le schéma - comparez les structures
#[account]anciennes et nouvelles. Identifiez les changements additifs vs cassants (réorganisation/suppression/changement de type = cassant). - Choisissez une stratégie - crank impatient vs migration paresseuse au touché vs copie vers un nouveau compte ->
migration-strategies.md. - Écrivez des structures versionnées - ajoutez une balise de version, branchez sur la version stockée ->
account-versioning.md. - Implémentez la migration -
reallocmanuel (base portable) ->realloc-migration.md; ou le typeMigrationd'Anchor si votre version le supporte ->anchor-migration-type.md. - Simulez sur un fork - clonez les comptes réels, exécutez la mise à niveau, différenciez les octets, vérifiez l'idempotence ->
fork-simulation.md. - Sécurisez l'autorité - vérifiez/déplacez vers le multisig Squads avant de toucher le mainnet ->
upgrade-authority.md. - Déployez le binaire - flux buffer,
extendsi plus volumineux, IDL,--final->program-deploy-upgrade.md. - Vérifiez et conservez un plan de rollback - confirmez que les comptes se désérialisent ; conservez le
.soprécédent et un chemin de récupération de demi-migration ->rollback-recovery.md.
Table de routage
Trouvez la ligne correspondant à la situation et lisez ce fichier.
| Symptôme / tâche | Lire |
|---|---|
AccountDidNotDeserialize / décalage de taille / mauvaises valeurs après une mise à niveau | account-versioning.md, puis realloc-migration.md |
Ajout/suppression/réorganisation/changement de type d'un champ sur une structure #[account] | account-versioning.md |
| "Comment versionner mon compte pour pouvoir le modifier plus tard ?" | account-versioning.md |
| Besoin d'agrandir/réduire un compte existant sur place | realloc-migration.md |
| Migration paresseuse "migre au touché" vs migration unique impatiente | realloc-migration.md, migration-strategies.md |
Piège des octets obsolètes realloc::zero / direction de reconstitution du loyer | realloc-migration.md |
| Limite de croissance par instruction de 10 Ko pour realloc, grandes croissances | realloc-migration.md |
Vous voulez le nouveau type Migration<'info, From, To> d'Anchor | anchor-migration-type.md |
Erreurs AccountAlreadyMigrated / AccountNotMigrated | anchor-migration-type.md |
| Choix entre migration impatiente vs paresseuse vs copie vers nouveau compte | migration-strategies.md |
| Migration d'un grand ensemble de comptes (ex. dizaines de milliers) à moindre coût | migration-strategies.md |
| Migration par lots/crank/gardien, pagination, suivi de progression | migration-strategies.md |
realloc sur place impossible (réduction au-delà des données, changement de type) | migration-strategies.md |
| Redéploiement / mise à niveau du binaire du programme | program-deploy-upgrade.md |
Flux solana program write-buffer / deploy --buffer | program-deploy-upgrade.md |
Le nouveau .so est plus grand que celui déployé (solana program extend) | program-deploy-upgrade.md |
Mise à niveau de l'IDL (anchor idl upgrade) | program-deploy-upgrade.md |
| Déploiement sur place vs nouvel ID de programme (effet sur les PDA/comptes) | program-deploy-upgrade.md |
| Qui contrôle le programme ? Clé unique vs multisig | upgrade-authority.md |
| Déplacer l'autorité de mise à niveau vers un multisig Squads v4 | upgrade-authority.md |
set-upgrade-authority, timelock, gestion de clés | upgrade-authority.md |
Rendre le programme immuable (--final) et ce que cela coûte | upgrade-authority.md |
| Tester la mise à niveau avant le mainnet / cloner l'état réel | fork-simulation.md |
| Fork du mainnet Surfpool ; différencier les octets des comptes avant/après | fork-simulation.md |
| Tests unitaires LiteSVM / Mollusk pour l'instruction de migration | fork-simulation.md |
| Prouver que la migration est idempotente (exécutée deux fois = sans effet) | fork-simulation.md |
| La mise à niveau a mal tourné - récupérer rapidement l'ancien code | rollback-recovery.md |
| Ensemble de comptes à moitié migrés ; reprendre en toute sécurité | rollback-recovery.md |
| Pause / garde de migration / drapeau de fonctionnalité d'urgence | rollback-recovery.md |
| Programme natif / Pinocchio (sans sucre Anchor) | realloc-migration.md, account-versioning.md |
| Liens et docs de référence (vérifier la version actuelle) | resources.md |
Outils compagnons
- Commandes :
/plan-upgrade(différence de schéma -> plan de migration + rapport de risque),/simulate-upgrade(fork, clone, exécute, différencie),/check-upgrade-authority(audit clé unique vs multisig). - Agents :
program-migration-architect(concevoir la migration à partir d'une différence de schéma),migration-qa-engineer(écrire des tests fork/LiteSVM, vérifier l'absence de corruption). - Règle :
account-layout-guardse déclenche automatiquement lors de modifications des structures#[account]/state.rset exige un changement de version + un chemin de migration.
Contrat d'exactitude
Chaque indicateur CLI, contrainte Anchor, crate et type de compte dans les fichiers routés doit être réel et vérifiable. En cas de doute, vérifiez auprès des versions installées (anchor --version, solana --version, le changelog Anchor) - n'inventez jamais. Traitez le type Migration comme peut-être non publié ; le motif manuel realloc est la valeur par défaut portable.