Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
ÐΞVp2p Wire Protocol
Clone this wiki locally
Peer-to-peer communications between nodes running Ethereum/Whisper/&c. clients are designed to be governed by a simple wire-protocol making use of existing ÐΞV technologies and standards such as RLP wherever practical.
This document is intended to specify this protocol comprehensively.
ÐΞVp2p nodes communicate by sending messages using RLPx, an encrypted and authenticated transport protocol. Peers are free to advertise and accept connections on any TCP ports they wish, however, a default port on which the connection may be listened and made will be 30303. Though TCP provides a connection-oriented medium, ÐΞVp2p nodes communicate in terms of packets. RLPx provides facilities to send and receive packets. For more information about RLPx, refer to the protocol specification.
ÐΞVp2p nodes find peers through the RLPx discovery protocol DHT. Peer connections can also be initiated by supplying the endpoint of a peer to a client-specific RPC API.
There are a number of different types of payload that may be encoded within the RLP. This ''type'' is always determined by the first entry of the RLP, interpreted as an integer.
ÐΞVp2p is designed to support arbitrary sub-protocols (aka capabilities) over the basic wire protocol. Each sub-protocol is given as much of the message-ID space as it needs (all such protocols must statically specify how many message IDs they require). On connection and reception of the
Hello message, both peers have equivalent information about what subprotocols they share (including versions) and are able to form consensus over the composition of message ID space.
Message IDs are assumed to be compact from ID 0x10 onwards (0x00-0x10 is reserved for ÐΞVp2p messages) and given to each shared (equal-version, equal name) sub-protocol in alphabetic order. Sub-protocols that are not shared are ignored. If multiple versions are shared of the same (equal name) sub-protocol, the numerically highest wins, others are ignored.
B_64] First packet sent over the connection, and sent once by both sides. No other messages may be sent until a Hello is received.
p2pVersionSpecifies the implemented version of the P2P protocol. Now must be 1.
clientIdSpecifies the client software identity, as a human-readable string (e.g. "Ethereum(++)/1.0.0").
capSpecifies a peer capability name as a length-3 ASCII string. Current supported capabilities are
capVersionSpecifies a peer capability version as a positive integer. Current supported versions are 34 for
eth, and 1 for
listenPortspecifies the port that the client is listening on (on the interface that the present connection traverses). If 0 it indicates the client is not listening.
nodeIdis the Unique Identity of the node and specifies a 512-bit hash that identifies this node.
P] Inform the peer that a disconnection is imminent; if received, a peer should disconnect immediately. When sending, well-behaved hosts give their peers a fighting chance (read: wait 2 seconds) to disconnect to before disconnecting themselves.
reasonis an optional integer specifying one of a number of reasons for disconnect:
0x01TCP sub-system error;
0x02Breach of protocol, e.g. a malformed message, bad RLP, incorrect magic number &c.;
0x04Too many peers;
0x06Incompatible P2P protocol version;
0x07Null node identity received - this is automatically invalid;
0x09Unexpected identity (i.e. a different identity to a previous connection/what a trusted peer told us).
0x0aIdentity is the same as this node (i.e. connected to itself);
0x0bTimeout on receiving a message (i.e. nothing received since sending last ping);
0x10Some other reason specific to a subprotocol.
0x02  Requests an immediate reply of
Pong from the peer.
0x03  Reply to peer's
NotImplemented (was GetPeers)
NotImplemented (was Peers)
Node identity and reputation
The identity of a ÐΞVp2p node is a secp256k1 public key.
Nodes are free to store ratings for given IDs (how useful the node has been in the past) and give preference accordingly. Nodes may also track node IDs (and their provenance) in order to help determine potential man-in-the-middle attacks. Clients are free to mark down new nodes and use the node ID as a means of determining a node's reputation.
Upon connecting, all clients (i.e. both sides of the connection) must send a
Hello message. Upon receiving the
Hello message and verifying compatibility of the network and versions, a session is active and any other P2P messages may be sent.
At any time, a Disconnect message may be sent.