Ця інструкція проведе вас через повний цикл розгортання навчального Solana-проєкту на Devnet: від налаштування змінних середовища до перевірки працездатності on-chain програми та frontend-застосунку. Припускається, що ваш проєкт уже локально протестований, а ви маєте під рукою зібраний Anchor-проєкт із frontend-частиною.
Структура повного проєкту
On-chain програма + frontend + скрипти
Навчальний проєкт, який ви деплоїте на Devnet, зазвичай складається з трьох логічних частин:
- On-chain програма — смарт-контракт, написаний на Rust і зібраний через Anchor. Це байткод, який розгортається на блокчейні.
- Frontend — клієнтський застосунок (React, Next.js або Svelte), який взаємодіє з програмою через Solana RPC.
- Скрипти — допоміжні CLI-команди або TypeScript-файли для ініціалізації стану програми (створення PDA-акаунтів, поповнення тощо).
Каталоги та ключові файли
Мінімальний набір файлів, які впливають на розгортання:
- Anchor.toml — конфігурація Anchor-проєкту: вказівка кластера, програм та їхніх шляхів.
- target/idl/ — каталог з IDL-файлами (Interface Definition Language), які генеруються після зборки програми. Frontend використовує їх для типізації викликів.
- target/deploy/ — каталог зі скомпільованим байткодом (
.so-файл) та ключовою парою програми (-keypair.json). - .env — файл зі змінними середовища для frontend (RPC endpoint, program ID).
Детальний розбір архітектурних рішень щодо структури проєкту викладено окремо — у матеріалі про те, як структурувати повний Solana-проєкт. Тут зосередимося виключно на механіці розгортання.
Налаштування змінних середовища
Перед деплоєм переконайтеся, що ваш Anchor.toml вказує на Devnet, а frontend отримує правильні значення через змінні середовища.
У Anchor.toml перевірте секцію [features]:
[features]
seeds = false
[features.localnet]
[provider]
cluster = "Devnet"
wallet = "~/.config/solana/id.json"
Якщо значення cluster відрізняється від "Devnet" — ви деплоїте не туди. Зверніть увагу: рядок чутливий до регістру, "devnet" не спрацює.
Для frontend створіть файл .env у корені frontend-каталогу:
VITE_SOLANA_RPC_URL=https://api.devnet.solana.com
VITE_PROGRAM_ID=ваш_фактичний_program_id
Префікс VITE_ стосується Vite-проєктів. Якщо ви використовуєте Next.js, замініть його на NEXT_PUBLIC_. Конкретний префікс залежить від вашого бандлера — перевірте документацію відповідного інструменту.
Різниця між Devnet та Mainnet конфігурацією полягає виключно в двох параметрах: RPC endpoint та program ID. Байткод програми на Devnet і Mainnet буде різним (різні ключові пари), тому program ID завжди змінюється при переході між кластерами. Ніколи не використовуйте один program ID для різних кластерів — це гарантована помилка підключення.
розгортання on-chain програми
anchor deploy — розгортання програми
Переконайтеся, що Solana CLI налаштований на Devnet:
solana config get
Очікуваний результат: RPC URL: https://api.devnet.solana.com. Якщо це не так, виконайте:
solana config set --url devnet
Перевірте, що на вашому гаманці є достатньо SOL для розгортання (на Devnet це безкоштовні тестові токени). Мінімальна сума змінюється — перевірте актуальне значення командою:
solana program deploy --help
Якщо баланс недостатній, отримайте тестові токени:
solana airdrop 2
Тепер виконайте розгортання:
anchor deploy
Очікуваний результат — у терміналі з'явиться program ID щойно розгорнутої програми. Скопіюйте його та оновіть у файлі .env вашого frontend, якщо ви цього ще не зробили.
Оновлення IDL на сервері (якщо потрібно)
Після anchor deploy IDL-файл оновлюється локально у target/idl/. Якщо ваш frontend зчитує IDL безпосередньо з цієї директорії під час збірки — нічого додатково робити не треба.
Якщо ж архітектура передбачає завантаження IDL з on-chain сховища (через anchor idl fetch або інший механізм), виконайте:
anchor idl init --filepath target/idl/ваша_програма.json ваша_програма
Або оновіть, якщо IDL вже був завантажений раніше:
anchor idl upgrade --filepath target/idl/ваша_програма.json ваша_програма
Для навчального проєкту на Devnet найпростіший підхід — вбудовувати IDL у frontend на етапі збірки. Це усуває додатковий мережевий запит і спрощує діагностику.
розгортання frontend
Збірка frontend (npm run build)
Перед збіркою переконайтеся, що змінні середовища з правильним program ID та Devnet RPC встановлені. Перейдіть до каталогу frontend:
cd frontend
npm install
npm run build
Очікуваний результат — у каталозі dist/ (або out/ для Next.js) з'являться статичні файли. Якщо збірка завершилася помилкою, перевірте, чи всі змінні середовища доступні на етапі білду (залежить від конфігурації бандлера).
Розміщення на Vercel, Netlify або іншому хостингу
Для навчального проєкту підійде будь-який статичний хостинг. Найпоширеніші варіанти:
Vercel: підключіть репозиторій GitHub до Vercel, вкажіть кореневий каталог frontend та команду білду. Змінні середовища додайте в налаштуваннях проєкту Vercel (Settings → Environment Variables).
Netlify: аналогічно — підключіть репозиторій, вкажіть каталог публікації (зазвичай dist) та команду білду. Змінні середовища — у розділі Site configuration → Environment variables.
Локальна альтернатива: для швидкої перевірки без зовнішнього хостингу можна використати npx serve dist, але це не дасть постійної публічної URL-адреси, тому підходить лише для локальної верифікації.
Після розгортання хостинг надасть вам публічну URL-адресу. Запишіть її — вона знадобиться для перевірки.
Перевірка розгортання
Перевірка програми через Explorer
Відкрийте Solana Explorer для Devnet:
https://explorer.solana.com/?cluster=devnet
У пошуковий рядок вставте ваш program ID. Очікуваний результат:
- Сторінка програми відкривається без помилок.
- Розділ "Program Info" показує вашу програму з коректним розміром байткоду.
- У розділі "Transactions" видно транзакцію розгортання (або кілька, якщо ви оновлювали програму).
Якщо Explorer не знаходить program ID — програма не була розгорнута або ви випадково деплоїли на інший кластер.
Перевірка frontend: підключення, транзакції
Відкрийте публічну URL-адресу вашого frontend у браузері. Виконайте такі кроки:
- Підключення гаманця. Натисніть кнопку підключення (зазвичай "Connect Wallet"). Переконайтеся, що Phantom (або інший гаманець) перемикається на Devnet-мережу. Якщо гаманець залишається на Mainnet — транзакції не пройдуть.
- Виклик програми. Виконайте базову дію вашого навчального проєкту (створення акаунта, запис даних, ініціалізація). Очікуваний результат — транзакція формується, підписується та відправляється без помилок у консолі браузера.
- Перевірка в Explorer. Скопіюйте signature транзакції з консолі браузера або з інтерфейсу гаманця та відкрийте її в Devnet Explorer. Статус має бути "Success", а в логах транзакції має бути видно виклик вашої програми.
Якщо на етапі виклику програми виникає помилка — відкрийте DevTools браузера (Console та Network), знайдіть RPC-запит та проаналізуйте відповідь. Найчастіше проблема в невідповідності program ID або в недостатньому балансі для оренди акаунтів.
Типові помилки
Frontend використовує старий program ID. Це найпоширеніша проблема. Ви перезібрали та задеплоїли програму, отримали новий program ID, але забули оновити його у .env frontend або не перезібрали frontend після оновлення. Результат — frontend звертається до неіснуючої (або старої) програми, і транзакції падають із помилкою InvalidAccountData або AccountNotFound.
Рішення: після кожного anchor deploy оновлюйте program ID у .env та виконуйте npm run build заново. У навчальному проєкті program ID змінюється при кожному повному розгортання, якщо ви не фіксуєте ключову пару програми.
IDL не оновлено після розгортання програми. Ви додали нову інструкцію в програму, задеплоїли, але frontend все ще використовує старий IDL. Результат — типізація не збігається з реальним інтерфейсом програми, і виклики формуються некоректно.
Рішення: переконайтеся, що файл IDL у target/idl/ оновився після збірки (перевірте timestamp файлу). Якщо frontend імпортує IDL локально — достатньо перезібрати frontend. Якщо IDL завантажується з on-chain сховища — виконайте anchor idl upgrade.
Гаманець на Mainnet замість Devnet. Користувач підключає гаманець, але не перемикає його на Devnet. Транзакція формується з правильним program ID, але відправляється на Mainnet RPC, де цієї програми не існує.
Рішення: у навчальному проєкті додайте явну перевірку мережі гаманця на стороні frontend та показуйте попередження, якщо гаманець не на Devnet. Це не production-рішення (там мережа визначається конфігурацією), але для навчального проєкту це заощадить значну кількість часу на діагностиці.
Недостатній баланс для оренди акаунтів. Навіть на Devnet створення PDA-акаунтів вимагає мінімального депозиту (rent-exempt minimum). Якщо на гаманці недостатньо тестового SOL — транзакція впаде з помилкою insufficient lamports.
Рішення: виконайте solana airdrop ще раз або перевірте баланс командою solana balance.
Після успішного розгортання на Devnet ваш навчальний проєкт повністю готовий до взаємодії. Наступний логічний крок — перевірити, як ваш поточний проєкт можна перетворити на структуру, придатну для масштабування та подальшої розробки.