From 9dbf280bfb2788c441356ebcd9451022aab3ccf4 Mon Sep 17 00:00:00 2001
From: Matthias Seitz <matthias.seitz@outlook.de>
Date: Thu, 15 Dec 2022 10:36:58 +0100
Subject: [PATCH] docs(net): add bird's eye view docs (#456)

---
 crates/net/network/README.md      |  1 +
 crates/net/network/src/lib.rs     | 31 +++++++++++++++++++++++++++++++
 crates/net/network/src/manager.rs | 16 ++++++++++------
 3 files changed, 42 insertions(+), 6 deletions(-)
 create mode 100644 crates/net/network/README.md

diff --git a/crates/net/network/README.md b/crates/net/network/README.md
new file mode 100644
index 000000000..52f407fdf
--- /dev/null
+++ b/crates/net/network/README.md
@@ -0,0 +1 @@
+# RETH network implementation
\ No newline at end of file
diff --git a/crates/net/network/src/lib.rs b/crates/net/network/src/lib.rs
index 15558ebb3..70380d426 100644
--- a/crates/net/network/src/lib.rs
+++ b/crates/net/network/src/lib.rs
@@ -14,6 +14,37 @@
 //! port of that network. This includes public identities (public key) and addresses (where to reach
 //! them).
 //!
+//! ## Bird's Eye View
+//!
+//! See also diagram in [`NetworkManager`]
+//!
+//! The `Network` is made up of several, separate tasks:
+//!
+//!    - `Transactions Task`: is a spawned
+//!      [`TransactionManager`](crate::transactions::TransactionsManager) future that:
+//!
+//!        * Responds to incoming transaction related requests
+//!        * Requests missing transactions from the `Network`
+//!        * Broadcasts new transactions received from the
+//!          [`TransactionPool`](reth_transaction_pool::TransactionPool) over the `Network`
+//!
+//!    - `ETH request Task`: is a spawned
+//!      [`EthRequestHandler`](crate::eth_requests::EthRequestHandler) future that:
+//!
+//!        * Responds to incoming ETH related requests: `Headers`, `Bodies`
+//!
+//!    - `Discovery Task`: is a spawned [`Discv4`](reth_discv4::Discv4) future that handles peer
+//!      discovery and emits new peers to the `Network`
+//!
+//!    - [`NetworkManager`] task advances the state of the `Network`, which includes:
+//!
+//!        * Initiating new _outgoing_ connections to discovered peers
+//!        * Handling _incoming_ TCP connections from peers
+//!        * Peer management
+//!        * Route requests:
+//!             - from remote peers to corresponding tasks
+//!             - from local to remote peers
+//!
 //! ## Usage
 //!
 //! ### Configure and launch a standalone network
diff --git a/crates/net/network/src/manager.rs b/crates/net/network/src/manager.rs
index bfbd8045b..733ab6979 100644
--- a/crates/net/network/src/manager.rs
+++ b/crates/net/network/src/manager.rs
@@ -62,19 +62,23 @@ use tracing::{error, info, trace, warn};
 ///  graph TB
 ///    handle(NetworkHandle)
 ///    events(NetworkEvents)
-///    transactions[(Transactions Task)]
+///    transactions(Transactions Task)
+///    ethrequest(ETH Request Task)
+///    discovery(Discovery Task)
 ///    subgraph NetworkManager
 ///      direction LR
 ///      subgraph Swarm
 ///          direction TB
-///          B1[(Peer Sessions)]
+///          B1[(Session Manager)]
 ///          B2[(Connection Lister)]
-///          B3[(State)]
+///          B3[(Network State)]
 ///      end
-///    end
-///   handle <--> |request/response channel| NetworkManager
+///   end
+///   handle <--> |request response channel| NetworkManager
 ///   NetworkManager --> |Network events| events
-///   transactions --> |propagate transactions| NetworkManager
+///   transactions <--> |transactions| NetworkManager
+///   ethrequest <--> |ETH request handing| NetworkManager
+///   discovery --> |Discovered peers| NetworkManager
 /// ```
 #[must_use = "The NetworkManager does nothing unless polled"]
 pub struct NetworkManager<C> {