API событий смарт-контрактов: чтение, фильтрация и подписка
Как работает API событий смарт-контрактов: логи, топики и декодирование ABI, прошлые и живые события, а также когда выбрать вебхуки, WebSockets или опрос.
Проверил(а) Maurice Sobiera

API событий смарт-контракта — это интерфейс, который даёт вашему приложению структурированный доступ к логам, которые пишет контракт, без самостоятельного сканирования каждой транзакции. Прошлые логи вы запрашиваете по адресу контракта и сигнатуре события, а новые получаете по подписке, когда приходят блоки. Можно использовать сырой RPC ноды, библиотеку вроде ethers.js или размещённый API с вебхуками.
В этом руководстве описано, как работает каждый путь, где он ломается и как выбрать.
TL;DR
- Событие контракта — это запись в логе, которая появляется при майнинге транзакции. Ваше приложение читает её позже. Сам контракт прочитать её не может.
- Прошлые события приходят из запроса логов (
eth_getLogsилиqueryFilter). Живые события приходят по подписке или вебхуку. Подписки ноды не воспроизводят историю. - Фильтровать можно только по индексированным параметрам. Для декодирования нужен ABI контракта.
- WebSocket-подписки умирают вместе с соединением и могут отключиться, если вы обрабатываете слишком медленно. Вебхуки с очередью и идемпотентными обработчиками лучше переживают перезапуски.
- Размещённый API избавляет от работы с нодой, ABI и переподключениями. Именно это делает Chaingateway для платежей и событий токенов.
Что такое событие смарт-контракта?
События — это способ, которым контракт общается с внешним миром. Согласно ethereum.org, события позволяют контракту общаться с фронтендом или другими подписанными приложениями, которые могут обработать записанную информацию после того, как транзакция подтверждена и добавлена в блок.
Из этого следуют три вывода, и они объясняют большую часть путаницы в поисковой выдаче.
- События — это вывод, а не хранилище, которое можно запросить из Solidity. Код контракта пишет логи, но не может их прочитать обратно. Поэтому ветки форумов о том, как контракт получает прошлые события, всегда заканчиваются словами «делайте это вне цепи».
- События появляются только после включения в блок. Для транзакции, которая ещё в мемпуле, лога нет.
- События дёшево генерировать и дёшево искать, поэтому переводы и одобрения ERC-20, выпуски NFT и свопы на DEX отслеживаются через логи, а не через чтение состояния.
API событий смарт-контракта — это всё, что даёт вашему бэкенду структурированный доступ к этим логам: JSON-RPC ноды, библиотека поверх него, индексатор или размещённый сервис, который присылает вебхуки.
Что находится внутри лога события?
Чтобы правильно фильтровать или декодировать логи, нужно знать их форму. Согласно спецификации ABI Solidity, лог содержит адрес контракта, до четырёх топиков и сегмент данных. Анонимные события не содержат хеша сигнатуры события.
Для обычного события:
- Топик 0 — это хеш Keccak-256 сигнатуры события, например
Transfer(address,address,uint256). - Топики 1–3 содержат индексированные параметры.
- Данные содержат неиндексированные параметры, закодированные по ABI.
ABI разделяет параметры на индексированные, которые хранятся как хеш-топики для эффективной фильтрации, и неиндексированные, которые хранятся как двоичные данные в логе.
Есть одна ловушка, которую стоит знать. В той же спецификации (в редакции v0.8.3) сказано, что индексированные параметры динамической длины, например строки и байтовые массивы, хранятся как хеш Keccak от специального кодирования, а не как значение. Исходную строку из лога не восстановить. Можно только проверить, совпадает ли кандидат с ней.
Конкретный пример: перевод ERC-20
Лог перевода токена содержит в топике 0 сигнатуру Transfer, в топике 1 адрес отправителя, в топике 2 адрес получателя, а сумма находится в поле данных. Если нужны все депозиты на один адрес клиента, вы фильтруете по топику 0 и топику 2. Подробно мы разбираем это в нашем руководстве по событию Transfer ERC-20.

Как читать прошлые события?
Чтение истории — это запрос, а не подписка. Стандартный метод JSON-RPC — eth_getLogs. Он принимает объект фильтра с диапазоном блоков, необязательным адресом контракта и необязательным массивом топиков. Справочник Coinbase Developer Documentation по eth_getLogs показывает форму запроса: fromBlock, toBlock и topics, и отмечает, что хеш блока может заменить диапазон.
Библиотеки оборачивают этот вызов. В ethers.js contract.queryFilter(event, fromBlock, toBlock) возвращает подходящие события, а документация ethers v5 по контрактам говорит, что фильтровать можно только индексированные параметры. Параметр, оставленный null, совпадает с любым значением.
Практические правила для запросов истории:
- Всегда ограничивайте диапазон. Многие провайдеры ограничивают протяжённость блоков или количество результатов за вызов. Проходите диапазоны порциями (например, по несколько тысяч блоков) и уменьшайте порцию вдвое, когда получаете ошибку.
- Фильтруйте как минимум по адресу и топику 0. Незафильтрованные запросы логов — самый быстрый способ упереться в лимит запросов.
- Сохраняйте последний обработанный блок. Эта контрольная точка позволяет продолжить после сбоя без пропусков и дубликатов.
- Декодируйте правильным ABI. Если у вас есть только топик 0, можно найти сигнатуру события, но прокси-контракт может генерировать события, определённые в его реализации, поэтому используйте ABI реализации.
Если хотите освежить в памяти работу с нодами напрямую, наше руководство по JSON-RPC с примерами на PHP, Python и JavaScript описывает формат запросов.
Как подписаться на новые события?
Живая часть работает иначе, и именно здесь проваливаются многие первые реализации.
Документация go-ethereum по событиям в реальном времени объясняет, что подписки используют постоянные соединения WebSocket или IPC, обычно через eth_subscribe, и передают события по мере их обработки нодой. Важны два ограничения:
- Без воспроизведения. Уведомления подписки касаются текущих событий, а не прошлых. Если ваш процесс был недоступен десять минут, подписка не вернёт пропущенное. Недостающее добирается запросом логов.
- Привязка к соединению. Подписки привязаны к одному соединению. Когда оно закрывается, закрываются и все его подписки.
На той же странице добавлено, что ноды буферизуют уведомления, и если клиент не успевает их обрабатывать, соединение может быть закрыто при достижении лимита буфера (в примере Geth — 10 000). Медленный обработчик, который пишет в базу прямо в процессе, именно так и вызывает это.
Шаблон, который выдерживает нагрузку
Сочетайте оба механизма:
- При старте прочитайте контрольный блок.
- Дозагрузите события от контрольного блока до текущей вершины через
eth_getLogsпорциями. - Откройте подписку и дедуплицируйте по хешу транзакции и индексу лога.
- Передавайте каждое событие в очередь и подтверждайте его сразу. Обрабатывайте в воркере.
- При разрыве соединения вернитесь к шагу 1.
Это остаётся корректным даже тогда, когда соединение рвётся, а оно будет рваться.
Что происходит при реорганизации?
Лог, который вы видели в последнем блоке, может исчезнуть, если цепь реорганизуется. Для всего, что связано с деньгами, не зачисляйте пользователю средства при первом появлении. Дождитесь глубины подтверждений, подходящей для сети и суммы, и обрабатывайте флаг «removed», который ноды в стиле Ethereum прикрепляют к логам из осиротевших блоков. Храните ID обработанного события и делайте обработчик идемпотентным, чтобы повторно воспроизведённое или исправленное событие не зачислило средства дважды.

Что выбрать: вебхуки, WebSockets или опрос?
Все три способа могут доставлять события. Они различаются тем, кто держит соединение и за какие сбои отвечает.
| Подход | Как работает | Сильная сторона | Слабая сторона |
|---|---|---|---|
| Опрос | Ваш код вызывает eth_getLogs по таймеру, начиная с последней контрольной точки | Просто, без состояния, легко возобновить | Задержка равна вашему интервалу, и это тратит запросы |
| Подписка WebSocket | Постоянное соединение передаёт логи от ноды | Минимальная задержка | Умирает вместе с соединением, нет воспроизведения, лимиты буфера |
| Вебхук | Сервис следит за цепью и отправляет HTTP POST на ваш endpoint | Не нужно поддерживать долгоживущее соединение, работает с serverless | Нужен публичный endpoint, проверка подписи и обработка дубликатов |
Опрос подходит для фоновых задач с небольшим объёмом. WebSockets подходят для дашборда или бота, который должен реагировать внутри блока и может терпеть пропуски. Вебхуки подходят для платёжных флоу, где нужна одна надёжная отправка на событие и очередь воркеров за ней. Наша статья о паттерне приём, очередь, fan-out для вебхуков и WebSockets подробнее разбирает компромиссы.
Как правильно принимать доставку вебхуков
Каким бы ни был отправитель вебхука, получатель стоит строить одинаково:
- Проверяйте подпись, прежде чем действовать по payload.
- Быстро возвращайте 2xx и обрабатывайте асинхронно.
- Делайте обработчики идемпотентными, с ключом по хешу транзакции и индексу лога.
- Ожидайте дубликатов и доставки не по порядку.
- Записывайте сбои в журнал, чтобы позже сверить их запросом логов.
Поведение доставки — отдельная тема проектирования. Наша статья о гарантиях доставки вебхуков охватывает дубликаты, порядок и пропущенные уведомления.
Пошагово: настройка мониторинга событий
Ниже минимальный путь для одного контракта EVM, независимо от инструмента.
- Получите ABI. Из верифицированного исходного кода контракта или из результатов вашей сборки. Без него вы видите только сырые топики и hex-данные.
- Выберите события. Перечислите сигнатуры, которые вам важны, например
Transfer,Approvalили собственноеOrderPaid. - Определите фильтры. Адрес контракта, топик 0 и любой индексированный параметр, например получатель. Помните, что фильтровать можно только индексированные значения.
- Дозагрузите историю. Запросите от блока развёртывания или от даты начала работы вашего бизнеса порциями.
- Переходите в режим реального времени. Подпишитесь по WebSocket или зарегистрируйте вебхук.
- Декодируйте и нормализуйте. Переведите hex-суммы с учётом десятичных знаков токена и сохраняйте номер блока, хеш транзакции, индекс лога и адрес контракта.
- Дождитесь финальности. Помечайте события как ожидающие, затем как подтверждённые.
- Следите за самим мониторингом. Поднимайте тревогу, если событие не приходит дольше обычного разрыва для сети или если ваша контрольная точка отстаёт от вершины.
События в разных сетях
Модель EVM с топиками и данными, декодированными по ABI, применима к Ethereum, Polygon, BNB Chain и Arbitrum, поэтому один декодер работает во всех них с разными RPC endpoint-ами и правилами подтверждений. Другие сети такой модели не используют. У Bitcoin вообще нет логов контрактов, поэтому вы следите за адресами и транзакциями. У Tron и Solana свои форматы и API.
Практический итог: продукт в нескольких сетях в итоге поддерживает по одному адаптеру на каждое семейство сетей, и у каждого свой код переподключения, декодирования и финальности. Именно эту часть команды чаще всего недооценивают. Карту вариантов см. в нашем сравнении шести типов blockchain API и разборе blockchain API против собственной ноды.
Собственная реализация или размещённый API?
Собственный стек означает ноду (или платный RPC endpoint), сканер логов, реестр ABI, обработчик реорганизаций, очередь и систему оповещений. Это разумно, если события — ваш основной продукт или вам нужна собственная индексация тысяч контрактов.
Это менее разумно, если события — средство достижения цели, например зачисление депозита или подтверждение заказа. В этом случае вам нужны декодированные события, доставленные на endpoint, которым вы управляете, и ничего больше в эксплуатации.
Наш взгляд
Большинство ошибок при обработке событий, которые мы видим, связаны не с чтением логов. Они связаны с тем, что происходит вокруг: пропущенное уведомление во время деплоя, двойное зачисление после повтора, неверное преобразование десятичных знаков для одного токена, соединение, которое тихо умерло за ночь.
Поэтому мы строим вокруг трёх убеждений. Во-первых, приложение должно получать декодированные структурированные данные, а не сырые топики, которые ему приходится интерпретировать. Во-вторых, для платежей push лучше опроса, при условии что каждое сообщение подписано и его можно проверить. В-третьих, разработчику не нужно запускать ноды или держать в синхронности endpoint-ы конкретных сетей только ради того, чтобы узнать, что платёж поступил.
Поэтому Chaingateway предоставляет один REST API для Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Chain и Arbitrum с декодированными транзакциями и ценами газа. Вебхуки работают поверх него и подписываются HMAC, поэтому ваш обработчик получает событие, а команда может сосредоточиться на продукте. Что бы вы ни выбрали, сохраняйте контрольную точку, ключ идемпотентности и правило подтверждений. От этих трёх вещей зависит, верны ли ваши цифры.
— Bitblade
Как получать события без собственных нод?
Если ваша цель — события платежей и токенов в приложении, Chaingateway Webhooks доставляют уведомления о блокчейне в реальном времени на ваш endpoint, а Blockchain API даёт декодированные транзакции, кошельки, переводы и цены газа через один интерфейс. Тарифы начинаются с 49 € в месяц за Plus; Pro стоит 99 €, Premium 249 €, Enterprise 499 € в месяц. При годовой оплате это 490 €, 990 €, 2 490 € и 4 990 € соответственно. Что входит в каждый тариф, см. на странице цен. Пример для конкретной сети — вебхуки Polygon без опроса.
Источники
- Anatomy of smart contracts, ethereum.org
- Спецификация ABI контрактов, Solidity v0.8.22
- Спецификация ABI контрактов, Solidity v0.8.3
- Real-time Events, go-ethereum
- eth_getLogs, Coinbase Developer Documentation
- Contract, документация ethers v5
Рекомендуем
Часто задаваемые вопросы
Нет. Контракты могут создавать логи, но не могут получить к ним доступ потом, поэтому данные событий предназначены для потребителей вне цепи. Если контракту нужны исторические данные внутри цепи, храните значение в состоянии контракта, что стоит больше газа.
Выполните запрос логов от последнего обработанного блока до текущей вершины. Подписки ноды передают только текущие события, поэтому переподключение ничего не воспроизводит. Сохраняйте контрольную точку после каждого обработанного блока и дедуплицируйте по хешу транзакции и индексу лога.
Только индексированные параметры сохраняются как топики, а фильтровать можно только топики. Неиндексированные значения находятся в поле данных, поэтому логи нужно получить и отфильтровать в собственном коде. Если вы управляете контрактом, помечайте поля, по которым будете искать, как индексированные, но не более трёх на событие.
Для платежей вебхуки с очередью обычно проще эксплуатировать, потому что вы не держите соединение, которое может разорваться. Используйте WebSockets, когда важна реакция меньше секунды и вы можете дозагрузить пропуски. В обоих случаях обрабатывайте события идемпотентно и дожидайтесь достаточного числа подтверждений, прежде чем зачислять средства.
Готовы собрать это сами? Получите свой API-ключ — 7-дневный пробный период, без карты — или посмотрите API блокчейна для полного справочника по эндпоинтам.