This specification defines the “eth” ENR entry, which provides information about the eth capability on a certain node.
Entry Format
entry-key = "eth"
entry-value = [[ forkHash, forkNext ]]At this time, the “eth” entry is a single element list containing an EIP-2124 fork ID
value. Please see the EIP for definitions of forkHash and forkNext.
In order to be compatible with future versions of this specifications, implementations
should ignore any additional list elements in entry-value.
Historical block-number fork identifiers and validation (EIP-2124)
Each node maintains the following values:
FORK_HASH: IEEE CRC32 checksum ([4]byte) of the genesis hash and fork blocks numbers that already passed.- The fork block numbers are fed into the CRC32 checksum in ascending order.
- If multiple forks are applied at the same block, the block number is checksummed only once.
- Block numbers are regarded as
uint64integers, encoded in big endian format when checksumming. - If a chain is configured to start with a non-Frontier ruleset already in its genesis, that is NOT considered a fork.
FORK_NEXT: Block number (uint64) of the next upcoming fork, or0if no next fork is known.
E.g. FORK_HASH for mainnet would be:
- forkhash₀ =
0xfc64ec04(Genesis) =CRC32(<genesis-hash>) - forkhash₁ =
0x97c2c34c(Homestead) =CRC32(<genesis-hash> || uint64(1150000)) - forkhash₂ =
0x91d1f948(DAO fork) =CRC32(<genesis-hash> || uint64(1150000) || uint64(1920000))
The fork identifier is defined as RLP([FORK_HASH, FORK_NEXT]). This forkid is cross validated (NOT naively compared) to assess a remote chain’s compatibility. Irrespective of fork state, both parties must come to the same conclusion to avoid indefinite reconnect attempts from one side.
Validation rules
-
- If local and remote
FORK_HASHmatches, compare local head toFORK_NEXT.
- The two nodes are in the same fork state currently. They might know of differing future forks, but that’s not relevant until the fork triggers (might be postponed, nodes might be updated to match).
- 1a) A remotely announced but remotely not passed block is already passed locally, disconnect, since the chains are incompatible.
- 1b) No remotely announced fork; or not yet passed locally, connect.
- If local and remote
-
- If the remote
FORK_HASHis a subset of the local past forks and the remoteFORK_NEXTmatches with the locally following fork block number, connect.
- Remote node is currently syncing. It might eventually diverge from us, but at this current point in time we don’t have enough information.
- If the remote
-
- If the remote
FORK_HASHis a superset of the local past forks and can be completed with locally known future forks, connect.
- Local node is currently syncing. It might eventually diverge from the remote, but at this current point in time we don’t have enough information.
- If the remote
-
- Reject in all other cases.
Stale software examples
The examples below try to exhaust the fork combination possibilities that arise when nodes do not run matching software versions, but otherwise follow the same chain (mainnet nodes, testnet nodes, etc).
| Past forks | Future forks | Head | Remote FORK_HASH | Remote FORK_NEXT | Connect | Reason |
|---|---|---|---|---|---|---|
| A | A | Yes (1b) | Same forks, same sync state. | |||
| A | < B | A | B | Yes (1b) | Remote is advertising a future fork, but that is uncertain. | |
| A | >= B | A | B | No (1a) | Remote is advertising a future fork that passed locally. | |
| A | B | A | Yes (1b) | Local knows about a future fork, but that is uncertain. | ||
| A | B | A | B | Yes (1b) | Both know about a future fork, but that is uncertain. | |
| A | B1 | < B2 | A | B2 | Yes (1b) | Both know about differing future forks, but those are uncertain. |
| A | B1 | >= B2 | A | B2 | No (1a) | Both know about differing future forks, but the remote one passed locally. |
| [A,B] | A | B | Yes (2) | Remote out of sync. | ||
| [A,B,C] | A | B | Yes¹ (2) | Remote out of sync. Remote will need a software update, but we don’t know it yet. | ||
| A | B | A ⊕ B | Yes (3) | Local out of sync. | ||
| A | B,C | A ⊕ B | Yes (3) | Local out of sync. Local also knows about a future fork, but that is uncertain yet. | ||
| A | A ⊕ B | No (4) | Local needs software update. | |||
| A | B | A ⊕ B ⊕ C | No² (4) | Local needs software update. | ||
| [A,B] | A | No (4) | Remote needs software update. |
Note, there’s one asymmetry in the table, marked with ¹ and ². Since we don’t have access to a remote node’s future fork list (just the next one), we can’t detect that it’s software is stale until it syncs up. This is acceptable as 1) the remote node will disconnect from us anyway, and 2) this is a temporary fluke during sync, not permanent with a leftover node.
Connection handoff to eth
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 message may be sent.