From 3b34f16e5a6d61cc67d6ffec8f4f4e70f604adca Mon Sep 17 00:00:00 2001 From: Danny Ryan Date: Thu, 22 Jul 2021 11:07:04 -0600 Subject: [PATCH 1/3] add base merge p2p spec --- specs/merge/p2p-interface.md | 111 +++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 specs/merge/p2p-interface.md diff --git a/specs/merge/p2p-interface.md b/specs/merge/p2p-interface.md new file mode 100644 index 000000000..4af3f8e10 --- /dev/null +++ b/specs/merge/p2p-interface.md @@ -0,0 +1,111 @@ +# Ethereum Merge networking specification + +This document contains the networking specification for Ethereum 2.0 clients added during the Merge deployment. + +The specification of these changes continues in the same format as the network specifications of previous upgrades, and assumes them as pre-requisite. This document should be viewed as additive to the documents from [Phase 0](../phase0/p2p-interface.md) and from [Altair](../altair/p2p-interface.md) +and will be referred to as the "Phase 0 document" and "Altair document" respectively, hereafter. +Readers should understand the Phase 0 and Altair documents and use them as a basis to understand the changes outlined in this document. + +## Table of contents + + + + + + - [Warning](#warning) +- [Modifications in the Merge](#modifications-in-the-merge) + - [The gossip domain: gossipsub](#the-gossip-domain-gossipsub) + - [Topics and messages](#topics-and-messages) + - [Global topics](#global-topics) + - [`beacon_block`](#beacon_block) + - [Transitioning the gossip](#transitioning-the-gossip) + - [The Req/Resp domain](#the-reqresp-domain) + - [Messages](#messages) + - [BeaconBlocksByRange v2](#beaconblocksbyrange-v2) + - [BeaconBlocksByRoot v2](#beaconblocksbyroot-v2) + + + + +## Warning + +This document is currently illustrative for early Merge testnets and some parts are subject to change. +Refer to the note in the [validator guide](./validator.md) for further details. + +# Modifications in the Merge + +## The gossip domain: gossipsub + +Some gossip meshes are upgraded in the Merge to support upgraded types. + +### Topics and messages + +Topics follow the same specification as in prior upgrades. +All topics remain stable except the beacon block topic which is updated with the modified type. + +The specification around the creation, validation, and dissemination of messages has not changed from the Phase 0 and Altair documents. + +The derivation of the `message-id` remains stable. + +The new topics along with the type of the `data` field of a gossipsub message are given in this table: + +| Name | Message Type | +| - | - | +| `beacon_block` | `SignedBeaconBlock` (modified) | + +Note that the `ForkDigestValue` path segment of the topic separates the old and the new `beacon_block` topics. + +#### Global topics + +The Merge changes the type of the global beacon block topic. + +##### `beacon_block` + +The existing specification for this topic does not change from prior upgrades, +but the type of the payload does change to the (modified) `SignedBeaconBlock` found in the Merge. +This type changes due to the addition of `execution_payload` to the inner `BeaconBlockBody`. + +See the Merge [state transition document](./beacon-chain.md#beaconblockbody) for further details. + +### Transitioning the gossip + +See gossip transition details found in the [Altair document](../altair/p2p) for +details on how to handle transitioning gossip topics for the Merge. + +## The Req/Resp domain + +### Messages + +#### BeaconBlocksByRange v2 + +**Protocol ID:** `/eth2/beacon_chain/req/beacon_blocks_by_range/2/` + +Request and Response remain unchanged. +`MERGE_FORK_VERSION` is used as an additional `context` to specify the Merge block type. + +Per `context = compute_fork_digest(fork_version, genesis_validators_root)`: + +[0]: # (eth2spec: skip) + +| `fork_version` | Chunk SSZ type | +| ------------------------ | -------------------------- | +| `GENESIS_FORK_VERSION` | `phase0.SignedBeaconBlock` | +| `ALTAIR_FORK_VERSION` | `altair.SignedBeaconBlock` | +| `MERGE_FORK_VERSION` | `merge.SignedBeaconBlock` | + +#### BeaconBlocksByRoot v2 + +**Protocol ID:** `/eth2/beacon_chain/req/beacon_blocks_by_root/2/` + +Request and Response remain unchanged. +`MERGE_FORK_VERSION` is used as an additional `context` to specify the Merge block type. + +Per `context = compute_fork_digest(fork_version, genesis_validators_root)`: + +[1]: # (eth2spec: skip) + +| `fork_version` | Chunk SSZ type | +| ------------------------ | -------------------------- | +| `GENESIS_FORK_VERSION` | `phase0.SignedBeaconBlock` | +| `ALTAIR_FORK_VERSION` | `altair.SignedBeaconBlock` | +| `MERGE_FORK_VERSION` | `merge.SignedBeaconBlock` | From 35df4b2d4f81b79dba5651614c5581f8bb400a90 Mon Sep 17 00:00:00 2001 From: Danny Ryan Date: Fri, 23 Jul 2021 07:54:26 -0600 Subject: [PATCH 2/3] rephrase context enum for blocks_by requests --- specs/merge/p2p-interface.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/merge/p2p-interface.md b/specs/merge/p2p-interface.md index 4af3f8e10..712a17549 100644 --- a/specs/merge/p2p-interface.md +++ b/specs/merge/p2p-interface.md @@ -81,7 +81,7 @@ details on how to handle transitioning gossip topics for the Merge. **Protocol ID:** `/eth2/beacon_chain/req/beacon_blocks_by_range/2/` Request and Response remain unchanged. -`MERGE_FORK_VERSION` is used as an additional `context` to specify the Merge block type. +The Merge fork-digest is introduced to the `context` enum to specify the Merge block type. Per `context = compute_fork_digest(fork_version, genesis_validators_root)`: @@ -98,7 +98,7 @@ Per `context = compute_fork_digest(fork_version, genesis_validators_root)`: **Protocol ID:** `/eth2/beacon_chain/req/beacon_blocks_by_root/2/` Request and Response remain unchanged. -`MERGE_FORK_VERSION` is used as an additional `context` to specify the Merge block type. +The Merge fork-digest is introduced to the `context` enum to specify the Merge block type. Per `context = compute_fork_digest(fork_version, genesis_validators_root)`: From 600f55ba7ff34a95756ba202537c46666a643e9d Mon Sep 17 00:00:00 2001 From: Danny Ryan Date: Mon, 9 Aug 2021 17:50:56 -0600 Subject: [PATCH 3/3] add basic execution-layer p2p beacon_block validations --- specs/merge/p2p-interface.md | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/specs/merge/p2p-interface.md b/specs/merge/p2p-interface.md index 712a17549..c79d14b05 100644 --- a/specs/merge/p2p-interface.md +++ b/specs/merge/p2p-interface.md @@ -61,12 +61,32 @@ The Merge changes the type of the global beacon block topic. ##### `beacon_block` -The existing specification for this topic does not change from prior upgrades, -but the type of the payload does change to the (modified) `SignedBeaconBlock` found in the Merge. -This type changes due to the addition of `execution_payload` to the inner `BeaconBlockBody`. - +The *type* of the payload of this topic changes to the (modified) `SignedBeaconBlock` found in the Merge. +Specifically, this type changes with the addition of `execution_payload` to the inner `BeaconBlockBody`. See the Merge [state transition document](./beacon-chain.md#beaconblockbody) for further details. +In addition to the gossip validations for this topic from prior specifications, +the following validations MUST pass before forwarding the `signed_beacon_block` on the network. +Alias `block = signed_beacon_block.message`, `execution_payload = block.body.execution_payload`. +- If the merge is complete with respect to the head state -- i.e. `is_merge_complete(state)` -- + then validate the following: + - _[REJECT]_ The block's execution payload must be non-empty -- + i.e. `execution_payload != ExecutionPayload()` +- If the execution is enabled for the block -- i.e. `is_execution_enabled(state, block.body)` + then validate the following: + - _[REJECT]_ The block's execution payload timestamp is correct with respect to the slot + -- i.e. `execution_payload.timestamp == compute_time_at_slot(state, block.slot)`. + - _[REJECT]_ Gas used is less than the gas limit -- + i.e. `execution_payload.gas_used <= execution_payload.gas_limit`. + - _[REJECT]_ The execution payload block hash is not equal to the parent hash -- + i.e. `execution_payload.block_hash != execution_payload.parent_hash`. + - _[REJECT]_ The execution payload transaction list data is within expected size limits, + the data MUST NOT be larger than the SSZ list-limit, + and a client MAY be more strict. + +*Note*: Additional [gossip validations](https://github.com/ethereum/devp2p/blob/master/caps/eth.md#block-encoding-and-validity) +(see block "data validity" conditions) that rely more heavily on execution-layer state and logic are currently under consideration. + ### Transitioning the gossip See gossip transition details found in the [Altair document](../altair/p2p) for