Implement a reorg-aware Stellar event ingestion pipeline that detects ledger rollbacks and reverses affected database state

[Chucks1093]

Summary

The current event ingestion pipeline assumes Stellar ledgers are final on first observation. In practice, a network partition or validator disagreement can cause a short ledger rollback (reorg), invalidating previously ingested events. The pipeline must detect when the next ledger's previousLedgerHash does not match the stored hash of the last ingested ledger, trigger a rollback of all affected database records, and re-ingest from the fork point.

Scope

• Store ledgerSequence and ledgerHash for every ingested event in a LedgerCheckpoint table
• On each new ledger, verify incoming.previousLedgerHash === checkpoint[incoming.sequence - 1].hash
• On mismatch: identify the fork point by walking backwards through LedgerCheckpoint until hashes agree, mark all events from the fork point forward as REORGED, reverse their database side effects (key balance changes, holder count changes, transaction history entries) inside a single database transaction, then re-ingest from the fork point
• Emit a warn-level structured log with forkPoint, reorgedLedgerCount, and affectedEventCount on every reorg
• Gate all buy/sell API responses on confirmed ledger depth ≥ 2 (no response until the ledger is 2 deep) to reduce reorg exposure
• Add integration tests: clean ingestion advances the checkpoint, a simulated reorg triggers rollback and re-ingestion, rolled-back balance changes are correctly reversed, re-ingested events produce the same final state as if the reorg never happened

Acceptance Criteria

• LedgerCheckpoint table stores hash and sequence for every ingested ledger
• Hash mismatch triggers rollback of all events from the fork point forward
• Rolled-back database side effects fully reversed in a single atomic transaction
• Warn log emitted with fork point and affected counts on every reorg
• Buy/sell responses gated on ledger depth ≥ 2
• Re-ingestion after rollback produces identical final state

ETA: 24 hours

---

Coordinate on Telegram

[martinshub-tech]

I'd like to take this issue. I've analyzed the root cause and am confident I can deliver a reliable fix with proper testing