Журналы событий

Что такое журналы событий в криптовалютах?

Журналы событий — это структурированные записи, создаваемые смарт-контрактами во время исполнения блокчейн-транзакций.

Они позволяют смарт-контракту публиковать информацию, которую могут находить и обрабатывать кошельки, децентрализованные приложения, обозреватели блокчейна, аналитические платформы и другие офчейн-системы.

В Ethereum и других сетях на базе EVM разработчики обычно создают журналы событий, объявляя событие Solidity и используя ключевое слово emit при возникновении соответствующего действия.

Например, контракт токена может создавать событие при переводе, выпуске, сжигании токенов или предоставлении разрешения на их расходование.

DeFi-протокол может создавать журналы, когда пользователь вносит обеспечение, занимает криптовалюту, погашает долг, получает вознаграждения или закрывает позицию.

В официальной документации Solidity о событиях объясняется, что события представляют собой абстракцию над функцией журналирования EVM.

Журналы событий обычно не управляют состоянием контракта и не запускают дополнительную бизнес-логику после создания.

Вместо этого они служат эффективной записью, с помощью которой внешнее программное обеспечение может понять, что произошло во время транзакции.

Таким образом, журналы событий связывают ончейн-смарт-контракты с офчейн-приложениями, отображающими пользователям активность блокчейна.

Как работают журналы событий

Журнал события создается, когда виртуальная машина Ethereum обрабатывает успешный путь исполнения транзакции.

Сначала смарт-контракт объявляет событие, задавая его имя и список параметров.

Затем контракт создает событие, когда код доходит до соответствующей инструкции.

Компилятор Solidity преобразует создание события в одну из операций журналирования EVM.

В итоговом журнале содержатся адрес создавшего его контракта, список доступных для поиска тем и поле данных с дополнительной закодированной информацией.

После включения транзакции в блок журнал становится частью квитанции о транзакции.

Приложения могут получить журнал через узел Ethereum, провайдера RPC, обозреватель блокчейна или специализированный блокчейн-индексатор.

В руководстве Ethereum по журналированию событий смарт-контрактов объясняется, что децентрализованные приложения могут отслеживать созданные события и выполнять офчейн-действия при их появлении.

Если транзакция откатывается, журналы, созданные в ходе отмененного исполнения, также удаляются из итогового результата транзакции.

Поэтому журнал, отображаемый во время симуляции или трассировки исполнения, может отсутствовать в подтвержденной квитанции, если весь вызов завершился ошибкой.

События и журналы событий

Событие — это заданное разработчиком объявление, описывающее информацию, которую контракт может публиковать.

Журнал события — это фактическая запись, создаваемая при генерации события контрактом во время транзакции.

Например, в исходном коде контракта можно объявить событие Transfer.

Каждый завершенный перевод может создать отдельный журнал согласно этому описанию события.

Событие служит шаблоном, а каждый журнал — отдельным зафиксированным случаем его использования.

Одна транзакция может не создавать журналов, создать один журнал или несколько.

При взаимодействии с несколькими смарт-контрактами в одной транзакции журналы могут создавать все участвующие в исполнении контракты.

Для сопоставления необработанных журналов с объявлениями событий и декодирования значений приложения используют ABI (интерфейс двоичного взаимодействия приложения) контракта.

Какая информация хранится в журнале события?

Журнал события EVM содержит адрес создавшего его контракта, от нуля до четырех тем и поле данных переменной длины.

Адрес создавшего журнал контракта указывает, исполнение какого контракта привело к его появлению.

Темы содержат значения, предназначенные для эффективной фильтрации и поиска.

В поле данных хранятся параметры события, не отмеченные как индексируемые.

В распространенных интерфейсах RPC вместе с журналами также возвращаются метаданные транзакции и блока.

К этим метаданным могут относиться хеш транзакции, индекс транзакции, хеш блока, номер блока и индекс журнала.

Индекс журнала указывает его положение среди других журналов в том же блоке.

Для создания уникального идентификатора записи приложениям обычно следует использовать сочетание идентификатора сети, хеша блока, хеша транзакции и индекса журнала.

Одного названия события или хеша транзакции может быть недостаточно, поскольку одна транзакция может несколько раз создавать одно и то же событие.

Что такое темы события?

Темы — это 32-байтовые значения, размещаемые в специальной доступной для поиска части журнала EVM.

Они позволяют приложению фильтровать историю блокчейна без отдельного декодирования каждого поля данных события.

Обычное событие Solidity, не объявленное как анонимное, может использовать до четырех тем.

Первая тема обычно указывает тип события, а до трех дополнительных тем представляют параметры, отмеченные как индексируемые.

Темы упорядочены: фильтрация значения во второй позиции отличается от фильтрации того же значения в третьей позиции.

В официальной документации Ethereum JSON-RPC по eth_getLogs объясняется, что фильтры тем зависят от их порядка и могут включать альтернативные значения для одной позиции.

Темы особенно полезны для поиска событий, связанных с адресом кошелька, идентификатором токена, рынком, предложением или другим часто запрашиваемым значением.

Непродуманный выбор индексируемых параметров может затруднить или удорожить поиск исторических данных приложения.

Что такое Topic 0?

Topic 0 обычно содержит хеш события, полученный с помощью Keccak-256 от канонической сигнатуры события.

Каноническая сигнатура объединяет имя события с упорядоченными типами его параметров.

Имена параметров и ключевое слово indexed не входят в хеш сигнатуры события.

Например, событие с именем Transfer и параметрами типов address, address и uint256 имеет предсказуемую сигнатуру.

Приложения могут сравнивать Topic 0 с известными хешами сигнатур, чтобы определить событие, представленное необработанным журналом.

Изменение имени события, порядка или типов его параметров создает другую сигнатуру.

Поэтому у двух событий с одинаковым именем, но разными типами параметров будут разные значения Topic 0.

В спецификации ABI Solidity для событий описано, как сигнатура события и его аргументы кодируются в темах и данных.

Индексируемые параметры событий

Индексируемый параметр — это аргумент события, хранящийся в теме, чтобы внешние системы могли эффективно фильтровать события по его значению.

В Solidity для обычного неанонимного события можно задать до трех индексируемых параметров.

Оставшаяся позиция темы отводится под сигнатуру события.

Адреса, целые числа, логические значения и другие значения, помещающиеся в одно 32-байтовое слово, можно записывать непосредственно в тему с использованием кодирования, совместимого с ABI.

Динамические значения, такие как строки, массивы байтов, динамические массивы и сложные структуры, обрабатываются иначе.

Если динамическое значение индексируется, в теме хранится хеш Keccak-256 его закодированного значения, а не исходное читаемое значение.

Если приложению известно искомое значение, оно может отфильтровать журналы по этому хешу.

Однако восстановить неизвестную исходную строку или массив байтов только по хешу невозможно.

Иногда разработчики дважды включают одну и ту же информацию: хешированную версию помещают в индексируемый параметр, а читаемую — в неиндексируемый.

Такой подход упрощает поиск и одновременно сохраняет исходное значение для декодирования.

Неиндексируемые параметры событий

Параметры без ключевого слова indexed хранятся в поле данных журнала.

Эти значения кодируются согласно правилам ABI Ethereum.

ABI необходим, поскольку необработанные данные журнала не содержат понятных человеку обозначений каждого значения и его типа.

Для надежного декодирования данных приложению требуется правильное описание события.

Неиндексируемые параметры могут содержать более крупные и сложные значения, чем отдельные темы.

Они подходят для сумм, подробных параметров конфигурации, массивов, строк и другой информации, которую не нужно напрямую фильтровать по темам.

Обычно приложения не могут попросить eth_getLogs отфильтровать произвольное значение внутри поля данных.

Сначала нужно получить журналы по адресу контракта и темам, а затем декодировать и проверить данные локально.

Анонимные события

Событие Solidity можно объявить анонимным.

Анонимное событие не помещает хеш своей сигнатуры в Topic 0 автоматически.

Это позволяет использовать все четыре позиции тем для индексируемых параметров.

Однако удаление темы с сигнатурой затрудняет автоматическое определение типа события внешним программным обеспечением.

Если у разных анонимных событий похожая структура тем и данных, их может быть трудно различить.

Анонимные события могут подойти для специализированных низкоуровневых решений, но обычные события приложений обычно проще индексировать и декодировать, если они не анонимны.

Разработчикам следует использовать анонимные события, только если дополнительная индексируемая тема дает явное преимущество, оправдывающее усложнение идентификации события.

Опкоды журналирования EVM

В EVM есть пять опкодов журналирования: LOG0–LOG4.

Число в названии каждого опкода указывает количество тем в журнале.

LOG0 создает журнал без тем, а LOG4 — с четырьмя темами.

Каждая операция журналирования также считывает выбранный диапазон памяти EVM и сохраняет его как поле данных журнала.

События Solidity компилируются в эти низкоуровневые инструкции журналирования.

Среда исполнения добавляет адрес контракта к журналу, а не получает его как обычный параметр события.

Операции журналирования расходуют газ; его стоимость зависит в том числе от количества тем и объема записанных данных.

В официальном справочнике опкодов Ethereum перечислены инструкции журналирования EVM и стоимость их исполнения.

Журналы событий и квитанции о транзакциях

Квитанция о транзакции — это запись исполнения, создаваемая после включения транзакции в блок.

Квитанция содержит такую информацию, как статус исполнения, совокупный расход газа, фильтр Блума для журналов и журналы, созданные транзакцией.

Ответы RPC могут также включать полезные поля: адрес созданного контракта, фактическую цену газа и расход газа конкретной транзакцией.

Массив журналов сохраняет порядок, в котором события возникали во время исполнения.

Успешная транзакция может содержать пустой массив журналов, если ни один контракт не создавал событий.

В неудачной транзакции обычно не остается журналов событий, поскольку изменения состояния и журналы были отменены.

Приложениям следует проверять статус квитанции, а не считать само наличие хеша транзакции доказательством успешного исполнения.

В описании метода Ethereum JSON-RPC для получения квитанций о транзакциях перечислены поля, возвращаемые клиентом исполнения.

Журналы событий и квитанции блоков

Квитанции о транзакциях криптографически фиксируются с помощью корня квитанций блока.

Это позволяет участникам блокчейна проверять, что квитанции относятся к определенной истории блоков.

Каждая квитанция содержит журналы, созданные соответствующей транзакцией.

В заголовок блока также включен фильтр Блума, который в текущем формате блока исполнения обобщает адреса журналов и темы транзакций этого блока.

Фильтр Блума помогает клиенту определить, могут ли в блоке находиться журналы, соответствующие запросу.

Положительное совпадение по фильтру Блума не доказывает наличие соответствующего журнала, поскольку такие фильтры могут давать ложноположительные результаты.

Отрицательное совпадение означает, что искомый адрес или тема отсутствуют в этом фильтре.

Для проверки точных значений событий приложениям все равно нужны сами журналы из квитанций.

Журналы событий и хранилище контракта

Журналы событий и хранилище смарт-контракта выполняют разные функции.

Хранилище контракта содержит постоянные данные, которые может напрямую считывать последующее исполнение смарт-контракта.

Журналы событий предназначены главным образом для внешнего наблюдения и индексации истории.

Контракты Solidity не могут напрямую считывать исторические журналы событий, включая журналы, созданные тем же контрактом.

В справочнике Solidity по событиям указано, что данные журналов и событий недоступны внутри контрактов.

Контракт не должен полагаться на более раннее событие как на единственный источник данных для будущих ончейн-решений.

Если будущей логике контракта понадобится определенное значение, его обычно следует сохранить в состоянии контракта или передать через проверяемый механизм.

Для информации, предназначенной только офчейн-пользователям, журналы обычно дешевле постоянного хранения.

Однако замена хранилища журналом меняет возможности последующей проверки или получения информации смарт-контрактами.

Журналы событий и возвращаемые функцией данные

Во время исполнения контракта возвращаемые функцией данные передаются непосредственному вызывающему объекту.

Журналы событий сохраняются в квитанциях о транзакциях для последующего получения вне блокчейна.

Интерфейс пользователя не получает возвращаемые данные от изменяющей состояние транзакции в таком же удобном историческом формате, как журнал события.

Чтобы узнать результат отправленной транзакции, приложения часто используют квитанции и события.

Вызовы только для чтения могут возвращать значения без создания журналов событий и изменения состояния блокчейна.

Разработчикам следует использовать возвращаемые значения для непосредственного взаимодействия при вызове контракта, а события — для надежных офчейн-уведомлений.

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

Как приложения запрашивают журналы событий

Для запроса исторических журналов приложения обычно используют метод JSON-RPC eth_getLogs.

В запросе можно указать начальный и конечный блоки, адрес контракта, хеш блока и фильтры тем.

Метод возвращает массив журналов, соответствующих фильтру.

Узкий запрос обычно надежнее и эффективнее, чем получение всех журналов за очень большой диапазон блоков.

Провайдеры RPC могут ограничивать диапазон блоков, размер ответа, время обработки запроса или частоту запросов.

При поиске по большой истории приложениям следует разбивать запрос на меньшие диапазоны блоков и сохранять прогресс.

При сбоях запросы следует повторять с контролируемыми интервалами, а не считать пустой или неудачный ответ доказательством отсутствия событий.

Фильтр blockHash, определенный в EIP-234, позволяет приложению запросить журналы из конкретного блока.

Опрос и подписки на события

Приложение может обнаруживать новые журналы событий с помощью периодических запросов или подписок.

При опросе узел регулярно запрашивается о журналах или изменениях фильтра.

Подписка поддерживает постоянное соединение, чтобы узел мог отправлять уведомления о новых журналах по мере появления блоков.

Подписки обеспечивают более быстрые обновления, но соединение может прерваться, а во время сбоя часть данных может быть пропущена.

Восстановиться после сбоев с помощью опроса может быть проще: приложение может повторно запросить известный диапазон блоков.

В надежных производственных системах часто сочетаются непрерывные подписки и периодическая сверка данных по блокам.

Это позволяет обнаруживать журналы, пропущенные при сетевых перебоях или перезапуске узла.

В официальной документации по API Ethereum JSON-RPC описаны методы фильтрации для получения журналов, появившихся после предыдущего опроса.

Журналы событий и реорганизации цепочки

Реорганизация цепочки происходит, когда блок, ранее считавшийся частью активной цепочки, заменяется другой историей блоков.

Журналы из замененного блока больше не относятся к каноническому блокчейну.

Приложению, которое немедленно отреагировало на такие журналы, может понадобиться отменить соответствующие изменения в локальной базе данных.

Некоторые ответы RPC-подписок могут сообщать, что ранее переданный журнал удален из-за реорганизации.

Однако из-за отключения сети приложение может не получить уведомление об удалении.

Надежные индексаторы отслеживают хеши блоков и связи с родительскими блоками, чтобы самостоятельно обнаруживать замены блоков.

Обоснование фильтрации журналов по хешу блока объясняет, почему приложениям важно учитывать реорганизации и потерю соединения.

Финансовым системам обычно следует ждать соответствующего числа подтверждений или порога финальности, прежде чем считать событие необратимым.

Необходимый порог зависит от сети, стоимости операции и последствий слишком раннего действия.

Журналы событий и финальность

Новое событие может появиться в предложенном блоке до достижения им более высокой степени финальности в рамках консенсуса.

При поддержке подключенного клиента приложения могут запрашивать журналы с тегами блоков, такими как latest, safe или finalized.

Тег latest предоставляет данные быстрее, но может включать блоки с более высоким риском реорганизации.

Тег finalized обеспечивает большую уверенность, но требует больше времени.

Интерфейс портфеля может отображать события latest, а мосту или крупному финансовому переводу может потребоваться более высокий уровень подтверждения.

Приложениям следует выбирать политику подтверждения с учетом экономических рисков, а не применять одно правило ко всем событиям.

Журналы событий в контрактах токенов

В стандартах токенов используются журналы событий, чтобы сделать переводы и разрешения видимыми для кошельков и систем анализа данных блокчейна.

При перемещении взаимозаменяемого токена обычно создается событие Transfer.

Когда владелец меняет разрешенный объем расходования для другого адреса, также может создаваться событие Approval.

Контракты NFT обычно создают события перевода и одобрения, содержащие идентификаторы токенов.

Контракты мульти-токенов могут создавать события для единичных и пакетных переводов.

Стандартизированные структуры событий позволяют внешним инструментам использовать одинаковую логику декодирования для множества контрактов токенов.

Однако токен может создавать вводящие в заблуждение события или некорректно следовать стандарту.

Одно событие само по себе не доказывает легитимность, ценность или безопасность контракта.

Журналы событий в DeFi

DeFi-протоколы используют журналы событий для описания сложных финансовых операций.

К распространенным примерам относятся депозиты, выводы средств, обмены, займы, погашения, ликвидации, обновления процентов, получение вознаграждений и изменения управления.

Интерфейс пользователя может отслеживать эти события для обновления балансов и истории транзакций.

Аналитическая система может агрегировать их для расчета объема торгов, ликвидности, активности заимствований или выручки протокола.

Система мониторинга рисков может отслеживать события ликвидации или обеспечения, чтобы выявлять позиции в стрессовом состоянии.

Поскольку одна транзакция DeFi может вызывать несколько контрактов, в квитанции может содержаться множество связанных журналов.

Приложениям следует учитывать адрес источника и порядок журналов, а не декодировать каждую знакомую сигнатуру события так, будто она создана главным контрактом протокола.

Журналы событий в кошельках и обозревателях блокчейна

Кошельки используют журналы событий, чтобы преобразовывать необработанные транзакции смарт-контрактов в понятную историю.

Перевод токена может не отображаться как перемещение нативного актива в основных полях транзакции.

Чтобы показать актив, отправителя, получателя и сумму, кошелек может декодировать событие Transfer контракта токена.

Обозреватели блокчейна также декодируют журналы с помощью ABI верифицированных контрактов и известных сигнатур событий.

Если исходный код или информация ABI недоступны, обозреватель может показывать необработанные значения тем и данных.

Декодированная подпись события — это интерпретация необработанного журнала, а не независимая гарантия намерений контракта.

Перед тем как доверять описанию события, пользователям следует проверить адрес создавшего его контракта.

Журналы событий и блокчейн-индексаторы

Блокчейн-индексатор считывает блоки и квитанции, а затем сохраняет выбранные данные событий в удобной для запросов базе данных.

Индексаторы упрощают решение задач, с которыми сложно справиться напрямую через RPC-запросы.

Например, можно получить все переводы токенов для кошелька, рассчитать активность протокола за период или отслеживать все открытые позиции на кредитном рынке.

Обычно индексатор начинает с выбранного блока и обрабатывает новые блоки по порядку.

Он декодирует необходимые журналы, создает записи в базе данных и сохраняет сведения о блоках для обработки реорганизаций.

Индексатор должен уметь продолжить работу после сбоя, не пропуская и не дублируя события.

Если схема декодирования или логика приложения меняется, индексатору также следует повторно обрабатывать исторические данные.

В документации Ethereum по данным и аналитике объясняется, как системы работы с данными блокчейна используют журналы, квитанции, трассировки и другую информацию исполнения.

Журналы событий и офчейн-автоматизация

Офчейн-сервисы могут отслеживать журналы событий и запускать действия за пределами блокчейна.

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

Сам журнал не заставляет офчейн-сервис выполнять действие.

Сервис должен быть в сети, получить событие, проверить его и решить, что делать дальше.

Перед выполнением важных действий офчейн-автоматизации следует проверять идентификатор сети, адрес контракта, статус блока и декодированные значения.

Также система должна быть идемпотентной: повторная обработка одного события не должна приводить к ошибочному дублированию результата.

Это важно, поскольку повторные запросы, переподключения и реорганизации могут привести к тому, что одно и то же событие будет получено несколько раз.

Могут ли смарт-контракты считывать журналы событий?

Во время обычного исполнения EVM смарт-контракты не могут напрямую искать исторические журналы событий.

Журналы предназначены для внешних приложений, а не для чтения в качестве состояния контракта.

Если контракту нужна информация из прошлого события, ее необходимо передать через другой механизм.

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

Прежде чем использовать переданную информацию, контракт должен проверить ее достоверность.

Это ограничение не позволяет смарт-контрактам автоматически считать ответ офчейн-сервиса RPC достоверными данными в блокчейне.

Можно ли изменить журналы событий?

Подтвержденный журнал нельзя изменить отдельно от транзакции и блока, в которых он был создан.

Для изменения журнала пришлось бы заменить или аннулировать историю блокчейна, содержащую соответствующую квитанцию.

До достижения более высокой степени финальности реорганизация цепочки может удалить журнал из активной истории.

Новая транзакция может создать корректирующее или обратное событие, но она не удаляет прежний журнал из канонической истории.

Приложениям следует сохранять исторические события и отражать исправления как последующие записи, а не незаметно переписывать исходные данные блокчейна.

Можно ли подделать журналы событий?

Любой смарт-контракт может объявить и создать событие со знакомым именем и сигнатурой.

Поэтому вредоносный контракт может создать событие Transfer, похожее на событие легитимного контракта токена.

Одна только сигнатура события не определяет актив и не доказывает, что в доверенном контракте действительно изменился баланс.

Приложения должны проверять адрес создавшего журнал контракта и учитывать его код и состояние.

Мошеннический токен также может создавать вводящие в заблуждение значения или события, из-за которых будет казаться, что неактивный кошелек получил актив.

Кошелькам и обозревателям не следует считать все знакомые сигнатуры событий одинаково надежными.

Пользователям не следует взаимодействовать с токеном только потому, что в истории транзакций появился неожиданный перевод.

Журналы событий и безопасность смарт-контрактов

Проектирование событий — часть безопасности смарт-контрактов, поскольку системы мониторинга зависят от точности журналов.

При изменении разрешений, комиссий, адресов оракулов, реализаций обновлений или аварийных настроек важные административные действия должны создавать понятные события.

Отсутствие событий может затруднить обнаружение опасных изменений для пользователей и специалистов по безопасности.

Из-за неправильных значений событий офчейн-системы могут отображать результат, не совпадающий с состоянием контракта.

Контракту следует создавать событие только после успешного прохождения связанных проверок и изменения состояния.

Разработчикам следует тестировать, что каждый важный путь исполнения создает ожидаемый журнал ровно один раз.

Также нужно проверять, что при откате транзакции в итоговом результате не остаются вводящие в заблуждение журналы.

Событие не заменяет контроль разрешений и правил баланса в коде контракта.

Расход газа на журналы событий

Создание события расходует газ, поскольку EVM должна обработать инструкцию журналирования и добавить информацию в квитанцию о транзакции.

Большее количество тем и увеличенный объем данных обычно повышают стоимость журналирования.

Поэтому событие с несколькими крупными значениями может стоить дороже минимального события.

Журналы часто обходятся дешевле, чем сохранение той же информации в постоянном хранилище контракта.

Однако ненужные журналы все равно повышают стоимость транзакций для пользователей и объем истории блокчейна.

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

Не следует включать в отдельное событие все внутренние вычисления, если внешним системам эти данные не требуются.

Оптимизация газа не должна лишать пользователей важной прозрачности, необходимой для безопасного мониторинга работы протокола.

Рекомендации по проектированию событий

Названия событий должны четко описывать произошедшее действие.

Названия параметров следует выбирать так, чтобы разработчики и аналитики могли понять их назначение.

Значения, которые пользователи часто ищут, стоит рассмотреть для индексирования.

К часто индексируемым значениям относятся адреса аккаунтов, идентификаторы токенов, рынков и предложений.

Суммы и подробные параметры конфигурации обычно можно оставить в поле данных, если прямой поиск по ним не требуется.

Не следует индексировать динамические значения, если фильтрация по хешу не дает конкретной пользы.

Каждое событие должно содержать достаточно контекста для интерпретации без ненадежных предположений о порядке транзакций.

В контрактах с несколькими активами или рынками следует указывать идентификатор соответствующего актива или рынка.

Если это помогает мониторингу, в событиях обновления следует указывать как старое, так и новое значение.

Объявления событий следует сохранять неизменными, если внешние приложения зависят от их сигнатур и структуры параметров.

Рекомендации по чтению журналов событий

Приложениям следует фильтровать журналы как по ожидаемому адресу контракта, так и по ожидаемой сигнатуре события.

Для декодирования журналов нужно использовать правильную версию ABI, соответствующую реализации контракта в блоке, где был создан журнал.

После обновления реализации обновляемого контракта набор доступных событий может измениться.

Индексаторам следует сохранять хеш и номер блока, хеш транзакции, индекс транзакции и индекс журнала.

Журналы следует обрабатывать в каноническом порядке блоков и поддерживать откат после реорганизации.

Большие исторические запросы следует разбивать на управляемые диапазоны блоков.

Приложениям следует отличать действительно пустой ответ от ошибки, усеченного ответа или ограничения частоты запросов.

Финансовые операции должны ждать уровня подтверждения, соответствующего их стоимости и рискам.

Если точность особенно важна, приложениям следует сравнивать значения из событий с состоянием контракта.

Журналы событий в сетях Layer 2

В сетях Layer 2 на базе EVM обычно используются журналы событий, структура которых похожа на журналы Ethereum.

Разработчики часто могут использовать привычные события Solidity, темы, ABI и запросы JSON-RPC.

Однако у сетей Layer 2 могут отличаться время создания блоков, правила подтверждения, секвенсоры, структура комиссий и процессы окончательного расчета.

Журнал, подтвержденный секвенсором Layer 2, может еще не достичь максимального уровня финальности в Ethereum.

События, связанные с мостом, могут появляться как в исходной, так и в целевой сети на разных этапах перевода.

Приложениям необходимо учитывать правильный идентификатор сети и не объединять события из разных сетей в одну историю.

Одинаковый адрес контракта или сигнатура события в разных сетях может относиться к разным контрактам и активам.

Журналы событий при кроссчейн-переводах

В кроссчейн-системах события часто сообщают о блокировке, сжигании, разблокировке или выпуске активов.

Офчейн-ретранслятор или протокол целевой сети может обнаружить событие исходной сети до продолжения перевода.

Для выполнения действия в целевой сети необходимо подтвердить исходное событие согласно механизму доказательств или системе валидаторов моста.

Одного обнаружения журнала через обычного провайдера RPC недостаточно, чтобы смарт-контракт без доверенной стороны мог доказать его достоверность.

Мостам также нужно учитывать реорганизации и финальность исходной сети.

Если мост сработает слишком быстро, он может обработать событие, которое впоследствии будет удалено из канонической истории исходной сети.

Пользователям следует понимать, что событие моста может обозначать начало перевода, а не его окончательное завершение.

Пример журнала события

Предположим, пользователь переводит 500 единиц взаимозаменяемого токена на другой кошелек.

Пользователь отправляет транзакцию, вызывающую функцию transfer контракта токена.

Контракт проверяет баланс отправителя и обновляет балансы отправителя и получателя.

Затем контракт создает событие Transfer с адресом отправителя, адресом получателя и количеством переведенных токенов.

Адреса отправителя и получателя могут храниться в индексируемых темах, а сумма — в поле данных, закодированном по ABI.

Хеш сигнатуры события находится в Topic 0.

После включения транзакции в блок журнал появляется в квитанции о транзакции.

Кошелек получает и декодирует журнал, чтобы отобразить перемещение токенов в понятной истории транзакций.

Индексатор также сохраняет событие, чтобы пользователи могли искать все переводы с участием обоих адресов.

Этот пример показывает, как один журнал события связывает исполнение контракта с кошельками, обозревателями и аналитикой блокчейна.

Распространенные ошибки при работе с журналами событий

Одна из распространенных ошибок — считать, что другое смарт-приложение может прочитать событие.

Еще одна ошибка — считать знакомую сигнатуру события доказательством легитимности создавшего его контракта.

Третья ошибка — декодировать журнал, не проверив адрес контракта.

Четвертая — считать, что индексированную строку можно напрямую восстановить по хешу темы.

Пятая — использовать только хеш транзакции как идентификатор журнала.

Шестая — не учитывать реорганизации цепочки.

Седьмая — обрабатывать один и тот же журнал дважды после повторного RPC-запроса или перезапуска приложения.

Восьмая — запрашивать чрезвычайно большой диапазон блоков и считать ответ с истекшим временем ожидания пустым результатом.

Девятая — полагаться только на события, если будущей логике смарт-контракта нужны те же данные в хранилище.

Десятая — считать, что успешно декодированное событие доказывает корректное выполнение всех предполагаемых изменений состояния.

FAQ

Что такое журналы событий в криптовалютах?

Журналы событий — это структурированные записи, создаваемые смарт-контрактами для описания действий, произошедших при исполнении блокчейн-транзакций.

Где хранятся журналы событий Ethereum?

Журналы событий Ethereum включаются в квитанции о транзакциях, которые фиксируются в истории исполнения блока.

Чем событие отличается от журнала?

Событие — это объявление в коде смарт-контракта, а журнал — фактическая запись, создаваемая при генерации этого события.

Могут ли смарт-контракты считывать старые журналы событий?

Нет. При обычном исполнении EVM смарт-контракты не могут напрямую искать или считывать исторические журналы.

Что такое Topic 0 в журнале события Ethereum?

Topic 0 обычно содержит хеш Keccak-256 от имени события и канонических типов параметров.

Сколько тем может быть в журнале события?

В журнале EVM может быть до четырех тем; обычное событие Solidity обычно резервирует одну из них для сигнатуры события.

Что означает indexed в событии Solidity?

Индексируемый параметр сохраняется в теме, чтобы внешние приложения могли фильтровать журналы по этому значению.

Можно ли индексировать строки в журналах событий?

Да, но индексированная строка представлена хешем Keccak-256, а не исходной читаемой строкой.

Что происходит с журналами событий при откате транзакции?

Журналы, созданные в ходе отмененного исполнения, удаляются из итогового результата транзакции.

Расходуют ли журналы событий газ?

Да. Создание журнала расходует газ; его стоимость частично зависит от количества тем и размера данных.

Доказывает ли журнал события легитимность токена?

Нет. Любой контракт может создать знакомое событие, поэтому пользователям необходимо проверять создавший его контракт и фактическое состояние.

Как разработчики могут получать журналы событий?

Разработчики могут получать журналы с помощью eth_getLogs, запросов квитанций, фильтров, подписок, обозревателей блокчейна или сервисов индексации.

Может ли реорганизация блокчейна удалить журнал события?

Да. Журнал из замененного блока удаляется из канонической истории цепочки.

Одинаковы ли журналы событий во всех сетях EVM?

Их базовая структура обычно похожа, однако идентификаторы сетей, контракты, история блоков, финальность и поведение RPC могут различаться.

Журналы событий дешевле хранилища контракта?

Для офчейн-исторической информации журналы часто обходятся дешевле, но они не могут заменить хранилище, которое должно считывать последующее исполнение смарт-контракта.

Зачем кошельки используют журналы событий?

Кошельки используют журналы, чтобы распознавать переводы токенов, разрешения, обмены и другие действия смарт-контрактов, которые не видны только по основным полям транзакции.

Заключение

Журналы событий — это структурированные записи, связывающие исполнение смарт-контрактов с кошельками, децентрализованными приложениями, обозревателями блокчейна, аналитическими системами и другими офчейн-сервисами.

Они создаются с помощью инструкций журналирования EVM и сохраняются в квитанциях о транзакциях после успешного исполнения.

Журнал содержит адрес создавшего его контракта, доступные для поиска темы и закодированные по ABI данные события.

Topic 0 обычно определяет сигнатуру события, а индексируемые параметры предоставляют дополнительные возможности фильтрации.

Неиндексируемые параметры сохраняются в поле данных; для их декодирования необходим правильный ABI.

Журналы событий отличаются от хранилища контракта: смарт-контракты не могут напрямую считывать исторические журналы.

Они также отличаются от возвращаемых функциями данных, поскольку журналы предназначены для последующей исторической обработки вне блокчейна.

Приложения могут получать журналы через фильтры JSON-RPC, подписки, квитанции о транзакциях, обозреватели блокчейна и специализированные индексаторы.

Надежные системы должны учитывать повторную обработку, ограничения RPC, реорганизации цепочки, обновления контрактов и различные уровни подтверждения.

Пользователям следует помнить, что знакомое название события не доказывает надежность создавшего его контракта или легитимность токена.

Разработчикам следует создавать события с понятными названиями, полезными индексируемыми параметрами, достаточным контекстом и стабильными схемами.

Понимание журналов событий помогает пользователям криптовалют и разработчикам точнее интерпретировать переводы токенов, активность DeFi, изменения смарт-контрактов, квитанции о транзакциях и данные ончейн-приложений.