This is a rust implementation of the Discovery v5 peer discovery protocol.
Discovery v5 is a protocol designed for encrypted peer discovery. Each peer/node on the network is
identified via it's ENR
(Ethereum Node Record), which
is essentially a signed key-value store containing the node's public key and optionally IP address
and port.
Discv5 employs a kademlia-like routing table to store and manage discovered peers and topics. The protocol allows for external IP discovery in NAT environments through regular PING/PONG's with discovered nodes. Nodes return the external IP address that they have received and a simple majority is chosen as our external IP address. If an external IP address is updated, this is produced as an event to notify the swarm (if one is used for this behaviour).
For a simple CLI discovery service see discv5-cli
A simple example of creating this service is as follows:
use discv5::{enr, enr::{CombinedKey, NodeId}, TokioExecutor, Discv5, ConfigBuilder};
use discv5::socket::ListenConfig;
use std::net::SocketAddr;
// construct a local ENR
let enr_key = CombinedKey::generate_secp256k1();
let enr = enr::Enr::empty(&enr_key).unwrap();
// build the tokio executor
let mut runtime = tokio::runtime::Builder::new_multi_thread()
.thread_name("Discv5-example")
.enable_all()
.build()
.unwrap();
// configuration for the sockets to listen on
let listen_config = ListenConfig::Ipv4 {
ip: Ipv4Addr::UNSPECIFIED,
port: 9000,
};
// default configuration
let config = ConfigBuilder::new(listen_config).build();
// construct the discv5 server
let mut discv5: Discv5 = Discv5::new(enr, enr_key, config).unwrap();
// In order to bootstrap the routing table an external ENR should be added
// This can be done via add_enr. I.e.:
// discv5.add_enr(<ENR>)
// start the discv5 server
runtime.block_on(discv5.start());
// run a find_node query
runtime.block_on(async {
let found_nodes = discv5.find_node(NodeId::random()).await.unwrap();
println!("Found nodes: {:?}", found_nodes);
});
This protocol will drop messages (i.e not respond to requests) from peers that
advertise non-contactable address in their ENR (e.g 127.0.0.1
when connecting
to non-local nodes). This section
explains the rationale behind this design decision.
An ENR is a signed record which is primarily used in this protocol for
identifying and connecting to peers. ENRs have OPTIONAL ip
and port
fields.
If a node does not know its contactable address (i.e if it is behind a NAT), it should leave these fields empty. This is done for the following reasons:
127.0.0.1
when connecting to
non-local nodes) we cannot use this ENR
to contact the node and we therefore do not wish to advertise it to other
nodes. Putting a non-contactable address is therefore functionally
equivalent to leaving the fields empty.ENR
is contactable. We do not want the scenario, where
any peer can give us any address and force us to attempt a connection to
arbitrary addresses (to check their validity) as it consumes unnecessary
bandwidth and we want to avoid DOS attacks where malicious users spam many
nodes attempting them all to send messages to a victim IP.To handle the above two cases this protocol filters out and only advertises contactable ENRs. It doesn't make sense for a discovery protocol to advertise non-contactable peers.
This is done in the following way:
127.0.0.1
, or
potentially some internal subnet IP that is unreachable from our current
network) we consider this peer malicious/faulty
and drop all packets. This way we can efficiently drop peers that may try to
get us to send messages to arbitrary remote IPs, and we can be sure that all
ENRs in our routing table are contactable (at least by our local node at
some point in time).