diff --git a/specs/networking/libp2p-standardization.md b/specs/networking/libp2p-standardization.md index 126ed53b4..c5add549a 100644 --- a/specs/networking/libp2p-standardization.md +++ b/specs/networking/libp2p-standardization.md @@ -9,6 +9,57 @@ configuration and messaging formats. # Libp2p Protocols +## Transport + +This section details the libp2p transport layer that underlies the +[protocols](#protocols) that are listed in this document. + +Libp2p allows composition of multiple transports. Eth2.0 clients should support +TCP/IP and optionally websockets. Websockets are useful for implementations +running in the browser and therefore native clients would ideally support these implementations +by supporting websockets. + +An ideal libp2p transport would therefore be TCP/IP with a fallback to +websockets. + +### Encryption + +Libp2p currently offers [Secio](https://github.com/libp2p/specs/pull/106) which +can upgrade a transport which will then encrypt all future communication. Secio +generates a symmetric ephemeral key which peers use to encrypt their +communication. It can support a range of ciphers and currently supports key +derivation for elliptic curve-based public keys. + +Current defaults are: +- Key agreement: `ECDH-P256` (also supports `ECDH-P384`) +- Cipher: `AES-128` (also supports `AES-256`, `TwofishCTR`) +- Digests: `SHA256` (also supports `SHA512`) + + +## Protocols + +This section lists the necessary libp2p protocols required by Ethereum 2.0 +running a libp2p network stack. + +## Multistream-select + +#### Protocol id: `/multistream/1.0.0` + +Clients running libp2p should support the [multistream-select](https://github.com/multiformats/multistream-select/) +protocol which allows clients to negotiate libp2p protocols establish streams +per protocol. + +## Multiplexing + +Libp2p allows clients to compose multiple multiplexing methods. Clients should +support [mplex](https://github.com/libp2p/specs/tree/master/mplex) and +optionally [yamux](https://github.com/hashicorp/yamux/blob/master/spec.md) +(these can be composed). + +**Mplex protocol id: `/mplex/6.7.0`** + +**Yamux protocol id: `/yamux/1.0.0`** + ## Gossipsub #### Protocol id: `/meshsub/1.0.0` @@ -70,11 +121,14 @@ number of shard subnets will be defined via `SHARD_SUBNET_COUNT` and the shard ### Messages -Messages sent across gossipsub are fixed-size length-prefixed byte arrays. -Each message has a maximum size of 512KB (estimated from expected largest uncompressed -block size). +#### Libp2p Specification -The byte array is prefixed with a unsigned 64 bit length number encoded as an +*This section simply outlines the data sent across the wire as specified by +libp2p - this section is aimed at gossipsub implementers to standardize their implementation of this protocol* + +Libp2p raw gossipsub messages are sent across the wire as fixed-size length-prefixed byte arrays. + +The byte array is prefixed with an unsigned 64 bit length number encoded as an `unsigned varint` (https://github.com/multiformats/unsigned-varint). Gossipsub messages therefore take the form: ``` +--------------------------+ @@ -86,7 +140,17 @@ The byte array is prefixed with a unsigned 64 bit length number encoded as an +--------------------------+ ``` -The body of the message is an SSZ-encoded object. For the `beacon_block` topic, +The body represents a protobuf-encoded [Message](https://github.com/libp2p/go-libp2p-pubsub/blob/master/pb/rpc.proto#L17-L24). + +In the following section we discuss the data being sent in the `data` field of +the protobuf gossipsub `Message`. + +#### Eth2.0 Specifics + +Each message has a maximum size of 512KB (estimated from expected largest uncompressed +block size). + +The `data` that is sent in a Gossipsub message is an SSZ-encoded object. For the `beacon_block` topic, this will be a `beacon_block`. For the `beacon_attestation` topic, this will be an `attestation`. @@ -100,6 +164,9 @@ The [RPC Interface](./rpc-interface.md) is specified in this repository. #### Protocol Id: `/ipfs/id/1.0.0` (to be updated to `/p2p/id/1.0.0`) +*To be updated to incorporate discv5* + + The Identify protocol (defined in go - [identify-go](https://github.com/ipfs/go-ipfs/blob/master/core/commands/id.go) and rust [rust-identify](https://github.com/libp2p/rust-libp2p/blob/master/protocols/identify/src/lib.rs)) allows a node A to query another node B which information B knows about A. This also includes the addresses B is listening on. @@ -120,4 +187,6 @@ type of connecting node. Suggested format: #### Protocol Id: `/eth/serenity/disc/1.0.0` +*To be updated to incorporate discv5* + The discovery protocol to be determined.