diff --git a/zebrad/src/components/mempool/downloads.rs b/zebrad/src/components/mempool/downloads.rs index b284897a..e4289a65 100644 --- a/zebrad/src/components/mempool/downloads.rs +++ b/zebrad/src/components/mempool/downloads.rs @@ -1,3 +1,26 @@ +//! Transaction downloader and verifier. +//! +//! The main struct [`Downloads`] allows downloading and verifying transactions. +//! It is used by the mempool to get transactions into it. It is also able to +//! just verify transactions that were directly pushed. +//! +//! The verification itself is done by the [`zebra_consensus`] crate. +//! +//! Verified transactions are returned to the caller in [`Downloads::poll_next`]. +//! This is in contrast to the block downloader and verifiers which don't +//! return anything and forward the verified blocks to the state themselves. +//! +//! # Correctness +//! +//! The mempool downloader doesn't send verified transactions to the [`Mempool`] service. +//! So Zebra must spawn a task that regularly polls the downloader for ready transactions. +//! (To ensure that transactions propagate across the entire network in each 75s block interval, +//! the polling interval should be around 5-10 seconds.) +//! +//! Polling the downloader from [`Mempool::poll_ready`] is not sufficient. +//! [`Service::poll_ready`] is only called when there is a service request. +//! But we want to download and gossip transactions, +//! even when there are no other service requests. use std::{ collections::{HashMap, HashSet}, pin::Pin, @@ -204,8 +227,11 @@ where ZS: Service + Send + Clone + 'static, ZS::Future: Send, { - /// Initialize a new download stream with the provided `network` and - /// `verifier` services. + /// Initialize a new download stream with the provided services. + /// + /// `network` is used to download transactions. + /// `verifier` is used to verify transactions. + /// `state` is used to check if transactions are already in the state. /// /// The [`Downloads`] stream is agnostic to the network policy, so retry and /// timeout limits should be applied to the `network` service passed into