feat: add indexer catch-up backfill tool with ledger range checkpoints

[abdulquadri123]

Overview

This PR adds a ledger-range backfill mode for the indexer catch-up path. It lets operators replay a bounded ledger range after prolonged downtime, persist progressive checkpoints, and resume safely without duplicating or skipping ledgers. RPC-compatible rate limits keep replay within node constraints.

Related Issue

Changes

🔁 Backfill Mode & Checkpointing

• [ADD] replay-events.ts

  • New CLI backfill mode with required --start-ledger and --end-ledger range validation.
  • Progressive checkpointing after each batch so interrupted runs resume from the last committed ledger.
  • Idempotent ledger upserts via conflict-safe writes and existing-event deduplication.

• [MODIFY] indexer.ts

  • Extracted shared RPC-safe fetch helpers used by both live ingestion and backfill replay.
  • Added configurable rate limiting (--rate-limit-ms, BACKFILL_RATE_LIMIT_MS) to avoid RPC exhaustion.

• [MODIFY] query-events.ts

  • Backfill queries are bounded by start_ledger / end_ledger and read from checkpoint markers.
  • No full-table scans; duplicate events are filtered before upsert.

• [ADD] config.ts

  • New backfill configuration: checkpoint path, ledger range, batch size, rate limit, retry count.

• [MODIFY] .env.example

  • Documented all BACKFILL_* variables with sane defaults.

Verification Results

npm test -- replay-events
✅ 8/8 passed

Backfill small ledger range twice:
$ npm run backfill -- --start-ledger 100 --end-ledger 110
✅ rows before: 0, after first run: 11

$ npm run backfill -- --start-ledger 100 --end-ledger 110
✅ rows before: 11, after second run: 11
✅ row counts stable — no duplicates, no skipped ledgers

Acceptance Criteria	Status
Checkpoint progressive	✅ Checkpoint written after each batch; interrupted runs resume from last checkpoint
Idempotent upserts	✅ Re-running the same range twice leaves row counts unchanged
Rate limit configurable	✅ --rate-limit-ms / BACKFILL_RATE_LIMIT_MS supported

Closes #880

[drips-wave]

@abdulquadri123 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits