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 veraltet ist.

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 auslaufend ist / veraltet:

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 von Netzwerküberlastung 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-Buffers keypair 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 geben, 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 die ausführbare Datei 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-Autorität bereitgestellt wurden:

solana program-v4 show --all

Um die Liste der Programme anzuzeigen, die mit einer bestimmten Autorität 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: Autoritätsübertragung

Das Recht, ein bestimmtes Programm zu ändern, liegt bei seiner Autorität. Diese Autorität 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 Autorität mehrere program account kontrollieren.

Wenn während des ersten Deployments nicht ausdrücklich angegeben, wird das Standard-Keypair als Autorität verwendet. Deshalb war es in den obigen Schritten nicht erforderlich, bei der erneuten Bereitstellung eines Programms eine Autorität explizit anzugeben.

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

Zunächst muss ein Keypair für die Autorität generiert werden:

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

Loader-v3

Die Autorität 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 Autorität:

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

Oder nach der Bereitstellung und unter Angabe der aktuellen Authority:

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 Authority 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 Authority:

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 Authority:

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: Zweistufige Neubereitstellung mit einem Buffer

Anstatt direkt in das Programmkonto hochzuladen, kann die ausführbare Datei zuerst in ein Buffer-Account hochgeladen und dann in einem zweiten Schritt (der eigentlichen Neu-/Bereitstellung) in das Programmkonto übertragen werden. Dies ist nützlich für Offline-Signierung und von mehreren Entitäten verwaltete Programme, wie z.B. eine DAO-Abstimmung, um eine hochgeladene ausführbare Datei vor der eigentlichen Neubereitstellung zu akzeptieren oder abzulehnen.

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 Programmkonto 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 Neubereitstellungen im Offline-Modus durchgeführt werden können. Die erste Programmbereitstellung muss von einem Online-Gerät aus durchgeführt werden, und nur nachfolgende Programm-Neubereitstellungen können die Offline-Signierung nutzen.

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

• Online-Signer (Fee-Zahler und Authority des Buffer-Accounts)
• Offline-Signer (Authority des Programmkontos)

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 On-Chain-Inhalte des Puffers ü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 Sie erfolgreich sind, oder erwägen Sie die Verwendung von dauerhaften Transaktions-Nonces.