[Backend] — Soroban on-chain event reconciliation & gap-backfill job

[Olowodarey]

Background

SorobanListener (src/soroban/soroban.listener.ts) streams contract events
and the indexer module persists them. If the process is down, the RPC drops a
connection, or an event is missed, the DB silently diverges from chain state and
nothing detects or repairs it.

Goal

Add a durable per-contract sync checkpoint plus a periodic reconciliation job
that detects gaps between the last indexed ledger and chain head and backfills
missing events, making indexing self-healing.

Tasks

1. Entity src/indexer/entities/chain-sync-checkpoint.entity.ts:
2. Update the listener/indexer ingest path to advance the checkpoint
3. ReconciliationService with a @Cron job (interval from
4. Health surface: extend the existing indexer health controller
5. Env RECONCILE_INTERVAL_MS, RECONCILE_WINDOW, RECONCILE_ENABLED in

Acceptance Criteria

• Killing the indexer, advancing the chain, and restarting results in the gap
• Re-running reconciliation over already-indexed ledgers inserts zero
• Checkpoint never advances past events that failed to persist.
• Health endpoint reports a non-negative lag.

Files

src/indexer/entities/chain-sync-checkpoint.entity.ts,
src/indexer/reconciliation.service.ts (new),
src/indexer/indexer.service.ts, src/soroban/soroban.listener.ts,
src/indexer/indexer-health.controller.ts,

[Oluwasuyi-Timilehin]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. Thank you!

[bukkybyte]

With my experience with Soroban as a full stack developer i should be able to submit a valid PR within 2 days. Allow mw jump on this.

[jaynomyaro]

Hi! I’m a full-stack developer with a strong blockchain background. I’d love to handle this issue and can deliver a clean, reliable solution. Kindly assign it to me.

[Menjay7]

Hi! I’m a full-stack developer with a strong blockchain background. I’d love to handle this issue and can deliver a clean, reliable solution. Kindly assign it to me.

[ZuLu0890]

I would love to work on this issue

[Shadow-MMN]

Hey, I have read through the issue. The goal is to make Soroban event indexing self-healing by introducing durable synchronization checkpoints and an automated reconciliation process that can detect and backfill missed on-chain events.

I will implement a per-contract chain sync checkpoint, update the listener/indexing flow to advance checkpoints only after successful persistence, and add a reconciliation service with a scheduled cron job that compares indexed state against chain progress and backfills any missing ledger ranges. I will also extend the health endpoint to expose indexing lag and add configuration support for reconciliation intervals, windows, and enable/disable controls.

For validation, I will test indexer downtime and restart scenarios, verify that missed events are correctly recovered, ensure reconciliation is idempotent when reprocessing already-indexed ledgers, and confirm checkpoints never advance past failed persistence operations. I will also validate that health reporting accurately reflects synchronization status and lag.

ETA within 2 days.

[strngecloud]

Hey, I’m a full-stack & smart contract dev in the Stellar ecosystem.

I’ve been building games and DeFi dapps with Soroban, and I love tackling technical challenges with fast-moving teams. Super excited to jump in and help with this one!