Programme deployen

Dieser Leitfaden setzt Kenntnisse zu folgenden Themen voraus:

• Solana-Kontenmodell
• Solana-Programme im Allgemeinen
• Entwicklung benutzerdefinierter Solana-Programme

Loader-v3 und Loader-v4

Derzeit findet ein Übergang von Loader-v3 (program-Unterbefehl) zu Loader-v4 (program -v4-Unterbefehl) statt, da Loader-v3 eingestellt wird.

Für neue Deployments verwenden Sie bitte solana program-v4 deploy anstelle von solana program deploy.

Um ein bestehendes Programm zu migrieren (was im Wesentlichen ein erneutes Deployment ist):

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

Vorbereitung

Zuerst muss das Programm gebaut werden (kompiliert, verlinkt, gestrippt).

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

Dieser Schritt muss vor jedem erneuten Deployment durchgeführt werden.

Überprüfen Sie, ob auf dem Standard-Zahlerkonto ausreichend Guthaben proportional zur Größe der ausführbaren Datei verfügbar ist:

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

Zusätzlich hat jedes Programm ein Programmkonto und eine Programm-ID, welche die Adresse dieses Programmkontos ist. Das Folgende generiert ein Keypair für das Programmkonto:

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

Dies muss nur einmal pro Programm durchgeführt werden und wird für spätere erneute Deployments desselben Programms wiederverwendet.

Die Toolchain enthielt eine Abkürzung, die jedoch auslaufen wird / veraltet ist:

cargo-build-sbf

Erstmalige Deployment

Jetzt kann die ausführbare Datei auf das Programmkonto hochgeladen werden:

Loader-v3

Der Parameter heißt program-id, obwohl er den Dateipfad eines Keypairs erwartet:

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

Redeployment

Das erneute Hochladen einer anderen ausführbaren Datei auf dasselbe Programmkonto wird diese überschreiben/ersetzen. Für Redeployments wird jedoch nur die Programm-ID (pubkey des Programm-keypairs) benötigt, nicht das gesamte Keypair, da der Signer das Upgrade-Authority-Keypair ist.

Loader-v3

Dies ist genau dasselbe wie beim ersten Deployment:

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

Wenn die alte ausführbare Datei kürzer war als die neue, könnte es notwendig sein, das programdata account zuerst zu vergrößern:

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

Loader-v4

Beachten Sie, dass beim ersten Deployment program-keypair verwendet wurde, während beim Redeployment stattdessen program-id verwendet wird:

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

Priorisierung eines Uploads

In Zeiten hoher Auslastung gibt es einige zusätzliche Flags, die Sie zur Unterstützung bei der Programm-Bereitstellung verwenden können:

• --with-compute-unit-price: Legt den Compute-Unit-Preis für die Transaktion fest, in Schritten von 0,000001 Lamports (Mikro-Lamports) pro Compute-Unit. Verwenden Sie die Priority Fee API von Helius, um eine Schätzung der zu setzenden priority fee zu erhalten.
• --use-rpc: Sendet Schreibtransaktionen an den konfigurierten RPC anstatt an Validator-TPUs. Dieses Flag erfordert eine stake-weighted RPC- Verbindung wie Helius oder Triton. Dieses Flag kann auch als Standard konfiguriert werden mit: solana config set --url <RPC_URL>.
• --max-sign-attempts: Maximale Anzahl von Versuchen, Transaktionen zu signieren oder neu zu signieren nach Ablauf des Blockhash. Wenn Transaktionen, die während des Programm-Deployments gesendet wurden, nach Ablauf des ursprünglich gewählten aktuellen Blockhash noch nicht bestätigt sind, werden diese Transaktionen mit einem neuen aktuellen Blockhash neu signiert und erneut gesendet. Verwenden Sie diese Einstellung, um die maximale Anzahl von Transaktions-Signierungsiterationen anzupassen. Jeder Blockhash ist etwa 60 Sekunden gültig, was bedeutet, dass die Verwendung des Standardwerts von 5 dazu führt, dass Transaktionen für mindestens 5 Minuten gesendet werden oder bis alle Transaktionen bestätigt sind, je nachdem, was zuerst eintritt.

Fortsetzen eines Uploads

Es ist möglich, dass ein Upload hängen bleibt oder abgebrochen wird.

Loader-v3

Wenn das Deployment eines Programms fehlschlägt, bleibt ein hängendes Zwischen-Buffer-Account mit einem Guthaben ungleich Null zurück. Um dieses Guthaben zurückzugewinnen, können Sie ein fehlgeschlagenes Deployment fortsetzen, indem Sie denselben Zwischen-Buffer für einen neuen Aufruf von deploy bereitstellen.

Bei Deployment-Fehlern wird eine Fehlermeldung angezeigt, die die seed-Phrase angibt, die zur Wiederherstellung des generierten Zwischen-Buffer-Keypairs benötigt wird:

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

Um das keypair wiederherzustellen:

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

Geben Sie bei Aufforderung die 12-Wörter-seed-Phrase ein.

Geben Sie dann einen neuen deploy Befehl ein und spezifizieren Sie den Buffer:

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 ist möglich, einen Upload an einem bestimmten Byte-Offset fortzusetzen:

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

Finalisierung

Dies ist eine irreversible Aktion.

Ein Programm kann unveränderlich gemacht werden, indem seine Upgrade-Authority entfernt wird.

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

Anstatt Programme zu überschreiben, ist es auch möglich, Benutzern die Wahl zu lassen, welche Version eines Programms sie verwenden möchten, indem eine verknüpfte Liste finalisierter Programme erstellt wird:

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

Schließen

Bei Programmen, die unter Loader-v3 bereitgestellt wurden, können nur ihr programdata account, die Buffer-Accounts und die darin gesperrten Gelder zurückgefordert werden. Das program account zusammen mit der Programm-ID und den speziell im program account gesperrten Geldern sind festgesetzt.

Programme, die unter loader-v4 bereitgestellt wurden, können mit ihrem Programm-Konto geschlossen werden, wobei ihre Programm-ID und ihre gesperrten Gelder wieder für andere Zwecke verfügbar werden.

Loader-v3

Dies ist eine irreversible Aktion für Programme, die mit loader-v3 bereitgestellt wurden.

Beachten Sie, dass sobald ein Programm geschlossen ist, seine Programm-ID nicht wiederverwendet werden kann. Der Versuch, ein Programm mit einer zuvor geschlossenen Programm-ID bereitzustellen, führt zu einem Fehler. Wenn Sie ein Programm nach dem Schließen erneut bereitstellen müssen, müssen Sie eine neue Programm-keypair-Datei generieren.

Um ein einzelnes programdata account zu schließen:

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

Um alle Buffer-Accounts zu schließen, die mit der aktuellen Authority verknüpft sind:

solana program close --buffers

Loader-v4

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

Metadaten inspizieren

Der Unterbefehl show listet die Metadaten eines Programms auf.

Eine Beispielausgabe sieht so aus:

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

• Program Id ist die Adresse, auf die im Feld program_id einer Anweisung verwiesen werden kann, wenn ein Programm aufgerufen wird.
• Owner: Der Loader, mit dem dieses Programm bereitgestellt wurde.
• ProgramData Address ist das programdata account, das mit dem Programm-Konto verknüpft ist und den ausführbaren Code des Programms enthält (nur loader-v3).
• Status: retracted, deployed oder finalized (nur loader-v4).
• Authority ist die Upgrade-Authority des Programms.
• Last Deployed In Slot ist der slot, in dem das Programm zuletzt bereitgestellt wurde.
• Data Length ist die Größe des für Deployments reservierten Speicherplatzes. Der tatsächlich vom aktuell bereitgestellten Programm genutzte Speicherplatz kann geringer sein.

Loader-v3

Um ein bestimmtes Programm anzuzeigen:

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

Um die Liste der Programme anzuzeigen, die mit der Standard-Authority bereitgestellt wurden:

solana program show --programs

Um alle Buffer-Accounts unabhängig von der Authority anzuzeigen:

solana program show --buffers --all

Um eine andere Authority anzugeben:

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

Loader-v4

Um ein bestimmtes Programm anzuzeigen:

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

Um die Liste der Programme anzuzeigen, die mit der Standard-Authority bereitgestellt wurden:

solana program-v4 show --all

Um die Liste der Programme anzuzeigen, die mit einer bestimmten Authority bereitgestellt wurden:

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

Herunterladen der ausführbaren Datei

Manchmal ist es nützlich, ein Programm herunterzuladen und zu vergleichen, um sicherzustellen, dass es eine bekannte ausführbare Datei enthält. Die heruntergeladene Datei kann gekürzt, gehasht und mit dem Hash der ursprünglichen Programmdatei verglichen werden.

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

Fortgeschritten: Authority-Übertragung

Das Recht, ein bestimmtes Programm zu ändern, liegt bei seiner Authority. Diese Authority kann auf ein anderes keypair übertragen werden, ohne das Programm-keypair zu ändern, sodass die Programm-ID gleich bleibt. Darüber hinaus kann eine einzelne Authority mehrere program accounts kontrollieren.

Wenn während des ersten Deployments nicht ausdrücklich angegeben, wird das Standard-keypair als Authority verwendet. Deshalb war es in den obigen Schritten beim erneuten Deployment eines Programms nicht erforderlich, eine Authority explizit anzugeben.

Eine explizite Authority ist nützlich für Offline-Signierung und von mehreren Entitäten verwaltete Programme.

Zunächst muss ein keypair für die Authority generiert werden:

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

Loader-v3

Die Authority kann während des Deployments angegeben werden:

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

Oder nach dem Deployment und unter Verwendung des Standard-keypairs als aktuelle Authority:

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

Oder nach dem Deployment und unter Angabe der aktuellen Autorität:

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

Die Autorität kann während des Deployments angegeben werden:

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

Oder nach dem Deployment und unter Verwendung des Standard-Keypairs als aktuelle Autorität:

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

Oder nach dem Deployment und unter Angabe der aktuellen Autorität:

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

Fortgeschritten: Zweistufiges Redeployment mit einem Buffer

Anstatt direkt auf das Programm-Konto hochzuladen, kann die ausführbare Datei zuerst auf ein Buffer-Account hochgeladen und dann in einem zweiten Schritt (dem eigentlichen Re-/Deployment) auf das Programm-Konto übertragen werden. Dies ist nützlich für Offline-Signierung und von mehreren Entitäten verwaltete Programme, wie z.B. eine DAO-Abstimmung zur Auswahl oder Ablehnung einer hochgeladenen ausführbaren Datei vor dem eigentlichen Redeployment.

Beachten Sie, dass die Verwendung von Buffer-Accounts die während des Upload-Prozesses benötigten Mittel ungefähr verdoppelt, da zwei Konten gleichzeitig jeweils eine ausführbare Datei enthalten.

Zunächst muss ein Keypair für das Buffer-Account erstellt werden:

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

Das Buffer-Account kann für verschiedene Uploads wiederverwendet werden und ist nicht an ein bestimmtes Programm-Konto gebunden.

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

Fortgeschritten: Offline-Signierung

Einige Sicherheitsmodelle erfordern die Trennung des Signierungsprozesses von der Transaktionsübertragung, sodass die Signierungsschlüssel vollständig von jedem Netzwerk getrennt sein können, auch bekannt als Offline-Signierung.

Beachten Sie, dass nur Redeployments im Offline-Modus durchgeführt werden können. Das erste Programm-Deployment muss von einem Online-Gerät aus durchgeführt werden, und nur nachfolgende Programm-Redeployments können die Offline-Signierung nutzen.

Ein typisches Setup würde aus zwei verschiedenen Signern bestehen:

• Online-Signer (Fee-Zahler und Autorität des Buffer-Accounts)
• Offline-Signer (Autorität des Programm-Kontos)

Der allgemeine Prozess ist eine zweistufige Neubereitstellung mit einigen Extras:

1. (online) ein neues Programm erstellen
2. (online) die Berechtigung an den Offline-Signer übertragen
3. (online) Puffer erstellen und eine ausführbare Datei hochladen
4. (optional) die Inhalte des Puffers auf der Blockchain überprüfen
5. (offline) eine Transaktion signieren, um das Programm mit dem Puffer neu bereitzustellen --blockhash <VALUE> --sign-only
6. (online) diese Signatur verwenden, um die Neubereitstellungstransaktion zu übertragen --blockhash <VALUE> --signer <OFFLINE_SIGNER_PUBKEY>:<OFFLINE_SIGNER_SIGNATURE>

Suchen Sie einen aktuellen blockhash und fügen Sie ihn ein, um die Offline-Transaktionssignatur zu generieren. Der blockhash läuft nach etwa 60 Sekunden ab. Wenn Sie es nicht rechtzeitig geschafft haben - holen Sie einfach einen neuen Hash und wiederholen Sie den Vorgang bis zum Erfolg, oder erwägen Sie die Verwendung von dauerhaften Transaktions-Nonces.