docs: indexer outage and gap recovery (fixes #580)#583
Merged
Chucks1093 merged 1 commit intoJul 19, 2026
Merged
Conversation
Documents indexer behavior during RPC outages, ledger gap detection, manual replay process, and consequences of unreplayed gaps. Closes accesslayerorg#580
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds comprehensive documentation for how the indexer handles Stellar RPC outages, ledger gaps, and recovery procedures.
Changes
New file:
docs/indexer/RECOVERY.md— covers all four acceptance criteria:RPC outage behaviour — documents that polling pauses when the RPC node is unreachable, no events are missed (with typical ~48h RPC retention), the heartbeat degrades to HTTP 503 after the stale threshold, and cursor staleness warnings fire at the configured interval.
Ledger gap detection — explains
detectLedgerGap()inledger-gap-detection.service.ts, which compares the last processed ledger against the Stellar network head and emits a structured warning when the gap exceeds 10 ledgers (~50s). Notes the current// TODOfor wiring a real RPC call in production.Manual replay process — step-by-step for
POST /api/v1/admin/indexer/replay:startLedger,endLedger,dryRun)Consequences of an unreplayed gap — table detailing permanent inaccuracies in price snapshots, ownership balances, activity feed, and webhook delivery if a gap is not replayed.
Modified:
docs/indexer/ARCHITECTURE.md— added cross-reference to the new RECOVERY.md in the "Reliability layers" section.Closes #580