Add reorg and ledger-gap handling to the Horizon indexer (lib/indexer.ts)

[greatest0fallt1me]

Description

lib/indexer.ts advances its cursor purely forward and only deduplicates by network:id:type; it has no detection for ledger gaps or chain reorganizations, so a reorg silently leaves processed events that no longer exist on-chain. Add reorg/gap handling so indexed stream events stay consistent with Horizon truth. This is a backend on-chain indexing feature.

Requirements and Context

• Detect gaps when event.ledger > cursor + 1 + overlapWindow and trigger a bounded backfill from the last safe ledger.
• Detect reorgs by tracking a short window of recent ledger hashes and rolling the cursor back when a hash mismatch is observed; re-emit affected events idempotently.
• Replace the console.error stall "alert" with structured logging via the project logger and a metric counter.
• Must be secure, tested, and documented
• Should be efficient and easy to review

Suggested Execution

1. Fork the repo and create a branch

   git checkout -b feature/indexer-reorg-handling

2. Implement changes
   • lib/indexer.ts — gap detection, reorg rollback, hash window
   • lib/indexer.test.ts — extend coverage
3. Test and commit
   • npm test -- lib/indexer.test.ts
   • Cover edge cases: ledger gap, reorg rollback + replay, duplicate suppression
   • Include test output and notes in the PR

Example commit message

feat: handle ledger gaps and reorgs in Horizon indexer

Acceptance Criteria

• Gaps trigger bounded backfill from a safe ledger
• Reorg rolls cursor back and re-emits affected events idempotently
• Stall detection uses structured logs + a counter, not console.error
• Coverage ≥ 90% for lib/indexer.ts

Guidelines

• Minimum 90% test coverage including reorg/gap simulations
• Clear documentation and inline comments
• Timeframe: 96 hours

[ComputerOracle]

@ComputerOracle has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Hello maintainer ill like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @ComputerOracle to this issue.

[drips-wave]

Congratulations, @ComputerOracle! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @ComputerOracle: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[drips-wave]

This issue has been completed by @ComputerOracle as part of the Stellar Wave Program's 5th Wave 🥳

😎 @ComputerOracle: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.