Хранилище ETH-транзакций: опциональный фильтр адресов, облегченные индексы и безопасный публичный API

ETH-transactions-storage — это self-hosted индексатор Ethereum, который подключается к узлу Ethereum, сохраняет данные о нативных ETH и ERC-20 транзакциях transfer(address,uint256) в базу данных PostgreSQL и предоставляет к ним доступ через REST API (только для чтения) с помощью PostgREST. Поскольку узлы Ethereum не могут напрямую отвечать на запросы истории по конкретному адресу, кошельки, dapps, казначейства и операторы обычно зависят от сторонних обозревателей блоков. Этот проект — альтернатива, которую вы запускаете самостоятельно: никаких API-ключей от сторонних поставщиков, никакого отслеживания и телеметрии.

В ветке dev теперь доступен опциональный фильтр адресов, добавленный в PR #29. Индексация всей цепочки остается режимом по умолчанию, который используют кошельки ADAMANT. Режим фильтрации предназначен для операторов, которым нужен только определенный набор адресов и которые не хотят хранить всю цепочку целиком.

Зачем нужен фильтр

Публичный индексатор Ethereum — это база данных большого объема. Для данных основной сети за один год (около 490 млн строк) старый набор индексов занимал сотни гигабайт. Многим операторам не нужен такой масштаб: кошельку или бэкенду кастодиального сервиса, обслуживающему только своих пользователей, казначейству проекта, отслеживающему несколько рабочих адресов, или self-hosted обозревателю для конкретного приложения — всем им выгоднее использовать выборочное хранение. Фильтр сохраняет существующий API-контракт: клиенты по-прежнему обращаются к /ethtxs, /max_block и /aval. Операторы меняют лишь то, что хранится, а не способ чтения данных.

Работа фильтра адресов

Фильтр по умолчанию отключен (ADDRESS_FILTER_ENABLED=false). Его включение требует указания ADDRESS_FILTER_FILE (по умолчанию filter/addresses.txt, файл игнорируется Git и не копируется в Docker-образ). Список принимает по одному адресу на строку (40 шестнадцатеричных символов с префиксом 0x), пустые строки и комментарии # игнорируются, регистр символов не учитывается. Нативные переводы сопоставляются с txfrom или txto. Поддерживаемые вызовы ERC-20 transfer(address,uint256) сопоставляются с отправителем (txfrom), контрактом токена (txto) и получателем, закодированным в ABI (contract_to).

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

Существующие ограничения индексатора остаются прежними: фильтр не захватывает внутренние ETH-переводы, потоки ERC-20, не являющиеся прямым вызовом transfer(address,uint256) (например, transferFrom, роутеры, мультисиги или пакетные вызовы), а также не выполняет автоматическое заполнение истории при добавлении адреса. Включение фильтра не удаляет уже сохраненные строки. Пересборка — это ручная операция: остановите индексатор, очистите таблицы ethtxs и sync_state в одной транзакции (или откатите обе к блоку N), установите START_BLOCK и перезапустите процесс. Очистка только ethtxs не приведет к повторному сканированию, так как контрольная точка по-прежнему будет указывать на завершение цепочки.

Надежный прогресс синхронизации

Ранее отфильтрованные и пустые блоки выглядели как «отсутствие активности», из-за чего индексатор мог сканировать их повторно. Теперь в ветке dev используется контрольная точка public.sync_state (одна строка), обновляемая в той же транзакции PostgreSQL, что и вставки для соответствующего блока. Эндпоинт /max_block по-прежнему возвращает { max, version }, где max — это GREATEST(MAX(ethtxs.block), sync_state.last_block). При запуске происходит откат к последнему обработанному блоку, теперь атомарно вместе с контрольной точкой. Скрипт create_tables.sql идемпотентен: он создает sync_state, инициализирует его из существующего максимального блока транзакций и предоставляет права DML для api_user и app_user, если эти роли существуют. Роль web_anon не может напрямую читать или изменять sync_state.

Индексы, защита API и эксплуатация

Фильтр адресов базируется на других изменениях из PR #28, которые еще не вошли в релиз GitHub (последний тег остается v2.4.1). Минимальный набор из пяти индексов покрывает запросы ADAMANT Web и iOS, экономя около 90–110 ГБ на годовом наборе данных по сравнению с устаревшим набором из восьми индексов. Анонимная роль PostgREST web_anon теперь имеет права только на SELECT для ethtxs, aval и max_block, а параметр db-max-rows = 10000 ограничивает размер сериализованного результата, чтобы неконтролируемый GET /ethtxs не приводил к исчерпанию памяти (OOM) API.

Публичные развертывания теперь защищены с помощью nginx: разрешен список методов (GET/HEAD/OPTIONS), обязательно наличие txfrom или txto в запросах к /ethtxs, а также отклоняются запросы с Prefer: count=exact и огромными смещениями. Рабочий процесс с .env теперь документирован с помощью шаблона, секреты не попадают в Git, а Compose больше не использует жестко закодированный пароль базы данных. Диагностика БД стала безопаснее: URI подключений работают корректно, а пароли скрываются из логов. Файл AGENTS.md определяет контракт для контрибьюторов и операторов репозитория.

Хосты, использующие systemd, должны сохранить текущий unit во время обновления кода и схемы. Примените create_tables.sql с параметром ON_ERROR_STOP перед запуском нового индексатора и не копируйте ethsync.service из репозитория, пока не будет создано рабочее окружение .env с соответствующими значениями.

Для кого это предназначено

ADAMANT использует этот индексатор, чтобы adamant-im и adamant-iOS могли отображать историю Ethereum и ERC-20 без централизованного обозревателя. Тот же бинарный файл является универсальным сервисом с открытым исходным кодом для кошельков, платежных процессоров, эмитентов токенов и всех, кому нужна индексируемая по адресам история Ethereum под собственным контролем PostgreSQL и политикой доступа. Разверните его самостоятельно, используйте режим полной индексации для публичного API или включите фильтр, чтобы хранить только те адреса, которые вы действительно обслуживаете.