docs: add d2 tool to repo and mempool arch diagram (#597)

* add mempool draft

* add svg

* update readme

* add missing edge

* make tx handler two lines

* make ext mempool interface impl two lines

Author: almk-dev

Makefile

@@ -395,3 +395,73 @@ mocks:
 	@go get github.com/vektra/mockery/v2
 	@go generate ./...
 	@make format-go
+
+###############################################################################
+###                              D2 Diagrams                                ###
+###############################################################################
+
+D2_THEME=300
+D2_DARK_THEME=200
+D2_LAYOUT=tala
+
+D2_ENV_VARS=D2_THEME=$(D2_THEME) \
+	    D2_DARK_THEME=$(D2_DARK_THEME) \
+	    D2_LAYOUT=$(D2_LAYOUT)
+
+.PHONY: d2check d2watch d2gen d2gen-all
+
+d2check:
+	@echo "🔍 checking if d2 is installed..."
+	@which d2 > /dev/null 2>&1 || { \
+		echo "🔴 d2 is not installed, see installation docs: https://d2lang.com/tour/install/"; \
+		exit 1; \
+	}
+	@echo "🟢 d2 is installed"
+	@echo "🔍 checking if $(D2_LAYOUT) layout is installed..."
+	@d2 layout | grep $(D2_LAYOUT) > /dev/null 2>&1 || { \
+		echo "🔴 $(D2_LAYOUT) layout is not installed, see docs: https://d2lang.com/tour/layouts/"; \
+		exit 1; \
+	}
+	@echo "🟢 $(D2_LAYOUT) layout is installed"
+
+d2watch: d2check
+	@if [ -z "$(FILE)" ]; then \
+		echo "🔴 missing required parameter FILE, the correct usage is: make d2watch FILE=path/to/file.d2"; \
+		exit 1; \
+	fi
+	@if [ ! -f "$(FILE)" ]; then \
+		echo "🔴 file $(FILE) does not exist"; \
+		exit 1; \
+	fi
+	@echo "🔄 watching $(FILE) for changes..."
+	@dir=$$(dirname "$(FILE)"); \
+	basename=$$(basename "$(FILE)" .d2); \
+	svgfile="$$dir/$$basename.svg"; \
+	printf "📊 generating $$svgfile from $(FILE)... "; \
+	$(D2_ENV_VARS) d2 --watch "$(FILE)" "$$svgfile"
+
+d2gen: d2check
+	@if [ -z "$(FILE)" ]; then \
+		echo "🔴 missing required parameter FILE, the correct usage is: make d2gen FILE=path/to/file.d2"; \
+		exit 1; \
+	fi
+	@if [ ! -f "$(FILE)" ]; then \
+		echo "🔴 file $(FILE) does not exist"; \
+		exit 1; \
+	fi
+	@dir=$$(dirname "$(FILE)"); \
+	basename=$$(basename "$(FILE)" .d2); \
+	svgfile="$$dir/$$basename.svg"; \
+	printf "📊 generating $$svgfile from $(FILE)... "; \
+	$(D2_ENV_VARS) d2 "$(FILE)" "$$svgfile" > /dev/null 2>&1 && echo "done ✅" || echo "failed ❌";
+
+d2gen-all: d2check
+	@echo "🟢 generating svg files for all d2 diagrams..."
+	@find . -name "*.d2" -type f | while read d2file; do \
+		dir=$$(dirname "$$d2file"); \
+		basename=$$(basename "$$d2file" .d2); \
+		svgfile="$$dir/$$basename.svg"; \
+		printf "📊 generating $$svgfile from $$d2file... "; \
+		$(D2_ENV_VARS) d2 "$$d2file" "$$svgfile" > /dev/null 2>&1 && echo "done ✅" || echo "failed ❌"; \
+	done
+	@echo "✅ svg files generated for all d2 diagrams"

mempool/README.md

@@ -411,7 +411,7 @@ The following diagrams illustrate the complete transaction flow architecture, sh
 
 ### Architecture Overview
 
-![EVM Mempool Architecture](img/mempool_architecture.jpg)
+![EVM Mempool Architecture](img/mempool_architecture.svg)
 
 ### Transaction Flow
 

mempool/img/mempool_architecture.d2

@@ -0,0 +1,62 @@
+direction: right
+
+# entities
+prepare proposal
+check tx\nhandler
+comet bft
+rpc call
+broadcast
+rebroadcast\ncallback: { shape: diamond }
+evm mempool: {
+    direction: up
+
+    # entities
+    ext mempool\ninterface impl
+    cosmos priority\nnonce mempool
+    tx pool: {
+        direction: up
+
+        # entities
+        queued\ntransactions
+        pending\ntransactions
+        tx pool\ninterface
+        reset loop\n(evicts from\nqueued and\npending txs)
+        promotion: {shape: diamond }
+        filter: { shape: diamond }
+        
+        # edges
+        filter -> queued\ntransactions: add nonce\ngapped txs
+        filter -> pending\ntransactions: add\nexecutable txs
+        promotion -> pending\ntransactions: promote tx
+        queued\ntransactions -> promotion: check closed gap\nand promote tx
+        pending\ntransactions -> tx pool\ninterface: get txs for\nblock building
+        tx pool\ninterface -> filter: add valid txs
+    }
+    
+    # edges
+    tx pool.tx pool\ninterface -> ext mempool\ninterface impl: get txs for\nblock building
+    
+    cosmos priority\nnonce mempool -> ext mempool\ninterface impl: get txs for\nblock building
+
+    ext mempool\ninterface impl -> tx pool.tx pool\ninterface: success/nonce gap failure:\nadd valid evm txs
+    ext mempool\ninterface impl -> tx pool.tx pool\ninterface: recheck tx\neviction
+    ext mempool\ninterface impl -> cosmos priority\nnonce mempool: add\ncosmos txs
+}
+
+# edges
+rebroadcast\ncallback -> comet bft: rebroadcast\nrebuilt tx
+
+evm mempool.tx pool.promotion -> rebroadcast\ncallback: call rebroadcast\ncallback
+evm mempool.ext mempool\ninterface impl -> prepare proposal: get txs for\nblock building
+
+comet bft -> broadcast: success:\nbroadcast tx
+comet bft -> check tx\nhandler: send tx for validation
+comet bft -> check tx\nhandler: send tx again\nfor recheck
+
+check tx\nhandler -> rpc call: queued\nsuccess response
+check tx\nhandler -> comet bft: success: broadcast\nand add to mempool
+check tx\nhandler -> comet bft: recheck tx complete\nfailure: discard from pool
+check tx\nhandler -> evm mempool.ext mempool\ninterface impl: complete failure:\nremove from pending
+check tx\nhandler -> evm mempool.ext mempool\ninterface impl: nonce gap failure:\nadd transaction
+check tx\nhandler -> evm mempool.ext mempool\ninterface impl: success:\nadd txs
+check tx\nhandler -> evm mempool.ext mempool\ninterface impl: recheck tx complete\nfailure: eviction