Чому TON-лайтсервер відповідає «not ready» і як це прибрати

Лайтсервер not ready: ви надіслали простий запит — а у відповідь прилетіло «not ready»

Ви пишете агента, який має перевірити баланс гаманця або викликати get-метод контракту. Код правильний, адреса правильна, конфіг лайтсервера взято з офіційного global-config.json. Але замість відповіді ви регулярно ловите то not ready, то взагалі нічого — з'єднання просто висить і обривається через ADNL-таймаут. Причому відтворюється не завжди: зранку працює, під навантаженням — ні. Знайомо? Це не баг у вашому коді й не «TON ліг». Це передбачувана поведінка публічних лайтсерверів із глобального конфігу. Розберімося, чому виникає TON liteserver not ready, що реально допомагає на боці клієнта, а що ні.

Що означає «not ready» та ADNL-таймаут у TON-лайтсервера

not ready — це пряма відповідь лайтсервера: «я ще не синхронізований, не можу тобі відповісти». У TON два рівні блокчейну: мастерчейн (masterchain) і basechain (воркчейн 0), який ділиться на шардчейни/шарди (shardchains). Мастерчейн — як зміст книги, а шарди — самі розділи з транзакціями та станом акаунтів. Нода часто отримує голову мастерчейна раніше, ніж наздоганяє відповідні shard-блоки. У цей момент мастерчейн випереджає basechain, а стан акаунта живе в останньому shard-блоці — і перевірити його поки що неможливо. Нода чесно відповідає not ready, замість того щоб віддати вам застарілі або неповні дані.

ADNL-таймаут — це сусідній симптом тієї самої хвороби. ADNL — нативний транспортний протокол TON, яким лайтсервер спілкується з клієнтом (жодного HTTP там немає). Коли нода перевантажена, вона просто не відповідає на ADNL-запит у відведене вікно, і клієнт обриває з'єднання через таймаут, навіть не дійшовши до бізнес-логіки.

Тут важливо не плутати шари. not ready та ADNL-таймаут живуть на рівні нативного ADNL-протоколу лайтсервера. Це не те саме, що HTTP 429 Too Many Requests, який віддають HTTP-шлюзи на кшталт toncenter і tonapi.io, коли ви перевищуєте ліміт. Різні шари, різні коди, різні причини. Якщо ви боретеся саме з 429 — це окрема історія: розбір про фікс 429 у toncenter. А мем про «помилку 228» із TON-чатів — це жарт спільноти, а не реальний код; лайтсервер таким не відповідає.

Чому публічні лайтсервери з глобального конфігу відвалюються під навантаженням

Корінь проблеми прозаїчний. Лайтсервери з ton.org/global-config.json — спільні й лімітовані. Це публічний ресурс, до якого одночасно ходять тисячі розробників, ботів, індексаторів та агентів з усього світу. У такого ресурсу три системні обмеження:

• Спільне навантаження. Ви ділите пул з усією екосистемою. На піку навантаження нода або не встигає наздогнати голову мережі (звідси not ready), або просто не відповідає вчасно (ADNL-таймаут).
• Немає глибокої історії. Публічні ноди не зберігають глибокий архів. Якщо вам потрібна стара транзакція за парою lt/hash, її там може вже не бути — про роботу з історією є окремий матеріал про lt і hash.
• Жодних гарантій. Це ресурс «як є». Пріоритету у вас немає, пропускну здатність вам ніхто не обіцяє: сьогодні пощастило, завтра ні.

Тобто not ready — не випадковість, яку можна «перечекати», а закономірна поведінка спільного ресурсу під навантаженням. І жоден ваш код не змусить чужу перевантажену ноду синхронізуватися швидше.

Клієнтські фікси: ретраї, ротація ендпоінтів і таймаути

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

1. Ретраї з експоненційним бекофом

not ready часто транзієнтний: через 200–800 мс той самий лайтсервер уже застосував потрібний shard-блок. Простий повтор із наростаючою затримкою знімає помітну частку помилок.

async function withRetry<T>(fn: () => Promise<T>, tries = 4): Promise<T> {
  let lastErr: unknown;
  for (let i = 0; i < tries; i++) {
    try {
      return await fn();
    } catch (e) {
      lastErr = e;
      // ретраїмо 'not ready' та ADNL-таймаути, але не бізнес-помилки
      await new Promise((r) => setTimeout(r, 200 * 2 ** i));
    }
  }
  throw lastErr;
}

2. Ротація ендпоінтів

Тримайте в пулі кілька лайтсерверів із конфігу й перемикайтеся на наступний, якщо поточний віддав not ready або пішов у таймаут. Одна нода відстає — сусідня, можливо, вже наздогнала.

3. Збільшений таймаут

Дефолтний ADNL-таймаут іноді занадто жорсткий для перевантаженої публічної ноди. Невеликий запас (кілька секунд) знижує хибні обриви. Але якщо нескінченно збільшувати таймаут — ви просто накопичуєте завислі запити; це не лікування, а анестезія.

Окремий корисний прийом — легкий healthcheck перед реальним запитом. Ідеально підходить get_masterchain_info (голова мастерчейна): саме ця операція першою віддає свіжий seqno, коли нода наздогнала голову мережі, і повертає not ready, лише коли нода ще не наздогнала саму голову мастерчейна. Віддала свіжий seqno — нода працює, можна робити get_account_state, get_balance, run_get_method.

Чесний висновок: ретраї + ротація + таймаути зсувають частоту помилок униз, але не прибирають причину. Публічні ноди перевантажені by design — ви просто акуратніше стукаєте у двері, за якими все та сама черга. Інші способи доступу до TON зібрано в огляді альтернатив toncenter на 2026.

Рішення без власної ноди: hosted-ключ TONNode на нашому лайтсервері

Радикально not ready прибирається одним способом — перестати ходити на спільні ноди. Піднімати й обслуговувати власну ноду TON дорого та марудно: синхронізація, диск, апдейти, моніторинг. Проміжний варіант — ходити не в спільний пул, а отримати через ключ гарантовану пропускну здатність і пріоритетний доступ.

TONNode — це hosted MCP-сервер для TON. MCP (Model Context Protocol) — стандарт, за яким ШІ-агенти (Claude, Cursor, ChatGPT/Codex, будь-який MCP-клієнт) викликають інструменти. Замість того щоб ваш код парсив глобальний конфіг і танцював навколо not ready, агент викликає готовий інструмент, а за ним — hosted-ендпоінт https://mcp.tonnode.io/mcp з вашим Bearer-ключем. Це гарантована пропускна здатність замість спільної черги.

Пакет @tonnode/mcp — open source (MIT, є на npm і GitHub tonnode/mcp) — працює за нативним ADNL-протоколом TON, без HTTP-прошарків. Тобто ви не міняєте транспорт на повільний HTTP-шлюз, а залишаєтеся на тому самому чесному ADNL — але з пріоритетним доступом під ваш ключ.

Для діагностики та повсякденного читання знадобляться:

• get_masterchain_info — голова мастерчейна, природний healthcheck.
• get_account_state — статус, прапорці й остання транзакція акаунта.
• get_balance — баланс у GRAM.
• run_get_method — будь-який read-only get-метод контракту.

Якщо ви тільки починаєте з MCP на TON, розберіться за гайдом з MCP для TON.

Як підключити: npx локально або hosted-ендпоінт із ключем

Безкоштовно локально

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

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"]
    }
  }
}

Це чудово для розробки та локальних експериментів. Але пам'ятайте: локальний npx під капотом усе ще ходить на ті самі спільні лайтсервери, тому від not ready під навантаженням він не рятує — він рятує від вовтузіння із залежностями й дає єдиний інтерфейс інструментів.

Hosted із ключем

Щоб відійти від спільних нод, перемкніть транспорт на HTTP-MCP зі своїм Bearer-ключем (самі виклики інструментів ідуть на нашу ноду через ADNL):

{
  "mcpServers": {
    "ton": {
      "type": "http",
      "url": "https://mcp.tonnode.io/mcp",
      "headers": { "Authorization": "Bearer tn_live_…" }
    }
  }
}

Як це виглядає в роботі з агентом

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

Спершу get_masterchain_info для healthcheck. Потім get_account_state для EQC… — покажи статус і останню транзакцію. Далі get_balance за тією ж адресою.

Під капотом це ланцюжок: get_masterchain_info (нода жива й наздогнала голову) → get_account_state (статус, прапорці, остання транзакція) → get_balance (баланс GRAM). Жодних ретраїв навколо чужої черги — запит іде на гарантовану пропускну здатність. До речі, GRAM — це перейменований Toncoin (перейменування відбулося в червні 2026); мережа, як і раніше, називається TON.

Безкоштовний ключ Hobby (60 запитів/хв) видається одразу після входу, без картки. Далі в міру зростання: Pro — $29/міс, 300 запитів/хв; Scale — $199/міс, 1200 запитів/хв. Важлива деталь: на всіх тарифах доступні всі 16 інструментів TONNode — платите ви лише за пропускну здатність, а не за функціональність.

Власний виділений лайтсервер — за запитом, а не self-serve

Іноді hosted-тарифу замало й потрібен виділений (single-tenant) лайтсервер — тільки під ваш трафік, взагалі без сусідів. Такий варіант є, але чесно: це не самообслуговування. Кнопки «увімкнути single-tenant» у дашборді немає — це оформлюється вручну: напишіть нам, обговоримо навантаження й конфігурацію.

І ще одне чесне застереження щодо глибини історії. Архівна нода TONNode зараз синхронізується й поки не обслуговує запити. «Архівна глибина» — це пункт роадмапу, а не готова функція. Якщо вам критично потрібна глибока історія за весь час уже сьогодні, плануйте це окремо. Що вже готове, а що в планах — на роадмапі.

Коротко

• not ready = нода не синхронізована: мастерчейн випереджає shard, стан акаунта в останньому shard-блоці ще не можна перевірити.
• Публічні лайтсервери з глобального конфігу — спільні й лімітовані: not ready, ADNL-таймаути, немає глибокої історії. Не плутати з HTTP 429 у toncenter/tonapi — інший шар.
• Клієнтські фікси (ретраї з бекофом, ротація ендпоінтів, таймаути) знижують частоту помилок, але не прибирають причину.
• get_masterchain_info — ваш healthcheck: червоніє not ready, лише коли нода взагалі не наздогнала голову мастерчейна.
• Реальне лікування — піти зі спільного ресурсу на гарантовану пропускну здатність.

Візьміть безкоштовний hosted-ключ Hobby і перестаньте ловити «not ready» на спільних нодах → tonnode.io/dashboard?plan=hobby

Далі в міру зростання навантаження — тарифи і роадмап.