chain-atlas

A research guide to building blockchain indexers — correctly.

EVM · ZK-EVM · non-EVM. Node architectures, finality models, RPC surfaces, fork timelines, storage tradeoffs, and the gotchas that bite indexer authors.

Concepts · Chains · Template · Contributing

---

Not a runtime. There are no production indexers in this repo. It is a reference. Code blocks (Rust) illustrate patterns; they are not meant to compile as a single binary.

Layout

• docs/concepts/ — cross-chain ideas: finality models, reorgs, storage tradeoffs, trace APIs, proxy resolution. Cited from every chain doc.
• docs/chains/ — per-chain deep dives. Every chain follows the same template.
• docs/chains/_template/ — canonical structure. Read this first if contributing.

Chain status

Chain	Family	Status
Ethereum	EVM L1	complete
Optimism	EVM L2 (OP Stack rollup)	complete
Arbitrum	EVM L2 (Nitro rollup)	complete
Base	EVM L2 (OP Stack rollup)	complete (delta on optimism/)
BSC	EVM sidechain (PoSA)	complete
Polygon	EVM sidechain (PoS, checkpointed)	complete
zkSync Era	ZK rollup (custom VM)	complete
Scroll	ZK-EVM rollup	complete
Linea	ZK-EVM rollup	complete (delta on scroll/)
StarkNet	ZK rollup (Cairo VM)	complete
Solana	non-EVM	complete
Cosmos	non-EVM family (Tendermint/IBC)	stub
Aptos	non-EVM (Move)	stub
Sui	non-EVM (Move, object-centric)	stub

Legend — stub: placeholder, key facts only · in-progress: partial sections written · complete: all 10 template files populated, fork heights and behavioral claims sourced against canonical chain configs and primary specs.

How to use this repo

1. Read docs/concepts/ to internalize the vocabulary and the cross-chain machinery.
2. Pick a chain in docs/chains/. Start with its README.md and walk through the template.
3. Cross-reference fork events in forks-changelog.md against the chain's primary specifications listed in references.md.

Contributing

See CONTRIBUTING.md. New chains must follow the structure in docs/chains/_template/. Every behavioral claim about a chain should be backed by a primary source in references.md.

License

Dual-licensed. See LICENSE for full text.

• Prose, tables, diagrams — CC-BY-4.0. Reuse freely with attribution.
• Code samples (Rust blocks, etc.) — MIT. Copy into your indexer; just keep the notice.

Copyright © 2026 auralshin.

_{Built as a reference for engineers writing their first indexer for a given chain. Not a tutorial. Not a runtime.}