Welcome

Message Types#

The protocol defines 15 message codes. Each message is RLP-encoded and carries a RequestId for request-response correlation:

1
const (
2
    StatusMsg                     = 0x00
3
    NewBlockHashesMsg             = 0x01  // ETH68 only (disabled post-Merge)
4
    TransactionsMsg               = 0x02
5
    GetBlockHeadersMsg            = 0x03
6
    BlockHeadersMsg               = 0x04
7
    GetBlockBodiesMsg             = 0x05
8
    BlockBodiesMsg                = 0x06
9
    NewBlockMsg                   = 0x07  // ETH68 only (disabled post-Merge)
10
    NewPooledTransactionHashesMsg = 0x08
11
    GetPooledTransactionsMsg      = 0x09
12
    PooledTransactionsMsg         = 0x0a
13
    GetReceiptsMsg                = 0x0f
14
    ReceiptsMsg                   = 0x10
15
    BlockRangeUpdateMsg           = 0x11  // ETH69 only
16
)

The messages group into three categories:

ETH69 drops NewBlockHashesMsg and NewBlockMsg (block announcements are no longer needed post-Merge since the consensus layer drives block progression) and adds BlockRangeUpdateMsg so peers can advertise which block range they serve.

The Status Handshake#

The first message on every eth connection is the status handshake, exchanged in both directions simultaneously:

1
type StatusPacket68 struct {
2
    ProtocolVersion uint32
3
    NetworkID       uint64
4
    TD              *big.Int       // Total difficulty
5
    Head            common.Hash    // Head block hash
6
    Genesis         common.Hash    // Genesis hash
7
    ForkID          forkid.ID      // Fork identifier (EIP-2124)
8
}
9

10
type StatusPacket69 struct {
11
    ProtocolVersion uint32
12
    NetworkID       uint64
13
    Genesis         common.Hash
14
    ForkID          forkid.ID
15
    EarliestBlock   uint64         // Earliest available block
16
    LatestBlock     uint64         // Latest available block
17
    LatestBlockHash common.Hash
18
}

ETH69 removes TD (total difficulty is meaningless post-Merge) and Head (replaced by the explicit block range), and adds EarliestBlock/LatestBlock so peers know which data the remote node can serve.

After exchanging status messages, each side validates:

1. NetworkID must match (mainnet = 1, sepolia = 11155111, etc.)
2. Genesis hash must match
3. ForkID must be compatible (see the Fork ID section below)
4. Protocol version must match

If any check fails, the peer is disconnected.

Startup#

Start() launches the background goroutines:

1
func (h *handler) Start(maxPeers int) {
2
    h.maxPeers = maxPeers
3

4
    // Subscribe to new transactions and start broadcast loop
5
    h.txsCh = make(chan core.NewTxsEvent, txChanSize)      // buffer: 4096
6
    h.txsSub = h.txpool.SubscribeTransactions(h.txsCh, false)
7
    go h.txBroadcastLoop()
8

9
    // Start block range state broadcaster (ETH69)
10
    h.blockRange = newBlockRangeState(h.chain, h.eventMux)
11
    go h.blockRangeLoop(h.blockRange)
12

13
    // Start the transaction fetcher
14
    h.txFetcher.Start()
15

16
    // Start peer handler tracker
17
    go h.protoTracker()
18
}

Peer Lifecycle#

When an eth peer connects, runEthPeer() handles the full lifecycle:

1
// eth/handler.go  (simplified)
2

3
func (h *handler) runEthPeer(peer *eth.Peer, handler eth.Handler) error {
4
    // 1. Wait for snap extension (if peer supports snap protocol)
5
    snap, err := h.peers.waitSnapExtension(peer)
6

7
    // 2. Execute the Ethereum status handshake
8
    peer.Handshake(h.networkID, h.chain, h.blockRange.currentRange())
9

10
    // 3. Enforce peer limits (reserve slots for snap-capable peers during snap sync)
11
    if h.snapSync.Load() && snap == nil {
12
        if all, snp := h.peers.len(), h.peers.snapLen(); all-snp > snp+5 {
13
            return p2p.DiscTooManyPeers
14
        }
15
    }
16

17
    // 4. Register peer with the handler, downloader, and snap syncer
18
    h.peers.registerPeer(peer, snap)
19
    h.downloader.RegisterPeer(peer.ID(), peer.Version(), peer)
20
    if snap != nil {
21
        h.downloader.SnapSyncer.Register(snap)
22
    }
23

24
    // 5. Send existing pending transactions
25
    h.syncTransactions(peer)
26

27
    // 6. Validate required blocks (configurable checkpoint hashes)
28
    for number, hash := range h.requiredBlocks {
29
        // Request the header and verify it matches
30
        // ...
31
    }
32

33
    // 7. Enter message handling loop (blocks until disconnect)
34
    return handler(peer)
35
}

Step 6 is a security feature: operators can configure RequiredBlocks — a map of block number to hash — and any peer that cannot produce matching headers within 15 seconds is disconnected. This defends against peers serving a different chain.

The Broadcast Strategy#

When new transactions enter the local pool, the handler distributes them to peers using a two-tier strategy:

1
// eth/handler.go  (simplified)
2

3
func (h *handler) BroadcastTransactions(txs types.Transactions) {
4
    var (
5
        txset = make(map[*ethPeer][]common.Hash) // peers to send full txs
6
        annos = make(map[*ethPeer][]common.Hash) // peers to send announcements
7
        choice = newBroadcastChoice(h.nodeID, h.txBroadcastKey)
8
        peers  = h.peers.all()
9
    )
10

11
    for _, tx := range txs {
12
        var directSet map[*ethPeer]struct{}
13
        switch {
14
        case tx.Type() == types.BlobTxType:
15
            // Blob txs: announce only (too large to broadcast)
16
        case tx.Size() > txMaxBroadcastSize:
17
            // Large txs (>4KB): announce only
18
        default:
19
            txSender, _ := types.Sender(signer, tx)
20
            directSet = choice.choosePeers(peers, txSender)
21
        }
22

23
        for _, peer := range peers {
24
            if peer.KnownTransaction(tx.Hash()) {
25
                continue
26
            }
27
            if _, ok := directSet[peer]; ok {
28
                txset[peer] = append(txset[peer], tx.Hash())
29
            } else {
30
                annos[peer] = append(annos[peer], tx.Hash())
31
            }
32
        }
33
    }
34

35
    for peer, hashes := range txset {
36
        peer.AsyncSendTransactions(hashes)
37
    }
38
    for peer, hashes := range annos {
39
        peer.AsyncSendPooledTransactionHashes(hashes)
40
    }
41
}

The routing rules:

• Blob transactions — always announced, never directly broadcast. Blob txs carry ~128KB of blob data, so sending them to all peers would be extremely wasteful.
• Large transactions (>4096 bytes) — also announce-only.
• Regular transactions — sent directly to approximately sqrt(N) peers (chosen deterministically using siphash(key, self_id, peer_id, tx_sender)), and announced to all remaining peers.

The deterministic peer selection ensures that different nodes in the network choose different subsets to broadcast to, providing good coverage without every node sending to every peer.

Per-Peer Send Queues#

Each peer has two async channels for transaction distribution:

1
type Peer struct {
2
    // ...
3
    knownTxs    *knownCache          // Set of tx hashes known to this peer (max 32768)
4
    txBroadcast chan []common.Hash    // Channel for direct tx broadcasts
5
    txAnnounce  chan []common.Hash    // Channel for tx announcements
6
    // ...
7
}

The broadcastTransactions() goroutine drains txBroadcast, batching hashes into packets up to 100KB:

1
// eth/protocols/eth/broadcast.go  (simplified)
2

3
func (p *Peer) broadcastTransactions() {
4
    for {
5
        // Accumulate hashes, then:
6
        // 1. Gather full tx data from txpool for each hash
7
        // 2. Build packet up to maxTxPacketSize (100KB)
8
        // 3. Send TransactionsMsg asynchronously
9
    }
10
}

Similarly, announceTransactions() drains txAnnounce and sends NewPooledTransactionHashesMsg packets containing the hash, type, and size of each announced transaction. The type and size metadata lets the recipient decide whether to fetch the transaction without needing a round trip.

The Transaction Fetcher#

When a peer announces transaction hashes, the TxFetcher manages retrieval through a three-stage pipeline:

1
 Stage 1: Waitlist          Stage 2: Queue           Stage 3: Fetching
2
 (wait 500ms for broadcast)  (ready to request)       (request in flight)
3

4
 Announced hash             Not arrived?              Pick peer, send
5
 -----> waitlist            -----> announces           GetPooledTransactionsMsg
6
                                                       |
7
                                                       v
8
                                                    PooledTransactionsMsg
9
                                                       |
10
                                                       v
11
                                                    Add to txpool

Key constants that control the pipeline:

1
const (
2
    maxTxAnnounces     = 4096          // Max announcements per peer
3
    maxTxRetrievals    = 256           // Max txs per request
4
    maxTxRetrievalSize = 128 * 1024    // 128KB max per request
5
    txArriveTimeout    = 500 * time.Millisecond
6
    txFetchTimeout     = 5 * time.Second
7
)

• Stage 1 (Waitlist): When a hash is first announced, it waits 500ms. Many transactions arrive via direct broadcast from other peers within this window, avoiding an unnecessary fetch request.
• Stage 2 (Queue): If the transaction hasn’t arrived after the wait, it moves to the request queue.
• Stage 3 (Fetching): The fetcher sends GetPooledTransactionsMsg to a peer that announced the hash. If the peer doesn’t respond within 5 seconds, the request is retried with a different peer.

The fetcher also tracks underpriced transactions — those that the txpool rejected as too cheap. These are cached for 5 minutes so the fetcher doesn’t repeatedly request them from different peers.

Serving Data#

Request handlers serve chain data to remote peers. For example, header requests:

1
func handleGetBlockHeaders(backend Backend, msg Decoder, peer *Peer) error {
2
    var query GetBlockHeadersPacket
3
    if err := msg.Decode(&query); err != nil {
4
        return err
5
    }
6
    response := ServiceGetBlockHeadersQuery(backend.Chain(), query.GetBlockHeadersRequest, peer)
7
    return peer.ReplyBlockHeadersRLP(query.RequestId, response)
8
}

ServiceGetBlockHeadersQuery() handles two modes: number mode (contiguous segment from a block number) and hash mode (starting from a specific hash). It respects response limits — at most 1024 headers and 2MB total.

Receiving Transactions#

Directly broadcast transactions arrive via TransactionsMsg:

1
// eth/protocols/eth/handlers.go  (simplified)
2

3
func handleTransactions(backend Backend, msg Decoder, peer *Peer) error {
4
    var txs TransactionsPacket
5
    if err := msg.Decode(&txs); err != nil {
6
        return err
7
    }
8
    // Mark each tx as known by this peer
9
    for _, tx := range txs {
10
        peer.markTransaction(tx.Hash())
11
    }
12
    // Inject into local txpool
13
    return backend.Handle(peer, &txs)
14
}

Transaction announcements arrive via NewPooledTransactionHashesMsg:

1
// eth/protocols/eth/handlers.go  (simplified)
2

3
func handleNewPooledTransactionHashes(backend Backend, msg Decoder, peer *Peer) error {
4
    var ann NewPooledTransactionHashesPacket
5
    if err := msg.Decode(&ann); err != nil {
6
        return err
7
    }
8
    // Validate: hashes, types, and sizes arrays must have equal length
9
    // Mark hashes as known, notify the tx fetcher
10
    return backend.Handle(peer, &ann)
11
}

The backend.Handle() call routes to the handler, which feeds the announcement to txFetcher.Notify(), triggering the three-stage retrieval pipeline.

Request/Response Dispatch#

Outgoing requests and incoming responses are correlated via the dispatcher goroutine in each peer. Each request carries a RequestId and a response sink channel:

1
type Request struct {
2
    peer *Peer
3
    id   uint64            // RequestId for correlation
4
    sink chan *Response     // Where the response will be delivered
5
    code uint64            // Request message code
6
    want uint64            // Expected response code
7
    data interface{}       // Request payload
8
}
9

10
type Response struct {
11
    Req  *Request
12
    Res  interface{}       // Response data
13
    Meta interface{}       // Computed metadata
14
    Time time.Duration     // Round-trip time
15
    Done chan error         // Signal to reader
16
}

When a response message arrives (e.g., BlockHeadersMsg), the handler dispatches it to the matching request’s sink channel based on RequestId. The requester reads from the sink and signals completion via Done.

The Downloader#

The Downloader struct in eth/downloader/downloader.go orchestrates the entire sync process:

1
type Downloader struct {
2
    mode atomic.Uint32    // FullSync or SnapSync
3

4
    queue *queue           // Scheduler for block fetching
5
    peers *peerSet         // Active peers
6

7
    stateDB    ethdb.Database
8
    blockchain BlockChain
9

10
    // Skeleton sync (post-merge)
11
    skeleton *skeleton
12

13
    // State sync
14
    pivotHeader *types.Header      // Snap sync pivot block
15
    SnapSyncer  *snap.Syncer       // State snapshot downloader
16

17
    // Cancellation
18
    cancelCh chan struct{}
19
    quitCh   chan struct{}
20
    // ...
21
}

Two sync modes are supported:

Snap sync is much faster (hours instead of days) because it avoids re-executing millions of historical transactions. However, it requires peers that support the snap protocol and have a recent state snapshot available.

Key Limits#

1
var (
2
    MaxBlockFetch   = 128   // Blocks per request
3
    MaxHeaderFetch  = 192   // Headers per request
4
    MaxReceiptFetch = 256   // Receipts per request
5
    maxResultsProcess = 2048   // Results to import at once
6
    fsMinFullBlocks   = 64     // Min full blocks in snap sync
7
)

The Sync Pipeline#

When the consensus layer signals a new head, the sync pipeline activates:

1
 Consensus layer: "New head at block N"
2
      |
3
      v
4
 skeleton.Sync(head, finalized)    -- Download header skeleton backwards
5
      |
6
      v
7
 syncToHead()                       -- Main sync orchestrator
8
      |
9
      +-- Determine sync mode (full/snap) and pivot block
10
      |
11
      +-- Spawn concurrent fetchers:
12
      |     fetchHeaders()           -- from skeleton chain
13
      |     fetchBodies()            -- block contents
14
      |     fetchReceipts()          -- tx receipts (snap sync only)
15
      |
16
      +-- Spawn processors:
17
      |     processHeaders()         -- validate and queue headers
18
      |     processFullSyncContent() -- execute blocks (full sync)
19
      |     processSnapSyncContent() -- import blocks + state (snap sync)
20
      |
21
      +-- State sync (snap sync only):
22
            SnapSyncer downloads account trie, storage tries, bytecode

The Skeleton Syncer#

The skeleton syncer (eth/downloader/skeleton.go) handles the first phase: downloading the header chain. Post-Merge, this is the primary mechanism for syncing headers since the consensus layer provides the chain head.

1
type skeleton struct {
2
    db       ethdb.Database
3
    filler   backfiller          // Callback to trigger body/receipt download
4
    peers    *peerSet
5
    progress *skeletonProgress   // Persistent sync state
6
    // ...
7
}
8

9
type skeletonProgress struct {
10
    Subchains []*subchain
11
    Finalized *uint64
12
}
13

14
type subchain struct {
15
    Head uint64           // Newest header block number
16
    Tail uint64           // Oldest header block number
17
    Next common.Hash      // Hash of the next oldest header
18
}

The skeleton works by downloading headers backwards — from the consensus-provided head toward genesis. Because the sync might be interrupted and restarted, the progress is tracked as a list of subchains — disjoint segments of downloaded headers. As headers are downloaded, subchains grow and eventually merge:

1
 Initial state (new head announced):
2

3
   Subchain 1:  [Head: 1000, Tail: 1000]
4
                 (just the tip)
5

6
 After some downloading:
7

8
   Subchain 1:  [Head: 1000, Tail: 800]
9
                 (200 headers downloaded backwards)
10

11
 After restart + new head:
12

13
   Subchain 1:  [Head: 1050, Tail: 1050]    (new tip)
14
   Subchain 2:  [Head: 1000, Tail: 800]     (previous progress)
15

16
 After gap is filled:
17

18
   Subchain 1:  [Head: 1050, Tail: 800]     (merged)
19

20
 Eventually links to local chain:
21

22
   Subchain 1:  [Head: 1050, Tail: 0]       (complete)

Headers are downloaded in batches of 512 (requestHeaders) and stored in a scratch space of up to 131072 headers (scratchHeaders, ~64MB). Once the skeleton chain links to the local chain (or genesis), the downloader starts backfilling bodies, receipts, and state.

Full Sync vs. Snap Sync#

After the skeleton chain is complete, the downloader fills in the remaining data:

Full Sync:

1. fetchBodies() downloads block bodies (transactions, uncles, withdrawals) for all headers.
2. processFullSyncContent() calls blockchain.InsertChain() for each batch, which executes every transaction and builds the state trie from scratch (see Chapter 10).

Snap Sync:

1. A pivot block is chosen near the chain head (at least 64 blocks from the tip). Everything at or below the pivot uses snap sync; everything above uses full execution.
2. fetchBodies() and fetchReceipts() download bodies and receipts for all blocks.
3. The SnapSyncer downloads the state trie at the pivot block using the snap protocol — fetching account ranges, storage ranges, and bytecode in parallel from multiple peers.
4. processSnapSyncContent() imports blocks below the pivot using the downloaded receipts (no re-execution needed), then switches to full execution for the last ~64 blocks.