Programma's implementeren

Deze handleiding gaat ervan uit dat je kennis hebt van de volgende onderwerpen:

• Solana accountmodel
• Solana programma's in het algemeen
• Ontwikkelen van aangepaste Solana programma's

Er is momenteel een lopende overgang van loader-v3 (program subcommand) naar loader-v4 (program -v4 subcommand) omdat loader-v3 wordt uitgefaseerd.

Gebruik voor nieuwe implementaties solana program-v4 deploy in plaats van solana program deploy.

Om een bestaand programma te migreren (wat in wezen het opnieuw implementeren is):

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

Voorbereiding

Eerst moet het programma worden gebouwd (gecompileerd, gelinkt, gestript).

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

Deze stap moet vóór elke (her)implementatie worden uitgevoerd.

Controleer of er voldoende fondsen beschikbaar zijn op het standaard betaalaccount in verhouding tot de grootte van het uitvoerbare bestand:

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

Daarnaast heeft elk programma een programma-account en een programma-ID, wat het adres is van dat programma-account. Het volgende genereert een keypair voor het programma-account:

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

$ 
solana-keygen newCopy

Dit maakt standaard een keypair aan op ~/.config/solana/id.json.

cargo-build-sbf

Initiële implementatie

Nu kan het uitvoerbare bestand worden geüpload naar het programma-account:

Kies naar welk Solana-cluster je wilt implementeren. Gebruik het solana config get-commando om je huidige configuratie te controleren:

$ 
solana config get
Copy
[show output]

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

$ 
solana config set --url mainnet-beta
Copy
$ 
solana config set --url devnet
Copy
$ 
solana config set --url localhost
Copy
$ 
solana config set --url testnet
Copy
$ 
solana config set --url "https://your-rpc-url.com"Copy

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

Herplaatsing

Het uploaden van een andere executable naar hetzelfde program account zal het overschrijven/vervangen. Voor herplaatsingen is echter alleen de program ID (pubkey van het program keypair) nodig, niet het volledige keypair, omdat de ondertekenaar de upgrade authority keypair is.

Loader-v3

Voor devnet of localhost kun je je wallet financieren met het solana airdrop-commando:

$ 
solana airdrop 2
Copy
[show output]

Als de oude executable korter was dan de nieuwe, kan het nodig zijn om eerst het programdata account te vergroten:

$ 
solana balance
Copy
[show output]

Loader-v4

Merk op dat de initiële plaatsing program-keypair gebruikte, terwijl de herplaatsing program-id gebruikt:

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

Een upload prioriteren

Om een programma te bouwen, gebruik je het cargo build-sbf-commando:

$ 
cargo build-sbfCopy

Een upload hervatten

Het is mogelijk dat een upload vastloopt of wordt afgebroken.

Loader-v3

Als de programma-implementatie mislukt, blijft er een tussenliggend bufferaccount hangen dat een saldo bevat dat niet nul is. Om dit saldo terug te krijgen, kun je een mislukte implementatie hervatten door dezelfde tussenliggende buffer te gebruiken voor een nieuwe aanroep naar deploy.

Om het keypair te herstellen:

Bouw je programma met het cargo build-sbf-commando:

$ 
cargo build-sbfCopy

Dit maakt twee belangrijke bestanden aan in target/deploy/:

1. hello_world-keypair.json: Een keypair-bestand waarvan de publieke sleutel wordt gebruikt als je program-ID
2. hello_world.so: Het gecompileerde programma-uitvoerbare bestand

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

Afronding

Dit is een onomkeerbare actie.

Een programma kan onveranderlijk worden gemaakt door de upgrade-autoriteit te verwijderen.

$ 
wc -c < ./target/deploy/hello_world.so
Copy
[show output]

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

$ 
solana rent 18504
Copy
[show output]

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

In plaats van programma's te overschrijven, is het ook mogelijk om gebruikers de keuze te geven welke versie van een programma ze willen gebruiken door een gekoppelde lijst van afgeronde programma's te maken:

Gebruik het solana program deploy-commando om je programma te implementeren:

$ 
solana program deploy ./target/deploy/hello_world.so
Copy
[show output]

Voor programma's die zijn geïmplementeerd onder loader-v3 kunnen alleen hun programdata account, de buffer accounts en de fondsen die daarin zijn vergrendeld worden teruggevorderd. Het programma-account samen met de programma-ID en fondsen die specifiek in het programma-account zijn vergrendeld, zitten vast.

Programma's die zijn geïmplementeerd onder loader-v4 kunnen worden gesloten, waardoor hun programma-account, hun programma-ID en hun vergrendelde fondsen weer beschikbaar komen voor ander gebruik.

Loader-v3

$ 
solana program deploy ./target/deploy/hello_world.so --program-id ./custom-keypair.jsonCopy

Je kunt nieuwe keypairs genereren met het solana-keygen-commando:

$ 
solana-keygen new -o ./custom-keypair.jsonCopy

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

Om alle buffer accounts te sluiten die gekoppeld zijn aan de huidige autoriteit:

Update je programma met hetzelfde solana program deploy commando:

1. Breng wijzigingen aan in je programmacode
2. Herbouw je programma: cargo build-sbf
3. Implementeer de update:

$ 
solana program deploy ./target/deploy/hello_world.so
Copy
[show output]

Metadata inspecteren

Het show subcommando toont de metadata van een programma.

Een voorbeelduitvoer ziet er als volgt uit:

$ 
solana program extend 7NxQjW8H8hVcqBKgXbVDWqGQCovHbqDW9p1SJJwUyTpE 1000
Copy
[show output]

• Program Id is het adres dat kan worden gerefereerd in het program_id veld van een instructie bij het aanroepen van een programma.
• Owner: De loader waarmee dit programma is geïmplementeerd.
• ProgramData Address is de programdata account die gekoppeld is aan de programma-account en die de uitvoerbare code van het programma bevat (alleen loader-v3).
• Status: retracted, deployed of finalized (alleen loader-v4).
• Authority is de upgrade-autoriteit van het programma.
• Last Deployed In Slot is de slot waarin het programma voor het laatst is geïmplementeerd.
• Data Length is de grootte van de ruimte die is gereserveerd voor implementaties. De werkelijke ruimte die door het momenteel geïmplementeerde programma wordt gebruikt, kan minder zijn.

Loader-v3

Om een specifiek programma te bekijken:

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

Om je programma-metadata te controleren, gebruik je het solana program show commando:

$ 
solana program show 7NxQjW8H8hVcqBKgXbVDWqGQCovHbqDW9p1SJJwUyTpECopy

Om alle buffer accounts te tonen, ongeacht de autoriteit:

solana program show --buffers --all

$ solana program show 7283x8k8fyBcfaFLyPsxbd2VV1AMmZFP7FNoyTXVKJw7
Program Id: 7283x8k8fyBcfaFLyPsxbd2VV1AMmZFP7FNoyTXVKJw7
Owner: BPFLoaderUpgradeab1e11111111111111111111111
ProgramData Address: Gqn7YQVCP8NtYV1qkEqR4Udhj8EJ3fkikvS7HskCNQ7c
Authority: 5kh6HxYZiAebF8HWLsUWod2EaQQ6iWHpHYCz8UcmFbM1
Last Deployed In Slot: 6573
Data Length: 18504 (0x4848) bytes
Balance: 0.12999192 SOL

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

Loader-v4

Om een specifiek programma te bekijken:

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

Om de lijst met programma's te bekijken die zijn geïmplementeerd met de standaardautoriteit:

solana program-v4 show --all

Om de lijst met programma's te bekijken die zijn geïmplementeerd met een specifieke autoriteit:

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

Het uitvoerbare bestand downloaden

Soms is het nuttig om een programma te downloaden en te vergelijken om er zeker van te zijn dat het een bekend uitvoerbaar bestand bevat. Het gedownloade bestand kan worden ingekort, gehasht en vergeleken met de hash van het originele programmabestand.

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

Geavanceerd: overdracht van autoriteit

Het recht om een bepaald programma te wijzigen ligt bij de autoriteit ervan. Deze autoriteit kan worden overgedragen aan een andere keypair zonder het programma keypair te wijzigen, zodat de programma-ID hetzelfde blijft. Bovendien kan één autoriteit meerdere program accounts beheren.

Om de programma-autoriteit over te dragen naar een ander account, gebruik je het solana program set-upgrade-authority commando:

$ 
solana program set-upgrade-authority 7NxQjW8H8hVcqBKgXbVDWqGQCovHbqDW9p1SJJwUyTpE --new-upgrade-authority ./new-authority-keypair.jsonCopy

Eerst moet er een keypair voor de autoriteit worden gegenereerd:

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

Om je programma onveranderlijk te maken, gebruik je het solana program set-upgrade-authority commando met de --final vlag om de programma-autoriteit te verwijderen:

$ 
solana program set-upgrade-authority 7NxQjW8H8hVcqBKgXbVDWqGQCovHbqDW9p1SJJwUyTpE --final
Copy
[show output]

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

Of na implementatie en met gebruik van de standaard keypair als huidige autoriteit:

Om je programma te sluiten en de SOL die aan het programma-account is toegewezen terug te vorderen, gebruik je het solana program close commando:

$ 
solana program close 7NxQjW8H8hVcqBKgXbVDWqGQCovHbqDW9p1SJJwUyTpE --bypass-warning
Copy
[show output]

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

De autoriteit kan tijdens de implementatie worden gespecificeerd:

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

$ 
solana program show --programsCopy

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

Program Id                                       | Slot       | Authority                                      | Balance
-------------------------------------------------|------------|------------------------------------------------|-------------
7NxQjW8H8hVcqBKgXbVDWqGQCovHbqDW9p1SJJwUyTpE     | 249885434  | 5kh6HxYZiAebF8HWLsUWod2EaQQ6iWHpHYCz8UcmFbM1   | 0.12999192
3KSGCk4m5hqJkTjPHBXUCPcqMwJnK3VmkqEsFUKKGJPK     | 249883212  | 5kh6HxYZiAebF8HWLsUWod2EaQQ6iWHpHYCz8UcmFbM1   | 0.28654328

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

Om een geïmplementeerd programma te downloaden, gebruik je het solana program dump commando:

$ 
solana program dump 7NxQjW8H8hVcqBKgXbVDWqGQCovHbqDW9p1SJJwUyTpE ./downloaded_program.so
Copy
[show output]

Houd er rekening mee dat het gebruik van buffer accounts ongeveer twee keer zoveel fondsen vereist tijdens het uploadproces, omdat twee accounts tegelijkertijd elk een uitvoerbaar bestand bevatten.

Eerst moet er een keypair voor het buffer account worden aangemaakt:

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

Het buffer account kan worden hergebruikt voor verschillende uploads en is niet gebonden aan een specifiek program account.

$ 
solana program deploy ./target/deploy/hello_world.so \
    --with-compute-unit-price 10000 \
    --max-sign-attempts 10 \
    --use-rpcCopy

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

• --with-compute-unit-price: Stel de prioriteitsvergoeding in in micro-lamports (0,000001 SOL) per rekeneenheid. Controleer de Helius Priority Fee API voor actuele tarieven. Een prioriteitsvergoeding is een extra vergoeding die wordt betaald aan de huidige leider om je transactie te prioriteren.
• --max-sign-attempts: Aantal keren om opnieuw te proberen met een nieuwe blockhash als transacties verlopen. (Standaard: 5)
• --use-rpc: Stuur transacties naar de geconfigureerde RPC. Deze vlag vereist een stake-weighted RPC- verbinding van providers zoals Triton of Helius.