DeBridge USDC Transfer Pipeline

Pet‑project про наблюдение за on‑chain активностью. Pipeline собирает события Transfer токена USDC в адрес deBridge, складывает данные в ClickHouse и строит агрегаты с помощью SQL окон. Основа — Temporal workflow с heartbeats и ретраями; Grafana смотрит в ClickHouse и показывает аналитику.

Зачем

• Потренироваться в построении end‑to‑end пайплайна поверх Temporal и TypeScript.
• Посчитать фактическое потребление газа для конкретного адреса и поиграться с SQL окнами в ClickHouse.
• Получить готовую демонстрацию для блога/портфолио: Temporal UI + Grafana + экспорт в output.json.

Что внутри

• Temporal workflow, который сам решает, когда делать backfill и когда переходить в forward‑режим.
• Активити, которые дергают Ethereum RPC через viem, складывают данные напрямую в ClickHouse и периодически шлют heartbeats.
• ClickHouse схемы и SQL‑запросы в отдельных файлах, чтобы их можно было переиспользовать вне Temporal.
• Grafana dashboard, который сразу поднимается вместе с инфраструктурой.

Требования

• Docker + Docker Compose (рекомендуемый запуск)
• Node.js 18+, если хотите гонять Temporal worker/client локально
• RPC‑нод USDC поддерживающего Ethereum mainnet (Alchemy, Infura и т.д.)

Быстрый старт (Docker)

1. Скопируйте .env.example → .env и заполните RPC_URL.
2. Запустите инфраструктуру и Temporal worker/client:

   make quick-start

3. Проверяйте прогресс:

   make logs       # все сервисы
   make logs-worker
   make logs-client

4. Результаты:
   • ClickHouse HTTP: http://localhost:8123
   • Grafana: http://localhost:3000 (admin / admin)
   • Temporal UI: http://localhost:8233

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

Переменная	Назначение
RPC_URL	Ethereum RPC endpoint (обязателен)
TEMPORAL_ADDRESS	gRPC адрес Temporal (default temporal:7233)
TEMPORAL_NAMESPACE	Namespace Temporal (обычно default)
CLICKHOUSE_HOST	HTTP endpoint ClickHouse
CLICKHOUSE_USER / CLICKHOUSE_PASSWORD	Доступ к ClickHouse
USDC_CONTRACT_ADDRESS	Адрес контракта USDC
DBR_ADDRESS	Адрес получателя, за которым наблюдаем
BATCH_SIZE	Сколько блоков сканировать за партию
MAX_CONCURRENCY	Ограничение на параллельные RPC запросы
PIPELINE_MODE	Можно оставить forward — workflow сам переключает backfill/forward

Константа TARGET_EVENTS в src/workflows.ts задаёт целевое число событий (по умолчанию 5000). Workflow автоматически уходит в backfill, пока не наберёт этот объём, затем переключается на forward. Агрегаты для Grafana пишутся только после завершения расчётов (calculateAndStoreGasStatistics); до этого дашборд пустой — это нормально.

Ручной запуск (без Docker Compose)

npm install
npm run build
npm run worker  # в первом терминале
npm run start   # во втором терминале

ClickHouse, Temporal и Grafana при таком способе нужно поднять самостоятельно (например, docker-compose up clickhouse temporal temporal-ui grafana).

Что создаёт pipeline

• usdc_transfer_events — сырые события Transfer.
• gas_statistics — результат SQL‑агрегатов (сумма газа по дням, кумулятивная сумма, 7‑дневное среднее). Таблица появляется после завершения workflow; значения газа в Grafana отображаются в ETH, цена газа — в Gwei.
• output.json — экспорт агрегатов в JSON для задания.

Grafana dashboard лежит в grafana/provisioning и автоматически подключается к ClickHouse. Обновите временной диапазон, чтобы увидеть новые данные.