Merge branch 'v011x' into publish-vs-subscribe

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,24 @@ 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.
+
+*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.
@@ -601,6 +622,60 @@ 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 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.
+
+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`.
+
+#### GetMetaData
+
+**Protocol ID:** `/eth2/beacon_chain/req/metadata/1/`
+
+No Request Content.
+
+Response Content:
+
+```
+(
+  MetaData
+)
+```
+
+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 most up-to-date MetaData.
+
+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.
@@ -633,12 +708,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.

specs/phase0/validator.md

@@ -201,7 +201,7 @@ The beacon chain shufflings are designed to provide a minimum of 1 epoch lookahe
 Specifically a validator should:
 * Call `get_committee_assignment(state, next_epoch, validator_index)` when checking for next epoch assignments.
 * Find peers of the pubsub topic `committee_index{committee_index % ATTESTATION_SUBNET_COUNT}_beacon_attestation`.
-    * 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 requesting `GetMetaData` and checking the resulting `attnets` field.
     * If the validator is assigned to be an aggregator for the slot (see `is_aggregator()`), then subscribe to the topic.
 
 *Note*: If the validator is _not_ assigned to be an aggregator, the validator only needs sufficient number of peers on the topic to be able to publish messages. The validator does not need to _subscribe_ and listen to all messages on the topic.