Развёртывание программ

В этом руководстве предполагается знание следующих тем:

• Модель аккаунтов Solana
• Программы Solana в общем
• Разработка пользовательских программ Solana

Loader-v3 и Loader-v4

В настоящее время происходит переход от loader-v3 (подкоманда program) к loader-v4 (подкоманда program -v4), так как loader-v3 устаревает.

Для новых развёртываний используйте solana program-v4 deploy вместо solana program deploy.

Чтобы перенести существующую программу (по сути, повторно развернуть её):

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

Подготовка

Сначала программу необходимо собрать (скомпилировать, связать, оптимизировать).

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

Этот шаг необходимо выполнять перед каждым повторным/новым развёртыванием.

Убедитесь, что на аккаунте плательщика по умолчанию достаточно средств, пропорционально размеру исполняемого файла:

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

Кроме того, каждая программа имеет аккаунт программы и ID программы, который является адресом этого аккаунта программы. Следующая команда создаёт keypair для аккаунта программы:

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

Это нужно выполнить только один раз для каждой программы, и этот keypair будет использоваться для повторных развёртываний той же программы в будущем.

Инструментарий содержал упрощение, однако оно постепенно выводится из использования/устаревает:

cargo-build-sbf

Первоначальное развёртывание

Теперь исполняемый файл можно загрузить в аккаунт программы:

Loader-v3

Параметр называется program-id, хотя он ожидает путь к файлу 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

Повторное развертывание

Загрузка другого исполняемого файла в тот же аккаунт программы снова перезапишет / заменит его. Однако для повторного развертывания требуется только идентификатор программы (pubkey аккаунта ключей программы), а не весь keypair, так как подписывающим является keypair полномочий на обновление.

Loader-v3

Это полностью аналогично первоначальному развертыванию:

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

Если старый исполняемый файл был короче нового, может потребоваться сначала увеличить аккаунт programdata:

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

Loader-v4

Обратите внимание, что при первоначальном развертывании использовался program-keypair, а при повторном развертывании используется program-id:

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

Приоритет загрузки

Во время перегрузки сети можно использовать несколько дополнительных флагов, чтобы помочь с развертыванием программы:

• --with-compute-unit-price: Установить цену вычислительных единиц для транзакции в микролампортах (0.000001 лампорта) за вычислительную единицу. Используйте Priority Fee API от Helius, чтобы получить оценку приоритетной комиссии.
• --use-rpc: Отправлять транзакции записи на настроенный RPC вместо TPU валидаторов. Этот флаг требует RPC-соединения с весом ставки, такого как Helius или Triton. Этот флаг также можно настроить как значение по умолчанию с помощью: solana config set --url <RPC_URL>.
• --max-sign-attempts: Максимальное количество попыток подписать или переподписать транзакции после истечения срока действия blockhash. Если какие-либо транзакции, отправленные во время развертывания программы, остаются неподтвержденными после истечения срока действия изначально выбранного blockhash, эти транзакции будут переподписаны с новым blockhash и отправлены снова. Используйте эту настройку, чтобы задать максимальное количество итераций подписания транзакций. Каждый blockhash действителен около 60 секунд, что означает, что использование значения по умолчанию 5 приведет к отправке транзакций как минимум в течение 5 минут или до подтверждения всех транзакций, в зависимости от того, что наступит раньше.

Возобновление загрузки

Загрузка может быть прервана или остановлена.

Loader-v3

Если развертывание программы завершилось неудачей, останется зависший промежуточный буферный аккаунт с ненулевым балансом. Чтобы вернуть этот баланс, вы можете возобновить неудачное развертывание, предоставив тот же промежуточный буфер для нового вызова deploy.

При сбое развертывания будет выведено сообщение об ошибке, указывающее seed-фразу, необходимую для восстановления сгенерированного ключевого ключевого keypair промежуточного буфера:

==================================================================================
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:

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

Когда будет предложено, введите 12-словную seed-фразу.

Затем выполните новую команду deploy и укажите буфер:

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

Loader-v4

Можно возобновить загрузку с указанного байтового смещения:

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

Завершение

Это действие необратимо.

Программа может быть сделана неизменяемой путем удаления полномочий на её обновление.

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

Вместо перезаписи программ также можно предоставить пользователям возможность выбора версии программы, которую они хотят использовать, создав связанный список финализированных программ:

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

Закрытие

Для программ, развернутых с использованием loader-v3, можно вернуть только их programdata аккаунт, буферные аккаунты и средства, заблокированные в них. Program аккаунт вместе с ID программы и средствами, заблокированными в program аккаунте, остаются недоступными.

Программы, развернутые с использованием loader-v4, могут быть закрыты вместе с их программным аккаунтом, их программным ID и заблокированными средствами, которые снова становятся доступными для других целей.

Loader-v3

Это необратимое действие для программ, развернутых с использованием loader-v3.

Обратите внимание, что после закрытия программы её программный ID не может быть повторно использован. Попытка развернуть программу с ранее закрытым программным ID приведет к ошибке. Если вам нужно повторно развернуть программу после её закрытия, вы должны сгенерировать новый файл ключевой пары программы.

Чтобы закрыть один аккаунт programdata:

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

Чтобы закрыть все буферные аккаунты, связанные с текущим владельцем:

solana program close --buffers

Loader-v4

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

Просмотр метаданных

Подкоманда show отображает метаданные программы.

Пример вывода выглядит следующим образом:

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

• Program Id — это адрес, который можно указать в поле program_id инструкции при вызове программы.
• Owner: Загрузчик, с которым была развернута эта программа.
• ProgramData Address — это аккаунт programdata, связанный с программным аккаунтом, который содержит исполняемый файл программы (только для loader-v3).
• Status: retracted, deployed или finalized (только для loader-v4).
• Authority — это полномочие на обновление программы.
• Last Deployed In Slot — это слот, в котором программа была развернута в последний раз.
• Data Length — это размер пространства, зарезервированного для развертываний. Фактическое пространство, используемое текущей развернутой программой, может быть меньше.

Loader-v3

Чтобы просмотреть конкретную программу:

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

Чтобы просмотреть список программ, развернутых с использованием владельца по умолчанию:

solana program show --programs

Чтобы показать все буферные аккаунты независимо от владельца:

solana program show --buffers --all

Чтобы указать другого владельца:

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

Loader-v4

Для просмотра определенной программы:

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

Для просмотра списка программ, развернутых с правами доступа по умолчанию:

solana program-v4 show --all

Для просмотра списка программ, развернутых с определенными правами доступа:

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

Загрузка исполняемого файла

Иногда полезно загрузить и сравнить программу, чтобы убедиться, что она содержит известный исполняемый файл. Загруженный файл можно обрезать, хешировать и сравнить с хешем оригинального файла программы.

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

Продвинуто: передача прав доступа

Право изменять данную программу принадлежит её владельцу. Эти права могут быть переданы другому keypair без изменения keypair программы, чтобы идентификатор программы оставался прежним. Более того, один владелец может управлять несколькими аккаунтами программ.

Если права доступа явно не указаны во время начального развертывания, то в качестве владельца используется keypair по умолчанию. Именно поэтому при повторном развертывании программы на предыдущих шагах не требовалось явного указания владельца.

Явное указание владельца полезно для оффлайн-подписей и программ, управляемых несколькими организациями.

Сначала необходимо сгенерировать keypair для владельца:

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

Loader-v3

Права доступа можно указать во время развертывания:

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

Или после развертывания, используя keypair по умолчанию в качестве текущего владельца:

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

Или после развертывания, указав текущего владельца:

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

Владелец может быть указан во время развертывания:

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

Или после развертывания с использованием keypair по умолчанию в качестве текущего владельца:

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

Или после развертывания, указав текущего владельца:

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

Продвинуто: двухэтапное повторное развертывание с использованием буфера

Вместо загрузки непосредственно в аккаунт программы, исполняемый файл может быть сначала загружен в промежуточный буферный аккаунт, а затем перенесён в аккаунт программы на втором этапе (фактическое повторное развертывание). Это полезно для оффлайн-подписания и программ с управлением несколькими участниками, таких как DAO, голосующие за выбор или отклонение загруженного исполняемого файла перед фактическим повторным развертыванием.

Имейте в виду, что использование буферных аккаунтов примерно удваивает средства, необходимые в процессе загрузки, так как два аккаунта одновременно хранят один исполняемый файл.

Сначала необходимо создать keypair для буферного аккаунта:

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

Буферный аккаунт может быть повторно использован для различных загрузок и не привязан к какому-либо конкретному аккаунту программы.

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

Продвинуто: оффлайн-подписание

Некоторые модели безопасности требуют разделения процесса подписания и передачи транзакции, чтобы ключи для подписания могли быть полностью отключены от любой сети, что также известно как оффлайн-подписание.

Обратите внимание, что только повторные развертывания могут выполняться в оффлайн-режиме. Первоначальное развертывание программы должно выполняться с онлайн-машины, и только последующие повторные развертывания программы могут использовать оффлайн-подписание.

Типичная настройка будет состоять из двух разных подписантов:

• онлайн-подписант (плательщик комиссии и владелец буферного аккаунта)
• оффлайн-подписант (владелец аккаунта программы)

Общий процесс включает два этапа повторного развертывания с некоторыми дополнительными шагами:

1. (онлайн) создать новую программу
2. (онлайн) передать полномочия оффлайн-подписанту
3. (онлайн) создать буфер и загрузить в него исполняемый файл
4. (опционально) проверить содержимое буфера в блокчейне
5. (оффлайн) подписать транзакцию для повторного развертывания программы с использованием буфера --blockhash <VALUE> --sign-only
6. (онлайн) использовать эту подпись для трансляции транзакции повторного развертывания --blockhash <VALUE> --signer <OFFLINE_SIGNER_PUBKEY>:<OFFLINE_SIGNER_SIGNATURE>

Найдите недавний blockhash и вставьте его, чтобы сгенерировать подпись оффлайн-транзакции. blockhash истекает примерно через 60 секунд. Если вы не успели вовремя — просто получите новый хэш и повторите попытку, пока не добьетесь успеха, или рассмотрите возможность использования долговременных неонсов транзакций.