Triển khai các chương trình

Hướng dẫn này giả định bạn đã có kiến thức về các chủ đề sau:

• Mô hình tài khoản Solana
• Tổng quan về chương trình Solana
• Phát triển chương trình Solana tùy chỉnh

Loader-v3 và Loader-v4

Hiện tại đang có quá trình chuyển đổi từ loader-v3 (lệnh phụ program) sang loader-v4 (lệnh phụ program -v4) vì loader-v3 đang bị loại bỏ dần.

Đối với các triển khai mới, vui lòng sử dụng solana program-v4 deploy thay vì solana program deploy.

Để di chuyển một chương trình hiện có (về cơ bản là triển khai lại):

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

Chuẩn bị

Đầu tiên, chương trình cần được xây dựng (biên dịch, liên kết, loại bỏ thông tin gỡ lỗi).

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

Bước này phải được thực hiện trước mỗi lần triển khai hoặc triển khai lại.

Kiểm tra xem tài khoản thanh toán mặc định có đủ tiền tương ứng với kích thước của tệp thực thi hay không:

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

Ngoài ra, mỗi chương trình có một tài khoản chương trình và một ID chương trình, đó là địa chỉ của tài khoản chương trình đó. Lệnh sau tạo ra một keypair cho tài khoản chương trình:

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

Việc này chỉ cần thực hiện một lần cho mỗi chương trình và sẽ được tái sử dụng cho các lần triển khai lại cùng một chương trình sau này.

Bộ công cụ có chứa một cách làm nhanh, tuy nhiên nó đang dần bị loại bỏ/ không còn được hỗ trợ:

cargo-build-sbf

Triển khai ban đầu

Bây giờ tệp thực thi có thể được tải lên tài khoản chương trình:

Loader-v3

Tham số được gọi là program-id mặc dù nó yêu cầu đường dẫn tệp của một 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

Triển khai lại

Tải lên một tệp thực thi khác vào cùng một program account sẽ ghi đè / thay thế nó. Tuy nhiên, đối với việc triển khai lại, chỉ cần program ID (pubkey của program keypair), không cần toàn bộ keypair, vì người ký là keypair của quyền nâng cấp.

Loader-v3

Điều này hoàn toàn giống với việc triển khai ban đầu:

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

Nếu tệp thực thi cũ ngắn hơn tệp mới, có thể cần phải mở rộng programdata account trước:

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

Loader-v4

Lưu ý rằng việc triển khai ban đầu sử dụng program-keypair, trong khi triển khai lại sử dụng program-id thay thế:

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

Ưu tiên tải lên

Trong thời điểm tắc nghẽn, có một vài cờ bổ sung bạn có thể sử dụng để hỗ trợ việc triển khai chương trình:

• --with-compute-unit-price: Đặt giá đơn vị tính toán cho giao dịch, theo đơn vị 0,000001 lamport (micro-lamport) cho mỗi đơn vị tính toán. Sử dụng Priority Fee API của Helius để ước tính phí ưu tiên cần đặt.
• --use-rpc: Gửi giao dịch ghi đến RPC đã cấu hình thay vì validator TPU. Cờ này yêu cầu kết nối RPC có trọng số cổ phần như Helius hoặc Triton. Cờ này cũng có thể được cấu hình làm mặc định bằng cách sử dụng: solana config set --url <RPC_URL>.
• --max-sign-attempts: Số lần thử tối đa để ký hoặc ký lại giao dịch sau khi blockhash hết hạn. Nếu bất kỳ giao dịch nào được gửi trong quá trình triển khai chương trình vẫn chưa được xác nhận sau khi blockhash gần đây đã chọn ban đầu hết hạn, những giao dịch đó sẽ được ký lại với một blockhash gần đây mới và gửi lại. Sử dụng cài đặt này để điều chỉnh số lần lặp lại ký giao dịch tối đa. Mỗi blockhash có hiệu lực trong khoảng 60 giây, nghĩa là sử dụng giá trị mặc định là 5 sẽ dẫn đến việc gửi giao dịch trong ít nhất 5 phút hoặc cho đến khi tất cả giao dịch được xác nhận, tùy điều kiện nào đến trước.

Tiếp tục một quá trình tải lên

Có thể xảy ra trường hợp quá trình tải lên bị treo hoặc bị hủy bỏ.

Loader-v3

Nếu việc triển khai chương trình thất bại, sẽ có một tài khoản bộ đệm trung gian bị treo chứa số dư khác không. Để lấy lại số dư đó, bạn có thể tiếp tục quá trình triển khai đã thất bại bằng cách cung cấp cùng một bộ đệm trung gian cho lệnh gọi mới đến deploy.

Các lỗi triển khai sẽ hiển thị thông báo lỗi chỉ định cụm từ seed cần thiết để khôi phục keypair của bộ đệm trung gian đã tạo:

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

Để khôi phục keypair:

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

Khi được yêu cầu, nhập cụm từ seed gồm 12 từ.

Sau đó đưa ra lệnh deploy mới và chỉ định bộ đệm:

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

Loader-v4

Có thể tiếp tục quá trình tải lên tại một vị trí byte cụ thể:

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

Hoàn thiện

Đây là một hành động không thể đảo ngược.

Một chương trình có thể được làm cho bất biến bằng cách loại bỏ quyền nâng cấp của nó.

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

Thay vì ghi đè các chương trình, cũng có thể cung cấp cho người dùng lựa chọn phiên bản chương trình họ muốn sử dụng bằng cách xây dựng một danh sách liên kết các chương trình đã hoàn thiện:

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

Đóng

Đối với các chương trình được triển khai dưới loader-v3, chỉ có tài khoản programdata, các tài khoản bộ đệm và tiền bị khóa trong những tài khoản đó có thể được lấy lại. Tài khoản program cùng với program ID và tiền bị khóa cụ thể trong tài khoản program sẽ bị mắc kẹt.

Các chương trình được triển khai dưới loader-v4 có thể được đóng cùng với tài khoản chương trình, program ID và các khoản tiền bị khóa của chúng sẽ trở nên khả dụng cho các mục đích khác một lần nữa.

Loader-v3

Đây là một hành động không thể hoàn tác đối với các chương trình được triển khai bằng loader-v3.

Lưu ý rằng khi một chương trình đã bị đóng, program ID của nó không thể được sử dụng lại. Việc cố gắng triển khai một chương trình với program ID đã bị đóng trước đó sẽ dẫn đến lỗi. Nếu bạn cần triển khai lại một chương trình sau khi đóng nó, bạn phải tạo một tệp keypair chương trình mới.

Để đóng một tài khoản programdata:

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

Để đóng tất cả các tài khoản buffer liên kết với quyền hiện tại:

solana program close --buffers

Loader-v4

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

Kiểm tra Metadata

Lệnh phụ show liệt kê metadata của một chương trình.

Một ví dụ về kết quả đầu ra:

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

• Program Id là địa chỉ có thể được tham chiếu trong trường program_id của một lệnh khi gọi một chương trình.
• Owner: Loader mà chương trình này được triển khai.
• ProgramData Address là tài khoản programdata liên kết với tài khoản chương trình chứa phần thực thi của chương trình (chỉ áp dụng cho loader-v3).
• Status: retracted, deployed hoặc finalized (chỉ áp dụng cho loader-v4).
• Authority là quyền nâng cấp của chương trình.
• Last Deployed In Slot là slot mà chương trình được triển khai lần cuối.
• Data Length là kích thước của không gian dành riêng cho việc triển khai. Không gian thực tế được sử dụng bởi chương trình hiện đang triển khai có thể ít hơn.

Loader-v3

Để xem một chương trình cụ thể:

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

Để xem danh sách các chương trình được triển khai với quyền mặc định:

solana program show --programs

Để hiển thị tất cả các tài khoản buffer bất kể quyền là gì:

solana program show --buffers --all

Để chỉ định một quyền khác:

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

Loader-v4

Để xem một chương trình cụ thể:

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

Để xem danh sách các chương trình được triển khai với quyền mặc định:

solana program-v4 show --all

Để xem danh sách các chương trình được triển khai với một quyền cụ thể:

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

Tải xuống tệp thực thi

Đôi khi việc tải xuống và so sánh một chương trình rất hữu ích để đảm bảo nó chứa một tệp thực thi đã biết. Tệp đã tải xuống có thể được cắt ngắn, băm và so sánh với mã băm của tệp chương trình gốc.

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

Nâng cao: Chuyển giao quyền

Quyền thay đổi một chương trình thuộc về người có quyền của nó. Quyền này có thể được chuyển giao cho một keypair khác mà không thay đổi keypair của chương trình, để ID chương trình vẫn giữ nguyên. Hơn nữa, một quyền duy nhất có thể kiểm soát nhiều program account.

Nếu không được chỉ định rõ ràng trong quá trình triển khai ban đầu, thì keypair mặc định sẽ được sử dụng làm quyền. Đó là lý do tại sao việc triển khai lại một chương trình trong các bước trên không yêu cầu phải chỉ định rõ quyền.

Một quyền được chỉ định rõ ràng rất hữu ích cho việc ký offline và các chương trình được quản lý bởi nhiều thực thể.

Đầu tiên, một keypair cho quyền phải được tạo:

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

Loader-v3

Quyền có thể được chỉ định trong quá trình triển khai:

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

Hoặc sau khi triển khai và sử dụng keypair mặc định làm quyền hiện tại:

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

Hoặc sau khi triển khai và chỉ định thẩm quyền hiện tại:

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

Thẩm quyền có thể được chỉ định trong quá trình triển khai:

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

Hoặc sau khi triển khai và sử dụng keypair mặc định làm thẩm quyền hiện tại:

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

Hoặc sau khi triển khai và chỉ định thẩm quyền hiện tại:

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

Nâng cao: Triển khai lại hai bước sử dụng Buffer

Thay vì tải trực tiếp lên program account, tệp thực thi có thể được tải lên một tài khoản buffer tạm thời trước và sau đó được chuyển đến program account trong bước thứ hai (quá trình triển khai/triển khai lại thực sự). Điều này hữu ích cho việc ký offline và các chương trình được quản lý bởi nhiều thực thể như một DAO bỏ phiếu để chọn hoặc từ chối một tệp thực thi đã tải lên trước khi triển khai lại thực sự.

Hãy lưu ý rằng việc sử dụng tài khoản buffer gần như làm tăng gấp đôi số tiền cần thiết trong quá trình tải lên vì hai tài khoản đang chứa một tệp thực thi mỗi tài khoản, cùng một lúc.

Đầu tiên, một keypair cho tài khoản buffer phải được tạo:

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

Tài khoản buffer có thể được tái sử dụng cho các lần tải lên khác nhau và không bị ràng buộc với bất kỳ program account cụ thể nào.

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

Nâng cao: Ký offline

Một số mô hình bảo mật yêu cầu tách biệt quá trình ký khỏi việc phát sóng giao dịch, sao cho các khóa ký có thể hoàn toàn ngắt kết nối khỏi bất kỳ mạng nào, còn được gọi là ký offline.

Lưu ý rằng chỉ có các lần triển khai lại mới có thể được thực hiện ở chế độ offline. Việc triển khai chương trình ban đầu phải được thực hiện từ một máy trực tuyến, và chỉ các lần triển khai lại chương trình sau đó mới có thể tận dụng việc ký offline.

Một thiết lập điển hình sẽ bao gồm hai người ký khác nhau:

• người ký trực tuyến (người trả phí và có thẩm quyền của tài khoản buffer)
• người ký offline (có thẩm quyền của program account)

Quy trình chung là triển khai lại hai bước với một số thao tác bổ sung:

1. (trực tuyến) tạo một chương trình mới
2. (trực tuyến) chuyển quyền cho người ký ngoại tuyến
3. (trực tuyến) tạo bộ đệm và tải tệp thực thi vào đó
4. (tùy chọn) xác minh nội dung trên chuỗi của bộ đệm
5. (ngoại tuyến) ký một giao dịch để triển khai lại chương trình sử dụng bộ đệm --blockhash <VALUE> --sign-only
6. (trực tuyến) sử dụng chữ ký này để phát sóng giao dịch triển khai lại --blockhash <VALUE> --signer <OFFLINE_SIGNER_PUBKEY>:<OFFLINE_SIGNER_SIGNATURE>

Tra cứu một blockhash gần đây và dán vào để tạo chữ ký giao dịch ngoại tuyến. blockhash sẽ hết hạn sau khoảng 60 giây. Nếu bạn không kịp thời gian - chỉ cần lấy một hash mới và lặp lại cho đến khi thành công, hoặc cân nhắc sử dụng nonce giao dịch bền vững.