From 128b8be95da64b02870470b06c3ae5266b4a8bc5 Mon Sep 17 00:00:00 2001 From: Conrado Gouvea Date: Mon, 18 Oct 2021 17:02:40 -0300 Subject: [PATCH] Improve mempool::downloads documentation (#2879) * Improve mempool::downloads documentation * Apply suggestions from code review Co-authored-by: teor Co-authored-by: Alfredo Garcia Co-authored-by: teor Co-authored-by: Alfredo Garcia --- zebrad/src/components/mempool/downloads.rs | 30 ++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) 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