Локальний validator — це повноцінна нода Solana, яка працює на вашій машині та дає повний контроль над середовищем: миттєві транзакції, необмежений тестовий SOL, завантаження власних програм і станів акаунтів. Нижче — покрокова інструкція від підготовки до робочого середовища.

Що таке solana-test-validator

Локальна нода для розробки та тестування

solana-test-validator — це утиліта з набору Solana CLI, яка запускає локальний кластер з однією нодою-валідатором. Вона імітує поведінку повноцінної мережі: обробляє транзакції, виконує програми, підтримує леджер та надає RPC-endpoint для взаємодії через SDK або CLI.

Ключова особливість — validator працює повністю ізольовано від інших мереж. Усі дані зберігаються в тимчасовій директорії і знищуються після зупинки, якщо ви не вкажете інше через прапорець --ledger.

Відмінності від Devnet

  • Швидкість. Транзакції підтверджуються миттєво, оскільки немає мережевих затримок і консенсусу між нодами.
  • Ресурси. Локальний airdrop дає значну кількість тестових SOL (за замовчуванням 1 000 000 000 SOL за запитом), тоді як на Devnet є ліміти та черги.
  • Контроль стану. Ви завантажуєте лише ті програми та акаунти, які потрібні для поточного тесту. Немає стороннього шуму від інших користувачів.
  • Детермінованість. Однакові дії завжди дають однаковий результат, що критично для відтворення багів.

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

Запуск validator

solana-test-validator — базовий запуск

Передумови: встановлений Solana CLI (перевірте командою solana --version), вільна оперативна пам'ять (мінімум 8 ГБ, рекомендовано 16 ГБ).

Середовище: локальна машина розробника (macOS, Linux, Windows через WSL).

Очікуваний результат: validator стартує, виводить логи в термінал і слухає RPC на http://127.0.0.1:8899.

Базовий запуск:

solana-test-validator

Після виконання ви побачите логи зі стартом ноди. Коли з'явиться рядок із зазначенням RPC-порту, validator готовий до роботи. Залиште це вікно терміналу відкритим — зупинка процесу (Ctrl+C) зупиняє ноду.

Налаштування: порт, ліміти, логи

За замовчуванням validator використовує порт 8899 для RPC та 8900 для WebSocket. Якщо цей порт зайнятий іншим процесом, ви отримаєте помилку при старті. Змініть порт прапорцем --rpc-port:

solana-test-validator --rpc-port 8999

У такому разі підключайтеся до http://127.0.0.1:8999.

Для обмеження розміру леджера (корисно, щоб не забивати диск під час тривалих сесій):

solana-test-validator --limit-ledger-size 50000000

Значення вказується в байтах. При досягненні ліміту validator почне видаляти старі слоти.

Для керування детальністю логів:

solana-test-validator --log -solana_rpc=debug

Це виводить детальні RPC-логи, що корисно при діагностиці проблем із транзакціями. Для зменшення шуму використовуйте рівень info або warn.

Збереження леджера між перезапусками (замість тимчасової директорії):

solana-test-validator --ledger ./test-ledger

Це дозволяє перезапускати validator зі збереженим станом, що зручно для багаторазових тестів без повторного завантаження програм.

Завантаження програм та акаунтів

bpf-program — завантаження скомпільованої програми

Щоб ваші смарт-контракти були доступні на локальному кластері, завантажте їх при старті validator. Для цього потрібен скомпільований файл .so (BPF-байткод).

Приклад:

solana-test-validator --bpf-program TARGET_ADDRESS ./target/deploy/program.so

Замість TARGET_ADDRESS вкажіть адресу, за якою програма має бути розгорнута. У розробці з Anchor ця адреса генерується при anchor build і міститься у файлі Anchor.toml або target/deploy/program-keypair.json.

Можна завантажити кілька програм одночасно, додавши кілька прапорців --bpf-program.

account — завантаження стану акаунта

Іноді потрібно відтворити конкретний стан акаунта (наприклад, конфігурацію токена або дані PDA). Для цього експортуйте акаунт із джерела у файл і завантажте при старті:

solana-test-validator --account ACCOUNT_ADDRESS ./accounts/account-data.bin

Файл .bin містить серіалізовані дані акаунта. Ви можете отримати його через solana account з додаванням прапорця --output-file з іншого кластера.

clone — клонування акаунта з Devnet

Замість ручного експорту validator може самостійно клонувати акаунт із Devnet при старті:

solana-test-validator --clone ACCOUNT_ADDRESS --url https://api.devnet.solana.com

Умова: ваша машина повинна мати доступ до Devnet. Validator підключається до вказаного кластера, завантажує дані акаунта та розміщує їх у локальному леджері.

Можна клонувати кілька акаунтів, додавши відповідну кількість прапорців --clone. Це зручно, коли ваші програми залежать від існуючих акаунтів (наприклад, від системної програми Token або конкретного mint-акаунта).

Робота з локальним validator

Підключення через http://127.0.0.1:8899

Після запуску validator ваші клієнтські додатки та CLI повинні вказувати на локальний endpoint. Для Solana CLI:

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

Перевірте підключення:

solana cluster-version

Очікуваний результат — версія встановленого CLI, що підтверджує успішне з'єднання з локальною нодою.

У JavaScript/TypeScript SDK (наприклад, @solana/web3.js) створюйте з'єднання з локальним endpoint:

const connection = new Connection("http://127.0.0.1:8899", "confirmed");

Для перевірки з SDK викличте connection.getHealth() — має повернути "ok".

Airdrop необмежених тестових SOL

На локальному validator ви можете отримати тестовий SOL без обмежень Devnet-лімітів:

solana airdrop 100

Перевірте результат:

solana balance

Тестовий SOL на локальному validator не має реальної вартості і існує лише для оплати комісій за транзакції та оренди простору на леджері під час розробки.

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

Validator не запускається (порт зайнятий)

Симптом: при виконанні solana-test-validator з'являється повідомлення про те, що порт 8899 вже використовується.

Причина: інший процес (попередній екземпляр validator, інший сервіс) зайняв цей порт.

Рішення:

  1. Знайдіть процес: lsof -i :8899 (macOS/Linux).
  2. Завершіть його або використайте інший порт: solana-test-validator --rpc-port 8999.
  3. Якщо попередній validator не завершився коректно, перевірте наявність залишкових процесів solana-test-validator у системному моніторі.

Програма не завантажується (невірний шлях)

Симптом: validator стартує, але програма за вказаною адресою відсутня, або при старті з'являється помилка завантаження файлу .so.

Причина: шлях до файлу вказано відносно поточної директорії, а не абсолютним шляхом, або файл не існує (програма не була скомпільована).

Рішення:

  1. Перевірте, що файл існує: ls -la ./target/deploy/program.so.
  2. Використовуйте абсолютний шлях: solana-test-validator --bpf-program ADDRESS /home/user/project/target/deploy/program.so.
  3. Переконайтеся, що програма скомпільована для цільової архітектури (BPF, а не x86). Anchor виконує це автоматично при anchor build.

Перевірка: після старту validator виконайте solana program show TARGET_ADDRESS. Якщо програма завантажена коректно, ви побачите її дані (розмір, authority).

Джерела