https://github.com/sigp/discv5
Rust implementation of Discovery v5
https://github.com/sigp/discv5
Last synced: 1 day ago
JSON representation
Rust implementation of Discovery v5
- Host: GitHub
- URL: https://github.com/sigp/discv5
- Owner: sigp
- License: apache-2.0
- Created: 2020-04-27T06:30:04.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2025-02-12T05:43:57.000Z (9 days ago)
- Last Synced: 2025-02-13T15:09:00.534Z (8 days ago)
- Language: Rust
- Size: 1.23 MB
- Stars: 169
- Watchers: 10
- Forks: 64
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-ethereum-rust - discv5
README
discv5
============
[![Build Status]][Build Link] [![Doc Status]][Doc Link] [![Crates
Status]][Crates Link]
[Build Status]: https://github.com/sigp/discv5/workflows/build/badge.svg?branch=master
[Build Link]: https://github.com/sigp/discv5/actions
[Doc Status]: https://docs.rs/discv5/badge.svg
[Doc Link]: https://docs.rs/discv5
[Crates Status]: https://img.shields.io/crates/v/discv5.svg
[Crates Link]: https://crates.io/crates/discv5
[Documentation at docs.rs](https://docs.rs/discv5)
# Overview
This is a rust implementation of the [Discovery v5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md)
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](https://eips.ethereum.org/EIPS/eip-778)), 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](https://github.com/AgeManning/discv5-cli)
# Usage
A simple example of creating this service is as follows:
```rust
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()
// 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);
});
```
# Addresses in ENRs
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:
1. When we receive an ENR we must decide whether to add it to our local routing
table and advertise it to other peers. If a node has put some
non-contactable address in the ENR (e.g `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.
2. For every new inbound connection, we do not wish to check that the address
given to us in an `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.
## How this protocol handles advertised IPs in ENRs
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:
1. If a connecting node provides an ENR without specifying an address (this
should be the default case for most nodes behind a NAT, or ones that have
just started) we consider this valid. Typically this will occur when a node
has yet to determine its external IP address via PONG responses and has not
updated its ENR to a contactable address. In this case, we respond to all
requests this peer asks for but we do not store or add its ENR to our
routing table.
2. If a peer connects to us with an ENR that specifies an IP address that
matches the src address we received the packet from, we consider this peer
valid and attempt to add it to our local routing table and therefore may advertise
its ENR to others.
3. If a peer connects to us with an ENR that specifies an IP address that does
not match the src socket it connects to us on (e.g `127.0.0.1`, or
potentially some internal subnet IP that is unreachable from our current
network) we consider this ENR invalid and will not add it to our routing
table. However we will still respond to discovery requests.