Ця інструкція проведе вас через розгортання скомпільованої Anchor-програми на тестовий кластер Solana Devnet. Ви отримаєте робочу програму з реальним Program ID, зможете викликати її з клієнта та перевірити стан через Explorer. Приклади базуються на стандартному проєкті, згенерованому через anchor init, і перевірені на Devnet.
Середовище: Linux або macOS, встановлені Solana CLI та Anchor CLI. Перед початком виконайте solana --version та anchor --version і переконайтеся, що обидва інструменти встановлені та їхні версії сумісні між собою. Перевірте актуальні версії в офіційних репозиторіях Solana та Anchor, оскільки сумісність змінюється між релізами.
Очікуваний результат: програма розгорнута на Devnet, її байт-код доступний за фіксованим Program ID, IDL завантажено на кластер.
Підготовка до розгортання
Збірка програми (anchor build)
Перш ніж деплоїти, програму потрібно скомпілювати. У корені проєкту виконайте:
anchor build
Ця команда робить дві ключові речі:
- Компілює Rust-код у байт-код Solana (файл
.so) і розміщує його уtarget/deploy/. - Генерує ключову пару програми — файл
target/deploy/<program-name>-keypair.json. Цей файл містить приватний і публічний ключі, які визначатимуть Program ID вашої програми на кластері.
Після успішної збірки в терміналі має з'явитися повідомлення про завершення без помилок компіляції. У каталозі target/deploy/ ви побачите файл з розширенням .so та відповідний файл ключової пари.
Перевірка ключової пари програми
Program ID — це публічний ключ із згенерованої ключової пари. Щоб його побачити:
solana address -k target/deploy/<program-name>-keypair.json
Цей ключ має збігатися з тим, що записаний у файлі programs/<program-name>/src/lib.rs у макросі declare_id!. Якщо ключі різні — програма не запрацює на кластері. Anchor автоматично оновлює declare_id! під час anchor build, але якщо ви вручну змінювали ключову пару або копіювали проєкт, перевірте це явно.
Важливо: ніколи не публікуйте файл ключової пари програми у відкритих репозиторіях. Для локальної розробки на Devnet це прийнятний ризик, але для production-середовища ключі мають зберігатися виключно в захищених сховищах.
Налаштування Anchor.toml для Devnet
cluster = "devnet"
Файл Anchor.toml у корені проєкту визначає, куди буде здійснено розгортання. Знайдіть секцію [provider] і встановіть:
cluster = "devnet"
Якщо там стоїть localnet або mainnet-beta, Anchor спробує звернутися до відповідного кластера, і розгортання або завершиться помилкою підключення, або, у гіршому випадку, програма потрапить не на той кластер. Перевірте це значення перед кожним деплоєм.
Також переконайтеся, що секція [programs.devnet] містить ваш Program ID:
[programs.devnet]
my_program = "ВашProgramIDТут"
wallet — шлях до ключової пари з SOL
У тій самій секції [provider] параметр wallet має вказувати на файл ключової пари гаманця, який сплатить за розгортання:
wallet = "/home/користувач/.config/solana/id.json"
Цей гаманець має містити достатньо SOL для оплати простору на блокчейні під байт-код програми. На Devnet ці кошти безкоштовні і не мають реальної вартості.
Щоб переконатися, що Solana CLI використовує саме цей гаманець і звертається до Devnet, виконайте:
solana config get
У виводі перевірте, що RPC URL вказує на Devnet-ендпоінт, а Keypair Path збігається зі значенням wallet у Anchor.toml. Якщо є розбіжність — виправте через solana config set --url devnet та solana config set --keypair <шлях>.
розгортання через Anchor CLI
anchor deploy — команда та вивід
Коли програма зібрана, а Anchor.toml налаштований, виконайте:
anchor deploy
Під капотом Anchor виконує кілька операцій у такій послідовності:
- Створює на кластері тимчасовий buffer-акаунт і записує туди байт-код програми.
- Створює основний акаунт програми за вашим Program ID.
- Завантажує байт-код з buffer-акаунта в акаунт програми.
- Завантажує IDL-файл у окремий акаунт на кластері (якщо це не вимкнено в конфігурації).
- Закриває buffer-акаунт, повертаючи залишок SOL на ваш гаманець.
Успішний вивід містить Program ID вашої програми та підтвердження розгортання. Якщо в терміналі з'явилися помилки — читайте далі розділ «Типові помилки».
Перевірка розгортання через Explorer
Після розгортання перевірте програму візуально. Відкрийте Solana Explorer для Devnet і вставте ваш Program ID у рядок пошуку. Ви маєте побачити:
- Акаунт програми з типом
Program. - Дані програми (байт-код) — розмір має відповідати розміру вашого
.soфайлу. - IDL-акаунт, якщо він завантажувався.
Це найшвидший спосіб переконатися, що розгортання реально відбувся, а не завершився з тихою помилкою.
Оновлення програми
Як перевизначити buffer та оновити
Після першого розгортання ви, ймовірно, будете вносити зміни в код і повторно розгортати програму. На Devnet процес простий: виконайте anchor build знову, потім anchor deploy. Anchor автоматично створить новий buffer-акаунт, запише туди оновлений байт-код і застосує його до існуючого Program ID.
Якщо вам потрібен більш детальний контроль, можна використати двокроковий процес:
anchor build -- --profile <profile-name>— збірка з конкретним профілем.anchor upgrade target/deploy/<program-name>.so --program-id <Program ID>— явне оновлення програми за вказаним ID.
Другий підхід корисний, коли ви хочете переконатися, що оновлюєте саме ту програму, яку планували.
Обмеження: на Devnet немає обмежень на кількість оновлень. На Mainnet діє механізм upgrade authority — лише власник авторитету на оновлення може змінювати програму, і цей авторитет можна передати або відкликати. Ця тема належить до production-практик і тут не розглядається.
Коли IDL потрібно оновити
IDL (Interface Definition Language) — це опис інтерфейсу вашої програми, який використовують клієнти для генерації типізованих викликів. IDL потрібно оновлювати на кластері щоразу, коли ви змінюєте публічний API програми:
- Додаєте або видаляєте інструкції.
- Змінюєте структуру акаунтів (додаєте або прибираєте поля).
- Змінюєте типи аргументів інструкцій.
anchor buildзавершується успішно, алеanchor deployвидає помилку про невідповідність Program ID.- Тести падають з повідомленням про те, що програма не знайдена за вказаним ID.
- Ви скопіювали проєкт і не перезгенерували ключову пару.
- Ви вручну змінили
declare_id!без оновлення файлу ключової пари.
За замовчуванням anchor deploy автоматично оновлює IDL на кластері. Якщо ви вимкнули цю поведінку в Anchor.toml параметром idl = false, завантажте IDL вручну:
anchor idl upgrade --filepath target/idl/<program-name>.json <Program ID>
Якщо ви змінили лише внутрішню логіку програми без зміни інтерфейсу, IDL оновлювати не обов'язково — існуючий клієнтський код продовжить працювати.
Типові помилки
Insufficient funds для розгортання
розгортання коштує SOL — блокчейн має зберегти байт-код програми в стані. На Devnet ці кошти безкоштовні, але їх потрібно отримати. Якщо ви бачите помилку про недостатність коштів, отримайте SOL з крану (faucet):
solana airdrop 2
Ця команда запитує 2 SOL на гаманець, що вказаний у конфігурації. Переконайтеся, що ви підключені саме до Devnet, інакше airdrop не спрацює. Якщо кран недоступний або обмежений за частотою запитів, перевірте альтернативні джерела тестових SOL у документації Solana.
Щоб перевірити баланс:
solana balance
Program ID невідповідність
Ця помилка виникає, коли публічний ключ у declare_id! у lib.rs не збігається з ключем із файлу ключової пари в target/deploy/. Симптоми:
Причина зазвичай одна з двох:
Рішення: видаліть старий файл ключової пари з target/deploy/ і виконайте anchor build знову. Anchor згенерує нову ключову пару та автоматично оновить declare_id! у lib.rs. Після цього оновіть Program ID у Anchor.toml у секції [programs.devnet].
Якщо ви навмисно використовуєте існуючий Program ID (наприклад, оновлюєте раніше розгорнуту програму), скопіюйте файл ключової пари у target/deploy/ з ім'ям, що відповідає вашій програмі, і переконайтеся, що declare_id! містить той самий ключ.
Після успішного розгортання на Devnet наступний логічний крок — викликати вашу програму з клієнтського коду або через anchor test з підключенням до Devnet, щоб переконатися, що інструкції виконуються коректно в реальному мережевому середовищі.