Ohjelmien käyttöönotto

Tämä opas olettaa seuraavien aiheiden tuntemusta:

Loader-v3 ja Loader-v4

Tällä hetkellä on käynnissä siirtymä loader-v3:sta (program-alikomento) loader-v4:ään (program -v4 -alikomento), koska loader-v3 on poistumassa käytöstä.

Uusissa käyttöönotoissa käytä solana program-v4 deploy komennon solana program deploy sijaan.

Olemassa olevan ohjelman siirtäminen (mikä on käytännössä sen uudelleenkäyttöönotto):

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

Valmistelu

Ensin ohjelma täytyy rakentaa (kääntää, linkittää, karsia).

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

Tämä vaihe on suoritettava ennen jokaista käyttöönottoa tai uudelleenkäyttöönottoa.

Tarkista, että oletustilin saldo on riittävä suoritettavan ohjelman kokoon nähden:

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

Lisäksi jokaisella ohjelmalla on ohjelmatili ja ohjelmatunnus (program ID), joka on kyseisen ohjelmatilin osoite. Seuraava komento luo avainparin ohjelmatilin:

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

Tämä täytyy tehdä vain kerran ohjelmaa kohden, ja samaa avainparia käytetään myöhemmin saman ohjelman uudelleenkäyttöönotossa.

Työkaluketjussa oli oikotie, mutta se on poistumassa käytöstä:

cargo-build-sbf

Ensimmäinen käyttöönotto

Nyt suoritettava ohjelma voidaan ladata ohjelmatilille:

Loader-v3

Parametrin nimi on program-id vaikka se odottaa avainparin tiedostopolkua:

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

Erilaisen suoritettavan tiedoston lataaminen samaan program account -tiliin uudelleen korvaa/vaihtaa sen. Uudelleenkäyttöönottoa varten tarvitaan kuitenkin vain ohjelmatunnus (program ID, program keypair -avaimen pubkey), ei koko keypair-avainta, koska allekirjoittajana toimii upgrade authority keypair -avain.

Loader-v3

Tämä on täsmälleen sama kuin ensimmäinen käyttöönotto:

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

Jos vanha suoritettava tiedosto oli lyhyempi kuin uusi, saattaa olla tarpeen kasvattaa programdata account -tiliä ensin:

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

Loader-v4

Huomaa, että ensimmäisessä käyttöönotossa käytettiin program-keypair, kun taas uudelleenkäyttöönotossa käytetään program-id:

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

Latauksen priorisointi

Ruuhka-aikoina voit käyttää muutamia lisälippuja auttamaan ohjelman käyttöönotossa:

--with-compute-unit-price: Asettaa laskentayksikön hinnan transaktiolle 0,000001 lamportin (mikro-lamportin) lisäyksinä laskentayksikköä kohden. Käytä Heliuksen Priority Fee API:a saadaksesi arvion asetettavasta prioriteettimaksusta.
--use-rpc: Lähettää kirjoitustransaktiot määritettyyn RPC:hen validaattoreiden TPU:iden sijaan. Tämä lippu vaatii stake-weighted RPC -yhteyden, kuten Helius tai Triton. Tämä lippu voidaan myös määrittää oletusarvoksi käyttämällä: solana config set --url <RPC_URL>.
--max-sign-attempts: Maksimimäärä yrityksiä allekirjoittaa tai uudelleenallekirjoittaa transaktioita blockhash-vanhentumisen jälkeen. Jos jokin ohjelman käyttöönoton aikana lähetetty transaktio on edelleen vahvistamatta alun perin valitun viimeisimmän blockhash-arvon vanhennuttua, nämä transaktiot allekirjoitetaan uudelleen uudella viimeisimmällä blockhash-arvolla ja lähetetään uudelleen. Käytä tätä asetusta säätääksesi transaktioiden allekirjoitusiteraatioiden enimmäismäärää. Kukin blockhash on voimassa noin 60 sekuntia, mikä tarkoittaa, että oletusarvon 5 käyttäminen johtaa transaktioiden lähettämiseen vähintään 5 minuutin ajan tai kunnes kaikki transaktiot on vahvistettu, kumpi tahansa tulee ensin.

Latauksen jatkaminen

On mahdollista, että lataus jumiutuu tai keskeytyy.

Loader-v3

Jos ohjelman käyttöönotto epäonnistuu, jäljelle jää väliaikainen puskuritili, jossa on nollasta poikkeava saldo. Saadaksesi saldon takaisin voit jatkaa epäonnistunutta käyttöönottoa antamalla saman väliaikaisen puskurin uudelle deploy -kutsulle.

Käyttöönoton epäonnistuessa näytetään virheviesti, jossa määritetään seed-lause, jota tarvitaan luodun väliaikaisen puskurin keypair-tietojen palauttamiseen:

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

Keypair-tietojen palauttaminen:

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

Kun sinulta kysytään, syötä 12 sanan seed-lause.

Anna sitten uusi deploy -komento ja määritä puskuri:

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

Loader-v4

On mahdollista jatkaa latausta määritetystä tavun sijainnista:

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

Viimeistely

Tämä on peruuttamaton toimenpide.

Ohjelma voidaan tehdä muuttumattomaksi poistamalla sen päivitysoikeus.

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

Ohjelmien ylikirjoittamisen sijaan on myös mahdollista tarjota käyttäjille mahdollisuus valita, mitä ohjelman versiota he haluavat käyttää, luomalla linkitetty lista viimeistellyistä ohjelmista:

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

Sulkeminen

Loader-v3:n alla käyttöönotetuista ohjelmista vain niiden programdata account, puskuritilit ja niihin lukitut varat voidaan palauttaa. Program account sekä ohjelmatunnus ja erityisesti program accountiin lukitut varat jäävät jumiin.

Loader-v4:llä käyttöönotetut ohjelmat voidaan sulkea, jolloin niiden ohjelmatili, ohjelmatunnus ja lukitut varat vapautuvat jälleen muuhun käyttöön.

Loader-v3

Tämä on peruuttamaton toimenpide loader-v3:lla käyttöönotetuille ohjelmille.

Huomaa, että kun ohjelma on suljettu, sen ohjelmatunnusta ei voi käyttää uudelleen. Jos yrität ottaa käyttöön ohjelman aiemmin suljetulla ohjelmatunnuksella, saat virheilmoituksen. Jos haluat ottaa ohjelman uudelleen käyttöön sulkemisen jälkeen, sinun on luotava uusi ohjelma-keypair-tiedosto.

Yksittäisen programdata-tilin sulkeminen:

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

Kaikkien nykyiseen valtuuteen liittyvien puskuritilien sulkeminen:

solana program close --buffers

Loader-v4

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

Metatietojen tarkastelu

show -alikomento näyttää ohjelman metatiedot.

Esimerkki tulosteesta:

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

Program Id on osoite, johon voidaan viitata ohjeen program_id -kentässä ohjelmaa kutsuttaessa.
Owner: Lataaja, jolla tämä ohjelma otettiin käyttöön.
ProgramData Address on ohjelmatiliin liittyvä programdata-tili, joka sisältää ohjelman suoritettavan koodin (vain loader-v3).
Status: retracted, deployed tai finalized (vain loader-v4).
Authority on ohjelman päivitysvaltuus.
Last Deployed In Slot on slot, jossa ohjelma viimeksi otettiin käyttöön.
Data Length on käyttöönottoja varten varatun tilan koko. Nykyisen käyttöönotetun ohjelman käyttämä todellinen tila voi olla pienempi.

Loader-v3

Tietyn ohjelman tarkasteleminen:

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

Oletusvaltuudella käyttöönotettujen ohjelmien luettelon tarkasteleminen:

solana program show --programs

Kaikkien puskuritilien näyttäminen valtuudesta riippumatta:

solana program show --buffers --all

Eri valtuuden määrittäminen:

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

Loader-v4

Tietyn ohjelman tarkastelu:

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

Oletusvaltuudella käyttöönotettujen ohjelmien luettelon tarkastelu:

solana program-v4 show --all

Tietyllä valtuudella käyttöönotettujen ohjelmien luettelon tarkastelu:

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

Suoritettavan tiedoston lataaminen

Joskus on hyödyllistä ladata ja verrata ohjelmaa varmistaakseen, että se sisältää tunnetun suoritettavan tiedoston. Ladattu tiedosto voidaan katkaista, laskea siitä tiiviste ja verrata sitä alkuperäisen ohjelmatiedoston tiivisteeseen.

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

Edistynyt: valtuuden siirto

Oikeus muuttaa tiettyä ohjelmaa kuuluu sen valtuudelle. Tämä valtuus voidaan siirtää toiselle keypair-avainparille muuttamatta ohjelman keypair-avainparia, jolloin ohjelmatunnus pysyy samana. Lisäksi yksi valtuus voi hallita useita program account -tilejä.

Jos valtuutta ei ole nimenomaisesti määritetty alkuperäisen käyttöönoton yhteydessä, käytetään oletusavainparia valtuutena. Tämän vuoksi ohjelman uudelleenkäyttöönotto yllä olevissa vaiheissa ei vaatinut valtuuden nimenomaista määrittämistä.

Nimenomainen valtuus on hyödyllinen offline-allekirjoituksessa ja usean tahon hallinnoimissa ohjelmissa.

Ensin on luotava avainpari valtuutta varten:

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

Loader-v3

Valtuus voidaan määrittää käyttöönoton aikana:

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

Tai käyttöönoton jälkeen käyttämällä oletusavainparia nykyisenä valtuutena:

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

Tai käyttöönoton jälkeen määrittäen nykyisen valtuuden:

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

Valtuus voidaan määrittää käyttöönoton yhteydessä:

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

Tai käyttöönoton jälkeen käyttäen oletuskeypairiä nykyisenä valtuutena:

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

Tai käyttöönoton jälkeen määrittäen nykyisen valtuuden:

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

Edistynyt: Kaksivaiheinen uudelleenkäyttöönotto puskuria käyttäen

Suoran program accountiin lataamisen sijaan suoritettava koodi voidaan ladata ensin väliaikaiseen puskuritiliin ja siirtää sitten program accountiin toisessa vaiheessa (varsinainen uudelleen-/käyttöönotto). Tämä on hyödyllistä offline-allekirjoituksessa ja usean tahon hallinnoimissa ohjelmissa, kuten DAO-äänestyksessä, jossa päätetään ladatun suoritettavan koodin hyväksymisestä tai hylkäämisestä ennen varsinaista uudelleenkäyttöönottoa.

Huomioi, että puskuritilien käyttö lähes kaksinkertaistaa lataamisprosessissa tarvittavat varat, koska kaksi tiliä pitää hallussaan yhtä suoritettavaa koodia samanaikaisesti.

Ensin on luotava keypair puskuritiliä varten:

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

Puskuritiliä voidaan käyttää uudelleen eri latauksiin, eikä se ole sidottu mihinkään tiettyyn program accountiin.

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

Edistynyt: Offline-allekirjoitus

Jotkin turvallisuusmallit edellyttävät allekirjoitusprosessin erottamista transaktion lähettämisestä, jotta allekirjoitusavaimet voidaan täysin irrottaa verkosta. Tätä kutsutaan offline-allekirjoitukseksi.

Huomaa, että vain uudelleenkäyttöönottoja voidaan suorittaa offline-tilassa. Alkuperäinen ohjelman käyttöönotto täytyy suorittaa verkossa olevalta koneelta, ja vain myöhemmät ohjelman uudelleenkäyttöönotot voivat hyödyntää offline-allekirjoitusta.

Tyypillinen kokoonpano koostuisi kahdesta eri allekirjoittajasta:

online-allekirjoittaja (maksun maksaja ja puskuritilin valtuus)
offline-allekirjoittaja (program accountin valtuus)

Yleinen prosessi on kaksivaiheinen uudelleenkäyttöönotto muutamilla lisäyksillä:

(online) luo uusi ohjelma
(online) siirrä valtuutus offline-allekirjoittajalle
(online) luo puskuri ja lataa suoritettava tiedosto siihen
(valinnainen) tarkista puskurin lohkoketjussa olevat sisällöt
(offline) allekirjoita transaktio ohjelman uudelleenkäyttöönottamiseksi puskuria käyttäen --blockhash <VALUE> --sign-only
(online) käytä tätä allekirjoitusta uudelleenkäyttöönoton transaktion lähettämiseen --blockhash <VALUE> --signer <OFFLINE_SIGNER_PUBKEY>:<OFFLINE_SIGNER_SIGNATURE>

Etsi tuore blockhash ja liitä se generoidaksesi offline-transaktion allekirjoituksen. blockhash vanhenee noin 60 sekunnin kuluttua. Jos et ehtinyt ajoissa - hae vain uusi tuore tiiviste ja toista kunnes onnistut, tai harkitse kestävien transaktiononcen käyttämistä.

Sisällysluettelo