zebrad: document Inbound, ChainSync responsibilities

zebrad/src/components.rs

@@ -1,3 +1,10 @@
+//! Holds components of a Zebra node.
+//!
+//! Some, but not all, of these components are structured as Abscissa components,
+//! while the others are just ordinary structures. This is because Abscissa's
+//! component and dependency injection models are designed to work together, but
+//! don't fit the async context well.
+
 mod inbound;
 pub mod metrics;
 mod sync;

zebrad/src/components/inbound.rs

@@ -21,6 +21,27 @@ type State = Buffer<BoxService<zs::Request, zs::Response, zs::BoxError>, zs::Req
 
 pub type SetupData = (Outbound, Arc<Mutex<AddressBook>>);
 
+/// Uses the node state to respond to inbound peer requests.
+///
+/// This service, wrapped in appropriate middleware, is passed to
+/// `zebra_network::init` to respond to inbound peer requests.
+///
+/// The `Inbound` service is responsible for:
+///
+/// - supplying network data like peer addresses to other nodes;
+/// - supplying chain data like blocks to other nodes;
+/// - performing transaction diffusion;
+/// - performing block diffusion.
+///
+/// Because the `Inbound` service is responsible for participating in the gossip
+/// protocols used for transaction and block diffusion, there is a potential
+/// overlap with the `ChainSync` component.
+///
+/// The division of responsibility is that the `ChainSync` component is
+/// *internally driven*, periodically polling the network to check whether it is
+/// behind the current tip, while the `Inbound` service is *externally driven*,
+/// responding to block gossip by attempting to download and validate advertised
+/// blocks.
 pub struct Inbound {
     // invariant: outbound, address_book are Some if network_setup is None
     //

zebrad/src/components/sync.rs

@@ -128,6 +128,12 @@ where
     genesis_hash: block::Hash,
 }
 
+/// Polls the network to determine whether further blocks are available and
+/// downloads them.
+///
+/// This component is used for initial block sync, but the `Inbound` service is
+/// responsible for participating in the gossip protocols used for block
+/// diffusion.
 impl<ZN, ZS, ZV> ChainSync<ZN, ZS, ZV>
 where
     ZN: Service<zn::Request, Response = zn::Response, Error = Error> + Send + Clone + 'static,