Welcome

Stage 1: RPC Arrival#

A user (or DApp) submits a signed transaction by calling eth_sendRawTransaction over HTTP, WebSocket, or IPC. The RPC server (Chapter 13) receives the request, splits the method name on _ to find the eth namespace, and dispatches to TransactionAPI.SendRawTransaction().

SendRawTransaction binary-decodes the raw bytes via tx.UnmarshalBinary() into a types.Transaction (Chapter 02) and calls SubmitTransaction(), which adds the transaction to the pool.

Stage 2: Transaction Pool#

The transaction enters the TxPool coordinator (Chapter 08), which routes it to the appropriate sub-pool — LegacyPool for regular transactions, BlobPool for EIP-4844 blob transactions. The sub-pool validates the transaction: signature recovery, nonce check, balance check, gas limit check, and pool-level limits (account slots, global slots, price floor).

If validation passes, the transaction lands in the pool’s pending map — it is ready for inclusion in a block. The pool publishes a NewTxsEvent via an event.Feed (Chapter 14), notifying the handler.

Stage 3: Peer Broadcast#

The handler in eth/handler.go (Chapter 12) picks up the NewTxsEvent and broadcasts the transaction to connected peers. For each peer, the handler decides between two strategies:

• Direct broadcast — send the full transaction to a small fraction of peers (square root of total).
• Hash announcement — send only the transaction hash to the remaining peers, who can request the full transaction if they don’t have it.

This is the eth/68 wire protocol at work. The transaction propagates across the network, landing in the pools of other nodes.

Stage 4: Block Building#

Block building is triggered by the consensus client. When the CL calls engine_forkchoiceUpdatedV* with payloadAttributes, geth’s Engine API (Chapter 09) tells the miner to start building a payload.

The miner’s generateWork() method:

1. Prepares a block header with the parent hash, timestamp, and other consensus fields.
2. Creates a StateDB snapshot at the parent block’s state root.
3. Calls fillTransactions() — pulls pending transactions from the pool, sorts them by effective tip (highest-paying first), and executes each one.

Stage 5: Transaction Execution#

For each transaction, the miner calls core.ApplyTransaction(), which creates a stateTransition and runs its execute() method (Chapter 06). The execution pipeline:

1. preCheck() — verify the sender’s nonce, balance, and call buyGas() to deduct the upfront gas cost and reduce the block’s GasPool.
2. EVM dispatch — call evm.Call() for message calls or evm.Create() for contract creation.
3. Gas refund — calcRefund() computes the refund (capped at 1/5 of gas used since EIP-3529), then returnGas() credits the remaining gas back to the sender.
4. Fee distribution — the priority fee (tip) goes to the coinbase; the base fee is burned.

Stage 6: EVM Execution#

Inside evm.Call(), the EVM.Run() loop (Chapter 07) takes over:

1. Fetch the next opcode from the contract’s bytecode.
2. Look up the opcode in the fork-specific jump table to get its gas cost and handler function.
3. Deduct gas. If insufficient, abort with an out-of-gas error.
4. Execute the handler — arithmetic (opAdd), storage (opSstore, opSload), calls (opCall, opDelegateCall), or any other EVM operation.
5. Repeat until STOP, RETURN, REVERT, or an error.

State-mutating opcodes like SSTORE write to the StateDB (Chapter 04), which records changes in dirty maps on the corresponding stateObject. These changes are not yet committed to the trie — they exist only in memory, protected by the journal’s undo log so they can be reverted if the transaction fails.

Stage 7: State and Trie#

After all transactions are executed, the miner calls the consensus engine’s FinalizeAndAssemble(), which internally invokes Finalize() to apply block-level state changes (beacon withdrawals, system-level operations), then computes the final state root by committing dirty state through the trie (Chapter 03):

• Each modified account’s storage trie is updated and hashed.
• The account trie is updated with new account states and hashed.
• The resulting 32-byte Merkle root becomes the block header’s StateRoot.

The assembled block — header, transaction list, receipts, and withdrawals — is the payload returned to the consensus client via engine_getPayloadV*.

Stage 8: Block Insertion#

The consensus client validates the block on the beacon chain, then sends it back to geth via engine_newPayloadV*. Geth runs InsertBlockWithoutSetHead() (Chapter 10):

1. Header verification — check timestamp, gas limit, extra data, and other consensus constraints.
2. Body validation — verify transaction root, uncles hash, withdrawals hash against the header.
3. State processing — re-execute all transactions (identical to step 5-6 above) and compare the resulting state root against the header’s StateRoot. If they don’t match, the block is rejected.
4. Write to database — block header, body, receipts, and state trie nodes are persisted to the key-value store (LevelDB or Pebble, Chapter 05).

When the CL calls engine_forkchoiceUpdatedV* designating this block as the new head, geth updates its canonical chain pointers and emits a ChainHeadEvent.

Stage 9: Persistence and Propagation#

The committed state flows down the storage stack:

• StateDB flushes dirty state objects to the trie (Chapter 03).
• The trie commits new nodes to TrieDB — either the path-based or hash-based scheme (Chapter 05).
• TrieDB eventually flushes to ethdb (LevelDB or Pebble) on disk.
• Old blocks are migrated to the freezer (append-only ancient storage) to keep the active database lean.

Simultaneously, the handler broadcasts the new block to peers (Chapter 12) — full block to a few, block hash to the rest. Peers that are behind can use snap sync or full sync to catch up.

Stage 10: Finality#

The consensus client eventually marks the block (or an ancestor) as finalized — meaning it will never be reverted. Geth updates its currentFinalBlock pointer (Chapter 10). The transaction is now permanently part of the canonical chain.

Foundation Layer#

State Architecture#

Execution#

Chain Operations#

Networking#

Interface and Lifecycle#

The Lifecycle Pattern#

Many long-lived components follow a similar contract — setup methods that launch goroutines, and teardown methods that shut them down. The Node orchestrates the formal Lifecycle interface (Start()/Stop()) for registered services (Chapter 14), starting them in registration order and stopping them in reverse order. Components that implement this interface include:

• Ethereum (eth/backend.go) — the core service
• handler (eth/handler.go) — sync and broadcast
• Server (p2p/server.go) — P2P networking

Other components use variant naming but follow the same pattern — LegacyPool and BlobPool use Init()/Close(), and BlockChain is initialized via NewBlockChain() and torn down via Stop().

The Event Feed Pattern#

Decoupled communication between subsystems uses event.Feed (Chapter 14). A producer calls Send(), and all subscribers receive the value on their channels. Key feeds in geth:

The Backend Interface Pattern#

API layers are decoupled from implementation through interfaces. The RPC methods in internal/ethapi/ talk to a Backend interface (Chapter 13), which EthAPIBackend implements by delegating to BlockChain, TxPool, Miner, and other concrete types. This allows the same API code to work in full node, light client, and test contexts.

The Config Struct Pattern#

Every major subsystem has a Config struct that aggregates its tunable parameters:

CLI flags map to these config structs during startup (Chapter 14): utils.SetNodeConfig() writes to node.Config, utils.SetEthConfig() writes to ethconfig.Config, and so on.

The Four-Layer Storage Model#

Data flows through four layers on its way to disk (Chapters 03, 04, 05):

1
  StateDB         in-memory dirty maps, journal for rollback
2
     |
3
     v
4
  Trie            Merkle Patricia Trie nodes (fullNode, shortNode)
5
     |
6
     v
7
  TrieDB          caching layer (path-based or hash-based scheme)
8
     |
9
     v
10
  ethdb           key-value store (LevelDB or Pebble) + freezer for ancient data

Reads traverse this stack top-down: StateDB checks its dirty cache, falls through to the trie, which falls through to TrieDB, which falls through to disk. Writes accumulate at the top and flush downward on commit.