ETH Transactions Storage 2.5.0: история адресов под вашим контролем

Клиенты исполнения Ethereum могут сообщить вам текущую вершину цепи, данные блока, квитанцию или лог, но они не способны ответить на вопрос, который задает интерфейс любого кошелька при открытии: какие транзакции связаны с этим адресом, начиная с самых новых? Публичные индексаторы дают ответ, но они также видят каждый адрес, который ищут ваши пользователи, ограничивают скорость запросов при росте трафика и могут изменить ценовую политику или вовсе исчезнуть. Если история транзакций является частью вашего продукта, эта зависимость становится критическим звеном.

ETH Transactions Storage — это самохостируемый индексатор, который считывает блоки из вашего узла Ethereum, записывает нативные переводы ETH и вызовы переводов ERC-20 в вашу базу данных PostgreSQL и предоставляет историю адресов через REST API с правами только на чтение. Здесь нет телеметрии, сторонних учетных записей и только два исходящих соединения: с узлом и с настроенной вами базой данных. Архитектура проста: узел Ethereum → ethsync.py → PostgreSQL → PostgREST → ваше приложение. Она работает с Geth, Nethermind, Besu и Erigon по протоколам HTTP, WebSocket или IPC, а также с сетями, совместимыми с EVM, которые предоставляют аналогичный интерфейс JSON-RPC.

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

Надежная синхронизация и фильтрация адресов

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

История всей цепи — это правильный выбор по умолчанию для публичного API кошелька, но не для монитора казначейства или инструмента поддержки, где набор адресов известен заранее. Версия 2.5.0 добавляет опциональный фильтр адресов. При его загрузке индексатор сохраняет перевод только в том случае, если отправитель, получатель нативного актива или получатель токена соответствуют списку. Список обновляется во время работы процесса. Валидация строгая и работает по принципу «закрыто при сбое»: если список не удается прочитать, индексация не продолжается с пустым фильтром. Обратите внимание, что включение фильтра или добавление адреса не приводит к заполнению предыдущих блоков, поэтому планируйте необходимую историю до начала работы.

Оптимизированная индексация и безопасность

Рекомендуемый набор индексов базы данных теперь состоит из пяти B-деревьев, сформированных на основе реального трафика запросов, а не на индексации каждого потенциально полезного столбца. На наборе данных из примерно 490 миллионов строк этот уменьшенный набор экономит около 90–110 ГБ. Использование citext для полей адресов позволяет выполнять сравнение без учета регистра, не оборачивая каждый запрос в LOWER().

Пользователь индексатора имеет права на запись, но публичный API — нет. В этом релизе задокументирована и поставляется роль web_anon с доступом только SELECT к ethtxs, aval и max_block. Для PostgREST установлено ограничение в 10 000 строк на ответ. Руководство по безопасности охватывает правила обратного прокси для публичных развертываний, включая списки разрешенных методов, обязательные фильтры адресов для /ethtxs и защиту от ресурсоемких агрегатов count и неограниченных смещений. Учетные данные загружаются из .env, поддерживаются URI подключения PostgreSQL, а диагностические данные скрывают пароли.

Контейнер и контракт API

Опубликованный образ — ghcr.io/adamant-im/eth-transactions-storage:2.5.0, собранный для архитектур linux/amd64 и linux/arm64. Теги версий неизменяемы; используйте 2.5.0 в продакшене. Docker Compose по умолчанию запускает этот образ вместе с PostgreSQL, PostgREST, опциональным локальным Geth и индексатором. Сайт документации по адресу eth-indexer.docs.adamant.im содержит информацию об архитектуре, быстром старте, настройке и безопасности.

Столь масштабный релиз полезен только в том случае, если существующие клиенты продолжают работать. Так и есть. Эндпоинты /ethtxs, /max_block и /aval остались без изменений.

Нативные переводы ETH, один запрос:

GET /ethtxs?and=(contract_to.eq.,or(txfrom.eq.{address},txto.eq.{address}))&order=time.desc&limit=25

Переводы ERC-20 для контракта токена:

GET /ethtxs?and=(txto.eq.{contract_address},or(txfrom.eq.{address},contract_to.eq.000000000000000000000000{address_without_0x}))&order=time.desc&limit=25

Здоровье системы:

GET /max_block
GET /aval

Имена столбцов, кодировки и адреса без учета регистра остались прежними. 24 ведущих нуля в contract_to — это дополнение ABI, а не особенность, требующая исправления.

Область применения и ограничения

Индексатор сохраняет нативные переводы ETH с ненулевым значением и переводы ERC-20, отправленные как прямой вызов верхнего уровня transfer(address,uint256). Он не сохраняет внутренние переводы ETH, transferFrom, потоки мультиподписей или роутеров, другие стандарты токенов или логи событий. Индексатор не восстанавливает автоматически глубокую реорганизацию цепи задним числом; CONFIRMATIONS_BLOCK удерживает его позади вершины, что означает, что глубокая реорганизация требует запланированной переиндексации затронутого диапазона. Если вашему приложению необходимо отражать каждое возможное движение токенов, вам нужен индексатор на основе логов. Если же нужны переводы, инициированные пользователем — та история, которую реально показывает кошелек, — то этот инструмент создан именно для этого и остается недорогим в эксплуатации.

Существующим операторам следует ознакомиться с руководством по обновлению перед развертыванием. Сначала примените аддитивную схему, сохраните значения вашей производственной среды и не считайте обновление тега образа в Compose обновлением PostgreSQL. ETH Transactions Storage — это инфраструктура с открытым исходным кодом, поддерживаемая сообществом разработчиков ADAMANT и cryptofoundry.