discv5

The protocol manages ENRs with optional ip and port fields to handle nodes behind NATs and prevent DoS attacks. The protocol filters and only advertises contactable ENRs based on the following logic:

1. Empty Address ENRs: If a node provides an ENR without an address (common for nodes behind NAT that haven't determined their external IP), the node is considered valid. The server responds to its requests but does not add the ENR to the local routing table.
2. Matching Address ENRs: If the IP address in the ENR matches the source address (src) from which the packet was received, the ENR is considered valid and is added to the local routing table (and may be advertised to others).
3. Mismatched Address ENRs: If the ENR specifies an IP that does not match the source socket (e.g., 127.0.0.1 or an unreachable internal subnet), the ENR is considered invalid. The server will not add it to the routing table but will still respond to discovery requests.

To use discv5, you need to generate a local ENR key, configure the listening socket, build a configuration using ConfigBuilder, and then initialize the Discv5 server. You can then start the server and perform queries like find_node using an async runtime like tokio.

Note: To bootstrap the routing table, you should manually add an external ENR using discv5.add_enr(<ENR>).

   use discv5::{enr, enr::{CombinedKey, NodeId}, TokioExecutor, Discv5, ConfigBuilder};
   use discv5::socket::ListenConfig;
   use std::net::{SocketAddr, Ipv4Addr};

   // 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);
   });

A KBucket is a collection of up to MAX_NODES_PER_BUCKET (16) nodes, ordered from least-recently connected to most-recently connected. It manages node connectivity states, handles pending insertions when the bucket is full, and enforces limits on incoming connections.

Key Concepts

• Node Ordering: Nodes are stored such that disconnected nodes appear first, followed by connected nodes. The first_connected_pos index marks the boundary between these two groups.
• Pending Nodes: If a bucket is full and a new connected node is encountered, the node can be marked as Pending. It becomes eligible for insertion after a specified pending_timeout if the least-recently connected node is not re-established as connected.
• Connection Limits: You can restrict the number of incoming connections per bucket using the max_incoming parameter during initialization.
• Filtering: KBucket supports an optional Filter to validate new entries against existing ones.

// Example initialization
let mut bucket = KBucket::new(
    Duration::from_secs(30), // pending_timeout
    8,                       // max_incoming
    None                     // filter
);

To use discv5, you need to generate a local ENR, configure your listening socket, and provide a tokio runtime. The service manages a Kademlia-like routing table and allows you to perform queries like find_node.

Note that discv5 requires a tokio runtime with timing and IO enabled. If you do not provide an explicit Executor via ConfigBuilder, the library will attempt to use the existing tokio runtime; if none is found, the Discv5::new call will panic.

    use discv5::{enr, enr::{CombinedKey, Enr, NodeId}, TokioExecutor, Discv5, ConfigBuilder};
    use discv5::socket::ListenConfig;
    use std::net::{Ipv4Addr, 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);
    });

The Discv5 struct is the primary interface for running a Discovery v5 server.

Initialization

To create a new instance, use Discv5::new. You must provide:

• local_enr: The local node's ENR.
• enr_key: The CombinedKey used to sign the ENR. The public key in this keypair must match the public key in the ENR.
• config: A Config object (typically built via ConfigBuilder).

If no executor is provided in the Config, the service defaults to using a TokioExecutor.

Lifecycle

1. Start: Call start() to spawn the background service tasks and begin listening on the configured UDP socket.
2. Shutdown: Call shutdown() to terminate the service. The Discv5 struct also implements Drop, so it will attempt to shut down automatically when it goes out of scope.

Note: start() will return an error if the service is already running.

let sk = CombinedKey::generate_secp256k1();
let enr = Enr::builder().build(&sk).unwrap();
let config = ConfigBuilder::new(ListenConfig::default()).build();

let mut discv5 = Discv5::new(enr, sk, config).unwrap();
discv5.start().await.unwrap();

// ... use service ...

discv5.shutdown();