How monero-project/monero works
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: portable_storage.cpp Portable structured-storage codec · cryptonote_core.cpp Consensus core · main.cpp Monerod command entry · daemonizer.h Daemon lifecycle host
Components 27
Runtime and Interfaces
Daemon entry, lifecycle, executor, and RPC boundary
- Monerod command entry · Defines main and invokes daemonization
src/daemon/main.cpp - Daemon lifecycle host · Provides cross-platform daemon/service lifecycle abstraction
src/daemonizer/daemonizer.h - Daemon runtime executor · Runs daemon work under the selected lifecycle mode
src/daemon/executor.cpp - Daemon RPC command layer · Executes daemon-side RPC commands
src/daemon/rpc_command_executor.cpp
Network and Consensus
Peer networking, synchronization, validation, and consensus
- P2P transport · Peer-network transport subsystem
src/p2p - Synchronization and relay · Synchronizes and propagates blocks and transactions
src/cryptonote_protocol/cryptonote_protocol_handler.h - Relay protocol contract · Defines synchronization and relay operations
src/cryptonote_protocol/cryptonote_protocol_handler_common.h - Consensus core · Coordinates chain, validation, construction, and pool processing
src/cryptonote_core/cryptonote_core.cpp - Blockchain ledger · Validates and organizes accepted blocks
src/cryptonote_core/blockchain.cpp - Transaction pool · Maintains pending transactions
src/cryptonote_core/tx_pool.cpp - Protocol and consensus data · Provides transaction, block, account, difficulty, mining, and related utilities
src/cryptonote_basic/cryptonote_basic_impl.cpp - Network-upgrade rules · Implements scheduled hard-fork and version rules
src/cryptonote_basic/hardfork.cpp
Cryptography and Chain State
Privacy primitives and durable blockchain storage
- Cryptographic primitives · Provides cryptographic operations and proof-of-work support
src/crypto/crypto.cpp - RingCT privacy proofs · Provides transaction confidentiality and ring-signature support
src/ringct - FCMP++ cryptography · Provides FCMP++ cryptographic operations
src/fcmp_pp/fcmp_pp_crypto.cpp - Blockchain database abstraction · Defines the blockchain storage layer
src/blockchain_db/blockchain_db.cpp - LMDB blockchain database · Concrete LMDB-backed blockchain database driver
src/blockchain_db/lmdb/db_lmdb.cpp
Wallet APIs
Wallet clients, management, and implementation
- Wallet manager API · Creates, opens, and recovers wallet instances
src/wallet/api/wallet_manager.cpp - Wallet implementation · Implements wallet behavior and API support
src/wallet - Daemon JSON-RPC 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 · Serializes and loads portable storage as binary or JSON
contrib/epee/src/portable_storage.cpp - Bounded binary storage reader · Parses bounded portable binary storage
contrib/epee/include/storages/portable_storage_from_bin.h - JSON storage parser · Builds storage sections and arrays from JSON
contrib/epee/include/storages/portable_storage_from_json.h - Typed JSON storage helpers · Converts typed structures to and from portable-storage JSON
contrib/epee/include/storages/portable_storage_template_helper.h
Other components
- Node operator · Starts monerod and supplies command-line arguments
- Remote Monero peers · Other nodes exchanging blocks and transactions
- Wallet application · Downstream application, binding, or UI using the wallet API
Connections 14
- 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