Призначення чек-листа

Цей чек-лист допомагає розробникам системно знаходити причини відмов транзакцій, некоректної поведінки смарт-контрактів та витоків обчислювальних ресурсів у програмах на Solana. Він охоплює повний цикл діагностики — від першого отримання помилки до локалізації рядка коду, що її викликає. Ресурс орієнтований на розробників, які пишуть на Rust або використовують фреймворк Anchor, і не замінює загальну логіку розгортання, яка розкрита в окремому чек-листі deployment на mainnet.

Етапи діагностики

Збір логів та трасування транзакцій

  • Отримати сигнатуру транзакції, яка завершилася помилкою, з інтерфейсу гаманця, CLI або dApp.
  • Відкрити транзакцію в Solana Explorer і перевірити загальний статус: чи відхилена вона на рівні runtime, чи впала конкретна інструкція.
  • Зберегти повний лог виклику solana confirm -v --print-trace <signature> — він показує послідовність виклику інструкцій, включно з CPI (Cross-Program Invocation).
  • Увімкнути детальне логування програми: переконатися, що змінна середовища RUST_LOG встановлена на solana_runtime::instruction_processor=trace,solana_program=debug при локальному запуску валідатора.
  • За наявності локального test-validator зберегти повний вивід консолі для подальшого порівняння з production-сценарієм.

Аналіз помилок та кодів повернення

  • Розшифрувати код помилки з логів: Solana повертає числові коди (наприклад, 0x1 — недостатньо балансу для оренди, 0xb9 — порушення власності акаунта).
  • Для програм на Anchor зіставити помилку з enum-значенням у файлі errors.rs — фреймворк перетворює кастомні помилки на відповідні числові коди.
  • Перевірити, чи не пов'язана помилка з перевищенням лімітів: обчислювальний бюджет (compute units), розмір транзакції (1232 байти), кількість підписів або тривалість слота.
  • Якщо помилка виникає всередині CPI-виклику, відокремити помилку зовнішньої програми від помилки поточної програми за допомогою трасування стеку викликів.
  • Зафіксувати точний рядок логу з помилкою і пов'язану з ним інструкцію — це базова точка для наступних етапів.

Перевірка стану акаунтів та даних

  • У Solana Explorer або через solana account <address> перевірити поточний стан кожного акаунта, переданого в транзакцію: баланс, власник (owner), стан виконання (executable), лампорт-ренду.
  • Переконатися, що акаунти, які мають бути записуваними (writable), дійсно передані як writable, а лише для читання — як read-only.
  • Для PDA (Program Derived Address) перевірити коректність насіння (seeds) і переконатися, що знайдений адрес збігається з очікуваним: використовувати solana address з тими самими seeds або локальну функцію Pubkey::find_program_address.
  • Десеріалізувати дані акаунта (наприклад, через anchor account fetch або вручну) і перевірити, чи відповідають поля очікуваним значенням після попередніх транзакцій.
  • Перевірити, чи не змінився стан акаунта між підписанням транзакції та її виконанням — це типова причина помилки invalid account data у конкурентних сценаріях.

Відтворення та ізоляція проблеми

  • Відтворити помилку в локальному середовищі solana-test-validator з тими ж даними акаунтів і тією ж послідовністю інструкцій.
  • Якщо помилка не відтворюється локально, експортувати стан акаунтів з mainnet або devnet (через snapshot або вручну) і завантажити їх у локальний валідатор за допомогою --account та --clone.
  • Спростити транзакцію до мінімального відтворювального прикладу: прибрати інструкції, які не впливають на помилку, зменшити кількість акаунтів.
  • Додати msg! або solana_log перед кожним критичним кроком у програмі та перезібрати з --features test-sbf для перевірки в test-validator.
  • Зафіксувати мінімальний тест у вигляді інтеграційного тесту Anchor (tests/*.ts), щоб проблема була відтворюваною і після виправлення.

Інструменти для налагодження

  • Solana CLI — базовий інструмент для трасування транзакцій (confirm -v --print-trace), перевірки стану акаунтів та запуску локального валідатора.
  • Solana Explorer — візуальний перегляд транзакцій, інструкцій, логів програм і стану акаунтів без CLI.
  • solana-test-validator — локальний валідатор із можливістю завантаження програм, акаунтів та гешів блоків для точного відтворення середовища.
  • Anchor test runner — запуск інтеграційних тестів із автоматичним підняттям test-validator та логуванням.
  • solana-logs (пакет) — парсинг і фільтрація логів транзакцій за програмою, типом інструкції чи рівнем деталізації.
  • Моніторинг RPC-провайдера — перевірка, чи не відхиляє RPC-вузол запити через rate-ліміти або несвіжий стан (stale slot).

Обмеження чек-листа

  • Чек-лист не охоплює налагодження проблем на рівні клієнтської частини (frontend, гаманець, підписання транзакцій) — лише логіку виконання on-chain програм.
  • Він не замінює профілювання продуктивності (compute profiling), хоча деякі пункти стосуються перевірки обчислювального бюджету.
  • Чек-лист не містить інструкцій із налаштування IDE, лінтерів або форматорів коду — фокус виключно на runtime-діагностиці.
  • Для проблем ізMEV (Maximal Extractable Value), пісочниць (sandbox) програм або специфічних атак на логіку програми потрібні окремі чек-листи з безпеки.
  • Ресурс не розкриває питання міграції між версіями Anchor або оновлення залежностей — лише діагностику в межах поточної збірки.

Версія ресурсу

Ресурс «Чек-лист debugging Solana-програми»: статична версія 1.0. Сторінка містить готовий текстовий чек-лист і готова до практичного використання без очікування окремого інтерактивного інструмента. Остання редакційна перевірка: 2 серпня 2026 року.

Джерела