From 2445bf519432b7aa01da832547ec51a1aaa1d19c Mon Sep 17 00:00:00 2001 From: Justin Traglia Date: Fri, 18 Oct 2024 10:33:54 -0500 Subject: [PATCH] Move p2p-interface intros to introduction section --- specs/_features/das/p2p-interface.md | 18 ++++----- specs/_features/eip7594/p2p-interface.md | 7 ++++ specs/_features/eip7732/p2p-interface.md | 47 +++++++++++++----------- specs/altair/p2p-interface.md | 16 ++++---- specs/bellatrix/p2p-interface.md | 17 +++++---- specs/capella/p2p-interface.md | 10 +++-- specs/deneb/p2p-interface.md | 11 ++++-- specs/electra/p2p-interface.md | 11 ++++-- specs/phase0/p2p-interface.md | 21 ++++++----- 9 files changed, 92 insertions(+), 66 deletions(-) diff --git a/specs/_features/das/p2p-interface.md b/specs/_features/das/p2p-interface.md index b166c9c3e4..2c165078d2 100644 --- a/specs/_features/das/p2p-interface.md +++ b/specs/_features/das/p2p-interface.md @@ -28,12 +28,10 @@ - - ## Introduction For an introduction about DAS itself, see [the DAS participation spec](sampling.md#data-availability-sampling). -This is not a pre-requisite for the network layer, but will give you valuable context. +This is not a pre-requisite for the network layer, but will give you valuable context. For sampling, all nodes need to query for `k` random samples each slot. @@ -55,13 +53,13 @@ The push model does not aim to serve "historical" queries (anything older than t Historical queries are still required for the unhappy case, where messages are not pushed quick enough, and missing samples are not reconstructed by other nodes on the horizontal subnet quick enough. -The main challenge in supporting historical queries is to target the right nodes, +The main challenge in supporting historical queries is to target the right nodes, without concentrating too many requests on a single node, or breaking the network/consensus identity separation. ## DAS Subnets On a high level, the push-model roles are divided into: -- Sources: create blobs of shard block data, and transformed into many tiny samples. +- Sources: create blobs of shard block data, and transformed into many tiny samples. - Sinks: continuously look for samples At full operation, the network has one proposer, per shard, per slot. @@ -93,15 +91,15 @@ Peers on the horizontal subnet are expected to at least perform regular propagat Nodes on this same subnet can replicate the sampling efficiently (including a proof for each sample), and distribute it to any vertical networks that are available to them. -Since the messages are content-addressed (instead of origin-stamped), -multiple publishers of the same samples on a vertical subnet do not hurt performance, +Since the messages are content-addressed (instead of origin-stamped), +multiple publishers of the same samples on a vertical subnet do not hurt performance, but actually improve it by shortcutting regular propagation on the vertical subnet, and thus lowering the latency to a sample. ### Vertical subnets Vertical subnets propagate the samples to every peer that is interested. -These interests are randomly sampled and rotate quickly: although not perfect, +These interests are randomly sampled and rotate quickly: although not perfect, sufficient to avoid any significant amount of nodes from being 100% predictable. As soon as a sample is missing after the expected propagation time window, @@ -166,7 +164,7 @@ The [DAS participation spec](sampling.md#horizontal-subnets) outlines when and w #### Vertical subnets: `das_sample_{subnet_index}` -Shard blob samples can be verified with just a 48 byte KZG proof (commitment quotient polynomial), +Shard blob samples can be verified with just a 48 byte KZG proof (commitment quotient polynomial), against the commitment to blob polynomial, specific to that `(shard, slot)` key. The following validations MUST pass before forwarding the `sample` on the vertical subnet. @@ -192,7 +190,7 @@ This is to serve other peers that may have missed it. To pull samples from nodes, in case of network instability when samples are unavailable, a new query method is added to the Req-Resp domain. -This builds on top of the protocol identification and encoding spec which was introduced in [the Phase0 network spec](../../phase0/p2p-interface.md). +This builds on top of the protocol identification and encoding spec which was introduced in [the Phase0 network spec](../../phase0/p2p-interface.md). Note that DAS networking uses a different protocol prefix: `/eth2/das/req` diff --git a/specs/_features/eip7594/p2p-interface.md b/specs/_features/eip7594/p2p-interface.md index c989711807..900d521ac2 100644 --- a/specs/_features/eip7594/p2p-interface.md +++ b/specs/_features/eip7594/p2p-interface.md @@ -8,6 +8,7 @@ +- [Introduction](#introduction) - [Modifications in EIP-7594](#modifications-in-eip-7594) - [Preset](#preset) - [Configuration](#configuration) @@ -36,6 +37,12 @@ +## Introduction + +This document contains the consensus-layer networking specification for EIP7594. + +The specification of these changes continues in the same format as the network specifications of previous upgrades, and assumes them as pre-requisite. + ## Modifications in EIP-7594 ### Preset diff --git a/specs/_features/eip7732/p2p-interface.md b/specs/_features/eip7732/p2p-interface.md index d33dfaba31..df02cc2382 100644 --- a/specs/_features/eip7732/p2p-interface.md +++ b/specs/_features/eip7732/p2p-interface.md @@ -1,10 +1,9 @@ # EIP-7732 -- Networking -This document contains the consensus-layer networking specification for EIP7732. - +- [Introduction](#introduction) - [Modification in EIP-7732](#modification-in-eip-7732) - [Preset](#preset) - [Configuration](#configuration) @@ -28,6 +27,12 @@ This document contains the consensus-layer networking specification for EIP7732. +## Introduction + +This document contains the consensus-layer networking specification for EIP7732. + +The specification of these changes continues in the same format as the network specifications of previous upgrades, and assumes them as pre-requisite. + ## Modification in EIP-7732 ### Preset @@ -67,7 +72,7 @@ class BlobSidecar(Container): ##### Modified `verify_blob_sidecar_inclusion_proof` -`verify_blob_sidecar_inclusion_proof` is modified in EIP-7732 to account for the fact that the KZG commitments are included in the `ExecutionPayloadEnvelope` and no longer in the beacon block body. +`verify_blob_sidecar_inclusion_proof` is modified in EIP-7732 to account for the fact that the KZG commitments are included in the `ExecutionPayloadEnvelope` and no longer in the beacon block body. ```python def verify_blob_sidecar_inclusion_proof(blob_sidecar: BlobSidecar) -> bool: @@ -121,7 +126,7 @@ EIP-7732 introduces new global topics for execution header, execution payload an [Modified in EIP-7732] -The *type* of the payload of this topic changes to the (modified) `SignedBeaconBlock` found in [the Beacon Chain changes](./beacon-chain.md). +The *type* of the payload of this topic changes to the (modified) `SignedBeaconBlock` found in [the Beacon Chain changes](./beacon-chain.md). There are no new validations for this topic. However, all validations with regards to the `ExecutionPayload` are removed: @@ -137,7 +142,7 @@ There are no new validations for this topic. However, all validations with regar And instead the following validations are set in place with the alias `header = signed_execution_payload_header.message`: - If `execution_payload` verification of block's execution payload parent by an execution node **is complete**: - - [REJECT] The block's execution payload parent (defined by `header.parent_block_hash`) passes all validation. + - [REJECT] The block's execution payload parent (defined by `header.parent_block_hash`) passes all validation. - [REJECT] The block's parent (defined by `block.parent_root`) passes validation. ###### `execution_payload` @@ -148,12 +153,12 @@ The following validations MUST pass before forwarding the `signed_execution_payl - _[IGNORE]_ The envelope's block root `envelope.block_root` has been seen (via both gossip and non-gossip sources) (a client MAY queue payload for processing once the block is retrieved). - _[IGNORE]_ The node has not seen another valid `SignedExecutionPayloadEnvelope` for this block root from this builder. - -Let `block` be the block with `envelope.beacon_block_root`. + +Let `block` be the block with `envelope.beacon_block_root`. Let `header` alias `block.body.signed_execution_payload_header.message` (notice that this can be obtained from the `state.signed_execution_payload_header`) -- _[REJECT]_ `block` passes validation. -- _[REJECT]_ `envelope.builder_index == header.builder_index` -- if `envelope.payload_withheld == False` then +- _[REJECT]_ `block` passes validation. +- _[REJECT]_ `envelope.builder_index == header.builder_index` +- if `envelope.payload_withheld == False` then - _[REJECT]_ `payload.block_hash == header.block_hash` - _[REJECT]_ The builder signature, `signed_execution_payload_envelope.signature`, is valid with respect to the builder's public key. @@ -163,14 +168,14 @@ This topic is used to propagate signed payload attestation message. The following validations MUST pass before forwarding the `payload_attestation_message` on the network, assuming the alias `data = payload_attestation_message.data`: -- _[IGNORE]_ The message's slot is for the current slot (with a `MAXIMUM_GOSSIP_CLOCK_DISPARITY` allowance), i.e. `data.slot == current_slot`. -- _[REJECT]_ The message's payload status is a valid status, i.e. `data.payload_status < PAYLOAD_INVALID_STATUS`. -- _[IGNORE]_ The `payload_attestation_message` is the first valid message received from the validator with index `payload_attestation_message.validate_index`. -- _[IGNORE]_ The message's block `data.beacon_block_root` has been seen (via both gossip and non-gossip sources) (a client MAY queue attestation for processing once the block is retrieved. Note a client might want to request payload after). -- _[REJECT]_ The message's block `data.beacon_block_root` passes validation. -- _[REJECT]_ The message's validator index is within the payload committee in `get_ptc(state, data.slot)`. The `state` is the head state corresponding to processing the block up to the current slot as determined by the fork choice. -- _[REJECT]_ The message's signature of `payload_attestation_message.signature` is valid with respect to the validator index. - +- _[IGNORE]_ The message's slot is for the current slot (with a `MAXIMUM_GOSSIP_CLOCK_DISPARITY` allowance), i.e. `data.slot == current_slot`. +- _[REJECT]_ The message's payload status is a valid status, i.e. `data.payload_status < PAYLOAD_INVALID_STATUS`. +- _[IGNORE]_ The `payload_attestation_message` is the first valid message received from the validator with index `payload_attestation_message.validate_index`. +- _[IGNORE]_ The message's block `data.beacon_block_root` has been seen (via both gossip and non-gossip sources) (a client MAY queue attestation for processing once the block is retrieved. Note a client might want to request payload after). +- _[REJECT]_ The message's block `data.beacon_block_root` passes validation. +- _[REJECT]_ The message's validator index is within the payload committee in `get_ptc(state, data.slot)`. The `state` is the head state corresponding to processing the block up to the current slot as determined by the fork choice. +- _[REJECT]_ The message's signature of `payload_attestation_message.signature` is valid with respect to the validator index. + ###### `execution_payload_header` This topic is used to propagate signed bids as `SignedExecutionPayloadHeader`. @@ -182,8 +187,8 @@ The following validations MUST pass before forwarding the `signed_execution_payl - _[REJECT]_ The signed builder bid, `header.builder_index` is a valid, active, and non-slashed builder index in state. - _[IGNORE]_ The signed builder bid value, `header.value`, is less or equal than the builder's balance in state. i.e. `MIN_BUILDER_BALANCE + header.value < state.builder_balances[header.builder_index]`. - _[IGNORE]_ `header.parent_block_hash` is the block hash of a known execution payload in fork choice. -_ _[IGNORE]_ `header.parent_block_root` is the hash tree root of a known beacon block in fork choice. -- _[IGNORE]_ `header.slot` is the current slot or the next slot. +_ _[IGNORE]_ `header.parent_block_root` is the hash tree root of a known beacon block in fork choice. +- _[IGNORE]_ `header.slot` is the current slot or the next slot. - _[REJECT]_ The builder signature, `signed_execution_payload_header_envelope.signature`, is valid with respect to the `header_envelope.builder_index`. ### The Req/Resp domain @@ -220,7 +225,7 @@ Per `context = compute_fork_digest(fork_version, genesis_validators_root)`: | `BELLATRIX_FORK_VERSION` | `bellatrix.SignedBeaconBlock` | | `CAPELLA_FORK_VERSION` | `capella.SignedBeaconBlock` | | `DENEB_FORK_VERSION` | `deneb.SignedBeaconBlock` | -| `EIP7732_FORK_VERSION` | `eip7732.SignedBeaconBlock` | +| `EIP7732_FORK_VERSION` | `eip7732.SignedBeaconBlock` | ##### BlobSidecarsByRoot v2 diff --git a/specs/altair/p2p-interface.md b/specs/altair/p2p-interface.md index 5b0c938df7..f70e4e9b15 100644 --- a/specs/altair/p2p-interface.md +++ b/specs/altair/p2p-interface.md @@ -1,18 +1,12 @@ # Altair -- Networking -This document contains the networking specification for Altair. -This document should be viewed as additive to the [document from Phase 0](../phase0/p2p-interface.md) and will be referred to as the "Phase 0 document" hereafter. -Readers should understand the Phase 0 document and use it as a basis to understand the changes outlined in this document. - -Altair adds new messages, topics and data to the Req-Resp, Gossip and Discovery domain. Some Phase 0 features will be deprecated, but not removed immediately. - - ## Table of contents +- [Introduction](#introduction) - [Modifications in Altair](#modifications-in-altair) - [MetaData](#metadata) - [The gossip domain: gossipsub](#the-gossip-domain-gossipsub) @@ -39,6 +33,14 @@ Altair adds new messages, topics and data to the Req-Resp, Gossip and Discovery +## Introduction + +This document contains the networking specification for Altair. +This document should be viewed as additive to the [document from Phase 0](../phase0/p2p-interface.md) and will be referred to as the "Phase 0 document" hereafter. +Readers should understand the Phase 0 document and use it as a basis to understand the changes outlined in this document. + +Altair adds new messages, topics and data to the Req-Resp, Gossip and Discovery domain. Some Phase 0 features will be deprecated, but not removed immediately. + ## Modifications in Altair ### MetaData diff --git a/specs/bellatrix/p2p-interface.md b/specs/bellatrix/p2p-interface.md index 617f6f1fc7..1f4c815660 100644 --- a/specs/bellatrix/p2p-interface.md +++ b/specs/bellatrix/p2p-interface.md @@ -1,17 +1,12 @@ # Bellatrix -- Networking -This document contains the networking specification for the Bellatrix. - -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 + - [Introduction](#introduction) - [Modifications in Bellatrix](#modifications-in-bellatrix) - [The gossip domain: gossipsub](#the-gossip-domain-gossipsub) - [Topics and messages](#topics-and-messages) @@ -32,6 +27,14 @@ Readers should understand the Phase 0 and Altair documents and use them as a bas +## Introduction + +This document contains the networking specification for Bellatrix. + +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. + ## Modifications in Bellatrix ### The gossip domain: gossipsub @@ -146,7 +149,7 @@ Per `context = compute_fork_digest(fork_version, genesis_validators_root)`: With the addition of `ExecutionPayload` to `BeaconBlock`s, there is a dynamic field -- `transactions` -- which can validly exceed the `GOSSIP_MAX_SIZE` limit (1 MiB) put in -place at Phase 0, so GOSSIP_MAX_SIZE has increased to 10 Mib on the network. +place at Phase 0, so GOSSIP_MAX_SIZE has increased to 10 Mib on the network. At the `GAS_LIMIT` (~30M) currently seen on mainnet in 2021, a single transaction filled entirely with data at a cost of 16 gas per byte can create a valid `ExecutionPayload` of ~2 MiB. Thus we need a size limit to at least account for diff --git a/specs/capella/p2p-interface.md b/specs/capella/p2p-interface.md index a71b6479f1..25b2fb3b99 100644 --- a/specs/capella/p2p-interface.md +++ b/specs/capella/p2p-interface.md @@ -1,15 +1,12 @@ # Capella -- Networking -This document contains the networking specification for Capella. - -The specification of these changes continues in the same format as the network specifications of previous upgrades, and assumes them as pre-requisite. - ### Table of contents +- [Introduction](#introduction) - [Modifications in Capella](#modifications-in-capella) - [The gossip domain: gossipsub](#the-gossip-domain-gossipsub) - [Topics and messages](#topics-and-messages) @@ -25,6 +22,11 @@ The specification of these changes continues in the same format as the network s +## Introduction + +This document contains the networking specification for Capella. + +The specification of these changes continues in the same format as the network specifications of previous upgrades, and assumes them as pre-requisite. ## Modifications in Capella diff --git a/specs/deneb/p2p-interface.md b/specs/deneb/p2p-interface.md index 41e2fa9d3f..1c1bb56a00 100644 --- a/specs/deneb/p2p-interface.md +++ b/specs/deneb/p2p-interface.md @@ -1,15 +1,12 @@ # Deneb -- Networking -This document contains the consensus-layer networking specification for Deneb. - -The specification of these changes continues in the same format as the network specifications of previous upgrades, and assumes them as pre-requisite. - ## Table of contents +- [Introduction](#introduction) - [Modifications in Deneb](#modifications-in-deneb) - [Constant](#constant) - [Preset](#preset) @@ -41,6 +38,12 @@ The specification of these changes continues in the same format as the network s +## Introduction + +This document contains the consensus-layer networking specification for Deneb. + +The specification of these changes continues in the same format as the network specifications of previous upgrades, and assumes them as pre-requisite. + ## Modifications in Deneb ### Constant diff --git a/specs/electra/p2p-interface.md b/specs/electra/p2p-interface.md index fca877a8aa..494a4d9255 100644 --- a/specs/electra/p2p-interface.md +++ b/specs/electra/p2p-interface.md @@ -1,15 +1,12 @@ # Electra -- Networking -This document contains the consensus-layer networking specification for Electra. - -The specification of these changes continues in the same format as the network specifications of previous upgrades, and assumes them as pre-requisite. - ## Table of contents +- [Introduction](#introduction) - [Modifications in Electra](#modifications-in-electra) - [The gossip domain: gossipsub](#the-gossip-domain-gossipsub) - [Topics and messages](#topics-and-messages) @@ -21,6 +18,12 @@ The specification of these changes continues in the same format as the network s +## Introduction + +This document contains the consensus-layer networking specification for Electra. + +The specification of these changes continues in the same format as the network specifications of previous upgrades, and assumes them as pre-requisite. + ## Modifications in Electra ### The gossip domain: gossipsub diff --git a/specs/phase0/p2p-interface.md b/specs/phase0/p2p-interface.md index bc29b9ad92..f531f9fd2f 100644 --- a/specs/phase0/p2p-interface.md +++ b/specs/phase0/p2p-interface.md @@ -1,19 +1,11 @@ # Phase 0 -- Networking -This document contains the networking specification for Phase 0. - -It consists of four main sections: - -1. A specification of the network fundamentals. -2. A specification of the three network interaction *domains* of the proof-of-stake consensus layer: (a) the gossip domain, (b) the discovery domain, and (c) the Req/Resp domain. -3. The rationale and further explanation for the design choices made in the previous two sections. -4. An analysis of the maturity/state of the libp2p features required by this spec across the languages in which clients are being developed. - ## Table of contents +- [Introduction](#introduction) - [Network fundamentals](#network-fundamentals) - [Transport](#transport) - [Encryption and identification](#encryption-and-identification) @@ -114,6 +106,17 @@ It consists of four main sections: +## Introduction + +This document contains the networking specification for Phase 0. + +It consists of four main sections: + +1. A specification of the network fundamentals. +2. A specification of the three network interaction *domains* of the proof-of-stake consensus layer: (a) the gossip domain, (b) the discovery domain, and (c) the Req/Resp domain. +3. The rationale and further explanation for the design choices made in the previous two sections. +4. An analysis of the maturity/state of the libp2p features required by this spec across the languages in which clients are being developed. + ## Network fundamentals This section outlines the specification for the networking stack in Ethereum consensus-layer clients.