Skip to main content

​
Что такое API v4 и зачем он нужен

TON API v4 — это внутренний HTTP API для работы с блокчейном TON. Он предоставляет доступ к историческому состоянию блокчейна и позволяет выполнять get-методы контрактов на указанном номере блока, то есть seqno. API получает данные из индексера блокчейна.
Эндпоинт: https://mainnet-v4.tonhubapi.com/

​
Основные задачи

  • Состояние на конкретном блоке — получение данных об аккаунтах, блоках и транзакциях не “на сейчас”, а на фиксированном masterchain seqno. Это нужно для воспроизводимой логики, например аудита, расчетов и симуляций.
  • Запуск get-метода на историческом блоке — вызов методов смарт-контрактов, например get_staking_status, get_pool_data, get_jetton_data, в контексте состояния на выбранном блоке. Публичные API обычно предоставляют только текущее состояние.
  • Высокая скорость и предсказуемая нагрузка — чтение из собственной индексированной базы данных ScyllaDB и эмуляция через Emulator Farm, когда это необходимо, вместо зависимости от публичных API с ограничениями.

​
Технический стек

  • ScyllaDB — хранение индексов блоков, состояний аккаунтов и транзакций, включая таблицы blocks, account_states, transactions, lt_buckets, mc_blocks_by_utime, sync и другие.
  • Emulator Farm — опциональный gRPC-сервис для выполнения run get-method через TVM-эмуляцию в режиме USE_EMULATOR=true.
  • TONAPI — внешний сервис, который используется только для отправки сообщений в сеть через /v2/liteserver/send_message.

​
Какие проекты Whales используют этот API

Реализация ton-api-v4-go и связанная с ней инфраструктура, то есть индекс ScyllaDB и Emulator Farm, используются в продуктах экосистемы Whales в тех сценариях, где критически важны историческое состояние и вызов get-методов на заданном блоке.
  1. Staking (Whales Staking) — используется для корректного отображения статуса стейка и расчетов на выбранный момент времени. Также применяется для отображения состояний пулов.
  2. Tonhub — получение состояний кошельков по адресу на конкретном блоке. Это нужно для балансов, метаданных и истории, привязанных к определенному состоянию блокчейна.
  3. Общая TON-инфраструктура — может использоваться любыми внутренними сервисами Whales, которым нужен быстрый и детерминированный доступ к историческим данным.

​
Преимущества API v4

​
Историческое состояние на конкретном блоке

Публичные API, например TONAPI и другие публичные индексеры, ориентированы в первую очередь на текущее состояние: последний блок, текущий баланс, последние транзакции.
Продуктам Whales нужен доступ к состоянию на произвольном masterchain seqno, то есть возможность ответить на вопрос “каким было состояние в блоке N”. Это необходимо для:
  • аудита и воспроизводимых расчетов,
  • корректного отображения стейкинга, пулов и jetton на выбранную дату или блок,
  • симуляций и тестов с фиксированным состоянием.
Такие запросы на состояние “в блоке X” либо вообще не поддерживаются публичными API, либо доступны только с ограничениями и непредсказуемыми задержками.

​
Запуск get-метода на историческом блоке

Ключевая возможность API v4 — запуск run get-method в контексте выбранного блока через маршрут /block/{seqno}/{address}/run/{command}. Публичные API обычно позволяют вызывать get-методы только для текущего состояния ноды. Вызов в контексте старого блока требует либо собственного индексирования состояния, либо эмуляции через Emulator Farm.
Для стейкинга вызовы на исторических блоках особенно важны, например get_staking_status или get_pool_data на конкретном seqno. Обычные сторонние API этого не покрывают.

​
Производительность и масштабирование

Собственное индексирование в ScyllaDB дает:
  • быстрый доступ к блокам, аккаунтам и транзакциям по ключам, удобным для продуктовых запросов;
  • возможность масштабировать кластер и настраивать его под собственную нагрузку.
У публичных API есть ограничения на частоту запросов, и эти лимиты делятся между всеми пользователями. Для высоконагруженных сценариев, например агрегации пулов, стейкинга и массовых проверок, этого недостаточно.

​
Контроль над форматом данных и SLA

В API v4 форматы ответов зафиксированы и адаптированы под внутренних клиентов. Кроме того, сторонние API могут менять контракты и версии без учета потребностей Whales.
Собственный стек дает полный контроль над доступностью, обновлением индексов и версиями протокола, но одновременно требует собственной поддержки в случае критических изменений блокчейна.

​
Эмуляция тяжелых get-методов

Некоторые get-методы выполняются через Emulator Farm, то есть в режиме HandleAccountRunV2 с USE_EMULATOR=true. Это позволяет исполнять сложные или тяжелые методы без нагрузки на ноды и без ограничений сторонних API.
Публичные провайдеры не предоставляют эмуляцию для блоков, отличных от последних.

​
Гибридный подход

Для отправки сообщений в сеть API v4 сам использует внешний TONAPI через TONAPI_ENDPOINT и TONAPI_TOKEN, проксируя запросы в v2/liteserver/send_message. То есть сторонний API используется там, где его достаточно, а чтение исторического состояния и запуск run get-method обеспечиваются только собственным API v4.