evstack / evstack/atlas

feat: reorg handling

Open
#56 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
2
Forks
1
PR merge metrics
No merged PRs in 30d

Description

## Summary

Atlas currently has no chain reorganization handling. If the chain reorgs, previously indexed blocks may become orphaned and the explorer will serve inconsistent data (e.g., transactions that no longer exist on the canonical chain).

## Motivation

Any EVM chain can experience reorgs. Without handling them, Atlas may:
- Show transactions/blocks that were reverted
- Miss the canonical replacement blocks
- Have inconsistent state in derived tables (ERC-20 balances, NFT ownership)

This is a correctness issue, not just a performance one.

## Design

### Detection
1. On each new batch, validate the parent hash of the first block against the stored hash of the previous block
2. If mismatch detected, walk back up to N blocks (e.g., 128) to find the fork point

### Rollback
1. Delete orphaned blocks and all associated data (transactions, logs, transfers, etc.) from the fork point onward
2. For partitioned tables, deletion needs to target the correct partitions
3. Update derived tables (ERC-20 balances, NFT ownership) — either recompute or reverse the orphaned changes
4. Update `indexer_state` watermark to the fork point
5. Resume indexing from the fork point

### Considerations
- Derived tables (erc20_balances, nft_tokens) make rollback more complex than raw-data-only indexers — may need to replay transfers from the fork point
- The `HeadTracker` in-memory buffer needs to be pruned of orphaned blocks
- SSE clients should be notified of the reorg (new event type or resync signal)
- Configurable max reorg depth (default 128, matching tidx)
- Optional `trust_rpc` flag to skip parent hash validation for trusted RPCs

## References

- tidx implementation: `sync/engine.rs` — `find_fork_point` walks back, deletes orphans from all sinks

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.