'eth' is a protocol on the RLPx transport that facilitates exchange of Ethereum blockchain information between peers. The current protocol version is eth/63. See end of document for a list of changes in past protocol versions.
Once a connection is established, a Status message must be sent. Following the reception of the peer's Status message, the Ethereum session is active and any other messages may be sent.
All known transactions should be sent following the Status exchange with one or more Transactions messages.
Transactions messages should also be sent periodically as the node has new transactions to disseminate. A node should never send a transaction back to a peer that it can determine already knows of it (either because it was previously sent or because it was informed from this peer originally).
Blocks are typically re-propagated to all connected peers as soon as basic validity of the announcement has been established (e.g. after the proof-of-work check). Propagation uses the NewBlock and NewBlockHashes messages. The NewBlock message includes the full block and is sent to a small fraction of connected peers (usually the square root of the total number of peers). All other peers are sent a NewBlockHashes message containing just the hash of the new block. Those peers may request the full block later if they fail to receive it from anyone within reasonable time.
Two peers get connected and send their Status message. Status includes the Total Difficulty (TD) and hash of their best block.
The client with the worst TD then proceeds to download block headers using the [BlockHeadersFromNumber] message. It verifies proof-of-work values in received headers and fetches block bodies using the GetBlockBodies message. Received blocks are executed using the Ethereum Virtual Machine, recreating the state tree.
Note that header downloads, block body downloads and block execution may happen concurrently.
eth/63 also allows synchronizing transaction execution results ("state"). This may be faster than re-executing all transactions but comes at the expense of some security.
State synchronization typically proceeds by downloading the chain of block headers, verifying their proof-of-work values. Block bodies are requested as in the Chain Synchronization section but block transactions aren't executed. Instead, the client picks a block near the head of the chain and downloads merkle tree nodes and contract code incrementally by requesting the root node, its children, grandchildren, ... using GetNodeData until the entire tree is synchronized.
[protocolVersion: P, networkId: P, td: P, bestHash: B_32, genesisHash: B_32, number: P]
Inform a peer of its current state. This message should be sent just after the connection is established and prior to any other eth protocol messages.
protocolVersion: the current protocol version, 63networkId: Integer identifying the blockchain, see table belowtd: total difficulty of the best chain. Integer, as found in block header.bestHash: The hash of the best (i.e. highest TD) known block.genesisHash: The hash of the Genesis block.number: The block number of the latest block in the chain.
This table lists common Network IDs and their corresponding networks. Other IDs exist which aren't listed, i.e. clients should not require that any particular network ID is used. Note that the Network ID may or may not correspond with the EIP-155 Chain ID used for transaction replay prevention.
| ID | chain |
|---|---|
| 0 | Olympic (disused) |
| 1 | Frontier (now mainnet) |
| 2 | Morden (disused) |
| 3 | Ropsten (current PoW testnet) |
| 4 | Rinkeby |
For a community curated list of chain IDs, see https://chainid.network.
[[hash_0: B_32, number_0: P], [hash_1: B_32, number_1: P], ...]
Specify one or more new blocks which have appeared on the network. To be maximally helpful, nodes should inform peers of all blocks that they may not be aware of. Including hashes that the sending peer could reasonably be considered to know (due to the fact they were previously informed of because that node has itself advertised knowledge of the hashes through NewBlockHashes) is considered bad form, and may reduce the reputation of the sending node. Including hashes that the sending node later refuses to honour with a proceeding GetBlockHeaders message is considered bad form, and may reduce the reputation of the sending node.
[[nonce: P, receivingAddress: B_20, value: P, ...], ...]
Specify transactions that the peer should make sure is included on its transaction queue. The items in the list are transactions in the format described in the main Ethereum specification. Transactions messages must contain at least one (new) transaction, empty Transactions messages are discouraged and may lead to disconnection.
Nodes must not resend the same transaction to a peer in the same session and must not relay transactions to a peer they received that transaction from. In practice this is often implemented by keeping a per-peer bloom filter or set of transaction hashes which have already been sent or received.
[block: {P, B_32}, maxHeaders: P, skip: P, reverse: P in {0, 1}]
Require peer to return a BlockHeaders message. Reply must contain a number of block
headers, of rising number when reverse is 0, falling when 1, skip blocks apart,
beginning at block block (denoted by either number or hash) in the canonical chain, and
with at most maxHeaders items.
[blockHeader_0, blockHeader_1, ...]
Reply to GetBlockHeaders. The items in the list (following the message ID) are block headers in the format described in the main Ethereum specification, previously asked for in a GetBlockHeaders message. This may validly contain no block headers if none of the requested block headers were found. The number of headers that can be requested in a single message may be subject to implementation-defined limits.
[hash_0: B_32, hash_1: B_32, ...]
Require peer to return a BlockBodies message. Specify the set of blocks that we're interested in with the hashes. The number of blocks that can be requested in a single message may be subject to implementation-defined limits.
[[transactions_0, uncles_0] , ...]
Reply to GetBlockBodies. The items in the list are some of the blocks, minus the header, in the format described in the main Ethereum specification, previously asked for in a GetBlockBodies message. This may be empty if no blocks were available for the last GetBlockBodies query.
[[blockHeader, transactionList, uncleList], totalDifficulty]
Specify a single block that the peer should know about. The composite item in the list (following the message ID) is a block in the format described in the main Ethereum specification.
totalDifficultyis the total difficulty of the block (aka score).
[hash_0: B_32, hash_1: B_32, ...]
Require peer to return a NodeData message containing state tree nodes or contract code matching the requested hashes.
[value_0: B, value_1: B, ...]
Provide a set of state tree nodes or contract code blobs which correspond to previously requested hashes from GetNodeData. Does not need to contain all; best effort is fine. This message may be an empty list if the peer doesn't know about any of the previously requested hashes. The number of items that can be requested in a single message may be subject to implementation-defined limits.
[blockHash_0: B_32, blockHash_1: B_32, ...]
Require peer to return a Receipts message containing the receipts of the given block hashes. The number of receipts that can be requested in a single message may be subject to implementation-defined limits.
[[receipt_0, receipt_1], ...]
Provide a set of receipts which correspond to block hashes in a previous GetReceipts message.
Version 63 added the GetNodeData, NodeData, GetReceipts and Receipts messages which allow synchronizing transaction execution results.
In version 62, the NewBlockHashes message was extended to include block numbers alongside the announced hashes. Messages GetBlockHashes (0x03), BlockHashes (0x04), GetBlocks (0x05) and Blocks (0x06) were replaced by messages that fetch block headers and bodies. The BlockHashesFromNumber (0x08) message was removed.
Previous encodings of the reassigned/removed message codes were:
GetBlockHashes (0x03) [hash: B_32, maxBlocks: P]
BlockHashes (0x04) [hash_0: B_32, hash_1: B_32, ...]
GetBlocks (0x05) [hash_0: B_32, hash_1: B_32, ...]
Blocks (0x06) [[blockHeader, transactionList, uncleList], ...]
BlockHashesFromNumber (0x08) [number: P, maxBlocks: P]
Version 61 added the BlockHashesFromNumber (0x08) message which could be used to request blocks in ascending order.
Version numbers below 60 were used during the Ethereum PoC development phase.
0x00for PoC-10x01for PoC-20x07for PoC-30x09for PoC-40x17for PoC-50x1cfor PoC-6