diff --git a/zebra-chain/src/lib.rs b/zebra-chain/src/lib.rs index 755cd48c..b529a5b4 100644 --- a/zebra-chain/src/lib.rs +++ b/zebra-chain/src/lib.rs @@ -6,6 +6,7 @@ #![doc(html_favicon_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-favicon-128.png")] #![doc(html_logo_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-icon.png")] #![doc(html_root_url = "https://doc.zebra.zfnd.org/zebra_chain")] +#![allow(rustdoc::private_intra_doc_links)] // Required by bitvec! macro #![recursion_limit = "256"] diff --git a/zebra-chain/src/transparent/utxo.rs b/zebra-chain/src/transparent/utxo.rs index ec17a704..f331619a 100644 --- a/zebra-chain/src/transparent/utxo.rs +++ b/zebra-chain/src/transparent/utxo.rs @@ -111,10 +111,8 @@ impl OrderedUtxo { /// A restriction that must be checked before spending a transparent output of a /// coinbase transaction. /// -/// TODO: fix the comment below because -/// [`CoinbaseSpendRestriction::check_spend`] doesn't exist. -/// -/// See [`CoinbaseSpendRestriction::check_spend`] for the consensus rules. +/// See the function `transparent_coinbase_spend` in `zebra-state` for the +/// consensus rules. #[derive(Copy, Clone, Debug, PartialEq, Eq)] #[cfg_attr( any(test, feature = "proptest-impl"), diff --git a/zebra-consensus/src/lib.rs b/zebra-consensus/src/lib.rs index 392971e1..43f1cbc7 100644 --- a/zebra-consensus/src/lib.rs +++ b/zebra-consensus/src/lib.rs @@ -33,6 +33,7 @@ #![doc(html_favicon_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-favicon-128.png")] #![doc(html_logo_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-icon.png")] #![doc(html_root_url = "https://doc.zebra.zfnd.org/zebra_consensus")] +#![allow(rustdoc::private_intra_doc_links)] mod block; mod checkpoint; diff --git a/zebra-network/src/isolated/tor.rs b/zebra-network/src/isolated/tor.rs index e9922511..b51113a0 100644 --- a/zebra-network/src/isolated/tor.rs +++ b/zebra-network/src/isolated/tor.rs @@ -96,9 +96,9 @@ async fn new_tor_stream(hostname: String) -> Result { Ok(tor_stream) } -/// Returns a new tor client instance, and updates [`SHARED_TOR_CLIENT`]. +/// Returns a new tor client instance, and updates [`struct@SHARED_TOR_CLIENT`]. /// -/// If there is a bootstrap error, [`SHARED_TOR_CLIENT`] is not modified. +/// If there is a bootstrap error, [`struct@SHARED_TOR_CLIENT`] is not modified. async fn new_tor_client() -> Result, BoxError> { let runtime = tokio::runtime::Handle::current(); let runtime = TokioRuntimeHandle::new(runtime); @@ -117,7 +117,7 @@ async fn new_tor_client() -> Result, BoxError> { Ok(tor_client) } -/// Returns an isolated tor client instance by cloning [`SHARED_TOR_CLIENT`]. +/// Returns an isolated tor client instance by cloning [`struct@SHARED_TOR_CLIENT`]. /// /// If [`new_tor_client`] has not run successfully yet, returns `None`. fn cloned_tor_client() -> Option> { diff --git a/zebra-network/src/lib.rs b/zebra-network/src/lib.rs index a8309fa4..172fe7f8 100644 --- a/zebra-network/src/lib.rs +++ b/zebra-network/src/lib.rs @@ -124,6 +124,7 @@ #![doc(html_favicon_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-favicon-128.png")] #![doc(html_logo_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-icon.png")] #![doc(html_root_url = "https://doc.zebra.zfnd.org/zebra_network")] +#![allow(rustdoc::private_intra_doc_links)] #[macro_use] extern crate pin_project; diff --git a/zebra-network/src/meta_addr.rs b/zebra-network/src/meta_addr.rs index 599585b5..be3b1ef4 100644 --- a/zebra-network/src/meta_addr.rs +++ b/zebra-network/src/meta_addr.rs @@ -91,6 +91,8 @@ impl Ord for PeerAddrState { /// order, ignoring liveness. /// /// See [`CandidateSet`] and [`MetaAddr::cmp`] for more details. + /// + /// [`CandidateSet`]: super::peer_set::CandidateSet fn cmp(&self, other: &Self) -> Ordering { use Ordering::*; match (self, other) { @@ -861,11 +863,12 @@ impl Ord for MetaAddr { /// with `Responded` peers sorted first as a group. /// /// But this order should not be used for reconnection attempts: use - /// [`reconnection_peers`][rp] instead. + /// [`reconnection_peers`] instead. /// /// See [`CandidateSet`] for more details. /// - /// [rp]: crate::AddressBook::reconnection_peers + /// [`CandidateSet`]: super::peer_set::CandidateSet + /// [`reconnection_peers`]: crate::AddressBook::reconnection_peers fn cmp(&self, other: &Self) -> Ordering { use std::net::IpAddr::{V4, V6}; use Ordering::*; diff --git a/zebra-network/src/peer/priority.rs b/zebra-network/src/peer/priority.rs index 5e01dc5a..d50130e7 100644 --- a/zebra-network/src/peer/priority.rs +++ b/zebra-network/src/peer/priority.rs @@ -10,7 +10,8 @@ use AttributePreference::*; /// /// Invalid peer attributes are represented as errors. /// -/// Outbound peer connections are initiated in the sorted [order](std::ops::Ord) of this type. +/// Outbound peer connections are initiated in the sorted [order](std::cmp::Ord) +/// of this type. /// /// The derived order depends on the order of the variants in the enum. /// The variants are sorted in the order they are listed. @@ -30,7 +31,8 @@ pub enum AttributePreference { /// A level of preference for a peer. /// -/// Outbound peer connections are initiated in the sorted [order](std::ops::Ord) of this type. +/// Outbound peer connections are initiated in the sorted [order](std::cmp::Ord) +/// of this type. /// /// The derived order depends on the order of the fields in the struct. /// The first field determines the overall order, then later fields sort equal first field values. @@ -84,6 +86,8 @@ impl PeerPreference { /// /// Since the addresses in the address book are unique, this check can be /// used to permanently reject entire [`MetaAddr`]s. +/// +/// [`MetaAddr`]: crate::meta_addr::MetaAddr fn address_is_valid_for_outbound_connections( peer_addr: &SocketAddr, network: impl Into>, diff --git a/zebra-network/src/peer_set/candidate_set.rs b/zebra-network/src/peer_set/candidate_set.rs index 212aa35b..950f0567 100644 --- a/zebra-network/src/peer_set/candidate_set.rs +++ b/zebra-network/src/peer_set/candidate_set.rs @@ -15,11 +15,11 @@ use crate::{ #[cfg(test)] mod tests; -/// The [`CandidateSet`] manages outbound peer connection attempts. -/// Successful connections become peers in the [`PeerSet`]. +/// The [`CandidateSet`] manages outbound peer connection attempts. Successful +/// connections become peers in the [`PeerSet`](super::set::PeerSet). /// /// The candidate set divides the set of all possible outbound peers into -/// disjoint subsets, using the [`PeerAddrState`]: +/// disjoint subsets, using the [`PeerAddrState`](crate::PeerAddrState): /// /// 1. [`Responded`] peers, which we have had an outbound connection to. /// 2. [`NeverAttemptedGossiped`] peers, which we learned about from other peers @@ -107,6 +107,13 @@ mod tests; /// │ * update last_response to now() │ /// └───────────────────────────────────────┘ /// ``` +/// +/// [`Responded`]: crate::PeerAddrState::Responded +/// [`Version`]: crate::protocol::external::types::Version +/// [`NeverAttemptedGossiped`]: crate::PeerAddrState::NeverAttemptedGossiped +/// [`NeverAttemptedAlternate`]: crate::PeerAddrState::NeverAttemptedAlternate +/// [`Failed`]: crate::PeerAddrState::Failed +/// [`AttemptPending`]: crate::PeerAddrState::AttemptPending // TODO: // * show all possible transitions between Attempt/Responded/Failed, // except Failed -> Responded is invalid, must go through Attempt @@ -340,10 +347,10 @@ where /// /// ## Correctness /// - /// `AttemptPending` peers will become `Responded` if they respond, or + /// `AttemptPending` peers will become [`Responded`] if they respond, or /// become `Failed` if they time out or provide a bad response. /// - /// Live `Responded` peers will stay live if they keep responding, or + /// Live [`Responded`] peers will stay live if they keep responding, or /// become a reconnection candidate if they stop responding. /// /// ## Security @@ -351,6 +358,8 @@ where /// Zebra resists distributed denial of service attacks by making sure that /// new peer connections are initiated at least /// [`MIN_PEER_CONNECTION_INTERVAL`][constants::MIN_PEER_CONNECTION_INTERVAL] apart. + /// + /// [`Responded`]: crate::PeerAddrState::Responded pub async fn next(&mut self) -> Option { // Correctness: To avoid hangs, computation in the critical section should be kept to a minimum. let address_book = self.address_book.clone(); diff --git a/zebra-network/src/peer_set/initialize.rs b/zebra-network/src/peer_set/initialize.rs index 6e222213..66fca1fb 100644 --- a/zebra-network/src/peer_set/initialize.rs +++ b/zebra-network/src/peer_set/initialize.rs @@ -42,9 +42,10 @@ use crate::{ #[cfg(test)] mod tests; -/// The result of an outbound peer connection attempt or inbound connection handshake. +/// The result of an outbound peer connection attempt or inbound connection +/// handshake. /// -/// This result comes from the [`Handshaker`]. +/// This result comes from the `Handshaker`. type DiscoveredPeer = Result<(SocketAddr, peer::Client), BoxError>; /// Initialize a peer set, using a network `config`, `inbound_service`, @@ -65,7 +66,7 @@ type DiscoveredPeer = Result<(SocketAddr, peer::Client), BoxError>; /// cause the peer set to shrink when the inbound service is unable to keep up /// with the volume of inbound requests. /// -/// Use [`NoChainTip`] to explicitly provide no chain tip receiver. +/// Use [`NoChainTip`][1] to explicitly provide no chain tip receiver. /// /// In addition to returning a service for outbound requests, this method /// returns a shared [`AddressBook`] updated with last-seen timestamps for @@ -77,6 +78,8 @@ type DiscoveredPeer = Result<(SocketAddr, peer::Client), BoxError>; /// /// If `config.config.peerset_initial_target_size` is zero. /// (zebra-network expects to be able to connect to at least one peer.) +/// +/// [1]: zebra_chain::chain_tip::NoChainTip pub async fn init( config: Config, inbound_service: S, diff --git a/zebra-network/src/peer_set/limit.rs b/zebra-network/src/peer_set/limit.rs index 9979ba3d..5b3a6244 100644 --- a/zebra-network/src/peer_set/limit.rs +++ b/zebra-network/src/peer_set/limit.rs @@ -7,9 +7,11 @@ use std::fmt; use tokio::sync::mpsc; -/// A signal sent by a [`Connection`] when it closes. +/// A signal sent by a [`Connection`][1] when it closes. /// /// Used to count the number of open connections. +/// +/// [1]: crate::peer::Connection #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] pub struct ConnectionClosed; diff --git a/zebra-network/src/peer_set/set.rs b/zebra-network/src/peer_set/set.rs index 5d563180..d12b60b9 100644 --- a/zebra-network/src/peer_set/set.rs +++ b/zebra-network/src/peer_set/set.rs @@ -55,8 +55,7 @@ //! therefore automatically increased when the block height reaches a network upgrade's activation //! height. The helper type is then used to: //! -//! - cancel handshakes to outdated peers, in -//! [`handshake::negotiate_version`][crate::peer::handshake::negotiate_version] +//! - cancel handshakes to outdated peers, in `handshake::negotiate_version` //! - cancel requests to and disconnect from peers that have become outdated, in //! [`PeerSet::push_unready`] //! - disconnect from peers that have just responded and became outdated, in @@ -67,9 +66,9 @@ //! ## Network Coalescence //! //! [ZIP-201] also specifies how Zcashd behaves [leading up to a activation -//! height][network-coalescence]. Since Zcashd limits the number of connections to at most eight -//! peers, it will gradually migrate its connections to up-to-date peers as it approaches the -//! activation height. +//! height][1]. Since Zcashd limits the number of connections to at most eight +//! peers, it will gradually migrate its connections to up-to-date peers as it +//! approaches the activation height. //! //! The motivation for this behavior is to avoid an abrupt partitioning the network, which can lead //! to isolated peers and increases the chance of an eclipse attack on some peers of the network. @@ -80,14 +79,18 @@ //! more costly to execute, and the probability of an abrupt network partition that isolates peers //! is lower. //! -//! Even if a Zebra node is manually configured to connect to a smaller number of peers, the -//! [`AddressBook`] is configured to hold a large number of peer addresses -//! ([`MAX_ADDRS_IN_ADDRESS_BOOK`]). Since the address book prioritizes addresses it trusts (like -//! those that it has successfully connected to before), the node should be able to recover and -//! rejoin the network by itself, as long as the address book is populated with enough entries. +//! Even if a Zebra node is manually configured to connect to a smaller number +//! of peers, the [`AddressBook`][2] is configured to hold a large number of +//! peer addresses ([`MAX_ADDRS_IN_ADDRESS_BOOK`][3]). Since the address book +//! prioritizes addresses it trusts (like those that it has successfully +//! connected to before), the node should be able to recover and rejoin the +//! network by itself, as long as the address book is populated with enough +//! entries. //! +//! [1]: https://zips.z.cash/zip-0201#network-coalescence +//! [2]: crate::AddressBook +//! [3]: crate::constants::MAX_ADDRS_IN_ADDRESS_BOOK //! [ZIP-201]: https://zips.z.cash/zip-0201 -//! [network-coalescence]: https://zips.z.cash/zip-0201#network-coalescence use std::{ collections::{HashMap, HashSet}, @@ -142,9 +145,12 @@ mod tests; #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] pub struct MorePeers; -/// A signal sent by the [`PeerSet`] to cancel a [`Client`]'s current request or response. +/// A signal sent by the [`PeerSet`] to cancel a [`Client`][1]'s current request +/// or response. /// -/// When it receives this signal, the [`Client`] stops processing and exits. +/// When it receives this signal, the [`Client`][1] stops processing and exits. +/// +/// [1]: crate::peer::Client #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] pub struct CancelClientWork; diff --git a/zebra-network/src/protocol/external/addr.rs b/zebra-network/src/protocol/external/addr.rs index a855e566..111100ec 100644 --- a/zebra-network/src/protocol/external/addr.rs +++ b/zebra-network/src/protocol/external/addr.rs @@ -1,9 +1,9 @@ //! Zcash node address types and serialization for Zcash network messages. //! //! Zcash has 3 different node address formats: -//! - [`AddrV1`]: the format used in `addr` (v1) messages, +//! - `AddrV1`: the format used in `addr` (v1) messages, //! - [`AddrInVersion`]: the format used in `version` messages, and -//! - [`AddrV2`]: the format used in `addrv2` messages. +//! - `AddrV2`: the format used in `addrv2` messages. pub mod canonical; pub mod in_version; diff --git a/zebra-network/src/protocol/external/addr/v1.rs b/zebra-network/src/protocol/external/addr/v1.rs index 8b09f90c..efdd8245 100644 --- a/zebra-network/src/protocol/external/addr/v1.rs +++ b/zebra-network/src/protocol/external/addr/v1.rs @@ -140,6 +140,8 @@ impl TrustedPreallocate for AddrV1 { /// Transform a `SocketAddr` into an IPv6-mapped IPv4 addresses. /// /// See [`canonical_ip_addr`] for detailed info on IPv6-mapped IPv4 addresses. +/// +/// [`canonical_ip_addr`]: super::canonical::canonical_ip_addr pub(in super::super) fn ipv6_mapped_ip_addr(ip_addr: &IpAddr) -> Ipv6Addr { use IpAddr::*; @@ -155,6 +157,8 @@ pub(in super::super) fn ipv6_mapped_ip_addr(ip_addr: &IpAddr) -> Ipv6Addr { /// Also remove IPv6 scope IDs and flow information. /// /// See [`canonical_ip_addr`] for detailed info on IPv6-mapped IPv4 addresses. +/// +/// [`canonical_ip_addr`]: super::canonical::canonical_ip_addr pub(in super::super) fn ipv6_mapped_socket_addr( socket_addr: impl Into, ) -> SocketAddrV6 { diff --git a/zebra-network/src/protocol/external/addr/v2.rs b/zebra-network/src/protocol/external/addr/v2.rs index 7d768f0d..d11c6560 100644 --- a/zebra-network/src/protocol/external/addr/v2.rs +++ b/zebra-network/src/protocol/external/addr/v2.rs @@ -47,11 +47,15 @@ pub const MAX_ADDR_V2_ADDR_SIZE: usize = 512; /// > 0x01 IPV4 4 IPv4 address (globally routed internet) /// /// +/// +/// [`Ipv4Addr`]: std::net::Ipv4Addr pub const ADDR_V2_IPV4_NETWORK_ID: u8 = 0x01; /// The size of [`Ipv4Addr`]s in `addrv2` messages. /// /// +/// +/// [`Ipv4Addr`]: std::net::Ipv4Addr pub const ADDR_V2_IPV4_ADDR_SIZE: usize = 4; /// The network ID of [`Ipv6Addr`]s in `addrv2` messages. @@ -59,11 +63,15 @@ pub const ADDR_V2_IPV4_ADDR_SIZE: usize = 4; /// > 0x02 IPV6 16 IPv6 address (globally routed internet) /// /// +/// +/// [`Ipv6Addr`]: std::net::Ipv6Addr pub const ADDR_V2_IPV6_NETWORK_ID: u8 = 0x02; /// The size of [`Ipv6Addr`]s in `addrv2` messages. /// /// +/// +/// [`Ipv6Addr`]: std::net::Ipv6Addr pub const ADDR_V2_IPV6_ADDR_SIZE: usize = 16; /// The second format used for Bitcoin node addresses. @@ -96,6 +104,8 @@ pub(in super::super) enum AddrV2 { /// The peer's IP address. /// /// Unlike [`AddrV1`], this can be an IPv4 or IPv6 address. + /// + /// [`AddrV1`]: super::v1::AddrV1 ip: IpAddr, /// The peer's TCP port. diff --git a/zebra-network/src/protocol/external/arbitrary.rs b/zebra-network/src/protocol/external/arbitrary.rs index 830b1138..de536928 100644 --- a/zebra-network/src/protocol/external/arbitrary.rs +++ b/zebra-network/src/protocol/external/arbitrary.rs @@ -29,7 +29,7 @@ impl InventoryHash { .boxed() } - /// Generate a proptest strategy for [`InventotryHash::Block`] hashes. + /// Generate a proptest strategy for [`InventoryHash::Block`] hashes. pub fn block_strategy() -> BoxedStrategy { (any::<[u8; 32]>()) .prop_map(block::Hash) @@ -126,14 +126,19 @@ impl Arbitrary for Version { /// Returns a random canonical Zebra `SocketAddr`. /// -/// See [`canonical_ip_addr`](super::addr::canonical_ip_addr) for details. +/// See [`canonical_ip_addr`] for details. +/// +/// [`canonical_ip_addr`]: super::addr::canonical::canonical_ip_addr pub fn canonical_socket_addr_strategy() -> impl Strategy { any::().prop_map(canonical_socket_addr) } -/// Returns a random `SocketAddrV6` for use in `addr` (v1) Zcash network messages. +/// Returns a random `SocketAddrV6` for use in `addr` (v1) Zcash network +/// messages. /// -/// See [`canonical_ip_addr`](super::addr::canonical_ip_addr) for details. +/// See [`canonical_ip_addr`] for details. +/// +/// [`canonical_ip_addr`]: super::addr::canonical::canonical_ip_addr pub fn addr_v1_ipv6_mapped_socket_addr_strategy() -> impl Strategy { any::().prop_map(ipv6_mapped_socket_addr) } diff --git a/zebra-network/src/protocol/external/message.rs b/zebra-network/src/protocol/external/message.rs index a55c2063..11ee9e55 100644 --- a/zebra-network/src/protocol/external/message.rs +++ b/zebra-network/src/protocol/external/message.rs @@ -103,7 +103,7 @@ pub enum Message { /// /// [Bitcoin reference](https://en.bitcoin.it/wiki/Protocol_documentation#ping) Ping( - /// A nonce unique to this [`Ping`] message. + /// A nonce unique to this [`Self::Ping`] message. Nonce, ), @@ -111,7 +111,7 @@ pub enum Message { /// /// [Bitcoin reference](https://en.bitcoin.it/wiki/Protocol_documentation#pong) Pong( - /// The nonce from the [`Ping`] message this was in response to. + /// The nonce from the [`Self::Ping`] message this was in response to. Nonce, ), diff --git a/zebra-state/src/lib.rs b/zebra-state/src/lib.rs index 3e8601bd..089c44c4 100644 --- a/zebra-state/src/lib.rs +++ b/zebra-state/src/lib.rs @@ -11,6 +11,7 @@ #![doc(html_favicon_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-favicon-128.png")] #![doc(html_logo_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-icon.png")] #![doc(html_root_url = "https://doc.zebra.zfnd.org/zebra_state")] +#![allow(rustdoc::private_intra_doc_links)] #[macro_use] extern crate tracing; diff --git a/zebra-test/src/lib.rs b/zebra-test/src/lib.rs index 254eff71..a9476529 100644 --- a/zebra-test/src/lib.rs +++ b/zebra-test/src/lib.rs @@ -2,9 +2,9 @@ #![doc(html_favicon_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-favicon-128.png")] #![doc(html_logo_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-icon.png")] #![doc(html_root_url = "https://doc.zebra.zfnd.org/zebra_test")] +#![allow(rustdoc::private_intra_doc_links)] // Each lazy_static variable uses additional recursion #![recursion_limit = "512"] - use color_eyre::section::PanicMessage; use once_cell::sync::Lazy; use owo_colors::OwoColorize; diff --git a/zebrad/src/components/mempool.rs b/zebrad/src/components/mempool.rs index 2454dea0..844624bb 100644 --- a/zebrad/src/components/mempool.rs +++ b/zebrad/src/components/mempool.rs @@ -111,7 +111,7 @@ impl Drop for ActiveState { } impl ActiveState { - /// Returns the current state, leaving a [`Disabled`] in its place. + /// Returns the current state, leaving [`Self::Disabled`] in its place. fn take(&mut self) -> Self { std::mem::take(self) } diff --git a/zebrad/src/components/mempool/config.rs b/zebrad/src/components/mempool/config.rs index 01708680..2b4f20f6 100644 --- a/zebrad/src/components/mempool/config.rs +++ b/zebrad/src/components/mempool/config.rs @@ -20,8 +20,9 @@ pub struct Config { /// The mempool transaction eviction age limit. /// - /// This limits the maximum amount of time evicted transaction IDs stay in the mempool rejection list. - /// Transactions are randomly evicted from the mempool when the mempool reaches [`tx_cost_limit`]. + /// This limits the maximum amount of time evicted transaction IDs stay in + /// the mempool rejection list. Transactions are randomly evicted from the + /// mempool when the mempool reaches [`Self::tx_cost_limit`]. /// /// (Transactions can also be rejected by the mempool for other reasons. /// Different rejection reasons can have different age limits.) diff --git a/zebrad/src/components/mempool/downloads.rs b/zebrad/src/components/mempool/downloads.rs index 7eda18f4..c8135fae 100644 --- a/zebrad/src/components/mempool/downloads.rs +++ b/zebrad/src/components/mempool/downloads.rs @@ -12,15 +12,19 @@ //! //! # 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.) +//! 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. +//! +//! [`Mempool`]: super::Mempool +//! [`Mempool::poll_ready`]: super::Mempool::poll_ready use std::{ collections::{HashMap, HashSet}, pin::Pin, diff --git a/zebrad/src/components/mempool/gossip.rs b/zebrad/src/components/mempool/gossip.rs index 93037a5c..b55dc37c 100644 --- a/zebrad/src/components/mempool/gossip.rs +++ b/zebrad/src/components/mempool/gossip.rs @@ -16,9 +16,12 @@ use crate::BoxError; use crate::components::sync::TIPS_RESPONSE_TIMEOUT; -/// Run continuously, gossiping new [`zebra_chain::transaction::UnminedTxId`] to peers. +/// Runs continuously, gossiping new [`UnminedTxId`] to peers. /// -/// Broadcast any [`transaction::UnminedTxId`] that gets stored in the mempool to all ready peers. +/// Broadcasts any [`UnminedTxId`] that gets stored in the mempool to all ready +/// peers. +/// +/// [`UnminedTxId`]: zebra_chain::transaction::UnminedTxId pub async fn gossip_mempool_transaction_id( mut receiver: watch::Receiver>, broadcast_network: ZN, diff --git a/zebrad/src/components/mempool/storage.rs b/zebrad/src/components/mempool/storage.rs index 83e49d8e..2af476e5 100644 --- a/zebrad/src/components/mempool/storage.rs +++ b/zebrad/src/components/mempool/storage.rs @@ -341,7 +341,8 @@ impl Storage { /// Returns the set of [`UnminedTx`]es with matching [`transaction::Hash`]es /// in the mempool. /// - /// This matches transactions with the same effects, regardless of [`AuthDigest`]. + /// This matches transactions with the same effects, regardless of + /// [`transaction::AuthDigest`]. pub fn transactions_same_effects( &self, tx_ids: HashSet, diff --git a/zebrad/src/components/mempool/storage/eviction_list.rs b/zebrad/src/components/mempool/storage/eviction_list.rs index 2809608e..8f0c001a 100644 --- a/zebrad/src/components/mempool/storage/eviction_list.rs +++ b/zebrad/src/components/mempool/storage/eviction_list.rs @@ -17,7 +17,9 @@ pub struct EvictionList { // The maximum size of `unique_entries`. max_size: usize, /// The mempool transaction eviction age limit. - /// Same as [`Config::eviction_memory_time`]. + /// Same as [`Config::eviction_memory_time`][1]. + /// + /// [1]: super::super::Config::eviction_memory_time eviction_memory_time: Duration, } diff --git a/zebrad/src/components/sync/gossip.rs b/zebrad/src/components/sync/gossip.rs index 06745349..09edc630 100644 --- a/zebrad/src/components/sync/gossip.rs +++ b/zebrad/src/components/sync/gossip.rs @@ -1,4 +1,6 @@ //! A task that gossips newly verified [`block::Hash`]es to peers. +//! +//! [`block::Hash`]: zebra_chain::block::Hash use thiserror::Error; use tokio::sync::watch; @@ -37,6 +39,8 @@ pub enum BlockGossipError { /// /// In particular, if a lot of blocks are committed at the same time, /// gossips will be disabled or skipped until the state reaches the latest tip. +/// +/// [`block::Hash`]: zebra_chain::block::Hash pub async fn gossip_best_tip_block_hashes( mut sync_status: SyncStatus, mut chain_state: ChainTipChange, diff --git a/zebrad/src/components/sync/recent_sync_lengths.rs b/zebrad/src/components/sync/recent_sync_lengths.rs index 2aa59d8b..acf32f07 100644 --- a/zebrad/src/components/sync/recent_sync_lengths.rs +++ b/zebrad/src/components/sync/recent_sync_lengths.rs @@ -51,7 +51,10 @@ impl RecentSyncLengths { // rather than asking peers for the next blocks in the chain. // (And if genesis downloads kept failing, we could accidentally activate the mempool.) - /// Insert a sync length from [`ChainSync::obtain_tips`] at the front of the list. + /// Insert a sync length from [`ChainSync::obtain_tips`] at the front of the + /// list. + /// + /// [`ChainSync::obtain_tips`]: super::ChainSync::obtain_tips #[instrument(skip(self), fields(self.recent_lengths))] pub fn push_obtain_tips_length(&mut self, sync_length: usize) { // currently, we treat lengths from obtain and extend tips exactly the same, @@ -62,7 +65,10 @@ impl RecentSyncLengths { self.update(sync_length) } - /// Insert a sync length from [`ChainSync::extend_tips`] at the front of the list. + /// Insert a sync length from [`ChainSync::extend_tips`] at the front of the + /// list. + /// + /// [`ChainSync::extend_tips`]: super::ChainSync::extend_tips #[instrument(skip(self), fields(self.recent_lengths))] pub fn push_extend_tips_length(&mut self, sync_length: usize) { self.update(sync_length) diff --git a/zebrad/src/lib.rs b/zebrad/src/lib.rs index b6976125..5711c50c 100644 --- a/zebrad/src/lib.rs +++ b/zebrad/src/lib.rs @@ -17,6 +17,7 @@ #![doc(html_favicon_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-favicon-128.png")] #![doc(html_logo_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-icon.png")] #![doc(html_root_url = "https://doc.zebra.zfnd.org/zebrad")] +#![allow(rustdoc::private_intra_doc_links)] // Tracing causes false positives on this lint: // https://github.com/tokio-rs/tracing/issues/553 #![allow(clippy::cognitive_complexity)]