Menerapkan Program

Panduan ini mengasumsikan pengetahuan tentang topik-topik berikut:

• Model akun Solana
• Program Solana secara umum
• Mengembangkan program Solana kustom

Loader-v3 dan Loader-v4

Saat ini sedang berlangsung transisi dari loader-v3 (subperintah program) ke loader-v4 (subperintah program -v4) karena loader-v3 sedang dalam proses penghentian.

Untuk penerapan baru, silakan gunakan solana program-v4 deploy alih-alih solana program deploy.

Untuk memigrasikan program yang sudah ada (yang pada dasarnya adalah menerapkannya kembali):

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

Persiapan

Pertama, program perlu dibangun (dikompilasi, ditautkan, distrip).

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

Langkah ini harus dilakukan sebelum setiap penerapan ulang/penerapan.

Periksa bahwa dana yang cukup tersedia di akun pembayar default sebanding dengan ukuran executable:

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

Selain itu, setiap program memiliki akun program dan ID program, yang merupakan alamat dari akun program tersebut. Berikut ini menghasilkan keypair untuk akun program:

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

Ini hanya perlu dilakukan sekali per program dan akan digunakan kembali untuk penerapan ulang program yang sama di kemudian hari.

Toolchain memiliki jalan pintas, namun sedang dihapus/ dihentikan:

cargo-build-sbf

Penerapan Awal

Sekarang executable dapat diunggah ke akun program:

Loader-v3

Parameternya disebut program-id meskipun sebenarnya mengharapkan jalur file dari keypair:

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

Penerapan ulang

Mengunggah executable yang berbeda ke program account yang sama akan menimpa/menggantinya. Namun, untuk penerapan ulang, hanya program ID (pubkey dari program keypair) yang diperlukan, bukan seluruh keypair, karena penandatangan adalah upgrade authority keypair.

Loader-v3

Ini persis sama dengan penerapan awal:

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

Jika executable lama lebih pendek dari yang baru, mungkin perlu untuk memperbesar programdata account terlebih dahulu:

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

Loader-v4

Perhatikan bahwa penerapan awal menggunakan program-keypair, sementara penerapan ulang menggunakan program-id:

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

Memprioritaskan unggahan

Selama waktu kemacetan, ada beberapa flag tambahan yang dapat Anda gunakan untuk membantu penerapan program:

• --with-compute-unit-price: Tetapkan harga unit komputasi untuk transaksi, dalam kelipatan 0,000001 lamport (micro-lamports) per unit komputasi. Gunakan Priority Fee API oleh Helius untuk mendapatkan perkiraan biaya prioritas yang akan ditetapkan.
• --use-rpc: Kirim transaksi tulis ke RPC yang dikonfigurasi alih-alih validator TPU. Flag ini memerlukan koneksi RPC stake-weighted seperti Helius atau Triton. Flag ini juga dapat dikonfigurasi menjadi default menggunakan: solana config set --url <RPC_URL>.
• --max-sign-attempts: Jumlah maksimum upaya untuk menandatangani atau menandatangani ulang transaksi setelah kedaluwarsa blockhash. Jika ada transaksi yang dikirim selama penerapan program masih belum dikonfirmasi setelah blockhash terbaru yang dipilih kedaluwarsa, transaksi tersebut akan ditandatangani ulang dengan blockhash terbaru dan dikirim ulang. Gunakan pengaturan ini untuk menyesuaikan jumlah maksimum iterasi penandatanganan transaksi. Setiap blockhash berlaku sekitar 60 detik, yang berarti menggunakan nilai default 5 akan mengarah pada pengiriman transaksi setidaknya selama 5 menit atau sampai semua transaksi dikonfirmasi, mana yang lebih dulu terjadi.

Melanjutkan Upload

Ada kemungkinan upload terhenti atau dibatalkan.

Loader-v3

Jika deployment program gagal, akan ada akun buffer perantara yang menggantung yang berisi saldo tidak nol. Untuk mendapatkan kembali saldo tersebut, Anda dapat melanjutkan deployment yang gagal dengan menyediakan buffer perantara yang sama ke panggilan baru untuk deploy.

Kegagalan deployment akan mencetak pesan kesalahan yang menentukan seed phrase yang diperlukan untuk memulihkan keypair buffer perantara yang dihasilkan:

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

Untuk memulihkan keypair:

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

Saat diminta, masukkan seed phrase 12 kata.

Kemudian keluarkan perintah deploy baru dan tentukan 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

Dimungkinkan untuk melanjutkan upload pada offset byte tertentu:

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

Finalisasi

Ini adalah tindakan yang tidak dapat dibalik.

Program dapat dibuat tidak dapat diubah dengan menghapus otoritas upgrade-nya.

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

Alih-alih menimpa program, juga dimungkinkan untuk memberikan pengguna pilihan versi program mana yang ingin mereka gunakan dengan membangun linked list program yang telah difinalisasi:

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

Penutupan

Untuk program yang di-deploy di bawah loader-v3, hanya akun programdata, akun buffer dan dana yang terkunci di dalamnya yang dapat diklaim kembali. Akun program bersama dengan ID program dan dana yang terkunci khusus di akun program tidak dapat diambil kembali.

Program yang di-deploy dengan loader-v4 dapat ditutup beserta akun programnya, program ID dan dana yang terkunci semuanya akan tersedia kembali untuk penggunaan lain.

Loader-v3

Ini adalah tindakan yang tidak dapat dibalik untuk program yang di-deploy menggunakan loader-v3.

Perhatikan bahwa setelah program ditutup, program ID-nya tidak dapat digunakan kembali. Upaya untuk men-deploy program dengan program ID yang sebelumnya telah ditutup akan menghasilkan error. Jika Anda perlu men-deploy ulang program setelah menutupnya, Anda harus membuat file program keypair baru.

Untuk menutup satu akun programdata:

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

Untuk menutup semua akun buffer yang terkait dengan authority saat ini:

solana program close --buffers

Loader-v4

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

Memeriksa Metadata

Subperintah show menampilkan metadata dari sebuah program.

Contoh outputnya seperti:

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

• Program Id adalah alamat yang dapat direferensikan di field program_id sebuah instruksi ketika memanggil program.
• Owner: Loader yang digunakan untuk men-deploy program ini.
• ProgramData Address adalah akun programdata yang terkait dengan akun program yang menyimpan executable program (hanya untuk loader-v3).
• Status: retracted, deployed atau finalized (hanya untuk loader-v4).
• Authority adalah authority upgrade program.
• Last Deployed In Slot adalah slot di mana program terakhir kali di-deploy.
• Data Length adalah ukuran ruang yang dicadangkan untuk deployment. Ruang yang sebenarnya digunakan oleh program yang saat ini di-deploy mungkin lebih kecil.

Loader-v3

Untuk melihat program tertentu:

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

Untuk melihat daftar program yang di-deploy dengan authority default:

solana program show --programs

Untuk menampilkan semua akun buffer tanpa memperhatikan authority:

solana program show --buffers --all

Untuk menentukan authority yang berbeda:

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

Loader-v4

Untuk melihat program tertentu:

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

Untuk melihat daftar program yang di-deploy dengan authority default:

solana program-v4 show --all

Untuk melihat daftar program yang di-deploy dengan authority tertentu:

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

Mengunduh Executable

Terkadang sangat berguna untuk mengunduh dan membandingkan program untuk memastikan program tersebut berisi executable yang dikenal. File yang diunduh dapat dipotong, di-hash, dan dibandingkan dengan hash dari file program asli.

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

Lanjutan: Transfer Authority

Hak untuk mengubah program tertentu berada pada authority-nya. Authority ini dapat ditransfer ke keypair lain tanpa mengubah keypair program, sehingga ID program tetap sama. Selain itu, satu authority dapat mengontrol beberapa program account.

Jika tidak ditentukan secara eksplisit selama deployment awal, maka keypair default akan digunakan sebagai authority. Inilah mengapa men-deploy ulang program dalam langkah-langkah di atas tidak memerlukan authority yang ditentukan secara eksplisit.

Authority eksplisit berguna untuk penandatanganan offline dan program yang diatur oleh multi-entitas.

Pertama, keypair untuk authority harus dibuat:

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

Loader-v3

Authority dapat ditentukan selama deployment:

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

Atau setelah deployment dan menggunakan keypair default sebagai authority saat ini:

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

Atau setelah deployment dan menentukan authority saat ini:

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

Authority dapat ditentukan selama deployment:

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

Atau setelah deployment dan menggunakan keypair default sebagai authority saat ini:

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

Atau setelah deployment dan menentukan authority saat ini:

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

Lanjutan: Redeployment dua langkah menggunakan buffer

Alih-alih mengunggah langsung ke program account, executable dapat diunggah ke akun buffer staging terlebih dahulu dan kemudian ditransfer ke program account pada langkah kedua (re-/deployment yang sebenarnya). Ini berguna untuk penandatanganan offline dan program yang diatur oleh multi-entitas seperti voting DAO untuk memilih atau menolak executable yang diunggah sebelum redeployment yang sebenarnya.

Perlu diingat bahwa menggunakan akun buffer kurang lebih menggandakan dana yang diperlukan selama proses unggahan karena dua akun masing-masing menyimpan satu executable secara bersamaan.

Pertama, keypair untuk akun buffer harus dibuat:

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

Akun buffer dapat digunakan kembali untuk unggahan yang berbeda dan tidak terikat pada program account tertentu.

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

Lanjutan: Penandatanganan offline

Beberapa model keamanan memerlukan pemisahan proses penandatanganan dari penyiaran transaksi, sehingga kunci penandatanganan dapat sepenuhnya terputus dari jaringan apa pun, juga dikenal sebagai penandatanganan offline.

Perhatikan bahwa hanya redeployment yang dapat dilakukan dalam mode offline. Deployment program awal harus dilakukan dari mesin online, dan hanya redeployment program berikutnya yang dapat memanfaatkan penandatanganan offline.

Pengaturan tipikal akan terdiri dari dua penandatangan berbeda:

• penandatangan online (pembayar biaya dan authority akun buffer)
• penandatangan offline (authority program account)

Proses umum adalah penerapan ulang dua langkah dengan beberapa tambahan:

1. (online) buat program baru
2. (online) transfer otoritas ke penandatangan offline
3. (online) buat buffer dan unggah executable ke dalamnya
4. (opsional) verifikasi konten on-chain buffer
5. (offline) tandatangani transaksi untuk menerapkan ulang program menggunakan buffer --blockhash <VALUE> --sign-only
6. (online) gunakan tanda tangan ini untuk menyiarkan transaksi penerapan ulang --blockhash <VALUE> --signer <OFFLINE_SIGNER_PUBKEY>:<OFFLINE_SIGNER_SIGNATURE>

Cari blockhash terbaru dan tempelkan untuk menghasilkan tanda tangan transaksi offline. blockhash kedaluwarsa setelah ~60 detik. Jika Anda tidak berhasil tepat waktu - dapatkan hash baru dan ulangi sampai berhasil, atau pertimbangkan untuk menggunakan nonce transaksi yang tahan lama.