diff --git a/zebrad/src/components.rs b/zebrad/src/components.rs index a6861489..1b78d397 100644 --- a/zebrad/src/components.rs +++ b/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; diff --git a/zebrad/src/components/inbound.rs b/zebrad/src/components/inbound.rs index a811b4d8..299cf176 100644 --- a/zebrad/src/components/inbound.rs +++ b/zebrad/src/components/inbound.rs @@ -21,6 +21,27 @@ type State = Buffer, zs::Req pub type SetupData = (Outbound, Arc>); +/// 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 // diff --git a/zebrad/src/components/sync.rs b/zebrad/src/components/sync.rs index 912c7a6b..ee06e5dc 100644 --- a/zebrad/src/components/sync.rs +++ b/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 ChainSync where ZN: Service + Send + Clone + 'static,