Phase 0 Networking Specifications

specs/networking/messaging.md

@@ -0,0 +1,44 @@
+ETH 2.0 Networking Spec - Messaging
+===
+
+# Abstract
+
+This specification describes how individual Ethereum 2.0 messages are represented on the wire.
+
+The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL”, NOT", “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
+
+# Motivation
+
+This specification seeks to define a messaging protocol that is flexible enough to be changed easily as the ETH 2.0 specification evolves.
+
+# Specification
+
+## Message Structure
+
+An ETH 2.0 message consists of an envelope that defines the message's compression, encoding, and length followed by the body itself.
+
+Visually, a message looks like this:
+
+```
++--------------------------+
+|    compression nibble    |
++--------------------------+
+|    encoding nibble       |
++--------------------------+
+|  body length (uint64)    |
++--------------------------+
+|                          |
+|           body           |
+|                          |
++--------------------------+
+```
+
+Clients MUST ignore messages with mal-formed bodies. The compression/encoding nibbles MUST be one of the following values:
+
+## Compression Nibble Values
+
+- `0x0`: no compression
+
+## Encoding Nibble Values
+
+- `0x1`: SSZ

specs/networking/node-identification.md

@@ -0,0 +1,32 @@
+ETH 2.0 Networking Spec - Node Identification
+===
+
+# Abstract
+
+This specification describes how Ethereum 2.0 nodes identify and address each other on the network.
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL", NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
+
+# Specification
+
+Clients use Ethereum Node Records (as described in [EIP-778](http://eips.ethereum.org/EIPS/eip-778)) to discover one another. Each ENR includes, among other things, the following keys:
+
+- The node's IP.
+- The node's TCP port.
+- The node's public key.
+
+For clients to be addressable, their ENR responses MUST contain all of the above keys. Client MUST verify the signature of any received ENRs, and disconnect from peers whose ENR signatures are invalid. Each node's public key MUST be unique.
+
+The keys above are enough to construct a [multiaddr](https://github.com/multiformats/multiaddr) for use with the rest of the `libp2p` stack.
+
+It is RECOMMENDED that clients set their TCP port to the default of `9000`.
+
+## Peer ID Generation
+
+The `libp2p` networking stack identifies peers via a "peer ID." Simply put, a node's Peer ID is the SHA2-256 `multihash` of the node's public key struct (serialized in protobuf, refer to the [Peer ID spec](https://github.com/libp2p/specs/pull/100)). `go-libp2p-crypto` contains the canonical implementation of how to hash `secp256k1` keys for use as a peer ID.
+
+# See Also
+
+- [multiaddr](https://github.com/multiformats/multiaddr)
+- [multihash](https://multiformats.io/multihash/)
+- [go-libp2p-crypto](https://github.com/libp2p/go-libp2p-crypto)

specs/networking/rpc-interface.md

@@ -0,0 +1,257 @@
+ETH 2.0 Networking Spec - RPC Interface
+===
+
+# Abstract
+
+The Ethereum 2.0 networking stack uses two modes of communication: a broadcast protocol that gossips information to interested parties via GossipSub, and an RPC protocol that retrieves information from specific clients. This specification defines the RPC protocol.
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL", NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
+
+# Dependencies
+
+This specification assumes familiarity with the [Messaging](./messaging.md), [Node Identification](./node-identification), and [Beacon Chain](../core/0_beacon-chain.md) specifications.
+
+# Specification
+
+## Message Schemas
+
+Message body schemas are notated like this:
+
+```
+(
+    field_name_1: type
+    field_name_2: type
+)
+```
+
+Embedded types are serialized as SSZ Containers unless otherwise noted.
+
+All referenced data structures can be found in the [0-beacon-chain](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#data-structures) specification.
+
+## `libp2p` Protocol Names
+
+A "Protocol ID" in `libp2p` parlance refers to a human-readable identifier `libp2p` uses in order to identify sub-protocols and stream messages of different types over the same connection. Peers exchange supported protocol IDs via the `Identify` protocol upon connection. When opening a new stream, peers pin a particular protocol ID to it, and the stream remains contextualised thereafter. Since messages are sent inside a stream, they do not need to bear the protocol ID.
+
+## RPC-Over-`libp2p`
+
+To facilitate RPC-over-`libp2p`, a single protocol path is used: `/eth/serenity/beacon/rpc/1.0.0`. Remote method calls are wrapped in a "request" structure:
+
+```
+(
+    id: uint64
+    method_id: uint16
+    body: Request
+)
+```
+
+and their corresponding responses are wrapped in a "response" structure:
+
+```
+(
+    id: uint64
+    is_error: boolean
+    result: Response
+)
+```
+
+If an error occurs, a variant of the response structure is returned:
+
+```
+(
+    id: uint64
+    is_error: boolean
+    result: (
+        code: uint16
+        data: bytes
+    )
+)
+```
+
+The details of the RPC-Over-`libp2p` protocol are similar to [JSON-RPC 2.0](https://www.jsonrpc.org/specification). Specifically:
+
+1. The `id` member is REQUIRED.
+2. The `id` member in the response MUST be the same as the value of the `id` in the request.
+3. The `id` member MUST be unique within the context of a single connection. Monotonically increasing `id`s are RECOMMENDED.
+4. The `method_id` member is REQUIRED.
+5. The `result` member is required on success, and MUST NOT exist if there was an error.
+6. The `error` member is REQUIRED on errors, and MUST NOT exist if there wasn't an error.
+7. `is_error` MUST be `true` on errors, or `false` otherwise.
+
+Structuring RPC requests in this manner allows multiple calls and responses to be multiplexed over the same stream without switching. Note that this implies that responses MAY arrive in a different order than requests.
+
+The "method ID" fields in the below messages refer to the `method` field in the request structure above.
+
+The first 1,000 values in `error.code` are reserved for system use. The following error codes are predefined:
+
+1. `0`: Parse error.
+2. `10`: Invalid request.
+3. `20`: Method not found.
+4. `30`: Server error.
+
+## Messages
+
+### Hello
+
+**Method ID:** `0`
+
+**Body**:
+
+```
+(
+    network_id: uint8
+    latest_finalized_root: bytes32
+    latest_finalized_epoch: uint64
+    best_root: bytes32
+    best_slot: uint64
+)
+```
+
+Clients exchange `hello` messages upon connection, forming a two-phase handshake. The first message the initiating client sends MUST be the `hello` message. In response, the receiving client MUST respond with its own `hello` message.
+
+Clients SHOULD immediately disconnect from one another following the handshake above under the following conditions:
+
+1. If `network_id` belongs to a different chain, since the client definitionally cannot sync with this client.
+2. If the `latest_finalized_root` shared by the peer is not in the client's chain at the expected epoch. For example, if Peer 1 in the diagram below has `(root, epoch)` of `(A, 5)` and Peer 2 has `(B, 3)`, Peer 1 would disconnect because it knows that `B` is not the root in their chain at epoch 3:
+
+```
+              Root A
+
+              +---+
+              |xxx|  +----+ Epoch 5
+              +-+-+
+                ^
+                |
+              +-+-+
+              |   |  +----+ Epoch 4
+              +-+-+
+Root B          ^
+                |
++---+         +-+-+
+|xxx+<---+--->+   |  +----+ Epoch 3
++---+    |    +---+
+         |
+       +-+-+
+       |   |  +-----------+ Epoch 2
+       +-+-+
+         ^
+         |
+       +-+-+
+       |   |  +-----------+ Epoch 1
+       +---+
+```
+
+Once the handshake completes, the client with the higher `latest_finalized_epoch` or `best_slot` (if the clients have equal `latest_finalized_epoch`s) SHOULD request beacon block roots from its counterparty via `beacon_block_roots` (i.e., RPC method `10`).
+
+### Goodbye
+
+**Method ID:** `1`
+
+**Body:**
+
+```
+(
+    reason: uint64
+)
+```
+
+Client MAY send `goodbye` messages upon disconnection. The reason field MUST be one of the following values:
+
+- `1`: Client shut down.
+- `2`: Irrelevant network.
+- `3`: Too many peers.
+- `4`: Fault/error.
+
+### Request Beacon Block Roots
+
+**Method ID:** `10`
+
+**Request Body**
+
+```
+()
+```
+
+**Response Body:**
+
+```
+# BlockRootSlot
+(
+    block_root: bytes32
+    slot: uint64
+)
+
+(
+    roots: []BlockRootSlot
+)
+```
+
+Send a list of block roots and slots to the requesting peer.
+
+### Beacon Block Headers
+
+**Method ID:** `11`
+
+**Request Body**
+
+```
+(
+    start_root: HashTreeRoot
+    start_slot: uint64
+    max_headers: uint64
+    skip_slots: uint64
+)
+```
+
+**Response Body:**
+
+```
+(
+    headers: []BlockHeader
+)
+```
+
+Requests beacon block headers from the peer starting from `(start_root, start_slot)`. The response MUST contain no more than `max_headers` headers. `skip_slots` defines the maximum number of slots to skip between blocks. For example, requesting blocks starting at slots `2` a `skip_slots` value of `2` would return the blocks at `[2, 4, 6, 8, 10]`. In cases where a slot is empty for a given slot number, the closest previous block MUST be returned. For example, if slot `4` were empty in the previous example, the returned array would contain `[2, 3, 6, 8, 10]`. If slot three were further empty, the array would contain `[2, 6, 8, 10]` - i.e., duplicate blocks MUST be collapsed.
+
+The function of the `skip_slots` parameter helps facilitate light client sync - for example, in [#459](https://github.com/ethereum/eth2.0-specs/issues/459) - and allows clients to balance the peers from whom they request headers. Clients could, for instance, request every 10th block from a set of peers where each per has a different starting block in order to populate block data.
+
+### Beacon Block Bodies
+
+**Method ID:** `12`
+
+**Request Body:**
+
+```
+(
+    block_roots: []HashTreeRoot
+)
+```
+
+**Response Body:**
+
+```
+(
+    block_bodies: []BeaconBlockBody
+)
+```
+
+Requests the `block_bodies` associated with the provided `block_roots` from the peer. Responses MUST return `block_roots` in the order provided in the request. If the receiver does not have a particular `block_root`, it must return a zero-value `block_body` (i.e., a `block_body` container with all zero fields).
+
+### Beacon Chain State
+
+**Note:** This section is preliminary, pending the definition of the data structures to be transferred over the wire during fast sync operations.
+
+**Method ID:** `13`
+
+**Request Body:**
+
+```
+(
+    hashes: []HashTreeRoot
+)
+```
+
+**Response Body:** TBD
+
+Requests contain the hashes of Merkle tree nodes that when merkelized yield the block's `state_root`.
+
+The response will contain the values that, when hashed, yield the hashes inside the request body.