# category-labs/monad architecture

> Architecture diagram of the GitHub repository category-labs/monad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/category-labs/monad
- Repository: https://github.com/category-labs/monad

## Overview

Monad Execution is the execution service for a Monad node, and can also replay historical EVM-chain blocks. Its principal workflow is block input, transaction scheduling and execution, then updated blockchain state. The documented architecture includes a custom EVM, database, and high-level scheduling; the tree also shows RPC, state sync, and execution-event facilities. The source excerpts are limited, so links between unsampled subsystems are shown only where the README or sampled entry point supports them.

Main entry points: [`cmd/monad/main.cpp`](https://github.com/category-labs/monad/blob/main/cmd/monad/main.cpp) (Execution daemon), [`category/execution/runloop`](https://github.com/category-labs/monad/tree/main/category/execution/runloop) (Block run loop), [`category/execution/ethereum/execute_block.cpp`](https://github.com/category-labs/monad/blob/main/category/execution/ethereum/execute_block.cpp) (Block execution), [`category/vm`](https://github.com/category-labs/monad/tree/main/category/vm) (Custom EVM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Execution runtime"]
  node_monad["Execution daemon<br/>[main.cpp]"]
  node_runloop["Block run loop"]
  node_scheduler["Transaction scheduling"]
  node_validation["Block and transaction validation<br/>[validate_block.cpp]"]
  node_block_exec["Block execution<br/>[execute_block.cpp]"]
end

subgraph group_evm["EVM execution"]
  node_evm["Custom EVM"]
  node_chain_rules["Chain rules and genesis"]
  node_monad_rules["Monad extensions"]
end

subgraph group_state["State and storage"]
  node_state["Execution state<br/>[state.cpp]"]
  node_triedb[("Trie database")]
  node_monaddb[("Monad page storage<br/>[storage_page.cpp]")]
  node_ethdb[("Ethereum database")]
  node_rust_triedb["Rust trie DB API<br/>[lib.rs]"]
end

subgraph group_interfaces["Node interfaces"]
  node_rpc["RPC execution support"]
  node_statesync["State sync"]
end

subgraph group_observability["Events and tooling"]
  node_event_ring["Event ring interface<br/>[event.hpp]"]
  node_exec_events["Execution events<br/>[mod.rs]"]
end

node_consensus(("Consensus daemon"))
node_replay(("Block replay input"))

node_consensus -->|"requests execution"| node_monad
node_replay -->|"provides blocks"| node_monad
node_monad -.->|"runs blocks"| node_runloop
node_runloop -->|"schedules transactions"| node_scheduler
node_runloop -.->|"validates blocks"| node_validation
node_runloop -->|"executes blocks"| node_block_exec
node_block_exec -->|"executes transactions"| node_evm
node_block_exec -->|"updates state"| node_state
node_evm -.->|"uses chain rules"| node_chain_rules
node_evm -->|"enables extensions"| node_monad_rules
node_state -.->|"stores trie state"| node_triedb
node_monad -->|"initializes database"| node_ethdb
node_monad -->|"starts sync server"| node_statesync
node_rpc -.->|"supports execution"| node_monad
node_monaddb -.->|"backs trie storage"| node_triedb
node_rust_triedb -.->|"accesses trie DB"| node_triedb
node_monad -->|"configures events"| node_event_ring
node_event_ring -.->|"carries event data"| node_exec_events

click node_monad "https://github.com/category-labs/monad/blob/main/cmd/monad/main.cpp"
click node_runloop "https://github.com/category-labs/monad/tree/main/category/execution/runloop"
click node_scheduler "https://github.com/category-labs/monad/blob/main/category/execution/monad/dispatch_transaction.cpp"
click node_validation "https://github.com/category-labs/monad/blob/main/category/execution/ethereum/validate_block.cpp"
click node_block_exec "https://github.com/category-labs/monad/blob/main/category/execution/ethereum/execute_block.cpp"
click node_evm "https://github.com/category-labs/monad/tree/main/category/vm"
click node_chain_rules "https://github.com/category-labs/monad/tree/main/category/execution/ethereum/chain"
click node_monad_rules "https://github.com/category-labs/monad/tree/main/category/execution/monad/staking"
click node_state "https://github.com/category-labs/monad/blob/main/category/execution/ethereum/state3/state.cpp"
click node_triedb "https://github.com/category-labs/monad/tree/main/category/mpt"
click node_monaddb "https://github.com/category-labs/monad/blob/main/category/execution/monad/db/storage_page.cpp"
click node_ethdb "https://github.com/category-labs/monad/tree/main/category/execution/ethereum/db"
click node_rpc "https://github.com/category-labs/monad/tree/main/category/rpc"
click node_statesync "https://github.com/category-labs/monad/tree/main/category/statesync"
click node_event_ring "https://github.com/category-labs/monad/blob/main/cmd/monad/event.hpp"
click node_exec_events "https://github.com/category-labs/monad/blob/main/rust/crates/monad-exec-events/src/events/mod.rs"
click node_rust_triedb "https://github.com/category-labs/monad/blob/main/rust/crates/monad-triedb/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_monad,node_runloop,node_scheduler,node_validation,node_block_exec toneBlue
class node_evm,node_chain_rules,node_monad_rules toneAmber
class node_state,node_triedb,node_monaddb,node_ethdb,node_rust_triedb toneMint
class node_rpc,node_statesync toneRose
class node_event_ring,node_exec_events,node_consensus,node_replay toneIndigo
```

## Components

### Execution runtime

- [Execution daemon](https://github.com/category-labs/monad/blob/main/cmd/monad/main.cpp): `cmd/monad/main.cpp`
- [Block run loop](https://github.com/category-labs/monad/tree/main/category/execution/runloop): `category/execution/runloop`
- [Transaction scheduling](https://github.com/category-labs/monad/blob/main/category/execution/monad/dispatch_transaction.cpp): `category/execution/monad/dispatch_transaction.cpp`
- [Block and transaction validation](https://github.com/category-labs/monad/blob/main/category/execution/ethereum/validate_block.cpp): `category/execution/ethereum/validate_block.cpp`
- [Block execution](https://github.com/category-labs/monad/blob/main/category/execution/ethereum/execute_block.cpp): `category/execution/ethereum/execute_block.cpp`

### EVM execution

- [Custom EVM](https://github.com/category-labs/monad/tree/main/category/vm): `category/vm`
- [Chain rules and genesis](https://github.com/category-labs/monad/tree/main/category/execution/ethereum/chain): `category/execution/ethereum/chain`
- [Monad extensions](https://github.com/category-labs/monad/tree/main/category/execution/monad/staking): `category/execution/monad/staking`

### State and storage

- [Execution state](https://github.com/category-labs/monad/blob/main/category/execution/ethereum/state3/state.cpp): `category/execution/ethereum/state3/state.cpp`
- [Trie database](https://github.com/category-labs/monad/tree/main/category/mpt): `category/mpt`
- [Monad page storage](https://github.com/category-labs/monad/blob/main/category/execution/monad/db/storage_page.cpp): `category/execution/monad/db/storage_page.cpp`
- [Ethereum database](https://github.com/category-labs/monad/tree/main/category/execution/ethereum/db): `category/execution/ethereum/db`
- [Rust trie DB API](https://github.com/category-labs/monad/blob/main/rust/crates/monad-triedb/src/lib.rs): `rust/crates/monad-triedb/src/lib.rs`

### Node interfaces

- [RPC execution support](https://github.com/category-labs/monad/tree/main/category/rpc): `category/rpc`
- [State sync](https://github.com/category-labs/monad/tree/main/category/statesync): `category/statesync`

### Events and tooling

- [Event ring interface](https://github.com/category-labs/monad/blob/main/cmd/monad/event.hpp): `cmd/monad/event.hpp`
- [Execution events](https://github.com/category-labs/monad/blob/main/rust/crates/monad-exec-events/src/events/mod.rs): `rust/crates/monad-exec-events/src/events/mod.rs`

### Other components

- **Consensus daemon**
- **Block replay input**

## Connections

- Consensus daemon → Execution daemon: requests execution (evidence: `README.md`)
- Block replay input → Execution daemon: provides blocks (evidence: `README.md`)
- Execution daemon → Block run loop: runs blocks
- Block run loop → Transaction scheduling: schedules transactions (evidence: `README.md`)
- Block run loop → Block and transaction validation: validates blocks
- Block run loop → Block execution: executes blocks (evidence: `README.md`)
- Block execution → Custom EVM: executes transactions (evidence: `README.md`)
- Block execution → Execution state: updates state (evidence: `README.md`)
- Custom EVM → Chain rules and genesis: uses chain rules
- Custom EVM → Monad extensions: enables extensions (evidence: `README.md`)
- Execution state → Trie database: stores trie state
- Execution daemon → Ethereum database: initializes database (evidence: `cmd/monad/main.cpp`)
- Execution daemon → State sync: starts sync server (evidence: `cmd/monad/main.cpp`)
- RPC execution support → Execution daemon: supports execution
- Monad page storage → Trie database: backs trie storage
- Rust trie DB API → Trie database: accesses trie DB
- Execution daemon → Event ring interface: configures events (evidence: `cmd/monad/event.hpp`)
- Event ring interface → Execution events: carries event data
