Skip to content

feat: implement blockchain indexing service (BE-003) - #340

Open
Tobi-8 wants to merge 1 commit into
DigiNodes:mainfrom
Tobi-8:feature/be-003-blockchain-indexer
Open

feat: implement blockchain indexing service (BE-003)#340
Tobi-8 wants to merge 1 commit into
DigiNodes:mainfrom
Tobi-8:feature/be-003-blockchain-indexer

Conversation

@Tobi-8

@Tobi-8 Tobi-8 commented Jul 28, 2026

Copy link
Copy Markdown

Summary

Implement the Blockchain Indexing Service (BE-003) — a production-ready TypeScript
service that synchronises TruthBounty protocol events from the blockchain into the
backend, with fault tolerance, reorg handling, and idempotent processing.

  • RPC Connectivity (ProviderManager): HTTP + optional WebSocket provider with
    automatic failover and reconnection strategies
  • Historical Block Sync: batch-processes past blocks (configurable batch size),
    resumable via checkpoint persistence
  • Live Event Listener: WebSocket block subscription with polling fallback,
    auto-recovery on connection failure
  • Event Processing Pipeline (EventPipeline): fetches logs, parses via ethers.js
    Interface, deduplicates by tx hash + log index, enriches with block metadata
  • Reorganisation Handling (detectReorg): verifies block hashes up to configurable
    depth (default 12 blocks), rolls back to fork point and replays
  • Idempotent Processing: tracks transactionHash:logIndex per event, skips
    duplicates on retry or replay
  • Indexing Checkpoints (CheckpointManager): persists blockNumber + blockHash
    after each sync batch, resumes from checkpoint on restart
  • Storage Abstraction (StorageAdapter): InMemoryStorage implementation included;
    designed for PostgreSQL swap via the interface
  • Event Definitions: full ABI fragments for TruthBountyWeighted (8 events),
    ReputationDecay (4 events), ReputationSnapshot (2 events)
  • CLI Entry Point (index.ts): loads config from env vars, starts/stop indexer,
    graceful shutdown on SIGINT

Architecture

config -> ProviderManager (RPC/WS)
         |
         v
      EventPipeline.fetchLogs()
         |
         v
      EventPipeline.processLogs() -> dedup -> deserialize -> enrich
         |
         v
      StorageAdapter.saveEvents() + CheckpointManager.saveCheckpoint()
         |
         v
      EventHandlers (logging, webhooks, etc.)
         ^
         |
      detectReorg() on each new block

Testing

  • 14 unit tests covering storage, checkpoint, pipeline, indexer, and events
  • Uses vitest with mocked providers, independent from Hardhat suite

Notes

  • BE-002 (PostgreSQL) not yet available; InMemoryStorage is the default adapter
  • Batch size: 1000 blocks, confirmations: 6, poll: 5s

Closes DigiNodes/truthbounty-api#270

@Tobi-8

Tobi-8 commented Jul 28, 2026

Copy link
Copy Markdown
Author

hey i can't seem to link this pr with the issue number

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

BE-003 — Implement Blockchain Indexing Service

1 participant