Despliegue y Actualizaciones en Detalle
Enviar un programa de Solana no es "subir un binario y olvidarse". Es un ciclo de vida: elegir una identidad de programa, financiar el alquiler para el almacenamiento de bytecode, preparar el ELF a través del cargador actualizable, demostrar lo que enviaste, decidir quién puede cambiarlo más tarde y planificar qué sucede cuando una versión sale mal.
Esta página es el mapa conceptual de la sección. Úsala para ubicar el flujo de despliegue, el cargador actualizable, las actualizaciones, la inmutabilidad, la autoridad controlada por gobernanza, las compilaciones verificables y las reversiones en un continuo antes de seguir las páginas de recetas enfocadas.
Resumen
En las herramientas modernas de Solana (Agave 4.1.1 / Solana CLI 3.0.10), los programas casi siempre se cargan con el BPF Upgradeable Loader. Ese modelo divide las responsabilidades:
- Una cuenta de programa en el ID del programa es la dirección estable y ejecutable a la que llaman los clientes.
- Una cuenta de datos del programa (
ProgramData) contiene los bytes ELF (SBF) y la clave pública de la autoridad de actualización (o ninguna). - Una cuenta búfer (
Buffer) prepara cargas paso a paso para que los despliegues grandes puedan reanudarse y el alquiler pueda ser recuperado en caso de fallo.
Despliegue crea (o llena) esas cuentas a partir de un .so compilado. Actualización reutiliza el mismo ID de programa y reemplaza el ELF bajo control de la autoridad. Inmutable significa que la autoridad se ha revocado permanentemente, por lo que ninguna actualización posterior puede tener éxito. Controlado por gobernanza significa que la autoridad es una bóveda multisig o DAO, no una clave de portátil de desarrollador. Compilaciones verificables cierran la brecha de confianza entre el código fuente público y los bytes en cadena. Reversión es operativa: reeditar un artefacto previamente atestiguado y volver a verificar el hash.
El estado de la cuenta que posee tu programa (PDAs, bóvedas, configuración) está separado del bytecode del programa. Actualizar el código no reescribe los diseños de datos del usuario por ti. La compatibilidad y la migración son tu responsabilidad.
Fundamentos
¿Qué significa "despliegue" en Solana?
El despliegue es el proceso de poner bytecode ejecutable en cadena para que el tiempo de ejecución pueda invocar tu programa cuando una transacción lista tu ID de programa. Clientes como Anchor 0.32.1, Solana CLI y @solana/kit 7.0.0 apuntan todos a los mismos contratos de cargador: financiar cuentas, escribir bytes, marcar como ejecutable, registrar quién puede actualizar.
A diferencia de los despliegues de servidores tradicionales, no hay una sesión SSH ni un gestor de procesos oculto. El artefacto es público, la autoridad está en cadena y cada cambio futuro es otra transacción firmada (o una parada forzada si la autoridad se ha ido).
El ID del programa es la identidad del producto
El ID del programa es la clave pública del par de claves del programa (o la dirección que pasas con --program-id). Debe coincidir con declare_id! (Anchor) o la dirección codificada en tus clientes. Cambiar el ID del programa es un nuevo despliegue: los clientes, exploradores y derivaciones de PDA que incluyen el ID del programa se mueven. Prefiere las actualizaciones con el mismo ID cuando la lógica cambie y el estado deba permanecer bajo las direcciones existentes.
El modelo de cuenta del cargador actualizable
| Cuenta | Rol |
|---|---|
| Cuenta de programa | Proxy ejecutable en el ID del programa; apunta a ProgramData |
| ProgramData | Bytes ELF + autoridad de actualización + metadatos del último despliegue |
| Búfer | Destino temporal de carga para escrituras fragmentadas durante el despliegue/actualización |
solana program show <PROGRAM_ID> es la herramienta de inspección del primer día: longitud de datos, autoridad, dirección de ProgramData y última ranura de despliegue. Trata esa salida como el plano de control para las operaciones de lanzamiento.
La autoridad de actualización es el verdadero límite de seguridad
Quien pueda firmar como autoridad de actualización puede reemplazar la lógica de producción para todos los usuarios de ese ID de programa. Eso es más fuerte que un despliegue web y más cercano a la raíz en un binario compartido. Las billeteras calientes están bien para localnet y devnet temprano. Antes de un TVL significativo o dependencia pública, mueve la autoridad a un titular controlado (típicamente una bóveda multisig de Squads o una ruta de ejecución de DAO) o revócala deliberadamente.
Perder la clave de autoridad sin una ruta de recuperación congela las actualizaciones para siempre. Eso puede ser intencional (inmutabilidad) o accidental (fallo operativo). Diseña para el resultado que deseas.
Fijaciones de cadena de herramientas para esta guía
Trata las versiones como un contrato de equipo. Esta guía asume Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 y @solana/kit 7.0.0. Fija CLI, herramientas de plataforma y Anchor como fijas Cargo.lock. Las cadenas de herramientas que no coinciden son una causa común de discrepancias de hash "se compiló en mi portátil" bajo solana-verify.
Mecánicas
Piensa en las operaciones de lanzamiento como un único pipeline con algunas ramas opcionales al final: compilar, preparar, aterrizar, verificar, y luego mantener actualizable (controlado o no), congelar o prepararse para revertir.
Pipeline de despliegue y actualización de extremo a extremo
Fuente (Rust / Anchor 0.32.1)
|
| cargo build-sbf / anchor build
| opcional: solana-verify build (reproducible)
v
Artefacto: target/deploy/my_program.so
Identidad: par de claves del programa / declare_id!
|
| solana program write-buffer (búfer explícito opcional)
| o solana program deploy / anchor deploy
v
+---------------------------+
| Upgradeable Loader |
| búfer <- fragmentos ELF |
| ProgramData <- búfer |
| enlaces cuenta programa |
+---------------------------+
|
| la autoridad firma el despliegue/actualización
v
Ejecutable en cadena en PROGRAM_ID
|
| solana-verify get-program-hash
| solana program show
v
Atestación: {commit, hash, program_id, cluster}
|
+--> mantener autoridad (dev / ruta caliente)
+--> transferir autoridad (Squads / DAO)
+--> establecer autoridad --final (inmutable)
|
| si hay una mala versión y aún es actualizable:
v
Reeditar el .so conocido como bueno (reversión)
1. Compilar el artefacto
anchor build envuelve cargo build-sbf y emite IDL más target/deploy/*.so para los espacios de trabajo de Anchor. Los crates nativos usan la cadena de herramientas SBF directamente. Compila en la pila Agave/CLI fijada para que el ELF coincida con lo que esperan los validadores.
Para los candidatos a lanzamiento, prefiere una ruta reproducible (solana-verify build en un contenedor controlado) en lugar de un binario de host de desarrollador solamente. Las compilaciones de host están bien para la iteración; son evidencia débil para la atestación en mainnet.
2. Primer despliegue
solana program deploy path/to/program.so --program-id <keypair> financia el alquiler para ProgramData proporcional al tamaño del bytecode, escribe a través de una ruta de búfer bajo el capó cuando es necesario, y establece el desplegador (o la autoridad configurada) como autoridad de actualización por defecto.
anchor deploy hace lo mismo dentro de la configuración del espacio de trabajo (Anchor.toml cluster y wallet). Confirma siempre el cluster con solana config get antes de mainnet. Usa --dry-run cuando necesites una vista previa del costo.
Los fallos a mitad de despliegue dejan atrás el alquiler del búfer. Cierra búferes abandonados o reanuda desde una dirección de búfer conocida. Los detalles y recetas se encuentran en Despliegue de Programas y Conceptos Básicos de Despliegue.
3. Actualización (mismo ID de programa)
La actualización no es una operación mágica separada para los equipos de producto: despliegas un nuevo .so apuntando al ID de programa existente mientras posees la autoridad de actualización. El cargador reemplaza el contenido de ProgramData; la dirección de la cuenta del programa permanece fija. Los clientes siguen llamando a la misma clave pública. Las nuevas transacciones ejecutan el nuevo ELF después de que la actualización aterrice.
Las actualizaciones seguras son un proceso, no una bandera de CLI:
- Etiqueta el commit y archiva el
.so+ hash. - Ejecuta pruebas completas (
anchor test, negativas, rutas de migración). - Ensaya en devnet con el mismo pipeline.
- Verifica el hash post-despliegue.
- Ejecuta en mainnet a través de gobernanza si la autoridad está controlada.
- Monitoriza y ten listo el artefacto anterior.
Las roturas de diseño de estado son el clásico asesino silencioso. Si las cuentas ganan campos o cambian de significado, envía diseños versionados e instrucciones de migración. Ver Actualizaciones de Programas.
4. Las compilaciones verificables cierran la brecha de código fuente a cadena
Los usuarios y auditores no deben confiar en un tweet que dice "este es el código". solana-verify recompila bajo un entorno controlado, calcula el hash del ejecutable y lo compara con los datos del programa en cadena a través de RPC.
Evidencia mínima de lanzamiento:
| Campo | Por qué importa |
|---|---|
| Commit SHA | Identidad del código fuente |
| ID del programa | Identidad en cadena |
| Cluster | mainnet vs devnet |
| Hash ejecutable / de programa | Atestación a nivel de bytes |
| Fijaciones de cadena de herramientas | Reproducibilidad |
Controla CI para que los trabajos de despliegue solo envíen el artefacto verificado. Después del despliegue, vuelve a obtener el hash del programa. La coincidencia local antes de la carga no es suficiente si se pasó el archivo incorrecto a program deploy.
5. Actualizaciones controladas por gobernanza
Transferir la autoridad de actualización a una multisig de Squads (o una bóveda controlada por DAO) convierte el cambio de bytecode en una propuesta: memo, hash, enlaces de CI, notas de riesgo y firmas M-de-N. Los timelocks dan a la comunidad tiempo para reaccionar antes de la ejecución.
División típica:
| Entorno | Patrón de autoridad |
|---|---|
| Local / CI | Clave efímera o del equipo |
| Devnet | Clave del equipo o multisig ligera |
| Mainnet pre-TVL | Multisig antes del riesgo público |
| Mainnet maduro | Multisig + política, o ruta a la inmutabilidad |
Nunca dejes una clave de emergencia "oculta" para emergencias mientras promocionas la seguridad multisig. Los exploradores y program show revelarán la autoridad real. Ver Actualizaciones Controladas por Gobernanza.
6. Hacer programas inmutables
solana program set-upgrade-authority <PROGRAM_ID> --final revoca la autoridad permanentemente. Después de eso, ninguna instrucción de actualización puede cambiar el ELF. La confianza en la estabilidad del código aumenta; la capacidad de parchear errores críticos sin un nuevo ID de programa cae a cero.
La inmutabilidad es una decisión de producto con consecuencias operativas:
- Hazlo solo después de auditoría, período de prueba y atestación de hash verificado.
- Pre-planifica herramientas de migración si un error futuro requiriera un nuevo programa y movimiento de estado.
- Prefiere
--finalejecutado por multisig para que un solo portátil comprometido no pueda congelar el artefacto incorrecto.
Detalle de la receta: Hacer Programas Inmutables.
7. Reversiones y respuesta a incidentes
El tiempo de ejecución no mantiene una pila de ELFs anteriores para deshacer con un solo clic. Reversión significa:
- Detectar y contener (pausar flujos de UI arriesgados si es necesario).
- Volcar los bytes actuales en cadena para análisis forense (
solana program dump). - Reeditar el
.soconocido como bueno más reciente bajo el mismo ID de programa (si aún es actualizable). - Verificar el hash y realizar pruebas de humo en rutas críticas.
- Comunicar la ranura, la firma, el impacto y los próximos pasos.
Si el programa ya es inmutable, "reversión" se convierte en migrar usuarios y liquidez a un nuevo ID de programa, lo cual es mucho más costoso. Archiva cada artefacto de lanzamiento y hash en CI para que la reversión sea posible. Patrones completos de runbook: Reversiones y Respuesta a Incidentes.
Avanzado
Actualización con el mismo ID vs. migración a nuevo programa
| Ruta | Mantener ID de programa | Mantener PDAs | Cuándo usar |
|---|---|---|---|
| Actualizar ELF | Sí | Sí si las semillas no cambian | Correcciones de lógica/diseño compatibles |
| Nuevo programa + migrar | No | Solo con rederivación/transferencia cuidadosa | Romper modelo de confianza, congelar, rediseño irreversible |
| Indicadores de función en datos | Sí | Sí | Alternar comportamiento cuando el código ya lo soporta |
Los indicadores de función no reemplazan las actualizaciones cuando el error está en el código enviado. Solo reducen la frecuencia con la que tocas el bytecode para superficies opcionales.
El alquiler escala con el tamaño de ProgramData (aproximadamente el tamaño del .so). Cierra los búferes abandonados para que los despliegues fallidos no dejen alquileres varados. Las tarifas de prioridad ayudan a aterrizar bajo congestión, pero son secundarias al alquiler para programas grandes.
Ciclo de vida de la autoridad que puedes defender en una auditoría
- Desplegar con autoridad del equipo en devnet; iterar rápidamente.
- Bloquear la autoridad de mainnet a multisig antes del TVL.
- Requerir hash verificable + evidencia de devnet en cada propuesta.
- Archivar artefactos para reversión.
- Opcionalmente, revocar la autoridad después de un largo período estable si la inmutabilidad es la promesa del producto.
Los auditores verifican program show, el historial de propuestas y los hashes publicados. Alinea el marketing con el estado real de la autoridad.
Clientes, monitorización y deriva
Las actualizaciones mantienen el ID del programa pero pueden romper las suposiciones de IDL. Fija las IDLs de cliente y los tipos generados por Codama/kit a la versión desplegada. Coordina los cortes cuando los diseños de instrucciones cambien. @solana/kit 7.0.0 no cambia la semántica del cargador; la higiene de lanzamiento es operativa.
Vigila actualizaciones inesperadas o cambios de autoridad, deriva de hash respecto a la última atestación, picos de error después de una ranura de despliegue y gobernanza atascada durante incidentes. La monitorización sin artefactos conservados aún deja la reversión ciega.
Conceptos erróneos comunes
Concepto erróneo: El despliegue es único; las actualizaciones son casos especiales raros. La mayoría de los sistemas de producción permanecen actualizables durante meses. Diseña la autoridad y la verificación desde el primer día.
Concepto erróneo: La cuenta del programa contiene todo el bytecode por sí sola. ProgramData contiene el ELF y la autoridad. La cuenta del programa es el manejador ejecutable estable.
Concepto erróneo: Multisig hace que las actualizaciones sean automáticamente seguras. Eleva el listón para el cambio unilateral. Las pruebas, las compilaciones verificables y los ensayos en devnet siguen siendo importantes. Los firmantes pueden aprobar una propuesta incorrecta.
Concepto erróneo: Las compilaciones verificables son solo marketing para código abierto. También te impiden desplegar el artefacto incorrecto y dan a los respondedores de incidentes la verdad fundamental para los bytes en cadena.
Concepto erróneo: Los programas inmutables aún pueden ser parcheados en caliente por el equipo original.
--final es final en el cargador. Después de eso, necesitas un nuevo programa y migración (a menos que hayas revelado un diseño de indirección).
Concepto erróneo: Una etiqueta de Git sola garantiza la reversión.
Archiva el .so de lanzamiento y el hash (o demuestra una reconstrucción reproducible de esa etiqueta). Git sin el binario no es un paquete de reversión.
Concepto erróneo: Actualizar código migra datos de cuenta. Solo tus instrucciones migran el estado. Los nuevos diseños en cuentas antiguas pueden romper rutas o leer fondos incorrectamente.
Concepto erróneo: El despliegue en devnet prueba la ejecución de gobernanza en mainnet. Devnet prueba el bytecode y las pruebas de humo. La experiencia de usuario multisig, los umbrales y los timelocks aún necesitan ensayos.
Concepto erróneo: Una clave de emergencia oculta es inofensiva. Si sigue siendo la autoridad de actualización, es el modelo de seguridad.
Preguntas frecuentes
¿Qué es el cargador actualizable?
El programa en cadena que posee las cuentas de programa actualizables, almacena el ELF en ProgramData y aplica la autoridad de actualización en el despliegue y la actualización.
¿Cambia una actualización mi ID de programa?
No. Mismo ID de programa; solo cambian los bytes ejecutables y los metadatos relacionados del cargador.
¿Qué es una cuenta búfer?
Una cuenta temporal para fragmentos ELF durante el despliegue o la actualización, para que las cargas grandes puedan reanudarse y los intentos fallidos puedan recuperar el alquiler.
¿Cómo veo quién puede actualizar un programa?
solana program show <PROGRAM_ID> y lee Authority. None significa inmutable.
¿Cuándo debo transferir la autoridad a multisig?
Antes de capital en mainnet o dependencia pública. Conserva las claves calientes solo para local y devnet temprano.
¿Qué prueba solana-verify?
Que una reconstrucción controlada coincide con el hash ejecutable en cadena cuando el código fuente, las características y los bloqueos coinciden. No prueba la seguridad económica de la lógica.
¿Puedo deshacer set-upgrade-authority --final?
No. Planifica la migración a un nuevo ID de programa si debes cambiar la lógica después de la inmutabilidad.
¿Cómo funcionan las reversiones en mainnet?
Si aún es actualizable, reedita un .so conocido como bueno retenido al mismo ID de programa a través de la ruta de autoridad, y luego vuelve a verificar el hash. Si es inmutable, migra.
¿Es anchor deploy diferente de solana program deploy?
anchor deploy envuelve la configuración del espacio de trabajo y el mismo flujo de trabajo del cargador. Los programas nativos suelen llamar directamente a la Solana CLI.
¿Por qué mi hash local no coincidió con CI?
Deriva de la cadena de herramientas, dependencias desbloqueadas, indicadores de características o compilaciones de host vs. contenedor. Controla los lanzamientos con solana-verify desde un entorno fijado.
¿Necesitan cambiar los clientes después de una actualización?
No si los contratos de instrucciones y cuentas se mantienen compatibles. De lo contrario, envía actualizaciones coordinadas de cliente/IDL con la actualización.
¿A dónde debo ir ahora en esta sección?
Comienza con Conceptos Básicos de Despliegue y Despliegue de Programas, luego Actualizaciones de Programas. Añade Actualizaciones Controladas por Gobernanza, Hacer Programas Inmutables y Reversiones y Respuesta a Incidentes para políticas de producción.
Relacionado
- Despliegue de Programas - búferes,
program deployy costos de despliegue - Conceptos Básicos de Despliegue - modelo de cargador, autoridad e inspecciones iniciales
- Actualizaciones de Programas - actualizaciones con el mismo ID y lista de verificación de lanzamiento seguro
- Actualizaciones Controladas por Gobernanza - autoridad controlada por multisig y DAO
- Hacer Programas Inmutables - revocar la autoridad de actualización para siempre
- Reversiones y Respuesta a Incidentes - malos despliegues, volcados y recuperación
Versiones de la pila: Esta página fue escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 y @solana/kit 7.0.0.