solana-program-upgrade
Actualiza un programa Solana en vivo y migra los datos de sus cuentas on-chain de forma segura: versionado, migración realloc perezosa, simulación en fork, higiene de la autoridad de actualización y reversión. Este es el paso más catastrófico del ciclo de vida en Solana, hecho sobrevivible.
Complemento de
solana-dev-skill. Ese skill se encarga de los fundamentos de Anchor/Pinocchio y pruebas en campo verde. Este skill solo maneja el ciclo de vida de actualización + migración – úsalo una vez que un programa ya está desplegado y necesita cambiar.
Reglas de oro (la columna vertebral de seguridad)
- Nunca cambies la disposición de una cuenta en vivo sin una etiqueta de versión + una ruta de migración.
Las cuentas antiguas son bytes sin procesar; el código nuevo que las lee con una estructura modificada ->
AccountDidNotDeserializeo corrupción silenciosa. El discriminador de 8 bytes protege el tipo, no la versión. - Simula contra un clon real del estado de mainnet antes de mainnet. Siempre ejecuta la actualización y migración exactas en un fork primero y compara los bytes de las cuentas. Sin excepciones.
- Usa multisig para la autoridad de actualización. Una sola clave activa que pueda reemplazar toda la lógica del programa es un vector de rug/compromiso. Muévela a Squads v4.
- Las migraciones de datos on-chain suelen ser solo hacia adelante. Diseña migraciones aditivas y reanudables; no asumas que puedes revertir los datos.
- Conserva el
.soanterior. Siempre puedes revertir el código rápidamente incluso cuando los datos no se pueden revertir. - Por defecto, usa devnet/localnet/fork. Nunca apuntes a mainnet automáticamente en ningún ejemplo.
El flujo de trabajo de actualización
Sigue en orden. Cada paso dirige a un archivo enfocado para profundizar.
- Diferenciar el esquema - compara las estructuras
#[account]antiguas vs nuevas. Identifica cambios aditivos vs cambios disruptivos (reordenar/eliminar/recambiar tipo = disruptivo). - Elegir una estrategia - migración eager (forzada) vs perezosa (al tocar) vs copiar a nueva cuenta ->
migration-strategies.md. - Escribir estructuras versionadas - agrega una etiqueta de versión, bifurca según la versión almacenada ->
account-versioning.md. - Implementar la migración -
reallocmanual (línea base portable) ->realloc-migration.md; o el tipoMigrationde Anchor si tu versión lo tiene ->anchor-migration-type.md. - Simular en un fork - clona cuentas reales, ejecuta la actualización, compara bytes, verifica idempotencia ->
fork-simulation.md. - Asegurar la autoridad - verifica/mueve a multisig Squads antes de tocar mainnet ->
upgrade-authority.md. - Desplegar el binario - flujo de buffer,
extendsi es más grande, IDL,--final->program-deploy-upgrade.md. - Verificar y mantener un plan de reversión - confirma que las cuentas se deserializan; conserva el
.soanterior y una ruta de recuperación de migración parcial ->rollback-recovery.md.
Tabla de enrutamiento
Encuentra la fila que coincida con la situación y lee ese archivo.
| Síntoma / tarea | Lee |
|---|---|
AccountDidNotDeserialize / discrepancia de tamaño / valores incorrectos después de una actualización | account-versioning.md, luego realloc-migration.md |
Se agregó/eliminó/reordenó/recambió un campo en una estructura #[account] | account-versioning.md |
| "¿Cómo versiono mi cuenta para poder cambiarla después?" | account-versioning.md |
| Necesitas agrandar/encoger una cuenta existente en su lugar | realloc-migration.md |
| Migración perezosa "al tocar" vs eager de una sola vez | realloc-migration.md, migration-strategies.md |
realloc::zero riesgo de bytes obsoletos / dirección del relleno de alquiler | realloc-migration.md |
| Límite de crecimiento de realloc de 10 KB por instrucción, crecimientos grandes | realloc-migration.md |
Quieres el nuevo tipo Migration<'info, From, To> de Anchor | anchor-migration-type.md |
Errores AccountAlreadyMigrated / AccountNotMigrated | anchor-migration-type.md |
| Elegir entre eager vs perezosa vs copiar a nueva cuenta | migration-strategies.md |
| Migrar un conjunto grande de cuentas (ej. decenas de miles) de forma económica | migration-strategies.md |
| Migración por lotes/crank/keeper, paginación, seguimiento de progreso | migration-strategies.md |
| Realloc en el lugar imposible (encoger más allá de los datos, cambio de tipo) | migration-strategies.md |
| Redesplegar / actualizar el binario del programa | program-deploy-upgrade.md |
Flujo solana program write-buffer / deploy --buffer | program-deploy-upgrade.md |
El nuevo .so es más grande que el desplegado (solana program extend) | program-deploy-upgrade.md |
Actualizar el IDL (anchor idl upgrade) | program-deploy-upgrade.md |
| Desplegar en el lugar vs nuevo id de programa (efecto en PDAs/cuentas) | program-deploy-upgrade.md |
| ¿Quién controla el programa? Clave única vs multisig | upgrade-authority.md |
| Mover la autoridad de actualización a un multisig Squads v4 | upgrade-authority.md |
set-upgrade-authority, timelock, gestión de claves | upgrade-authority.md |
Hacer el programa inmutable (--final) y qué cuesta | upgrade-authority.md |
| Probar la actualización antes de mainnet / clonar estado real | fork-simulation.md |
| Fork de mainnet con Surfpool; comparar bytes de cuentas antes/después | fork-simulation.md |
| Pruebas unitarias con LiteSVM / Mollusk para la instrucción de migración | fork-simulation.md |
| Demostrar que la migración es idempotente (ejecutar dos veces = no operación) | fork-simulation.md |
| La actualización salió mal - recuperar el código antiguo rápidamente | rollback-recovery.md |
| Conjunto de cuentas migrado a medias; reanudar de forma segura | rollback-recovery.md |
| Pausa / guardia de migración / flag de características de emergencia | rollback-recovery.md |
| Programa nativo / Pinocchio (sin azúcar de Anchor) | realloc-migration.md, account-versioning.md |
| Enlaces autoritativos y documentación (verificar actualidad) | resources.md |
Herramientas complementarias
- Comandos:
/plan-upgrade(diferencia de esquemas -> plan de migración + informe de riesgos),/simulate-upgrade(fork, clonar, ejecutar, comparar),/check-upgrade-authority(auditar clave única vs multisig). - Agentes:
program-migration-architect(diseñar la migración a partir de una diferencia de esquemas),migration-qa-engineer(escribir pruebas en fork/LiteSVM, verificar que no haya corrupción). - Regla:
account-layout-guardse activa automáticamente al editar estructuras#[account]/state.rsy requiere un incremento de versión + una ruta de migración.
Contrato de precisión
Cada flag de CLI, restricción de Anchor, crate y tipo de cuenta en los archivos enrutados debe ser real y verificable. Cuando tengas dudas, verifica contra las versiones instaladas (anchor --version, solana --version, el changelog de Anchor) – nunca inventes. Trata el tipo Migration como posiblemente no liberado; el patrón manual de realloc es la opción portable por defecto.