[FEAT] Distributed Reorg-Resilient Stellar Ledger Event Indexer & State Snapshot Engine

[jotel-dev]

telegram link : t.me/nullifiersystem

---

1. Summary & Core Promise

Linear ledger indexers in apps/api/src/lib/stellar-indexer.ts corrupt database balances during Stellar blockchain reorganizations (reorgs). This feature implements a Distributed Reorg-Resilient Event Indexer & Snapshot Engine. It maintains ledger header DAGs, detects parent hash mismatches, executes atomic DB undo-logs during reorgs (up to 10 ledgers), and provides multi-node RPC failover.

---

2. Background & Architectural Risks

• Reorg State Divergence: Blockchain reorgs cause database state to diverge from on-chain smart contract reality.
• Single Node Failover: RPC node latency or drops interrupt real-time indexer event streams.

---

3. Database Layer Specifications

Migration SQL (027_add_reorg_resilient_indexer.sql)

CREATE TABLE indexer_block_headers (
    ledger_sequence INT PRIMARY KEY,
    block_hash VARCHAR(64) NOT NULL,
    parent_hash VARCHAR(64) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE indexer_undo_logs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    ledger_sequence INT NOT NULL,
    table_name VARCHAR(64) NOT NULL,
    previous_row_data JSONB NOT NULL
);

---

4. Backend Route & Service Layer Specifications

Route: POST /api/v1/indexer/rollback

1. Rollbacks database state to a confirmed ledger checkpoint.
2. Re-indexes canonical branch events cleanly.

---

5. Background Processors / Workers

Reorg Indexer Worker (apps/api/src/lib/workers/reorgIndexerWorker.ts)

• Checks ledger parent hash DAG continuity and manages RPC node failover.

---

6. Frontend / UI Component Specifications

Component: mobile/frontend/src/pages/IndexerMonitorDashboard.tsx

• Shows real-time indexer block height, ledger DAG graph, reorg alert banners, and manual snapshot rollback controls.

---

7. Rigor & Test Plan

1. Reorg Simulation Test (indexer_reorg_simulation.test.ts): Simulates 5-ledger fork and asserts DB state rewinds cleanly.
2. RPC Failover Test (rpc-failover.ts).

---

8. Relevant Files Inventory (20 Files)

• apps/api/src/lib/indexer/reorg-handler.ts
• apps/api/src/lib/indexer/snapshot-engine.ts
• apps/api/src/lib/indexer/block-dag.ts
• apps/api/src/lib/indexer/rpc-failover.ts
• apps/api/src/lib/workers/reorgIndexerWorker.ts
• apps/api/src/db/migrations/027_add_reorg_resilient_indexer.sql
• apps/api/src/routes/indexer-admin.ts
• apps/api/src/lib/stellar-indexer.ts
• apps/api/src/lib/stellar-event-store.ts
• apps/relayer/src/soroban-watcher.ts
• apps/api/src/lib/stellar.ts
• apps/api/src/app.ts
• mobile/frontend/src/pages/IndexerMonitorDashboard.tsx
• mobile/frontend/src/components/ReorgAlertBanner.tsx
• mobile/frontend/src/components/LedgerDagViewer.tsx
• packages/shared/src/types/indexer.ts
• packages/shared/src/index.ts
• apps/api/src/lib/indexer/__tests__/reorg-handler.test.ts
• apps/api/src/routes/__tests__/indexer-admin.test.ts
• tests/e2e/indexer_reorg_simulation.test.ts

---

9. Acceptance Criteria

• Parent hash mismatches trigger automatic 10-ledger DB undo-log rollbacks.
• Multi-node RPC failover switches endpoints in <500ms on failure.

---

10. Contributor Notes

• ⚠️ Confirmation Rule: NEVER mark high-value trades as finalized until 6 ledger confirmations pass.

[angelraph]

I’d like to take #409.

This is the kind of infrastructure work I’m interested in because the difficult part isn’t adding another indexer worker. It’s preserving canonical database state when the chain changes underneath it.

My approach would be to first trace the existing Stellar indexing flow end-to-end, including ledger/event persistence and transaction boundaries, before changing the state model. From there I’d implement the header DAG and parent-hash continuity checks, then build the undo-log/snapshot layer around atomic database transactions so a detected fork can rewind deterministically to a confirmed checkpoint before canonical events are replayed.

I’d treat RPC failover separately from reorg recovery, with explicit failure and recovery tests rather than coupling the two paths. I’d also add the 5-ledger fork simulation and E2E coverage early, since rollback correctness is the part that needs the strongest proof.

For the frontend, I’d keep the monitor focused on operational visibility: current indexed height, canonical DAG state, reorg detection, RPC health, and guarded manual rollback controls.

I’m comfortable using Claude Code to accelerate repository analysis, implementation, test generation, and iteration, while keeping the state-transition design and correctness review deliberate. I’d want the final implementation to prove the important invariants through tests, especially that a reorg cannot leave balances or indexed events representing a non-canonical branch.

I can take this from repository investigation through implementation, tests, and integration rather than treating the individual files as isolated tasks.

[rabsqueen]

Hi, I can work on this task.

[Benedict315]

hello please assign

[grantfox-oss]

🦊 GrantFox — @Benedict315 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #409)
2. Your PR will be reviewed by the Nullifier-Systems maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@Benedict315's PR #418 was approved and merged by @jotel-dev.

🏆 @Benedict315: You earned 40 FoxPoints for this contribution! Your current tier: Builder (1,265 total points). Track your full progress on GrantFox.

👏 Great work, @Benedict315! Keep contributing to Nullifier-Systems.