From 01060df459ea9da7b74de8d552d267835e8d324c Mon Sep 17 00:00:00 2001 From: Pierre Krieger Date: Wed, 10 Jul 2019 10:01:56 +0200 Subject: [PATCH] Some documentation for discovery.rs (#3024) * Some documentation for discovery.rs * Typos * Address concerns * Fix doc after imports --- substrate/core/network/src/discovery.rs | 44 +++++++++++++++++++++++-- 1 file changed, 42 insertions(+), 2 deletions(-) diff --git a/substrate/core/network/src/discovery.rs b/substrate/core/network/src/discovery.rs index 30777c0c22..27c3982734 100644 --- a/substrate/core/network/src/discovery.rs +++ b/substrate/core/network/src/discovery.rs @@ -14,6 +14,38 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +//! Discovery mechanisms of Substrate. +//! +//! The `DiscoveryBehaviour` struct implements the `NetworkBehaviour` trait of libp2p and is +//! responsible for discovering other nodes that are part of the network. +//! +//! Substrate uses the following mechanisms in order to discover nodes that are part of the network: +//! +//! - Bootstrap nodes. These are hard-coded node identities and addresses passed in the constructor +//! of the `DiscoveryBehaviour`. You can also call `add_known_address` later to add an entry. +//! +//! - mDNS. As of the writing of this documentation, mDNS is handled somewhere else. It is planned +//! to be moved here. +//! +//! - Kademlia random walk. Once connected, we perform random Kademlia `FIND_NODE` requests in +//! order for nodes to propagate to us their view of the network. This is performed automatically +//! by the `DiscoveryBehaviour`. +//! +//! Additionally, the `DiscoveryBehaviour` is also capable of storing and loading value in the +//! network-wide DHT. +//! +//! ## Usage +//! +//! The `DiscoveryBehaviour` generates events of type `DiscoveryOut`, most notably +//! `DiscoveryOut::Discovered` that is generated whenever we discover a node. +//! Only the identity of the node is returned. The node's addresses are stored within the +//! `DiscoveryBehaviour` and can be queried through the `NetworkBehaviour` trait. +//! +//! **Important**: In order for the discovery mechanism to work properly, there needs to be an +//! active mechanism that asks nodes for the addresses they are listening on. Whenever we learn +//! of a node's address, you must call `add_self_reported_address`. +//! + use futures::prelude::*; use libp2p::core::{Multiaddr, PeerId, ProtocolsHandler, PublicKey}; use libp2p::core::swarm::{ConnectedPoint, NetworkBehaviour, NetworkBehaviourAction}; @@ -88,17 +120,25 @@ impl DiscoveryBehaviour { } /// Call this method when a node reports an address for itself. + /// + /// **Note**: It is important that you call this method, otherwise the discovery mechanism will + /// not properly work. pub fn add_self_reported_address(&mut self, peer_id: &PeerId, addr: Multiaddr) { self.kademlia.add_address(peer_id, addr); } - /// Get a record from the DHT. + /// Start fetching a record from the DHT. + /// + /// A corresponding `ValueFound` or `ValueNotFound` event will later be generated. pub fn get_value(&mut self, key: &Multihash) { self.kademlia.get_value(key, NonZeroU8::new(10) .expect("Casting 10 to NonZeroU8 should succeed; qed")); } - /// Put a record into the DHT. + /// Start putting a record into the DHT. Other nodes can later fetch that value with + /// `get_value`. + /// + /// A corresponding `ValuePut` or `ValuePutFailed` event will later be generated. pub fn put_value(&mut self, key: Multihash, value: Vec) { self.kademlia.put_value(key, value); }