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 build (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 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

Việc tải lên một tệp thực thi khác vào cùng một tài khoản chương trình sẽ ghi đè / thay thế nó. Tuy nhiên, đối với việc triển khai lại, chỉ cần ID chương trình (pubkey của cặp khóa chương trình), không cần toàn bộ keypair, vì người ký là cặp khóa của cơ quan 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 tài khoản programdata 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ì TPU của validator. Cờ này yêu cầu kết nối RPC có trọng số stake 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 ký giao dịch tối đa. Mỗi blockhash có hiệu lực 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, hãy 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 vị trí byte được chỉ định:

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à 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 chương trình cùng với ID chương trình và tiền bị khóa cụ thể trong tài khoản chương trình 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à 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 một khi 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 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 instruction 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 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ó thẩm quyền của nó. Thẩm quyền này có thể được chuyển giao cho một keypair khác mà không cần 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 thẩm quyền duy nhất có thể kiểm soát nhiều tài khoản chương trình.

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 thẩ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õ thẩm quyền.

Một thẩm quyền 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 thẩm quyền phải được tạo:

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

Loader-v3

Thẩm 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 thẩ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 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

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 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 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 tài khoản chương trình, tệp thực thi có thể được tải lên tài khoản buffer tạm thời trước và sau đó được chuyển đến tài khoản chương trình trong bước thứ hai (triển khai hoặc 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ư DAO bỏ phiếu để chọn hoặc từ chối 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ỳ tài khoản chương trình 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ó thể thực hiện triển khai lại ở 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 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ó quyền đối với tài khoản buffer)
• người ký offline (có quyền đối với tài khoản chương trình)

Quy trình chung là quá trình triển khai lại hai bước với một số tính năng 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 buffer và tải một tệp thực thi vào đó
4. (tùy chọn) xác minh nội dung trên chuỗi của buffer
5. (ngoại tuyến) ký một giao dịch để triển khai lại chương trình sử dụng buffer --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>

Tìm kiếm 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 durable transaction nonces.