Як підключитися до Devnet з TypeScript

Ця інструкція проведе вас через підключення до Solana Devnet за допомогою TypeScript — від вибору RPC-вузла до отримання тестових SOL і перевірки з'єднання. Усі приклади перевірені в середовищі Node.js 20 LTS із пакетом @solana/web3.js версії 1.95.x на кластері Devnet.

Вибір RPC endpoint

RPC endpoint (Remote Procedure Call endpoint) — це адреса ноди, через яку ваш клієнт надсилає запити до блокчейну. Без коректного endpoint жоден запит не дійде до кластера.

Офіційний Devnet endpoint

Solana надає публічний Devnet endpoint безкоштовно:

https://api.devnet.solana.com

Цей endpoint підходить для навчання та базових експериментів. Його обмеження: відсутній SLA, часткове обмеження швидкості (rate limit) та періодичні технічні перерви під час оновлень кластера.

Альтернативні провайдери

Коли публічний endpoint не вистачає (повільні відповіді, таймаути), можна використовувати сторонніх провайдерів — Helius, QuickNode, Triton та інші. Вони пропонують вищу швидкість, додаткові методи індексації та стабільніше з'єднання, але вимагають реєстрації та мають власні безкоштовні ліміти.

Для цієї інструкції ми використовуємо офіційний endpoint — це достатньо для перевірки підключення та перших кроків.

Створення Connection

Об'єкт Connection із @solana/web3.js — це центральна точка взаємодії з кластером. Через нього ви надсилатимете транзакції, читатимете стан акаунтів і підписуватиметеся на події.

new Connection(endpoint, commitment)

Базове створення підключення:

import { Connection } from '@solana/web3.js';
const endpoint = 'https://api.devnet.solana.com';
const connection = new Connection(endpoint, 'confirmed');

Перший аргумент — рядок із URL endpoint. Другий — рівень commitment, який визначає, наскільки «глибоко» нода має переконатися в обробці запиту перед поверненням відповіді.

Рівні commitment: processed, confirmed, finalized

Для розробки та тестування на Devnet рекомендується confirmed — це типовий баланс між швидкістю та надійністю.

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

Створити Connection недостатньо — треба переконатися, що кластер відповідає саме вашому клієнту. Два методи дозволяють це зробити без витрат SOL.

getHealth — перевірка стану кластера

const health = await connection.getHealth();
console.log(health); // "ok"

Метод повертає рядок "ok", якщо кластер працює нормально. Якщо Devnet знаходиться на технічному обслуговуванні або endpoint недоступний, метод викидає помилку. Це найшвидший спосіб перевірити, чи взагалі є зв'язок із нодою.

getVersion — версія ноди

const version = await connection.getVersion();
console.log(version); // { "solana-core": "1.18.26", "feature-set": 1234567890 }

Цей метод повертає об'єкт із версією solana-core та ідентифікатором набору функцій (feature-set). Він корисний для діагностики: якщо версія суттєво відрізняється від очікуваної, можливо, endpoint вказує на інший кластер або застарілу ноду.

Повний приклад перевірки:

import { Connection } from '@solana/web3.js';

async function checkConnection() {
  const connection = new Connection('https://api.devnet.solana.com', 'confirmed');
  try {
    const health = await connection.getHealth();
    console.log('Стан кластера:', health);
    const version = await connection.getVersion();
    console.log('Версія ноди:', version['solana-core']);
  } catch (error) {
    console.error('Помилка підключення:', error);
  }
}

checkConnection();

Очікуваний результат при успішному підключенні:

Стан кластера: ok
Версія ноди: 1.18.26

Зверніть увагу: конкретна версія змінюється з релізами Solana. Перевіряйте актуальну версію Devnet у офіційному репозиторії Solana перед тим, як спиратися на конкретне значення.

Отримання тестових SOL

Devnet-SOL не має реальної вартості і призначений виключно для тестування. Щоб виконувати транзакції, вам потрібен баланс на акаунті.

requestAirdrop через SDK

import { Connection, Keypair, LAMPORTS_PER_SOL } from '@solana/web3.js';

async function requestAirdrop() {
  const connection = new Connection('https://api.devnet.solana.com', 'confirmed');
  const keypair = Keypair.generate();
  console.log('Адреса гаманця:', keypair.publicKey.toBase58());

  const signature = await connection.requestAirdrop(
    keypair.publicKey,
    2 * LAMPORTS_PER_SOL // 2 SOL
  );

  await connection.confirmTransaction(signature, 'confirmed');
  const balance = await connection.getBalance(keypair.publicKey);
  console.log('Баланс:', balance / LAMPORTS_PER_SOL, 'SOL');
}

requestAirdrop();

Що відбувається крок за кроком:

1. Keypair.generate() створює нову випадкову пару ключів. У реальному застосунку ви б завантажили існуючий ключ із файлу або змінної середовища.
2. requestAirdrop надсилає запит на faucet (кран) Devnet. Аргументи — адреса отримувача та сума в lamports (1 SOL = 1 000 000 000 lamports, константа LAMPORTS_PER_SOL).
3. confirmTransaction чекає, поки транзакція досягне вказаного рівня commitment.
4. getBalance підтверджує, що кошти надійшли.

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

Ліміти airdrop та як їх обійти

Офіційний faucet Devnet має обмеження: зазвичай не більше 2 SOL на один запит і не більше певної суми на одну адресу за певний період. Точні ліміти змінюються — перевіряйте актуальні значення в документації Solana перед розробкою.

Якщо ви отримали помилку ліміту, є кілька варіантів:

• Зачекайте. Ліміти скидаються з часом. Для базових тестів 2 SOL зазвичай достатньо.
• Згенеруйте нову адресу. Нова пара ключів — новий ліміт. Підходить для ізольованих тестів, але не для послідовного сценарію, де потрібен один і той самий акаунт.
• Використовуйте CLI-фільтр. Команда solana airdrop у CLI має дещо інші ліміти, ніж HTTP-faucet через SDK.
• Сторонні faucet-сервіси. Деякі провайдери (наприклад, Helius) пропонують власні крани для своїх користувачів із окремими лімітами.

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

Devnet недоступний (maintenance)

Devnet — тестовий кластер, і його перезапускають регулярно. Під час оновлень кластера (які відбуваються приблизно раз на тиждень, але графік не фіксований) endpoint може не відповідати або повертати помилки.

Симптоми:

• getHealth() викидає помилку із повідомленням про недоступність
• Таймаут при будь-якому запиті до кластера
• Транзакції не підтверджуються довго (більше 60 секунд)

Що робити: перевірте статус кластера на сторінці Solana Status. Якщо Devnet на обслуговуванні — зачекайте, зазвичай перезапуск займає від кількох хвилин до години. Альтернативно, спробуйте інший endpoint (від стороннього провайдера), який може підключатися до іншої ноди того ж кластера.

Airdrop rate limit exceeded

Симптом: при виклику requestAirdrop повертається помилка з текстом "Too many requests" або "airdrop rate limit exceeded".

Причини:

• Ви надіслали занадто багато запитів з однієї IP-адреси за короткий час
• Адреса отримувача вже досягла кумулятивного ліміту airdrop
• Faucet тимчасово перевантажений (часто буває після перезапуску Devnet, коли багато розробників одночасно запитують кошти)

Що робити:

• Додайте затримку між запитами (наприклад, 2–3 секунди через await new Promise(r => setTimeout(r, 3000)))
• Перевірте поточний баланс перед запитом — можливо, кошти вже на рахунку
• Використовуйте збережену адресу замість генерації нової для кожного запуску
• Якщо ви тестуєте повторювані сценарії, розгляньте можливість створення власного локального кластера через solana-test-validator — там немає лімітів на airdrop

Після успішного підключення до Devnet та отримання тестових SOL ви готові переходити до читання стану акаунтів та створення транзакцій. Наступний логічний крок у вашому навчальному шляху — робота з даними на блокчейні через клієнтські методи SDK.

Джерела

• Solana Documentation