From 0b1c86df3035f139283e2b5de3468d7a217d4976 Mon Sep 17 00:00:00 2001
From: Matthias Seitz <matthias.seitz@outlook.de>
Date: Tue, 11 Oct 2022 19:07:16 +0200
Subject: [PATCH] docs(txpool): add mermaid diagram (#46)

---
 Cargo.lock                                 | 29 ++++++++++++++++++++
 crates/transaction-pool/Cargo.toml         |  3 ++-
 crates/transaction-pool/src/pool/txpool.rs | 31 ++++++++++++++++++++++
 3 files changed, 62 insertions(+), 1 deletion(-)

diff --git a/Cargo.lock b/Cargo.lock
index b37b3d459..4155af63a 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -28,6 +28,19 @@ version = "1.0.65"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "98161a4e3e2184da77bb14f02184cdd111e83bbbcc9979dfee3c44b9a85f5602"
 
+[[package]]
+name = "aquamarine"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a941c39708478e8eea39243b5983f1c42d2717b3620ee91f4a52115fd02ac43f"
+dependencies = [
+ "itertools",
+ "proc-macro-error",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "arrayref"
 version = "0.3.6"
@@ -379,6 +392,12 @@ dependencies = [
  "signature",
 ]
 
+[[package]]
+name = "either"
+version = "1.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "90e5c1c8368803113bf0c9584fc495a58b86dc8a29edbf8fe877d21d9507e797"
+
 [[package]]
 name = "elliptic-curve"
 version = "0.12.3"
@@ -965,6 +984,15 @@ dependencies = [
  "cfg-if",
 ]
 
+[[package]]
+name = "itertools"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "284f18f85651fe11e8a991b2adb42cb078325c996ed026d994719efcfca1d54b"
+dependencies = [
+ "either",
+]
+
 [[package]]
 name = "itoa"
 version = "1.0.3"
@@ -1816,6 +1844,7 @@ dependencies = [
 name = "reth-transaction-pool"
 version = "0.1.0"
 dependencies = [
+ "aquamarine",
  "async-trait",
  "bitflags",
  "fnv",
diff --git a/crates/transaction-pool/Cargo.toml b/crates/transaction-pool/Cargo.toml
index e0bcb6650..b5abdde20 100644
--- a/crates/transaction-pool/Cargo.toml
+++ b/crates/transaction-pool/Cargo.toml
@@ -20,6 +20,7 @@ futures = "0.3"
 parking_lot = "0.12"
 
 # misc
+aquamarine = "0.1" # docs
 thiserror = "1.0"
 tracing = "0.1"
 serde = { version = "1.0", features = ["derive"] }
@@ -28,4 +29,4 @@ fnv = "1.0.7"
 bitflags = "1.3"
 
 [dev-dependencies]
-paste = "1.0"
+paste = "1.0"
\ No newline at end of file
diff --git a/crates/transaction-pool/src/pool/txpool.rs b/crates/transaction-pool/src/pool/txpool.rs
index 20fbc0b63..38d7f5a4b 100644
--- a/crates/transaction-pool/src/pool/txpool.rs
+++ b/crates/transaction-pool/src/pool/txpool.rs
@@ -23,6 +23,37 @@ use std::{
 /// A pool that manages transactions.
 ///
 /// This pool maintains the state of all transactions and stores them accordingly.
+
+#[cfg_attr(doc, aquamarine::aquamarine)]
+/// ```mermaid
+/// graph TB
+///   subgraph TxPool
+///     direction TB
+///     pool[(All Transactions)]
+///     subgraph Subpools
+///         direction TB
+///         B3[(Queued)]
+///         B1[(Pending)]
+///         B2[(Basefee)]
+///     end
+///   end
+///   discard([discard])
+///   production([Block Production])
+///   new([New Block])
+///   A[Incoming Tx] --> B[Validation] -->|insert| pool
+///   pool --> |if ready| B1
+///   pool --> |if ready + basfee too low| B2
+///   pool --> |nonce gap or lack of funds| B3
+///   pool --> |update| pool
+///   B1 --> |best| production
+///   B2 --> |worst| discard
+///   B3 --> |worst| discard
+///   B1 --> |increased fee| B2
+///   B2 --> |decreased fee| B1
+///   B3 --> |promote| B1
+///   B3 -->  |promote| B2
+///   new -->  |apply state changes| pool
+/// ```
 pub struct TxPool<T: TransactionOrdering> {
     /// How to order transactions.
     ordering: Arc<T>,