Solana Kit для початківця

Solana Kit (@solana/kit) — це високорівневий TypeScript-пакет із сімейства Solana Web3.js v2, який спрощує взаємодію з блокчейном Solana у frontend- та backend-застосунках. На відміну від попереднього покоління бібліотек, Kit пропонує функціональний API, сувору типізацію та сумісність із сучасними бандлерами через tree-shaking.

Цей довідник проведе вас від встановлення до першого робочого запиту на Devnet. Усі приклади розраховані на середовище Node.js 18+ та кластер Devnet.

Що таке Solana Kit

Сучасний набір інструментів для Solana-frontend

@solana/kit — це зручна оболонка (convenience layer) над низькорівневими пакетами @solana/web3.js v2. Він не замінює ядро, а агрегує найчастіші операції в єдину точку входу:

• Створення RPC-клієнта для зв'язку з кластером
• Генерація та обробка адрес (Account Public Keys)
• Формування транзакцій та підписів
• Отримання балансів, станів акаунтів, інформації про блоки

Архітектурно Kit належить до монорепозиторію @solana/web3.js v2 і залежить від пакетів @solana/rpc, @solana/addresses, @solana/transactions та інших. Ви не імпортуєте їх окремо — Kit робить це за вас.

Відмінності від @solana/web3.js

Головна різниця — покоління API:

• @solana/web3.js v1 (стабільний, широко використовуваний) — об'єктно-орієнтований підхід з класами Connection, Transaction, Keypair
• @solana/kit (частина v2-екосистеми) — функціональний підхід: замість класів використовуються фабричні функції та незмінні об'єкти

Наприклад, у v1 ви створюєте new Connection(endpoint), а в Kit — викликаєте createSolanaRpc(endpoint). Результат концептуально схожий, але типи та внутрішня структура відрізняються. Kit не є прямою заміною web3.js v1. Це окрема гілка розвитку з іншим API-контрактом.

Встановлення та налаштування

npm install @solana/kit

Передумови:

• Node.js 18 або новіший
• npm 9+ або сумісний пакетний менеджер
• Доступ до інтернету для зв'язку з Devnet RPC

Встановлення:

npm install @solana/kit

Перевірте встановлену версію:

npm ls @solana/kit

Очікуваний результат: виведення версії пакета без помилок залежностей. Актуальну версію на момент вашого читання перевірте на сторінці пакета в npm-реєстрі, оскільки екосистема v2 активно оновлюється.

Базова конфігурація

Створіть мінімальний скрипт для перевірки зв'язку з Devnet. Збережіть як test-rpc.ts і запустіть через npx tsx test-rpc.ts:

import { createSolanaRpc, address } from '@solana/kit';

const DEVNET_ENDPOINT = 'https://api.devnet.solana.com';
const rpc = createSolanaRpc(DEVNET_ENDPOINT);

const testAddress = address('11111111111111111111111111111111');
const balance = await rpc.getBalance(testAddress).send();

console.log('Баланс системної програми:', balance.value, 'lamports');

Очікуваний результат: Баланс системної програми: 0 lamports. Якщо ви отримали цей вивід — RPC-клієнт працює коректно.

Важлива деталь: функція address() перетворює рядок на типізований об'єкт Address. У v2 адреси — це не просто рядки, а спеціальні типи, що запобігає плутанині між рядковими літералами та справжніми публічними ключами.

Основні можливості

Створення транзакцій

У Solana Kit транзакція формується крок за кроком: створюється повідомлення (message), додаються інструкції, потім повідомлення підписується та серіалізується.

Концептуальний приклад — формування транзакції переказу SOL на Devnet. Для роботи цього прикладу також потрібен пакет системної програми:

npm install @solana-program/system

import {
  createSolanaRpc,
  address,
  generateKeyPairSigner,
  appendTransactionInstruction,
  compressTransactionMessage,
  createTransactionMessage,
  getBase58EncodedAddress,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  signTransactionMessageWithSigners,
} from '@solana/kit';
import { getTransferSolInstruction } from '@solana-program/system';

const rpc = createSolanaRpc('https://api.devnet.solana.com');

// Генеруємо пару ключів для відправника
const sender = await generateKeyPairSigner();
const recipientAddress = address('11111111111111111111111111111111');

// Отримуємо останній blockhash
const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();

// Формуємо транзакцію
const message = createTransactionMessage({ version: 'legacy' });
setTransactionMessageFeePayer(sender.address, message);
setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, message);

const transferInstruction = getTransferSolInstruction({
  amount: 1_000_000n, // 0.001 SOL у lamports
  destination: recipientAddress,
  source: sender.address,
});

appendTransactionInstruction(transferInstruction, message);

// Підписуємо
const signedTransaction = await signTransactionMessageWithSigners(message);
const serialized = compressTransactionMessage(signedTransaction);

console.log('Відправник:', getBase58EncodedAddress(sender.address));
console.log('Транзакцію сформовано. Для відправки потрібен SOL на балансі відправника.');

Цей приклад демонструє формування транзакції, але не відправляє її. Щоб реально надіслати транзакцію на Devnet, відправник повинен мати баланс у lamports. Отримати тестові токени можна через кран (faucet) — це окрема тема, яка не розглядається в цьому матеріалі.

Зверніть увагу: getTransferSolInstruction імпортується з @solana-program/system, а не з @solana/kit. Інструкції для програм у v2-екосистемі рознесені по окремих пакетах.

Робота з акаунтами та підписами

Solana Kit розрізняє кілька концепцій, які в web3.js v1 часто змішувалися:

• Address — публічний ключ акаунта, створюється через address() або читається через getBase58EncodedAddress()
• KeyPairSigner — пара ключів, що може підписувати транзакції, створюється через generateKeyPairSigner()
• Signer — загальна абстракція для будь-чого, що може підписати (ключова пара, зовнішній гаманець тощо)

Приклад генерації ключової пари та отримання адреси:

import { generateKeyPairSigner, getBase58EncodedAddress } from '@solana/kit';

const keyPair = await generateKeyPairSigner();
const publicKey = getBase58EncodedAddress(keyPair.address);

console.log('Публічний ключ:', publicKey);

Очікуваний результат: рядок із 43–44 символів у форматі Base58. Кожен виклик generateKeyPairSigner() створює нову унікальну пару — це корисно для тестів, але не для production, де приватні ключі треба зберігати безпечно.

Порівняння з web3.js

Коли обрати Solana Kit замість web3.js

Вибір залежить від контексту проєкту:

Рекомендація для початківця: якщо ви вчитеся за існуючими туторіалами або працюєте з Anchor — почніть з web3.js v1. Якщо ви стартуєте новий проєкт з нуля і готові орієнтуватися на актуальну документацію v2 — Solana Kit буде природнішим вибором.

Міграція з web3.js на Solana Kit

Міграція — це не заміна викликів один на один, а переписування з іншою ментальною моделлю. Основні відповідності:

• new Connection(url) → createSolanaRpc(url)
• new PublicKey(str) → address(str)
• new Keypair() → generateKeyPairSigner()
• connection.getBalance(pubkey) → rpc.getBalance(addr).send()
• transaction.add(instruction) → appendTransactionInstruction(instruction, message)

Зверніть увагу на .send() у кінці RPC-викликів. У v2 більшість запитів повертають об'єкт-запит, який треба явно виконати через .send(). Це дозволяє повторно використовувати налаштований запит або комбінувати їх.

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

Невідповідність версій пакетів

Solana Kit залежить від низки пакетів з монорепозиторію v2. Якщо версії не узгоджені — виникають помилки типізації або виконання.

Типова помилка — встановлення пакетів із жорстко вказаними різними версіями:

npm install @solana/[email protected]
npm install @solana-program/[email protected]

Проблема: різні мінорні версії можуть бути несумісні між собою.

Правильний підхід — встановлювати без вказання версій, щоб npm вирішив сумісність автоматично:

npm install @solana/kit @solana-program/system

Або вказувати однакову мінорну версію для всіх пакетів v2-екосистеми. Точну таблицю сумісності версій перевірте в офіційному репозиторії @solana/web3.js на GitHub.

Ознака змішування пакетів v1 та v2 в одному файлі — помилки на кшталт Type 'Address' is not assignable to type 'PublicKey'. Якщо бачите це, перевірте імпорти: ймовірно, ви використовуєте типи з обох поколінь одночасно.

Невірний імпорт модулів

Поширена помилка — намагатися імпортувати щось з @solana/kit, що насправді належить до іншого пакета v2-екосистеми.

Інструкції для програм (System, Token, Stake) не входять до @solana/kit. Вони розташовані в окремих пакетах:

• System Program: @solana-program/system
• Token Program: @solana-program/token
• Stake Program: @solana-program/stake

Якщо ви намагаєтеся імпортувати getTransferSolInstruction з @solana/kit — отримаєте помилку Module not found. Правильний шлях: import { getTransferSolInstruction } from '@solana-program/system'.

Ще одна часта помилка — використання звичайних рядків там, де очікується тип Address:

// Неправильно — передається рядок
await rpc.getBalance('11111111111111111111111111111111').send();

// Правильно — рядок обгорнутий у address()
await rpc.getBalance(address('11111111111111111111111111111111')).send();

TypeScript може не завжди спіймати цю помилку на етапі компіляції залежно від конфігурації, але виконання завершиться помилкою. Завжди використовуйте address() для перетворення рядкових літералів у типізовані адреси.

Перелік усіх експортів @solana/kit та їх точні сигнатури перевіряйте в офіційній документації — API v2 продовжує розвиватися, і імена функцій можуть змінюватися між мінорними релізами.

Джерела

• Anchor stable v1 documentation
• Anchor 1.0 release notes
• Anchor: TypeScript clients and compatibility
• Anchor v2 alpha documentation
• Solana: Staying Safe on Solana
• Solana: What Is a Wallet?