Сервис мониторинга блокчейн cобытий BNB Chain (BEP20)

Проект: Сервис мониторинга блокчейна BNB Chain (BEP20)
Стек: Node.js, Web3/ethers, Aerospike, Docker

1. Цель проекта

Реализовать фоновый сервис (демон), который:

• Получает данные по WebSocket от узла BNB Chain (с приоритетом нашей приватной ноды)

• Мониторит входящие транзакции для указанных адресов:

  • Native BNB

  • Опционально — массив BEP20 токенов для каждого адреса свой, только по указанным контрактам (если список задан, если не задан мониторить всё)

• Отправляет вебхуки при обнаружении транзакций

• Имеет управляемый API для добавления/удаления адресов

• Хранит состояние, адреса и мониторинговые данные в Aerospike

• Работает устойчиво (failover), восстанавливается корректно

• Запускается через docker-compose

2. Основной функционал

2.1 Мониторинг транзакций

• WebSocket для онлайна

• HTTP RPC для догоняния пропущенных блоков

• Фильтрация транзакций:

  • по адресам

  • по указанным контрактам (опционально)

• Вебхуки на события

3. API

3.1 Общие требования

• POST / JSON (application/json)

• Авторизация через API ключ (API_KEY в .env)

3.2 Endpoints

3.3 /add — запрос

{
  "address": "0x123...",
  "webhook": "https://my-webhook.site",
  "contracts": [
    "0xToken1...",
    "0xToken2..."
  ]
}

Логика:

• Если contracts не указан или передан пустым массивом → мониторятся все транзакции по адресу:

  • BNB

  • Все BEP20 токены

• Если contracts указан → мониторятся только события Transfer по этим контрактам + native BNB.

3.4 /remove — запрос

{
  "address": "0x123..."
}

4. Хранение данных (Aerospike)

4.1 Watchlist (мониторинг адресов)

• address

• webhook

• contracts — массив контрактов (опционально)

• created_at

4.2 Синхронизация блоков

• chainId

• last_processed_block

• updated_at

• (опционально) last_received_block, processing_flag

4.3 Таблица транзакций (для идемпотентности)

• tx_hash

• log_index или (tx_hash, address, direction)

• timestamp

• тип события (BNB / token)

• адреса участников

• контракт (если BEP20)

5. Логика обработки

5.1 Онлайн-режим (WebSocket)

• Приходит блок N

• Извлекаем транзакции и логи

• Для каждого лог/tx:

  • фильтрация по address

  • если есть contracts — фильтруем по ним

• Записываем в БД

• Отправляем webhook

• После полного завершения блока:

  • last_processed_block = N

5.2 Рестарт/обрыв WebSocket

• Считываем last_processed_block

• Получаем актуальный blockNumber

• Догоняем блоки last_processed_block+1 ... current

• Обрабатываем так же, как онлайн

• Снова подключаемся по WebSocket

5.3 Идемпотентность

• Уникальные ключи (tx_hash, log_index)
  или (tx_hash, address, contract)

• Повторная обработка блоков не вызывает дублей

6. Конфигурация / .env

# Основная приватная нода
WS_PRIMARY=wss://private-node-1

# Резервные публичные ноды
WS_SECONDARIES=wss://public-node-1,wss://public-node-2

# HTTP RPC для догоняния блоков
RPC_HTTP=https://private-http

API_KEY=...

CHAIN_ID=56

7. Отказоустойчивость

7.1 Алгоритм с приоритетом нашей ноды

1. Используем WS_PRIMARY

2. Если отвалилась — переходим на secondary

3. Проверяем доступность primary

4. Как только primary восстановилась — возвращаемся

5. Курсоры состояния не теряются

7.2 Без round-robin

• Не балансируем, только fallback → return

7.3 Корректность данных

• Пропусков нет, так как курсор last_processed_block хранится в БД

8. Docker

• Запуск через docker-compose

• Контейнеры:

  • Node.js (демон + API)

  • Aerospike

9. Требования к коду

• Node.js (предпочтительно TypeScript)

• Модульная архитектура

• Логирование

• Обработка ошибок

• Конфигурация исключительно через .env

10. Результаты проекта

• Репозиторий с кодом

• Документация по API

• Документация по запуску

• docker-compose.yml

Если нужно — могу:

• Нарисовать диаграмму обработки токенов с условием contracts

• Добавить в API метод /list

• Сделать схему индексов для Aerospike