feat(indexer): BFT multi-node consensus protocol with state roots and gossip (#536)

[MarcusDavidG]

Summary

Closes #536

Implements a Byzantine-fault-tolerant multi-node indexer consensus protocol using optimistic replication with cryptographic state roots.

Changes

Phase 1 — ADR

• docs/ADR-003-indexer-consensus.md: evaluates Raft, PBFT/Tendermint, and optimistic replication; selects the state-root gossip approach, justified by Soroban events being deterministically totally ordered. Includes CAP trade-off analysis and failure mode coverage table.

Phase 2 — Cryptographic State Root

• migrations/006_indexer_state.sql: indexer_state(ledger_sequence, state_root) table
• src/stateRoot.ts: deterministic Merkle tree over sorted row hashes for posts/follows/profiles/pools; computeStateRoot, saveStateRoot, getStateRoot
• src/api/routes/stateRoot.ts: GET /api/state-root?ledger=N
• src/cli/verify-state.ts: re-derives root from DB and compares to --trusted-root or --peer; exits 1 on mismatch

Phase 3 — Gossip & Divergence Detection

• src/gossip.ts: HTTP gossip loop broadcasting (ledger, state_root) to INDEXER_PEERS; emits DIVERGENCE_DETECTED structured log; binary-search reconciliation; self-fences with SELF_FENCED alert when >= DIVERGENCE_THRESHOLD peers disagree
• src/api/index.ts: 503 SELF_FENCED middleware blocks all /api traffic when fenced
• src/index.ts: saves state root after each new ledger; starts gossip background loop

Tests

• src/__tests__/stateRoot.test.ts: determinism (same data → same root twice), different data → different root, merkleRoot edge cases
• src/__tests__/gossip.test.ts: divergence detection logs DIVERGENCE_DETECTED, self-fencing sets isFenced() and logs SELF_FENCED, fenced node returns 503

Test Results

All 66 tests pass (8 suites).

[devJaja]

Solid implementation @MarcusDavidG
fix the CI checks error then ready to merge

[MarcusDavidG]

cl checks error fixed @devJaja we're good to go

[devJaja]

Nice work @MarcusDavidG
The architecture and overall design are correct. The ADR reasoning is sound. The self-fencing mechanism, 503 middleware, and saveStateRoot idempotency are all good. But the reconciliation stub is the one thing that could mislead an operator into thinking their node recovered when it hasn't — that needs to be either implemented or explicitly surfaced as a known limitation with a tracking issue. The md5/sha256 mismatch also needs fixing before the state root can be considered trustworthy for its stated purpose.

Request changes on the reconciliation stub and md5 issue. All other notes are non-blocking.

[vercel]

@MarcusDavidG is attempting to deploy a commit to the Jaja's projects Team on Vercel.

A member of the Team first needs to authorize it.

[MarcusDavidG]

thanks @devJaja ...requested changes have been addressed, please review