From f227e026fa295cc6a90c70f6eb04ab96810a8503 Mon Sep 17 00:00:00 2001 From: Age Manning Date: Mon, 23 Mar 2020 16:22:13 +1100 Subject: [PATCH 1/3] Draft PING and ENR rpc protocol --- specs/phase0/p2p-interface.md | 63 +++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/specs/phase0/p2p-interface.md b/specs/phase0/p2p-interface.md index fbbcb088e..acd3fc8c0 100644 --- a/specs/phase0/p2p-interface.md +++ b/specs/phase0/p2p-interface.md @@ -601,6 +601,69 @@ Clients MUST support requesting blocks since the latest finalized epoch. Clients MUST respond with at least one block, if they have it. Clients MAY limit the number of blocks in the response. +#### Ping + +**Protocol ID:** `/eth2/beacon_chain/req/ping/1/` + +Request Content: + +``` +( + uint64 +) +``` + +Response Content: + +``` +( + uint64 +) +``` + +Sent intermittently, the PING protocol checks liveness of connected peers. +Peers send and respond with their local ENR sequence number. + +A client may then determine if their local record of a peer's ENR is up to date +and may request an updated version via the ENR RPC method if not. + +The request MUST be encoded as an SSZ-field. + +The response MUST consist of a single `response_chunk`. + +#### Enr + +**Protocol ID:** `/eth2/beacon_chain/req/enr/1/` + +No Request Content. + + +Response Content: + +``` +( + enr: Bytes, + subnet_expiries: []Slot +) +``` + +Requests the ENR of a peer. The request opens and negotiates the stream without +sending any request content. Once established the receiving peer responds with +it's local up-to-date ENR along with a list of `Slot` corresponding to +the expiry of all long-lived subnets specified by the `attnets` field in the +sent ENR. + +The `subnet_expiries` list MUST have a length corresponding to the number of +true values in the `attnets` bitfield. The order of the slots in `subnet_expiries` +MUST correspond to the order of long-lived subnets specified in the `attnets` +bitfield. + +The `enr` field represents the rlp-encoded bytes of the local ENR. + +The response MUST be encoded as an SSZ-container. + +The response MUST consist of a single `response_chunk`. + ## The discovery domain: discv5 Discovery Version 5 ([discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md)) is used for peer discovery, both in the interoperability testnet and mainnet. From d5a9af6469754da2ba4d1ede8650463b212955be Mon Sep 17 00:00:00 2001 From: Danny Ryan Date: Wed, 25 Mar 2020 11:57:37 -0600 Subject: [PATCH 2/3] update ping protocol to use MetaData --- specs/phase0/p2p-interface.md | 56 ++++++++++++++++++++++------------- specs/phase0/validator.md | 2 +- 2 files changed, 36 insertions(+), 22 deletions(-) diff --git a/specs/phase0/p2p-interface.md b/specs/phase0/p2p-interface.md index acd3fc8c0..0c436f057 100644 --- a/specs/phase0/p2p-interface.md +++ b/specs/phase0/p2p-interface.md @@ -28,6 +28,7 @@ It consists of four main sections: - [Multiplexing](#multiplexing) - [Eth2 network interaction domains](#eth2-network-interaction-domains) - [Configuration](#configuration) + - [MetaData](#metadata) - [The gossip domain: gossipsub](#the-gossip-domain-gossipsub) - [Topics and messages](#topics-and-messages) - [Global topics](#global-topics) @@ -49,6 +50,8 @@ It consists of four main sections: - [Goodbye](#goodbye) - [BeaconBlocksByRange](#beaconblocksbyrange) - [BeaconBlocksByRoot](#beaconblocksbyroot) + - [Ping](#ping) + - [GetMetaData](#getmetadata) - [The discovery domain: discv5](#the-discovery-domain-discv5) - [Integration into libp2p stacks](#integration-into-libp2p-stacks) - [ENR structure](#enr-structure) @@ -195,6 +198,22 @@ This section outlines constants that are used in this spec. | `ATTESTATION_PROPAGATION_SLOT_RANGE` | `32` | The maximum number of slots during which an attestation can be propagated. | | `MAXIMUM_GOSSIP_CLOCK_DISPARITY` | `500ms` | The maximum milliseconds of clock disparity assumed between honest nodes. | +## MetaData + +Clients MUST locally store the following `MetaData`: + +``` +( + seq_number: uint64 + attnets: Bitvector[ATTESTATION_SUBNET_COUNT] +) +``` + +Where + +- `seq_number` is a `uint64` starting at `0` used to version the node's metadata. If any other field in the local `MetaData` changes, the node MUST increment `seq_number` by 1. +- `attnets` is a `Bitvector` representing the node's persistent attestation subnet subscriptions. + ## The gossip domain: gossipsub Clients MUST support the [gossipsub](https://github.com/libp2p/specs/tree/master/pubsub/gossipsub) libp2p protocol. @@ -621,44 +640,35 @@ Response Content: ) ``` -Sent intermittently, the PING protocol checks liveness of connected peers. -Peers send and respond with their local ENR sequence number. +Sent intermittently, the `Ping` protocol checks liveness of connected peers. +Peers send and respond with their local metadata sequence number (`MetaData.seq_number`). -A client may then determine if their local record of a peer's ENR is up to date -and may request an updated version via the ENR RPC method if not. +If the peer does not respond to the `Ping` request, the client MAY disconnect from the peer. + +A client can then determine if their local record of a peer's MetaData is up to date +and MAY request an updated version via the `MetaData` RPC method if not. The request MUST be encoded as an SSZ-field. The response MUST consist of a single `response_chunk`. -#### Enr +#### GetMetaData -**Protocol ID:** `/eth2/beacon_chain/req/enr/1/` +**Protocol ID:** `/eth2/beacon_chain/req/metadata/1/` No Request Content. - Response Content: ``` ( - enr: Bytes, - subnet_expiries: []Slot + MetaData ) ``` -Requests the ENR of a peer. The request opens and negotiates the stream without +Requests the MetaData of a peer. The request opens and negotiates the stream without sending any request content. Once established the receiving peer responds with -it's local up-to-date ENR along with a list of `Slot` corresponding to -the expiry of all long-lived subnets specified by the `attnets` field in the -sent ENR. - -The `subnet_expiries` list MUST have a length corresponding to the number of -true values in the `attnets` bitfield. The order of the slots in `subnet_expiries` -MUST correspond to the order of long-lived subnets specified in the `attnets` -bitfield. - -The `enr` field represents the rlp-encoded bytes of the local ENR. +it's local most up-to-date MetaData. The response MUST be encoded as an SSZ-container. @@ -693,12 +703,16 @@ Specifications of these parameters can be found in the [ENR Specification](http: #### Attestation subnet bitfield -The ENR MAY contain an entry (`attnets`) signifying the attestation subnet bitfield with the following form to more easily discover peers participating in particular attestation gossip subnets. +The ENR `attnets` entry signifies the attestation subnet bitfield with the following form to more easily discover peers participating in particular attestation gossip subnets. | Key | Value | |:-------------|:-------------------------------------------------| | `attnets` | SSZ `Bitvector[ATTESTATION_SUBNET_COUNT]` | +If a node's `MetaData.attnets` has any non-zero bit, the ENR MUST include the `attnets` entry with the same value as `MetaData.attnets`. + +If a node's `MetaData.attnets` is composed of all zeros, the ENR MAY optionally include the `attnets` entry or leave it out entirely. + #### Interop In the interoperability testnet, all peers will support all capabilities defined in this document (gossip, full Req/Resp suite, discovery protocol), therefore the ENR record does not need to carry Eth2 capability information, as it would be superfluous. diff --git a/specs/phase0/validator.md b/specs/phase0/validator.md index 54cd19a93..bbed14ec2 100644 --- a/specs/phase0/validator.md +++ b/specs/phase0/validator.md @@ -202,7 +202,7 @@ Specifically a validator should: * Call `get_committee_assignment(state, next_epoch, validator_index)` when checking for next epoch assignments. * Join the pubsub topic -- `committee_index{committee_index % ATTESTATION_SUBNET_COUNT}_beacon_attestation`. * For any current peer subscribed to the topic, the validator simply sends a `subscribe` message for the new topic. - * If an _insufficient_ number of current peers are subscribed to the topic, the validator must discover new peers on this topic. Via the discovery protocol, find peers with an ENR containing the `attnets` entry such that `ENR["attnets"][committee_index % ATTESTATION_SUBNET_COUNT] == True`. + * If an _insufficient_ number of current peers are subscribed to the topic, the validator must discover new peers on this topic. Via the discovery protocol, find peers with an ENR containing the `attnets` entry such that `ENR["attnets"][committee_index % ATTESTATION_SUBNET_COUNT] == True`. Then validate that the peers are still persisted on the desired topic by sending a `GetMetaData` and checking the resulting `attnets` field. ## Beacon chain responsibilities From ee45cf77ef439df5b7ca47f52ff4f755e4902603 Mon Sep 17 00:00:00 2001 From: Danny Ryan Date: Thu, 26 Mar 2020 07:47:20 -0600 Subject: [PATCH 3/3] proto feedback on MetaData --- specs/phase0/p2p-interface.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/specs/phase0/p2p-interface.md b/specs/phase0/p2p-interface.md index 0c436f057..4acd58bb2 100644 --- a/specs/phase0/p2p-interface.md +++ b/specs/phase0/p2p-interface.md @@ -214,6 +214,8 @@ Where - `seq_number` is a `uint64` starting at `0` used to version the node's metadata. If any other field in the local `MetaData` changes, the node MUST increment `seq_number` by 1. - `attnets` is a `Bitvector` representing the node's persistent attestation subnet subscriptions. +*Note*: `MetaData.seq_number` is used for versioning of the node's metadata, is entirely independent of the ENR sequence number, and will in most cases be out of sync with the ENR sequence number. + ## The gossip domain: gossipsub Clients MUST support the [gossipsub](https://github.com/libp2p/specs/tree/master/pubsub/gossipsub) libp2p protocol. @@ -641,7 +643,7 @@ Response Content: ``` Sent intermittently, the `Ping` protocol checks liveness of connected peers. -Peers send and respond with their local metadata sequence number (`MetaData.seq_number`). +Peers request and respond with their local metadata sequence number (`MetaData.seq_number`). If the peer does not respond to the `Ping` request, the client MAY disconnect from the peer.