# monero-project/monero architecture

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

- Interactive diagram: https://gitdiagram.com/monero-project/monero
- Repository: https://github.com/monero-project/monero

## Overview

Monero is a C++ implementation of a privacy-preserving, decentralized digital-currency node and wallet library. The principal node workflow is initiated when a **node operator or OS process launcher** starts `monerod`: it parses startup options, enters the daemon lifecycle, runs an executor, and then participates in the Monero peer-to-peer network by synchronizing, validating, storing, and relaying blockchain data.

#### Runtime and operator interfaces

- **Node operator / OS process launcher** — path: null — Starts the `monerod` process and supplies command-line arguments.
- **Monerod command entry** — `src/daemon/main.cpp` — Defines `main`, initializes process utilities, builds daemon/core option sets, and passes a daemon executor to `daemonizer::daemonize`.
- **Daemon lifecycle host** — `src/daemonizer/daemonizer.h` — Provides the cross-platform daemon/service lifecycle abstraction invoked by the command entry; implementation details were not sampled.
- **Daemon runtime executor** — `src/daemon/executor.cpp` — Represents the callback-based runtime work handed to the daemonizer, although its startup and construction logic was not sampled.
- **Daemon RPC command layer** — `src/daemon/rpc_command_executor.cpp` — Contains daemon-side RPC command execution functionality; the sampled inputs do not establish its HTTP server binding.

#### Peer network and consensus processing

- **Remote Monero P2P peers** — path: null — Other nodes in the decentralized network that exchange blocks and transactions with this node.
- **P2P transport** — `src/p2p` — Owns the repository’s peer-network transport subsystem; its concrete connection/message implementation was not included in the sample.
- **Synchronization and relay protocol** — `src/cryptonote_protocol/cryptonote_protocol_handler.h` — Implements the Cryptonote network-protocol handler family for synchronization and block/transaction propagation.
- **Relay protocol contract** — `src/cryptonote_protocol/cryptonote_protocol_handler_common.h` — Defines the protocol interface for synchronization status and relaying fluffy blocks and transactions to peers.
- **Consensus core** — `src/cryptonote_core/cryptonote_core.cpp` — Houses the node’s core coordination layer, with neighboring modules for blockchain handling, transaction validation, transaction construction, and pool management.
- **Blockchain ledger** — `src/cryptonote_core/blockchain.cpp` — Maintains the chain-state subsystem used to validate and organize accepted blocks.
- **Transaction pool** — `src/cryptonote_core/tx_pool.cpp` — Maintains pending transactions prior to their inclusion in accepted blocks.
- **Protocol data, accounts, difficulty, and mining** — `src/cryptonote_basic/cryptonote_basic_impl.cpp` — Provides foundational Cryptonote transaction/block structures and related consensus utilities; the directory also contains account, difficulty, miner, and hard-fork modules.
- **Network-upgrade rules** — `src/cryptonote_basic/hardfork.cpp` — Implements the scheduled hard-fork/version-rule mechanism documented in the README.

#### Cryptography and durable chain state

- **Cryptographic primitives and proof-of-work support** — `src/crypto/crypto.cpp` — Provides core cryptographic operations within a larger subsystem containing hashes, key operations, RandomX/Cryptonight-related code, and secure randomness.
- **RingCT privacy proofs** — `src/ringct` — Represents the transaction-confidentiality and ring-signature subsystem referenced by the project’s privacy model; its internal files were not sampled.
- **FCMP++ cryptographic support** — `src/fcmp_pp/fcmp_pp_crypto.cpp` — Implements cryptographic operations for the separate FCMP++ subsystem.
- **LMDB blockchain database backend** — `src/blockchain_db/lmdb/db_lmdb.cpp` — Implements an LMDB-backed blockchain database driver.
- **Blockchain database abstraction** — `src/blockchain_db/blockchain_db.cpp` — Defines the storage-layer abstraction used by concrete blockchain database backends.

#### Wallet and client-facing APIs

- **Wallet application or binding** — path: null — A downstream application, language binding, or UI that consumes the public wallet API.
- **Wallet manager API** — `src/wallet/api/wallet_manager.cpp` — Creates, opens, and recovers `WalletImpl` instances, configures restore height, and attaches optional wallet listeners.
- **Wallet implementation subsystem** — `src/wallet` — Contains wallet implementation code, including wallet basics and API support; the `WalletImpl` definition itself was not sampled.
- **Daemon JSON-RPC client** — `src/common/rpc_client.h` — Opens HTTP connections to a daemon and invokes JSON-RPC methods at `/json_rpc`, checking both transport success and daemon status.

#### Serialization infrastructure

- **Portable structured-storage codec** — `contrib/epee/src/portable_storage.cpp` — Serializes the portable storage tree to binary or JSON and loads structured data from those formats.
- **Bounded binary structured-storage reader** — `contrib/epee/include/storages/portable_storage_from_bin.h` — Parses portable binary storage with recursion, object, field, and string limits.
- **JSON structured-storage parser** — `contrib/epee/include/storages/portable_storage_from_json.h` — Builds nested storage sections and arrays while parsing JSON input.
- **Typed JSON storage helpers** — `contrib/epee/include/storages/portable_storage_template_helper.h` — Converts typed structures to and from the portable-storage JSON representation.

#### Relationships

- **Node operator / OS process launcher -> Monerod command entry:** starts the process with `argc`/`argv`; evidence: `main` is defined here.
- **Monerod command entry -> Daemon lifecycle host:** invokes daemonization with a constructed executor; evidence: the call to `daemonizer::daemonize`.
- **Daemon lifecycle host -> Daemon runtime executor:** receives the supplied executor callback to run under the chosen lifecycle mode; evidence: the executor object is passed into daemonization.
- **Synchronization and relay protocol -> Remote Monero P2P peers:** relays blocks and transactions; evidence: the protocol contract declares `relay_block` and `relay_transactions`.
- **Consensus core -> Blockchain ledger:** owns or coordinates accepted-chain processing; evidence: the core module is colocated with the blockchain subsystem, though construction call sites were not sampled.
- **Consensus core -> Transaction pool:** owns or coordinates pending-transaction processing; evidence: the core module is colocated with the transaction-pool subsystem, though construction call sites were not sampled.
- **Blockchain ledger -> Blockchain database abstraction:** reads and writes durable chain state through the database layer; exact call sites were not sampled.
- **Blockchain database abstraction -> LMDB blockchain database backend:** supports LMDB as a concrete persistence implementation; evidence: the backend is organized beneath the blockchain database subsystem.
- **Wallet application or binding -> Wallet manager API:** calls public create, open, and recovery operations.
- **Wallet manager API -> Wallet implementation subsystem:** instantiates `WalletImpl`, calls create/open/recover methods, sets restore height, and assigns listeners.
- **Daemon JSON-RPC client -> Daemon RPC command layer:** targets a daemon JSON-RPC endpoint using HTTP; the client explicitly invokes `/json_rpc`, while server-side endpoint wiring was not sampled.
- **Portable structured-storage codec -> Bounded binary structured-storage reader:** uses the binary portable-storage parsing machinery; evidence: the codec includes the binary reader implementation.
- **Portable structured-storage codec -> JSON structured-storage parser:** loads JSON into the portable-storage tree; evidence: the codec includes and calls its JSON loading path.
- **Typed JSON storage helpers -> Portable structured-storage codec:** create a portable-storage object before loading or emitting typed JSON.

#### Coverage limits

The sampled source proves daemon entry/daemonization, wallet-manager behavior, RPC-client calls, relay interface methods, and portable-storage behavior. It does not show the daemon executor’s internals, concrete P2P transport, RPC server registration, core-to-ledger call sites, database selection, or the detailed RingCT/FCMP++ verification path; those relationships are therefore qualified as ownership or organization rather than asserted runtime wiring.

Main entry points: [`contrib/epee/src/portable_storage.cpp`](https://github.com/monero-project/monero/blob/master/contrib/epee/src/portable_storage.cpp) (Portable structured-storage codec), [`src/cryptonote_core/cryptonote_core.cpp`](https://github.com/monero-project/monero/blob/master/src/cryptonote_core/cryptonote_core.cpp) (Consensus core), [`src/daemon/main.cpp`](https://github.com/monero-project/monero/blob/master/src/daemon/main.cpp) (Monerod command entry), [`src/daemonizer/daemonizer.h`](https://github.com/monero-project/monero/blob/master/src/daemonizer/daemonizer.h) (Daemon lifecycle host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and Interfaces"]
  node_monerod_entry["Monerod command entry<br/>entry point"]
  node_daemonizer["Daemon lifecycle host<br/>lifecycle service"]
  node_executor["Daemon runtime executor<br/>runtime callback"]
  node_rpc_commands["Daemon RPC command layer<br/>RPC service"]
end

subgraph group_network["Network and Consensus"]
  node_p2p["P2P transport<br/>network transport"]
  node_protocol["Synchronization and relay<br/>protocol handler"]
  node_protocol_contract["Relay protocol contract<br/>protocol interface"]
  node_consensus["Consensus core<br/>core service"]
  node_ledger["Blockchain ledger<br/>chain state"]
  node_tx_pool["Transaction pool<br/>pending state"]
  node_basic["Protocol and consensus data<br/>consensus utilities"]
  node_hardfork["Network-upgrade rules<br/>rule service"]
end

subgraph group_storage_crypto["Cryptography and Chain State"]
  node_crypto{{"Cryptographic primitives<br/>cryptography"}}
  node_ringct{{"RingCT privacy proofs<br/>privacy cryptography"}}
  node_fcmp{{"FCMP++ cryptography<br/>[fcmp_pp_crypto.cpp]"}}
  node_db_abstraction["Blockchain database abstraction<br/>storage abstraction"]
  node_lmdb[("LMDB blockchain database<br/>[db_lmdb.cpp]")]
end

subgraph group_wallet["Wallet APIs"]
  node_wallet_manager["Wallet manager API<br/>wallet API"]
  node_wallet_impl["Wallet implementation<br/>wallet subsystem"]
  node_rpc_client["Daemon JSON-RPC client<br/>HTTP client"]
end

subgraph group_serialization["Serialization Infrastructure"]
  node_codec["Portable structured-storage codec<br/>serialization codec"]
  node_binary_reader["Bounded binary storage reader<br/>binary parser"]
  node_json_parser["JSON storage parser<br/>JSON parser"]
  node_json_helpers["Typed JSON storage helpers<br/>serialization helper"]
end

node_operator(("Node operator<br/>external actor"))
node_peers(("Remote Monero peers<br/>external network"))
node_wallet_app(("Wallet application<br/>external client"))

node_operator -->|"starts process"| node_monerod_entry
node_monerod_entry -->|"daemonizes"| node_daemonizer
node_daemonizer -->|"runs executor"| node_executor
node_protocol -->|"relays data"| node_peers
node_consensus -->|"coordinates chain"| node_ledger
node_consensus -->|"coordinates pool"| node_tx_pool
node_ledger -->|"persists chain"| node_db_abstraction
node_db_abstraction -->|"supports backend"| node_lmdb
node_wallet_app -->|"uses wallet API"| node_wallet_manager
node_wallet_manager -->|"manages wallets"| node_wallet_impl
node_rpc_client -->|"calls JSON-RPC"| node_rpc_commands
node_codec -->|"reads binary"| node_binary_reader
node_codec -->|"loads JSON"| node_json_parser
node_json_helpers -->|"creates storage"| node_codec

click node_monerod_entry "https://github.com/monero-project/monero/blob/master/src/daemon/main.cpp"
click node_daemonizer "https://github.com/monero-project/monero/blob/master/src/daemonizer/daemonizer.h"
click node_executor "https://github.com/monero-project/monero/blob/master/src/daemon/executor.cpp"
click node_rpc_commands "https://github.com/monero-project/monero/blob/master/src/daemon/rpc_command_executor.cpp"
click node_p2p "https://github.com/monero-project/monero/tree/master/src/p2p"
click node_protocol "https://github.com/monero-project/monero/blob/master/src/cryptonote_protocol/cryptonote_protocol_handler.h"
click node_protocol_contract "https://github.com/monero-project/monero/blob/master/src/cryptonote_protocol/cryptonote_protocol_handler_common.h"
click node_consensus "https://github.com/monero-project/monero/blob/master/src/cryptonote_core/cryptonote_core.cpp"
click node_ledger "https://github.com/monero-project/monero/blob/master/src/cryptonote_core/blockchain.cpp"
click node_tx_pool "https://github.com/monero-project/monero/blob/master/src/cryptonote_core/tx_pool.cpp"
click node_basic "https://github.com/monero-project/monero/blob/master/src/cryptonote_basic/cryptonote_basic_impl.cpp"
click node_hardfork "https://github.com/monero-project/monero/blob/master/src/cryptonote_basic/hardfork.cpp"
click node_crypto "https://github.com/monero-project/monero/blob/master/src/crypto/crypto.cpp"
click node_ringct "https://github.com/monero-project/monero/tree/master/src/ringct"
click node_fcmp "https://github.com/monero-project/monero/blob/master/src/fcmp_pp/fcmp_pp_crypto.cpp"
click node_db_abstraction "https://github.com/monero-project/monero/blob/master/src/blockchain_db/blockchain_db.cpp"
click node_lmdb "https://github.com/monero-project/monero/blob/master/src/blockchain_db/lmdb/db_lmdb.cpp"
click node_wallet_manager "https://github.com/monero-project/monero/blob/master/src/wallet/api/wallet_manager.cpp"
click node_wallet_impl "https://github.com/monero-project/monero/tree/master/src/wallet"
click node_rpc_client "https://github.com/monero-project/monero/blob/master/src/common/rpc_client.h"
click node_codec "https://github.com/monero-project/monero/blob/master/contrib/epee/src/portable_storage.cpp"
click node_binary_reader "https://github.com/monero-project/monero/blob/master/contrib/epee/include/storages/portable_storage_from_bin.h"
click node_json_parser "https://github.com/monero-project/monero/blob/master/contrib/epee/include/storages/portable_storage_from_json.h"
click node_json_helpers "https://github.com/monero-project/monero/blob/master/contrib/epee/include/storages/portable_storage_template_helper.h"

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_monerod_entry,node_daemonizer,node_executor,node_rpc_commands,node_wallet_app toneBlue
class node_p2p,node_protocol,node_protocol_contract,node_consensus,node_ledger,node_tx_pool,node_basic,node_hardfork toneAmber
class node_crypto,node_ringct,node_fcmp,node_db_abstraction,node_lmdb toneMint
class node_wallet_manager,node_wallet_impl,node_rpc_client toneRose
class node_codec,node_binary_reader,node_json_parser,node_json_helpers,node_operator,node_peers toneIndigo
```

## Components

### Runtime and Interfaces

Daemon entry, lifecycle, executor, and RPC boundary

- [Monerod command entry](https://github.com/monero-project/monero/blob/master/src/daemon/main.cpp): entry point · Defines main and invokes daemonization · `src/daemon/main.cpp`
- [Daemon lifecycle host](https://github.com/monero-project/monero/blob/master/src/daemonizer/daemonizer.h): lifecycle service · Provides cross-platform daemon/service lifecycle abstraction · `src/daemonizer/daemonizer.h`
- [Daemon runtime executor](https://github.com/monero-project/monero/blob/master/src/daemon/executor.cpp): runtime callback · Runs daemon work under the selected lifecycle mode · `src/daemon/executor.cpp`
- [Daemon RPC command layer](https://github.com/monero-project/monero/blob/master/src/daemon/rpc_command_executor.cpp): RPC service · Executes daemon-side RPC commands · `src/daemon/rpc_command_executor.cpp`

### Network and Consensus

Peer networking, synchronization, validation, and consensus

- [P2P transport](https://github.com/monero-project/monero/tree/master/src/p2p): network transport · Peer-network transport subsystem · `src/p2p`
- [Synchronization and relay](https://github.com/monero-project/monero/blob/master/src/cryptonote_protocol/cryptonote_protocol_handler.h): protocol handler · Synchronizes and propagates blocks and transactions · `src/cryptonote_protocol/cryptonote_protocol_handler.h`
- [Relay protocol contract](https://github.com/monero-project/monero/blob/master/src/cryptonote_protocol/cryptonote_protocol_handler_common.h): protocol interface · Defines synchronization and relay operations · `src/cryptonote_protocol/cryptonote_protocol_handler_common.h`
- [Consensus core](https://github.com/monero-project/monero/blob/master/src/cryptonote_core/cryptonote_core.cpp): core service · Coordinates chain, validation, construction, and pool processing · `src/cryptonote_core/cryptonote_core.cpp`
- [Blockchain ledger](https://github.com/monero-project/monero/blob/master/src/cryptonote_core/blockchain.cpp): chain state · Validates and organizes accepted blocks · `src/cryptonote_core/blockchain.cpp`
- [Transaction pool](https://github.com/monero-project/monero/blob/master/src/cryptonote_core/tx_pool.cpp): pending state · Maintains pending transactions · `src/cryptonote_core/tx_pool.cpp`
- [Protocol and consensus data](https://github.com/monero-project/monero/blob/master/src/cryptonote_basic/cryptonote_basic_impl.cpp): consensus utilities · Provides transaction, block, account, difficulty, mining, and related utilities · `src/cryptonote_basic/cryptonote_basic_impl.cpp`
- [Network-upgrade rules](https://github.com/monero-project/monero/blob/master/src/cryptonote_basic/hardfork.cpp): rule service · Implements scheduled hard-fork and version rules · `src/cryptonote_basic/hardfork.cpp`

### Cryptography and Chain State

Privacy primitives and durable blockchain storage

- [Cryptographic primitives](https://github.com/monero-project/monero/blob/master/src/crypto/crypto.cpp): cryptography · Provides cryptographic operations and proof-of-work support · `src/crypto/crypto.cpp`
- [RingCT privacy proofs](https://github.com/monero-project/monero/tree/master/src/ringct): privacy cryptography · Provides transaction confidentiality and ring-signature support · `src/ringct`
- [FCMP++ cryptography](https://github.com/monero-project/monero/blob/master/src/fcmp_pp/fcmp_pp_crypto.cpp): cryptography · Provides FCMP++ cryptographic operations · `src/fcmp_pp/fcmp_pp_crypto.cpp`
- [Blockchain database abstraction](https://github.com/monero-project/monero/blob/master/src/blockchain_db/blockchain_db.cpp): storage abstraction · Defines the blockchain storage layer · `src/blockchain_db/blockchain_db.cpp`
- [LMDB blockchain database](https://github.com/monero-project/monero/blob/master/src/blockchain_db/lmdb/db_lmdb.cpp): database · Concrete LMDB-backed blockchain database driver · `src/blockchain_db/lmdb/db_lmdb.cpp`

### Wallet APIs

Wallet clients, management, and implementation

- [Wallet manager API](https://github.com/monero-project/monero/blob/master/src/wallet/api/wallet_manager.cpp): wallet API · Creates, opens, and recovers wallet instances · `src/wallet/api/wallet_manager.cpp`
- [Wallet implementation](https://github.com/monero-project/monero/tree/master/src/wallet): wallet subsystem · Implements wallet behavior and API support · `src/wallet`
- [Daemon JSON-RPC client](https://github.com/monero-project/monero/blob/master/src/common/rpc_client.h): HTTP client · Invokes daemon JSON-RPC methods at /json_rpc · `src/common/rpc_client.h`

### Serialization Infrastructure

Portable structured-storage codecs and helpers

- [Portable structured-storage codec](https://github.com/monero-project/monero/blob/master/contrib/epee/src/portable_storage.cpp): serialization codec · Serializes and loads portable storage as binary or JSON · `contrib/epee/src/portable_storage.cpp`
- [Bounded binary storage reader](https://github.com/monero-project/monero/blob/master/contrib/epee/include/storages/portable_storage_from_bin.h): binary parser · Parses bounded portable binary storage · `contrib/epee/include/storages/portable_storage_from_bin.h`
- [JSON storage parser](https://github.com/monero-project/monero/blob/master/contrib/epee/include/storages/portable_storage_from_json.h): JSON parser · Builds storage sections and arrays from JSON · `contrib/epee/include/storages/portable_storage_from_json.h`
- [Typed JSON storage helpers](https://github.com/monero-project/monero/blob/master/contrib/epee/include/storages/portable_storage_template_helper.h): serialization helper · Converts typed structures to and from portable-storage JSON · `contrib/epee/include/storages/portable_storage_template_helper.h`

### Other components

- **Node operator**: external actor · Starts monerod and supplies command-line arguments
- **Remote Monero peers**: external network · Other nodes exchanging blocks and transactions
- **Wallet application**: external client · Downstream application, binding, or UI using the wallet API

## Connections

- Node operator → Monerod command entry: starts process · Supplies argc/argv to monerod
- Monerod command entry → Daemon lifecycle host: daemonizes · Passes a constructed executor to daemonizer::daemonize
- Daemon lifecycle host → Daemon runtime executor: runs executor · Receives the supplied executor callback
- Synchronization and relay → Remote Monero peers: relays data · Relays blocks and transactions to peers
- Consensus core → Blockchain ledger: coordinates chain · Owns or coordinates accepted-chain processing
- Consensus core → Transaction pool: coordinates pool · Owns or coordinates pending-transaction processing
- Blockchain ledger → Blockchain database abstraction: persists chain · Reads and writes durable chain state
- Blockchain database abstraction → LMDB blockchain database: supports backend · Supports LMDB as a concrete persistence implementation
- Wallet application → Wallet manager API: uses wallet API · Calls create, open, and recovery operations
- Wallet manager API → Wallet implementation: manages wallets · Instantiates WalletImpl and calls wallet operations
- Daemon JSON-RPC client → Daemon RPC command layer: calls JSON-RPC · Uses HTTP and invokes /json_rpc
- Portable structured-storage codec → Bounded binary storage reader: reads binary · Uses binary portable-storage parsing machinery
- Portable structured-storage codec → JSON storage parser: loads JSON · Loads JSON into the portable-storage tree
- Typed JSON storage helpers → Portable structured-storage codec: creates storage · Creates portable-storage objects for typed JSON conversion
