diff --git a/Makefile b/Makefile index f4c3b5899..5bd994ea3 100644 --- a/Makefile +++ b/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" diff --git a/mempool/README.md b/mempool/README.md index e0a373740..25230c870 100644 --- a/mempool/README.md +++ b/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 diff --git a/mempool/img/mempool_architecture.d2 b/mempool/img/mempool_architecture.d2 new file mode 100644 index 000000000..20f07e9ab --- /dev/null +++ b/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 \ No newline at end of file diff --git a/mempool/img/mempool_architecture.svg b/mempool/img/mempool_architecture.svg new file mode 100644 index 000000000..5a98f5c7d --- /dev/null +++ b/mempool/img/mempool_architecture.svg @@ -0,0 +1,237 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +PREPARE PROPOSALCHECK TXHANDLERCOMET BFTRPC CALLBROADCASTREBROADCASTCALLBACKEVM MEMPOOLEXT MEMPOOLINTERFACE IMPLCOSMOS PRIORITYNONCE MEMPOOLTX POOLQUEUEDTRANSACTIONSPENDINGTRANSACTIONSTX POOLINTERFACERESET LOOP(EVICTS FROMQUEUED ANDPENDING TXS)PROMOTIONFILTER ADD NONCEGAPPED TXSADDEXECUTABLE TXSPROMOTE TXCHECK CLOSED GAPAND PROMOTE TXGET TXS FORBLOCK BUILDINGADD VALID TXSGET TXS FORBLOCK BUILDINGGET TXS FORBLOCK BUILDINGSUCCESS/NONCE GAP FAILURE:ADD VALID EVM TXSRECHECK TXEVICTIONADDCOSMOS TXSREBROADCASTREBUILT TXCALL REBROADCASTCALLBACKGET TXS FORBLOCK BUILDINGSUCCESS:BROADCAST TXSEND TX FOR VALIDATIONSEND TX AGAINFOR RECHECKQUEUEDSUCCESS RESPONSESUCCESS: BROADCASTAND ADD TO MEMPOOLRECHECK TX COMPLETEFAILURE: DISCARD FROM POOLCOMPLETE FAILURE:REMOVE FROM PENDINGNONCE GAP FAILURE:ADD TRANSACTIONSUCCESS:ADD TXSRECHECK TX COMPLETEFAILURE: EVICTION + + + + + + + + + + + + + + + + + + + + + + + + + +UNLICENSED COPY