Welcome

1
Block arrives (network / Engine API)
2
    │
3
    ▼
4
InsertChain()
5
    ├─ Contiguity check (sequential block numbers? parent hashes match?)
6
    ├─ Acquire write lock (chainmu)
7
    │
8
    │  Three things start concurrently:
9
    │  ├─ Background: ECDSA signature recovery (most CPU-intensive)
10
    │  ├─ Background: engine.VerifyHeaders() (consensus rule checks)
11
    │  └─ Foreground: process blocks one by one ↓
12
    │
13
    ▼
14
ProcessBlock() (for each block)
15
    ├─ ① Create StateDB from parent's state root
16
    ├─ ② processor.Process() — execute all transactions (Chapter 6)
17
    ├─ ③ validator.ValidateState() — verify gas, receipt root, state root
18
    └─ ④ Write to disk ↓
19
    │
20
    ▼
21
writeBlockAndSetHead()
22
    ├─ writeBlockWithState() — persist block + state
23
    ├─ reorg() (if needed) — switch canonical chain
24
    ├─ writeHeadBlock() — update head pointers
25
    └─ Emit events (ChainEvent, ChainHeadEvent)

1
Layer 1: Block data (atomic batch)
2
  ├─ rawdb.WriteBlock()      — header + body
3
  ├─ rawdb.WriteReceipts()   — receipts
4
  └─ rawdb.WritePreimages()  — preimage mappings
5
  → batch.Write() (all succeed or all fail)
6

7
Layer 2: State commit
8
  └─ statedb.Commit()        — dirty state → trie database
9

10
Layer 3: Trie GC
11
  ├─ Archive node: flush to disk every block
12
  └─ Full node: keep last 128 blocks' tries in memory, older ones eligible for GC

1
batch := bc.db.NewBatch()
2
rawdb.WriteHeadHeaderHash(batch, block.Hash())      // head header
3
rawdb.WriteHeadFastBlockHash(batch, block.Hash())    // snap sync head
4
rawdb.WriteCanonicalHash(batch, block.Hash(), num)   // block number → hash mapping
5
rawdb.WriteTxLookupEntriesByBlock(batch, block)      // tx hash → block number
6
rawdb.WriteHeadBlockHash(batch, block.Hash())        // head block
7
batch.Write()
8

9
// Then update in-memory atomic pointers
10
bc.currentBlock.Store(block.Header())

1
NewPayload        → InsertBlockWithoutSetHead() — validate + store, don't move head
2
ForkchoiceUpdated → SetCanonical()              — move head to specified block

1
Current canonical chain:  1 → 2 → 3 → A4 → A5 (current head)
2

3
New block B5 arrives, parent is B4, B4's parent is 3:
4

5
              ┌→ A4 → A5 (old head)
6
1 → 2 → 3 ──┤
7
              └→ B4 → B5 (new head)

1
Step 1: Bring both chains to the same height
2
  Old chain: A5 (height 5)
3
  New chain: B5 (height 5)
4
  → Already equal, skip
5

6
Step 2: Walk both back simultaneously until hashes match
7
  A5 vs B5 → different, continue
8
  A4 vs B4 → different, continue
9
  3  vs 3  → match! Common ancestor = block 3
10

11
Result:
12
  Old chain only: [A4, A5]
13
  New chain only: [B4, B5]

1
1. Collect logs from old chain blocks → send RemovedLogsEvent
2
   (notify subscribers these logs are no longer valid)
3

4
2. Collect transaction hashes from old chain blocks → deletion list
5

6
3. Iterate new chain blocks in forward order, for each:
7
   ├─ writeHeadBlock() — update canonical hash mapping and tx lookup index
8
   └─ Collect reborn logs → send to logsFeed
9

10
4. Clean up tx index:
11
   Deleted txs = old chain txs - new chain txs
12
   (some txs may exist in both chains — don't accidentally delete those)
13

14
5. Clear tx lookup LRU cache (may hold stale data)

1
Old chain: block A4 contains tx1, tx2; block A5 contains tx3
2
New chain: block B4 contains tx1, tx4; block B5 contains tx5
3

4
Old chain txs: {tx1, tx2, tx3}
5
New chain txs: {tx1, tx4, tx5}
6

7
Need to delete index for: {tx2, tx3} (old-chain-only)
8
tx1 exists in both chains → keep
9
tx4, tx5 are new → create index

1
TxPool Reset:
2
  1. Find common ancestor (similar logic to reorg)
3
  2. Transactions from old-chain-only blocks → re-inject into pool
4
  3. promoteExecutables() → promote executable transactions
5
  4. demoteUnexecutables() → demote invalid transactions