Déploiement de programmes

Ce guide suppose la connaissance des sujets suivants :

• Modèle de compte Solana
• Programmes Solana en général
• Développement de programmes Solana personnalisés

Loader-v3 et Loader-v4

Il y a actuellement une transition en cours du loader-v3 (sous-commande program) vers loader-v4 (sous-commande program -v4) car le loader-v3 est en cours de dépréciation.

Pour les nouveaux déploiements, veuillez utiliser solana program-v4 deploy au lieu de solana program deploy.

Pour migrer un programme existant (ce qui revient essentiellement à le redéployer) :

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

Préparation

Tout d'abord, le programme doit être compilé (compilé, lié, nettoyé).

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

Cette étape doit être effectuée avant chaque re-/déploiement.

Vérifiez que des fonds suffisants sont disponibles sur le compte payeur par défaut proportionnellement à la taille de l'exécutable :

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

De plus, chaque programme possède un compte de programme et un ID de programme, qui est l'adresse de ce compte de programme. La commande suivante génère une paire de clés pour le compte de programme :

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

Cette opération ne doit être effectuée qu'une seule fois par programme et sera réutilisée pour les redéploiements ultérieurs du même programme.

La chaîne d'outils contenait un raccourci, mais celui-ci est en cours d'élimination / dépréciation :

cargo-build-sbf

Déploiement initial

Maintenant, l'exécutable peut être téléchargé sur le compte du programme :

Loader-v3

Le paramètre s'appelle program-id même s'il attend le chemin de fichier d'une paire de clés :

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

Redéploiement

Le téléchargement d'un exécutable différent sur le même compte de programme écrasera / remplacera celui-ci. Cependant, pour les redéploiements, seul l'ID du programme (clé publique de la paire de clés du programme) est nécessaire, et non la paire de clés entière, car le signataire est la paire de clés de l'autorité de mise à niveau.

Loader-v3

C'est exactement identique au déploiement initial :

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

Si l'ancien exécutable était plus court que le nouveau, il pourrait être nécessaire d'agrandir d'abord le compte programdata :

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

Loader-v4

Notez que le déploiement initial utilisait program-keypair, tandis que le redéploiement utilise program-id à la place :

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

Priorisation d'un téléchargement

Pendant les périodes de congestion, il existe quelques drapeaux supplémentaires que vous pouvez utiliser pour faciliter le déploiement du programme :

• --with-compute-unit-price : Définit le prix de l'unité de calcul pour la transaction, par incréments de 0,000001 lamports (micro-lamports) par unité de calcul. Utilisez l'API de frais prioritaires de Helius pour obtenir une estimation des frais prioritaires à définir.
• --use-rpc : Envoie les transactions d'écriture au RPC configuré au lieu des TPU du validateur. Ce drapeau nécessite une connexion RPC pondérée par enjeu comme Helius ou Triton. Ce drapeau peut également être configuré par défaut en utilisant : solana config set --url <RPC_URL>.
• --max-sign-attempts : Nombre maximum de tentatives pour signer ou re-signer des transactions après l'expiration du blockhash. Si des transactions envoyées pendant le déploiement du programme ne sont toujours pas confirmées après l'expiration du blockhash récent initialement choisi, ces transactions seront re-signées avec un nouveau blockhash récent et renvoyées. Utilisez ce paramètre pour ajuster le nombre maximum d'itérations de signature de transaction. Chaque blockhash est valide pendant environ 60 secondes, ce qui signifie que l'utilisation de la valeur par défaut de 5 conduira à l'envoi de transactions pendant au moins 5 minutes ou jusqu'à ce que toutes les transactions soient confirmées, selon ce qui se produit en premier.

Reprise d'un téléversement

Il est possible qu'un téléversement se bloque ou soit interrompu.

Loader-v3

Si le déploiement du programme échoue, il restera un compte tampon intermédiaire contenant un solde non nul. Pour récupérer ce solde, vous pouvez reprendre un déploiement échoué en fournissant le même tampon intermédiaire à un nouvel appel à deploy.

Les échecs de déploiement afficheront un message d'erreur spécifiant la phrase mnémonique nécessaire pour récupérer la paire de clés du tampon intermédiaire généré :

==================================================================================
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`.
==================================================================================

Pour récupérer la paire de clés :

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

Lorsque demandé, saisissez la phrase mnémonique de 12 mots.

Ensuite, émettez une nouvelle commande deploy et spécifiez le tampon :

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

Loader-v4

Il est possible de reprendre un téléversement à un décalage d'octets spécifié :

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

Finalisation

Il s'agit d'une action irréversible.

Un programme peut être rendu immuable en supprimant son autorité de mise à niveau.

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

Au lieu de remplacer les programmes, il est également possible d'offrir aux utilisateurs le choix de la version du programme qu'ils souhaitent utiliser en construisant une liste chaînée de programmes finalisés :

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

Fermeture

Pour les programmes déployés sous loader-v3, seuls leur compte programdata, les comptes tampons et les fonds verrouillés dans ceux-ci peuvent être récupérés. Le compte du programme ainsi que l'ID du programme et les fonds verrouillés spécifiquement dans le compte du programme sont bloqués.

Les programmes déployés sous loader-v4 peuvent être fermés avec leur compte de programme, leur ID de programme et leurs fonds verrouillés devenant tous disponibles pour d'autres utilisations à nouveau.

Loader-v3

Il s'agit d'une action irréversible pour les programmes déployés avec loader-v3.

Notez qu'une fois un programme fermé, son ID de programme ne peut pas être réutilisé. Tenter de déployer un programme avec un ID de programme précédemment fermé entraînera une erreur. Si vous devez redéployer un programme après l'avoir fermé, vous devez générer un nouveau fichier de paire de clés de programme.

Pour fermer un seul compte programdata :

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

Pour fermer tous les comptes tampon associés à l'autorité actuelle :

solana program close --buffers

Loader-v4

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

Inspection des métadonnées

La sous-commande show liste les métadonnées d'un programme.

Un exemple de sortie ressemble à :

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

• Program Id est l'adresse qui peut être référencée dans le champ program_id d'une instruction lors de l'invocation d'un programme.
• Owner : Le chargeur avec lequel ce programme a été déployé.
• ProgramData Address est le compte programdata associé au compte du programme qui contient l'exécutable du programme (loader-v3 uniquement).
• Status : retracted, deployed ou finalized (loader-v4 uniquement).
• Authority est l'autorité de mise à niveau du programme.
• Last Deployed In Slot est le slot dans lequel le programme a été déployé pour la dernière fois.
• Data Length est la taille de l'espace réservé pour les déploiements. L'espace réel utilisé par le programme actuellement déployé peut être inférieur.

Loader-v3

Pour visualiser un programme spécifique :

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

Pour visualiser la liste des programmes déployés avec l'autorité par défaut :

solana program show --programs

Pour afficher tous les comptes tampon indépendamment de l'autorité :

solana program show --buffers --all

Pour spécifier une autorité différente :

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

Loader-v4

Pour afficher un programme spécifique :

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

Pour afficher la liste des programmes déployés avec l'autorité par défaut :

solana program-v4 show --all

Pour afficher la liste des programmes déployés avec une autorité spécifique :

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

Téléchargement de l'exécutable

Il est parfois utile de télécharger et de comparer un programme pour s'assurer qu'il contient un exécutable connu. Le fichier téléchargé peut être tronqué, haché et comparé au hachage du fichier programme 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

Avancé : transfert d'autorité

Le droit de modifier un programme donné appartient à son autorité. Cette autorité peut être transférée à une autre paire de clés sans changer la paire de clés du programme, de sorte que l'ID du programme reste le même. De plus, une seule autorité peut contrôler plusieurs comptes de programme.

Si elle n'est pas explicitement spécifiée lors du déploiement initial, la paire de clés par défaut est utilisée comme autorité. C'est pourquoi le redéploiement d'un programme dans les étapes ci-dessus ne nécessitait pas qu'une autorité soit explicitement spécifiée.

Une autorité explicite est utile pour la signature hors ligne et les programmes régis par plusieurs entités.

Tout d'abord, une paire de clés pour l'autorité doit être générée :

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

Loader-v3

L'autorité peut être spécifiée pendant le déploiement :

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

Ou après le déploiement et en utilisant la paire de clés par défaut comme autorité actuelle :

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

Ou après le déploiement et en spécifiant l'autorité actuelle :

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

L'autorité peut être spécifiée pendant le déploiement :

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

Ou après le déploiement et en utilisant la paire de clés par défaut comme autorité actuelle :

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

Ou après le déploiement et en spécifiant l'autorité actuelle :

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

Avancé : redéploiement en deux étapes utilisant un tampon

Au lieu de télécharger directement vers le compte du programme, l'exécutable peut être d'abord téléchargé vers un compte tampon intermédiaire, puis transféré vers le compte du programme dans une seconde étape (le redéploiement proprement dit). Ceci est utile pour la signature hors ligne et les programmes gouvernés par plusieurs entités, comme un vote DAO pour choisir ou rejeter un exécutable téléchargé avant le redéploiement effectif.

Gardez à l'esprit que l'utilisation de comptes tampons double approximativement les fonds nécessaires pendant le processus de téléchargement, car deux comptes contiennent chacun un exécutable simultanément.

Tout d'abord, une paire de clés pour le compte tampon doit être créée :

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

Le compte tampon peut être réutilisé pour différents téléchargements et n'est pas lié à un compte de programme spécifique.

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

Avancé : signature hors ligne

Certains modèles de sécurité nécessitent de séparer le processus de signature de la diffusion de la transaction, de sorte que les clés de signature puissent être complètement déconnectées de tout réseau, également connu sous le nom de signature hors ligne.

Notez que seuls les redéploiements peuvent être effectués en mode hors ligne. Le déploiement initial du programme doit être effectué depuis une machine en ligne, et seuls les redéploiements ultérieurs du programme peuvent exploiter la signature hors ligne.

Une configuration typique consisterait en deux signataires différents :

• signataire en ligne (payeur des frais et autorité du compte tampon)
• signataire hors ligne (autorité du compte du programme)

Le processus général est un redéploiement en deux étapes avec quelques extras :

1. (en ligne) créer un nouveau programme
2. (en ligne) transférer l'autorité au signataire hors ligne
3. (en ligne) créer un tampon et y télécharger un exécutable
4. (facultatif) vérifier le contenu on-chain du tampon
5. (hors ligne) signer une transaction pour redéployer le programme en utilisant le tampon --blockhash <VALUE> --sign-only
6. (en ligne) utiliser cette signature pour diffuser la transaction de redéploiement --blockhash <VALUE> --signer <OFFLINE_SIGNER_PUBKEY>:<OFFLINE_SIGNER_SIGNATURE>

Recherchez un blockhash récent et collez-le pour générer la signature de transaction hors ligne. Le blockhash expire après environ 60 secondes. Si vous n'avez pas réussi à temps - obtenez simplement un autre hash frais et répétez jusqu'à ce que vous réussissiez, ou envisagez d'utiliser des nonces de transaction durables.