Implementación de programas

Esta guía asume conocimiento de los siguientes temas:

• Modelo de cuenta de Solana
• Programas de Solana en general
• Desarrollo de programas personalizados de Solana

Loader-v3 y Loader-v4

Actualmente hay una transición en curso del loader-v3 (subcomando program) al loader-v4 (subcomando program -v4) ya que loader-v3 está siendo descontinuado.

Para nuevas implementaciones, utilice solana program-v4 deploy en lugar de solana program deploy.

Para migrar un programa existente (que es esencialmente reimplementarlo):

solana program migrate ./target/deploy/your_program-keypair.json

Preparación

Primero, el programa necesita ser compilado (compilado, enlazado, reducido).

cargo +solana build --target sbpf-solana-solana --release

Este paso debe realizarse antes de cada reimplementación/implementación.

Verifique que haya fondos suficientes disponibles en la cuenta de pago predeterminada proporcional al tamaño del ejecutable:

du -h ./target/deploy/your_program.so
solana balance

Además, cada programa tiene una cuenta de programa y un ID de programa, que es la dirección de esa cuenta de programa. Lo siguiente genera un keypair para la cuenta del programa:

solana-keygen new -o ./target/deploy/your_program-keypair.json

Esto solo debe realizarse una vez por programa y se reutilizará para reimplementaciones del mismo programa más adelante.

El conjunto de herramientas contenía un atajo, sin embargo, está siendo eliminado / descontinuado:

cargo-build-sbf

Implementación inicial

Ahora el ejecutable puede ser cargado en la cuenta del programa:

Loader-v3

El parámetro se llama program-id aunque espera la ruta de archivo de un keypair:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

Loader-v4

solana program-v4 deploy ./target/deploy/your_program.so --program-keypair ./target/deploy/your_program-keypair.json

Redespliegue

Subir un ejecutable diferente a la misma cuenta de programa nuevamente lo sobrescribirá / reemplazará. Sin embargo, para redespliegues, solo se necesita el ID del programa (pubkey del par de claves del programa), no el par de claves completo, porque el firmante es el par de claves de la autoridad de actualización.

Loader-v3

Esto es exactamente igual que el despliegue inicial:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

Si el ejecutable antiguo era más corto que el nuevo, podría ser necesario aumentar primero el tamaño de la cuenta programdata:

solana program extend ./target/deploy/your_program.so <ADDITIONAL_BYTES>

Loader-v4

Observa que el despliegue inicial utilizó program-keypair, mientras que el redespliegue utiliza program-id en su lugar:

solana program-v4 deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

Priorización de una carga

Durante períodos de congestión, hay algunas banderas adicionales que puedes usar para ayudar con el despliegue del programa:

• --with-compute-unit-price: Establece el precio de unidad de cómputo para la transacción, en incrementos de 0.000001 lamports (micro-lamports) por unidad de cómputo. Usa la API de tarifas prioritarias de Helius para obtener una estimación de la tarifa prioritaria a establecer.
• --use-rpc: Envía transacciones de escritura al RPC configurado en lugar de a las TPU del validador. Esta bandera requiere una conexión RPC ponderada por stake como Helius o Triton. Esta bandera también puede configurarse como predeterminada usando: solana config set --url <RPC_URL>.
• --max-sign-attempts: Número máximo de intentos para firmar o volver a firmar transacciones después de la expiración del blockhash. Si alguna transacción enviada durante el despliegue del programa sigue sin confirmarse después de que expire el blockhash reciente inicialmente elegido, esas transacciones se volverán a firmar con un nuevo blockhash reciente y se reenviarán. Usa esta configuración para ajustar el número máximo de iteraciones de firma de transacciones. Cada blockhash es válido durante aproximadamente 60 segundos, lo que significa que usar el valor predeterminado de 5 llevará a enviar transacciones durante al menos 5 minutos o hasta que todas las transacciones estén confirmadas, lo que ocurra primero.

Reanudando una carga

Es posible que una carga se quede atascada o sea interrumpida.

Loader-v3

Si el despliegue del programa falla, quedará una cuenta de búfer intermedia pendiente que contiene un saldo distinto de cero. Para recuperar ese saldo, puedes reanudar un despliegue fallido proporcionando el mismo búfer intermedio a una nueva llamada a deploy.

Los fallos de despliegue mostrarán un mensaje de error especificando la frase seed necesaria para recuperar el keypair del búfer intermedio generado:

==================================================================================
Recover the intermediate account's ephemeral keypair file with
`solana-keygen recover` and the following 12-word seed phrase:
==================================================================================
valley flat great hockey share token excess clever benefit traffic avocado athlete
==================================================================================
To resume a deploy, pass the recovered keypair as
the [BUFFER_SIGNER] to `solana program deploy` or `solana program write-buffer'.
Or to recover the account's lamports, pass it as the
[BUFFER_ACCOUNT_ADDRESS] argument to `solana program drain`.
==================================================================================

Para recuperar el keypair:

solana-keygen recover -o ./target/deploy/buffer-keypair.json

Cuando se te solicite, introduce la frase seed de 12 palabras.

Luego emite un nuevo comando deploy y especifica el búfer:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json --buffer ./target/deploy/buffer-keypair.json

Loader-v4

Es posible reanudar una carga desde un punto específico en bytes:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json --start-offset <BYTES_UPLOADED_SO_FAR>

Finalización

Esta es una acción irreversible.

Un programa puede hacerse inmutable eliminando su autoridad de actualización.

Loader-v3

solana program set-upgrade-authority ./target/deploy/your_program-keypair.json --final

Loader-v4

solana program finalize --program-id ./target/deploy/your_program-keypair.json

En lugar de sobrescribir programas, también es posible ofrecer a los usuarios la opción de elegir qué versión de un programa quieren usar mediante la construcción de una lista enlazada de programas finalizados:

solana program finalize --program-id ./target/deploy/your_program-keypair.json --next-version ../your_newer_program/target/deploy/your_newer_program-keypair.json

Cierre

Para programas desplegados bajo loader-v3, solo su programdata account, las cuentas de búfer y los fondos bloqueados en ellas pueden ser recuperados. La program account junto con el ID del programa y los fondos bloqueados específicamente en la program account quedan atrapados.

Los programas desplegados bajo loader-v4 pueden cerrarse junto con su cuenta de programa, su ID de programa y sus fondos bloqueados, quedando todos disponibles para otros usos nuevamente.

Loader-v3

Esta es una acción irreversible para programas desplegados usando loader-v3.

Ten en cuenta que una vez que un programa se cierra, su ID de programa no puede reutilizarse. Intentar desplegar un programa con un ID de programa previamente cerrado resultará en un error. Si necesitas redesplegar un programa después de cerrarlo, debes generar un nuevo archivo de keypair del programa.

Para cerrar una sola cuenta programdata:

solana program close ./target/deploy/your_program-keypair.json

Para cerrar todas las cuentas buffer asociadas con la autoridad actual:

solana program close --buffers

Loader-v4

solana program-v4 close --program-id ./target/deploy/your_program-keypair.json

Inspección de metadatos

El subcomando show lista los metadatos de un programa.

Un ejemplo de salida se ve así:

Program Id: 3KS2k14CmtnuVv2fvYcvdrNgC94Y11WETBpMUGgXyWZL
Owner: BPFLoaderUpgradeab1e11111111111111111111111
ProgramData Address: EHsACWBhgmw8iq5dmUZzTA1esRqcTognhKNHUkPi4q4g
Authority: FwoGJNUaJN2zfVEex9BB11Dqb3NJKy3e9oY3KTh9XzCU
Last Deployed In Slot: 63890568
Data Length: 5216 (0x1460) bytes

• Program Id es la dirección que puede ser referenciada en el campo program_id de una instrucción cuando se invoca un programa.
• Owner: El loader con el que se desplegó este programa.
• ProgramData Address es la cuenta programdata asociada con la cuenta del programa que contiene el ejecutable del programa (solo loader-v3).
• Status: retracted, deployed o finalized (solo loader-v4).
• Authority es la autoridad de actualización del programa.
• Last Deployed In Slot es el slot en el que el programa fue desplegado por última vez.
• Data Length es el tamaño del espacio reservado para despliegues. El espacio real utilizado por el programa actualmente desplegado puede ser menor.

Loader-v3

Para ver un programa específico:

solana program show ./target/deploy/your_program-keypair.json

Para ver la lista de programas desplegados con la autoridad predeterminada:

solana program show --programs

Para mostrar todas las cuentas buffer independientemente de la autoridad:

solana program show --buffers --all

Para especificar una autoridad diferente:

solana program show --programs --buffer-authority ~/.config/solana/authority-keypair.json
solana program show --buffers --buffer-authority ~/.config/solana/authority-keypair.json

Loader-v4

Para ver un programa específico:

solana program-v4 show --program-id ./target/deploy/your_program-keypair.json

Para ver la lista de programas desplegados con la autoridad predeterminada:

solana program-v4 show --all

Para ver la lista de programas desplegados con una autoridad específica:

solana program-v4 show --authority ~/.config/solana/authority-keypair.json

Descarga del ejecutable

A veces es útil descargar y comparar un programa para asegurar que contiene un ejecutable conocido. El archivo descargado puede ser truncado, hasheado y comparado con el hash del archivo del programa original.

Loader-v3

solana program dump ./target/deploy/your_program-keypair.json ./target/deploy/your_program.so

Loader-v4

solana program download ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

Avanzado: transferencia de autoridad

El derecho a cambiar un programa determinado recae en su autoridad. Esta autoridad puede ser transferida a otro keypair sin cambiar el keypair del programa, de modo que el ID del programa permanezca igual. Además, una sola autoridad puede controlar múltiples program accounts.

Si no se especifica explícitamente durante el despliegue inicial, entonces se utiliza el keypair predeterminado como autoridad. Por eso, redesplegar un programa en los pasos anteriores no requería que se especificara explícitamente una autoridad.

Una autoridad explícita es útil para la firma offline y programas gobernados por múltiples entidades.

Primero, debe generarse un keypair para la autoridad:

solana-keygen new -o ~/.config/solana/authority-keypair.json

Loader-v3

La autoridad puede especificarse durante el despliegue:

solana program deploy ./target/deploy/your_program.so --upgrade-authority ~/.config/solana/authority-keypair.json

O después del despliegue y usando el keypair predeterminado como la autoridad actual:

solana program set-upgrade-authority ./target/deploy/your_program-keypair.json --new-upgrade-authority ~/.config/solana/authority-keypair.json

O después del despliegue y especificando la autoridad actual:

solana program set-upgrade-authority ./target/deploy/your_program-keypair.json --upgrade-authority ~/.config/solana/authority-keypair.json --new-upgrade-authority ~/.config/solana/new_authority-keypair.json

Loader-v4

La autoridad puede ser especificada durante el despliegue:

solana program-v4 deploy ./target/deploy/your_program.so --program-keypair ./target/deploy/your_program-keypair.json --authority ~/.config/solana/authority-keypair.json

O después del despliegue y usando el keypair predeterminado como la autoridad actual:

solana program-v4 transfer-authority --program-id ./target/deploy/your_program-keypair.json --new-authority ~/.config/solana/authority-keypair.json

O después del despliegue y especificando la autoridad actual:

solana program-v4 transfer-authority --program-id ./target/deploy/your_program-keypair.json --authority ~/.config/solana/authority-keypair.json --new-authority ~/.config/solana/new_authority-keypair.json

Avanzado: redespliegue en dos pasos usando un buffer

En lugar de cargar directamente a la program account, el ejecutable puede ser cargado primero a una cuenta buffer provisional y luego ser transferido a la program account en un segundo paso (el redespliegue o despliegue real). Esto es útil para la firma offline y programas gobernados por múltiples entidades, como una DAO que vota para elegir o rechazar un ejecutable cargado antes del redespliegue real.

Ten en cuenta que usar cuentas buffer aproximadamente duplica los fondos requeridos durante el proceso de carga, ya que dos cuentas mantienen un ejecutable cada una, simultáneamente.

Primero, se debe crear un keypair para la cuenta buffer:

solana-keygen new -o ~/.config/solana/buffer-keypair.json

La cuenta buffer puede reutilizarse para diferentes cargas y no está vinculada a ninguna program account específica.

Loader-v3

solana program write-buffer ./target/deploy/your_program.so --buffer ~/.config/solana/buffer-keypair.json
solana program deploy --program-id ./target/deploy/your_program-keypair.json --buffer ~/.config/solana/buffer-keypair.json

Loader-v4

solana program-v4 deploy ./target/deploy/your_program.so --buffer ~/.config/solana/buffer-keypair.json
solana program-v4 deploy --program-id ./target/deploy/your_program-keypair.json --buffer ~/.config/solana/buffer-keypair.json

Avanzado: firma offline

Algunos modelos de seguridad requieren separar el proceso de firma de la transmisión de la transacción, de modo que las claves de firma puedan estar completamente desconectadas de cualquier red, también conocido como firma offline.

Ten en cuenta que solo los redespliegues pueden realizarse en modo offline. El despliegue inicial del programa debe realizarse desde una máquina online, y solo los redespliegues posteriores del programa pueden aprovechar la firma offline.

Una configuración típica consistiría en dos firmantes diferentes:

• firmante online (pagador de tarifas y autoridad de la cuenta buffer)
• firmante offline (autoridad de la program account)

El proceso general es una reimplementación en dos pasos con algunos extras:

1. (en línea) crear un nuevo programa
2. (en línea) transferir la autoridad al firmante fuera de línea
3. (en línea) crear un búfer y cargar un ejecutable en él
4. (opcional) verificar el contenido del búfer en la cadena
5. (fuera de línea) firmar una transacción para reimplementar el programa usando el búfer --blockhash <VALUE> --sign-only
6. (en línea) usar esta firma para transmitir la transacción de reimplementación --blockhash <VALUE> --signer <OFFLINE_SIGNER_PUBKEY>:<OFFLINE_SIGNER_SIGNATURE>

Busca un blockhash reciente y pégalo para generar la firma de transacción fuera de línea. El blockhash expira después de ~60 segundos. Si no lo lograste a tiempo - simplemente obtén otro hash nuevo y repite hasta que tengas éxito, o considera usar nonces de transacción durables.