Як встановити та налаштувати Solana CLI

Solana CLI — це основний інструмент командного рядка для взаємодії з блокчейном Solana: розгортання програм, управління гаманцями, відправка транзакцій та моніторинг кластера. Без нього не працює жоден серйозний процес розробки, навіть якщо ви плануєте писати frontend на web3.js. Ця інструкція проведе вас від встановлення до повністю робочого середовища на Devnet.

Встановлення Solana CLI

Офіційний інсталятор для macOS та Linux

Найпростіший спосіб — використати офіційний скрипт встановлення. Він завантажує попередньо зібрані бінарні файли та розміщує їх у вашій системі.

Відкрийте термінал і виконайте:

sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

Увага: екосистема Solana активно трансформується. Перевірте актуальну адресу інсталятора в офіційному репозиторії Solana Labs на GitHub перед виконанням команди.

Очікуваний результат: скрипт завантажує архів, розпаковує його у каталог ~/.local/share/solana/install/active_release/bin і виводить повідомлення про успішне встановлення з підказкою додати шлях до змінної PATH.

Після встановлення оновіть поточну сесію терміналу:

source ~/.bashrc

Або для zsh:

source ~/.zshrc

Якщо скрипт не додав шлях автоматично, виконайте це вручну. Додайте наступний рядок у ваш конфігураційний файл оболонки (.bashrc, .zshrc або інший):

export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"

Встановлення для Windows

Solana CLI не має нативного інсталятора для Windows. Офіційно підтримуваний спосіб — використання WSL (Windows Subsystem for Linux). Встановіть WSL з дистрибутивом Ubuntu, відкрийте термінал WSL і виконайте ті самі кроки, що й для Linux.

Альтернативний варіант — збірка з вихідного коду через Rust і Cargo, але це значно повільніший процес і вимагає встановленого Rust-компілятора.

Перевірка версії: solana --version

Після встановлення обов'язково перевірте, що CLI доступний і працює:

solana --version

Очікуваний результат: рядок із версією, наприклад solana-cli 1.18.x. Точна версія залежить від дати встановлення — актуальну стабільну версію перевірте в офіційному репозиторії на GitHub.

Якщо термінал повертає помилку command not found, проблема у змінній PATH — поверніться до кроку додавання шляху.

Конфігурація CLI

solana config get — поточні налаштування

Solana CLI зберігає всі налаштування у файлі конфігурації. Щоб побачити поточний стан, виконайте:

solana config get

Очікуваний результат — таблиця з трьома ключовими параметрами:

• RPC URL — адреса ноди, до якої CLI надсилає запити
• WebSocket URL — адреса для підключення через WebSocket
• Keypair Path — шлях до файлу з приватним ключем за замовчуванням

Файл конфігурації розташований за адресою ~/.config/solana/cli/config.yml. Ви можете редагувати його вручну, але використання CLI-команд надійніше, оскільки вони валідують значення.

Зміна RPC-endpoint та keypair path

Щоб змінити RPC-ендпоінт, наприклад, перейти на Devnet:

solana config set --url https://api.devnet.solana.com

Щоб вказати інший файл ключів:

solana config set --keypair ~/my-project/wallet.json

Після кожної зміни виконуйте solana config get, щоб переконатися, що значення оновилися коректно. Це простий спосіб перевірки, який виключає помилки через описки в шляху або URL.

Генерація ключової пари

solana-keygen new — створення нового гаманця

Для взаємодії з блокчейном вам потрібна ключова пара — приватний і публічний ключі. У контексті Solana CLI це файл гаманця, який використовується за замовчуванням для підпису транзакцій.

Створіть нову ключову пару:

solana-keygen new

CLI запитає парольну фразу (bip39 passphrase) — це додатковий рівень захисту. Ви можете залишити її порожньою, натиснувши Enter, але для будь-яких непорожніх коштів це не рекомендується.

Очікуваний результат: у терміналі з'явиться публічна адреса гаманця (рядок, що починається з букв і цифр), а файл із приватним ключем буде збережено за шляхом, вказаним у конфігурації (за замовчуванням ~/.config/solana/id.json).

Формат файлу ключів та безпека

Файл id.json містить масив байтів приватного ключа у форматі JSON. Це повний приватний ключ — той, хто має доступ до цього файлу, має повний контроль над відповідним гаманцем.

Основні правила безпеки для цього етапу:

• Ніколи не комітьте файл ключів у системи контролю версій — додайте id.json до .gitignore
• Не передавайте файл ключів через месенджери чи пошту
• Використовуйте окремий гаманець для Devnet-розробки — він не повинен мати жодного зв'язку з вашим основним гаманцем на Mainnet
• Зберігайте seed-фразу, яку виводить solana-keygen new, у надійному місці — вона дозволяє відновити гаманець навіть без файлу ключів

Для локальної розробки на Devnet ці обмеження менш критичні, але формування правильної звички з першого дня захистить вас від помилок у майбутньому.

Перехід між кластерами

solana config set --url — localhost, devnet, mainnet-beta

Solana має три основні кластери для розробки та експлуатації. Перехід між ними — це зміна одного параметра конфігурації.

Приклади перемикання:

На локальну ноду:

solana config set --url http://127.0.0.1:8899

На Devnet:

solana config set --url https://api.devnet.solana.com

На Mainnet-beta:

solana config set --url https://api.mainnet-beta.solana.com

Як перевірити поточний кластер

Щоб переконатися, що ви підключені до правильного кластера, виконайте:

solana config get

Зверніть увагу на поле RPC URL. Додатково можна перевірити з'єднання та отримати інформацію про ноду:

solana cluster-version

Очікуваний результат: рядок із версією програмного забезпечення ноди, до якої ви підключені. Якщо ви отримуєте помилку тайм-ауту, перевірте підключення до інтернету та коректність URL.

Важливий нюанс: гаманці (ключові пари) однаково працюють у всіх кластерах, але баланси — ні. Гаманець із 100 SOL на Devnet матиме нульовий баланс на Mainnet. Транзакції, підписані одним і тим самим ключем, йдуть у той кластер, який зараз вказано у конфігурації.

Типові помилки

CLI не знайдено після встановлення

Симптом: після виконання скрипта встановлення команда solana --version повертає solana: command not found.

Причина: шлях до бінарних файлів Solana не додано до змінної PATH або зміни не застосовано до поточної сесії терміналу.

Рішення крок за кроком:

1. Перевірте, чи існує каталог із бінарними файлами: ls ~/.local/share/solana/install/active_release/bin/
2. Якщо каталог існує, додайте його до PATH у вашому конфігураційному файлі оболонки
3. Застосуйте зміни: source ~/.bashrc або source ~/.zshrc
4. Якщо ви використовуєте іншу оболонку (fish, nushell), синтаксис додавання до PATH буде іншим — зверніться до документації вашої оболонки

Невірна версія для поточного проєкту

Симптом: команди CLI виконуються, але при розгортанні програми або взаємодії з контрактом виникають помилки сумісності.

Причина: екосистема Solana активно розвивається, і різні версії CLI можуть використовувати різні формати транзакцій, версії BPF-компілятора або структури даних.

Рішення:

1. Перевірте, яку версію CLI вимагає ваш проєкт — зазвичай це вказано у файлі Cargo.toml для Rust-програм або у документації фреймворку
2. Перевірте поточну версію: solana --version
3. Якщо версії не збігаються, встановіть потрібну версію, вказавши її тег у скрипті встановлення: sh -c "$(curl -sSfL https://release.solana.com/v1.18.0/install)" — замініть v1.18.0 на потрібну версію, точний тег перевірте у репозиторії проєкту
4. Перевірте, що після встановлення іншої версії solana --version показує очікуване значення

У професійній розробці версію CLI часто фіксують у скриптах налаштування проєкту або використовують інструменти керування версіями, щоб уникнути конфліктів між різними проєктами на одній машині.

Тепер, коли Solana CLI встановлено та налаштовано, а ви маєте робочий гаманець на Devnet, логічний наступний крок — почати взаємодіяти з блокчейном програмно. Наступний матеріал у цьому розділі присвячений Solana web3.js: перші кроки, де ви напишете перший скрипт, що підключається до кластера з коду.

Джерела

• Solana: Staying Safe on Solana
• Solana: What Is a Wallet?