Moves code walkthrough book chapters to docs (paradigmxyz#629)

* replaced template blocks with code blocks in stages chapter

* replaced template blocks with code blocks in network chapter

* moved book sections to docs

* fix indentation in recover_signer codeblock

* remove unnecessary TODO comment in network.md

Author: akirillo

bin/reth/src/node/mod.rs

@@ -105,7 +105,6 @@ impl Command {
         let genesis_hash = init_genesis(db.clone(), self.chain.genesis.clone())?;
 
         info!("Connecting to p2p");
-        // ANCHOR: snippet-execute
         let network = start_network(network_config(db.clone(), chain_id, genesis_hash)).await?;
 
         // TODO: Are most of these Arcs unnecessary? For example, fetch client is completely
@@ -155,7 +154,6 @@ impl Command {
         // Run pipeline
         info!("Starting pipeline");
         pipeline.run(db.clone()).await?;
-        // ANCHOR_END: snippet-execute
 
         info!("Finishing up");
         Ok(())
@@ -224,7 +222,6 @@ fn network_config<DB: Database>(
 }
 
 /// Starts the networking stack given a [NetworkConfig] and returns a handle to the network.
-// ANCHOR: fn-start_network
 async fn start_network<C>(config: NetworkConfig<C>) -> Result<NetworkHandle, NetworkError>
 where
     C: BlockProvider + HeaderProvider + 'static,
@@ -238,4 +235,3 @@ where
     tokio::task::spawn(eth);
     Ok(handle)
 }
-// ANCHOR_END: fn-start_network

book/README.md

@@ -17,8 +17,5 @@ The book is continuously rendered [here](https://paradigmxyz.github.io/reth/)!
 To get started with Reth, install, configure and sync your node.
 * To install and build reth, you can use the following [installation instruction](./installation.md).
 
-**[A Tour Of Reth]()**
-
-This section will take a deep dive into the inner workings of Reth. 
 
 [gh-book]: https://github.com/paradigmxyz/reth/tree/main/book

book/SUMMARY.md

@@ -7,44 +7,3 @@
 <!-- An overview of all the flags, how they work and how to configure the node   -->
 - [Configuring The Node]()
 - [Running Reth]()
-
-# A Tour Of Reth
-
-- [Database]()
-    - [codecs]()
-    - [libmdbx-rs]()
-    - [db](./db/README.md)
-- [Networking]()
-    - [P2P](./networking/p2p/README.md)
-        - [network](./networking/p2p/network/README.md)
-        - [eth-wire]()
-        - [discv4]()
-        - [ipc]()
-    - [RPC]()
-        - [rpc-api]()
-        - [rpc]()
-        - [rpc-types]()
-    - [Downloaders]()
-        - [bodies-downloaders]()
-        - [headers-downloaders]()
-- [Ethereum]()
-    - [executor]()
-    - [consensus]()
-    - [transaction-pool]()
-- [Staged Sync]()
-    - [stages](./stages/README.md)
-- [Primitives]()
-    - [primitives]()
-    - [rlp]()
-    - [rlp-derive]()
-- [Misc]()
-    - [interfaces]()
-    - [tracing]()
-    - [crate-template]()
-    - [examples]()
-
-
-
-# Design
-
-- [Goals](./design/goals.md)

book/networking/network.md

@@ -12,7 +12,6 @@ use reth_primitives::{SealedHeader, H256};
 ///
 /// A downloader represents a distinct strategy for submitting requests to download block headers,
 /// while a [HeadersClient] represents a client capable of fulfilling these requests.
-// ANCHOR: trait-HeaderDownloader
 #[auto_impl::auto_impl(&, Arc, Box)]
 pub trait HeaderDownloader: Downloader {
     /// Stream the headers
@@ -24,7 +23,6 @@ pub trait HeaderDownloader: Downloader {
         Ok(())
     }
 }
-// ANCHOR_END: trait-HeaderDownloader
 
 /// Validate whether the header is valid in relation to it's parent
 ///

book/networking/p2p/README.md

@@ -17,7 +17,6 @@ use std::{borrow::Borrow, sync::Arc};
 /// Downloads bodies in batches.
 ///
 /// All blocks in a batch are fetched at the same time.
-// ANCHOR: struct-ConcurrentDownloader
 #[derive(Debug)]
 pub struct ConcurrentDownloader<Client, Consensus> {
     /// The bodies client
@@ -31,7 +30,6 @@ pub struct ConcurrentDownloader<Client, Consensus> {
     /// The maximum number of requests to send concurrently.
     concurrency: usize,
 }
-// ANCHOR_END: struct-ConcurrentDownloader
 
 impl<Client, Consensus> Downloader for ConcurrentDownloader<Client, Consensus>
 where

book/networking/p2p/network/README.md

@@ -21,7 +21,6 @@ use std::{
 };
 
 /// Download headers in batches
-// ANCHOR: struct-LinearDownloader
 #[derive(Debug)]
 pub struct LinearDownloader<C, H> {
     /// The consensus client
@@ -33,7 +32,6 @@ pub struct LinearDownloader<C, H> {
     /// The number of retries for downloading
     pub request_retries: usize,
 }
-// ANCHOR_END: struct-LinearDownloader
 
 impl<C, H> Downloader for LinearDownloader<C, H>
 where
@@ -194,7 +192,6 @@ where
     }
 
     /// Get a current future or instantiate a new one
-    // ANCHOR: fn-get_or_init_fut
     fn get_or_init_fut(&mut self) -> HeadersRequestFuture {
         match self.request.take() {
             None => {
@@ -215,7 +212,6 @@ where
             Some(fut) => fut,
         }
     }
-    // ANCHOR_END: fn-get_or_init_fut
 
     /// Tries to fuse the future with a new request.
     ///

crates/interfaces/src/p2p/headers/downloader.rs

@@ -17,7 +17,6 @@ use serde::{Deserialize, Serialize};
 #[derive(
     Copy, Clone, Debug, PartialEq, Eq, Hash, RlpEncodable, RlpDecodable, Serialize, Deserialize,
 )]
-// ANCHOR: struct-GetBlockHeaders
 pub struct GetBlockHeaders {
     /// The block number or hash that the peer should start returning headers from.
     pub start_block: BlockHashOrNumber,
@@ -34,7 +33,6 @@ pub struct GetBlockHeaders {
     /// The direction in which the headers should be returned in.
     pub direction: HeadersDirection,
 }
-// ANCHOR_END: struct-GetBlockHeaders
 
 /// The response to [`GetBlockHeaders`], containing headers if any headers were found.
 #[derive(
@@ -71,12 +69,10 @@ impl From<Vec<Header>> for BlockHeaders {
     Deserialize,
     Default,
 )]
-// ANCHOR: struct-GetBlockBodies
 pub struct GetBlockBodies(
     /// The block hashes to request bodies for.
     pub Vec<H256>,
 );
-// ANCHOR_END: struct-GetBlockBodies
 
 impl From<Vec<H256>> for GetBlockBodies {
     fn from(hashes: Vec<H256>) -> Self {

crates/net/downloaders/src/bodies/concurrent.rs

@@ -30,7 +30,6 @@ pub fn rng_secret_key() -> SecretKey {
 }
 
 /// All network related initialization settings.
-// ANCHOR: struct-NetworkConfig
 pub struct NetworkConfig<C> {
     /// The client type that can interact with the chain.
     pub client: Arc<C>,
@@ -70,7 +69,6 @@ pub struct NetworkConfig<C> {
     /// Sets the hello message for the p2p handshake in RLPx
     pub hello_message: HelloMessage,
 }
-// ANCHOR_END: struct-NetworkConfig
 
 // === impl NetworkConfig ===
 

crates/net/downloaders/src/headers/linear.rs

@@ -46,7 +46,6 @@ const APPROX_HEADER_SIZE: usize = 500;
 /// Manages eth related requests on top of the p2p network.
 ///
 /// This can be spawned to another task and is supposed to be run as background service.
-// ANCHOR: struct-EthRequestHandler
 #[must_use = "Manager does nothing unless polled."]
 pub struct EthRequestHandler<C> {
     /// The client type that can interact with the chain.
@@ -58,7 +57,6 @@ pub struct EthRequestHandler<C> {
     /// Incoming request from the [NetworkManager](crate::NetworkManager).
     incoming_requests: UnboundedReceiverStream<IncomingEthRequest>,
 }
-// ANCHOR_END: struct-EthRequestHandler
 
 // === impl EthRequestHandler ===
 impl<C> EthRequestHandler<C> {
@@ -77,7 +75,6 @@ where
     C: BlockProvider + HeaderProvider,
 {
     /// Returns the list of requested heders
-    // ANCHOR:fn-get_headers_response
     fn get_headers_response(&self, request: GetBlockHeaders) -> Vec<Header> {
         let GetBlockHeaders { start_block, limit, skip, direction } = request;
 
@@ -142,7 +139,6 @@ where
 
         headers
     }
-    // ANCHOR_END:fn-get_headers_response
 
     fn on_headers_request(
         &mut self,
@@ -154,7 +150,6 @@ where
         let _ = response.send(Ok(BlockHeaders(headers)));
     }
 
-    // ANCHOR: fn-on_bodies_request
     fn on_bodies_request(
         &mut self,
         _peer_id: PeerId,
@@ -187,7 +182,6 @@ where
 
         let _ = response.send(Ok(BlockBodies(bodies)));
     }
-    // ANCHOR_END: fn-on_bodies_request
 }
 
 /// An endless future.
@@ -199,7 +193,6 @@ where
 {
     type Output = ();
 
-    // ANCHOR: fn-poll
     fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
         let this = self.get_mut();
 
@@ -220,7 +213,6 @@ where
             }
         }
     }
-    // ANCHOR_END: fn-poll
 }
 
 /// Represents a handled [`GetBlockHeaders`] requests

crates/net/eth-wire/src/types/blocks.rs

@@ -15,23 +15,20 @@ use reth_primitives::{PeerId, WithPeerId, H256};
 use tokio::sync::{mpsc::UnboundedSender, oneshot};
 
 /// Front-end API for fetching data from the network.
-// ANCHOR: struct-FetchClient
 #[derive(Debug)]
 pub struct FetchClient {
     /// Sender half of the request channel.
     pub(crate) request_tx: UnboundedSender<DownloadRequest>,
     /// The handle to the peers
     pub(crate) peers_handle: PeersHandle,
 }
-// ANCHOR_END: struct-FetchClient
 
 impl DownloadClient for FetchClient {
     fn report_bad_message(&self, peer_id: PeerId) {
         self.peers_handle.reputation_change(peer_id, ReputationChangeKind::BadMessage);
     }
 }
 
-// ANCHOR: trait-HeadersClient-BodiesClient
 #[async_trait::async_trait]
 impl HeadersClient for FetchClient {
     /// Sends a `GetBlockHeaders` request to an available peer.
@@ -50,4 +47,3 @@ impl BodiesClient for FetchClient {
         rx.await?
     }
 }
-// ANCHOR_END: trait-HeadersClient-BodiesClient

crates/net/network/src/config.rs

@@ -25,7 +25,6 @@ pub use client::FetchClient;
 /// peers and sends the response once ready.
 ///
 /// This type maintains a list of connected peers that are available for requests.
-// ANCHOR: struct-StateFetcher
 pub struct StateFetcher {
     /// Currently active [`GetBlockHeaders`] requests
     inflight_headers_requests:
@@ -44,7 +43,6 @@ pub struct StateFetcher {
     /// Sender for download requests, used to detach a [`FetchClient`]
     download_requests_tx: UnboundedSender<DownloadRequest>,
 }
-// ANCHOR_END: struct-StateFetcher
 
 // === impl StateSyncer ===
 

crates/net/network/src/eth_requests.rs

@@ -79,7 +79,6 @@ use tracing::{error, info, trace, warn};
 ///   ethrequest <--> |ETH request handing| NetworkManager
 ///   discovery --> |Discovered peers| NetworkManager
 /// ```
-// ANCHOR: struct-NetworkManager
 #[must_use = "The NetworkManager does nothing unless polled"]
 pub struct NetworkManager<C> {
     /// The type that manages the actual network part, which includes connections.
@@ -104,7 +103,6 @@ pub struct NetworkManager<C> {
     /// Updated by the `NetworkWorker` and loaded by the `NetworkService`.
     num_active_peers: Arc<AtomicUsize>,
 }
-// ANCHOR_END: struct-NetworkManager
 
 // === impl NetworkManager ===
 impl<C> NetworkManager<C> {
@@ -672,7 +670,6 @@ where
 ///
 /// This includes any event types that may be relevant to tasks, for metrics, keep track of peers
 /// etc.
-// ANCHOR: enum-NetworkEvent
 #[derive(Debug, Clone)]
 pub enum NetworkEvent {
     /// Closed the peer session.
@@ -698,7 +695,6 @@ pub enum NetworkEvent {
     /// Event emitted when a new peer is removed
     PeerRemoved(PeerId),
 }
-// ANCHOR_END: enum-NetworkEvent
 
 /// Bundles all listeners for [`NetworkEvent`]s.
 #[derive(Default)]

crates/net/network/src/fetch/client.rs

@@ -167,7 +167,6 @@ impl StatusUpdater for NetworkHandle {
     }
 }
 
-// ANCHOR: struct-NetworkInner
 #[derive(Debug)]
 struct NetworkInner {
     /// Number of active peer sessions the node's currently handling.
@@ -183,7 +182,6 @@ struct NetworkInner {
     /// The mode of the network
     network_mode: NetworkMode,
 }
-// ANCHOR_END: struct-NetworkInner
 
 /// Internal messages that can be passed to the  [`NetworkManager`](crate::NetworkManager).
 #[allow(missing_docs)]

crates/net/network/src/fetch/mod.rs

@@ -39,7 +39,6 @@ const PEER_BLOCK_CACHE_LIMIT: usize = 512;
 ///     then send to the session of the peer.
 ///
 /// This type is also responsible for responding for received request.
-// ANCHOR: struct-NetworkState
 pub struct NetworkState<C> {
     /// All active peers and their state.
     active_peers: HashMap<PeerId, ActivePeer>,
@@ -59,7 +58,6 @@ pub struct NetworkState<C> {
     /// then queue in the request and notify the fetcher once the result has been received.
     state_fetcher: StateFetcher,
 }
-// ANCHOR_END: struct-NetworkState
 
 impl<C> NetworkState<C>
 where

crates/net/network/src/manager.rs

@@ -61,7 +61,6 @@ use tracing::{trace, warn};
 ///   fetchRequest --> |request Headers, Bodies| StateFetch
 ///   State --> |poll pending requests| StateFetch
 /// ```
-// ANCHOR: struct-Swarm
 #[must_use = "Swarm does nothing unless polled"]
 pub(crate) struct Swarm<C> {
     /// Listens for new incoming connections.
@@ -71,7 +70,6 @@ pub(crate) struct Swarm<C> {
     /// Tracks the entire state of the network and handles events received from the sessions.
     state: NetworkState<C>,
 }
-// ANCHOR_END: struct-Swarm
 
 // === impl Swarm ===