This page introduces the rsnano-node repository, describes its purpose, and provides high-level diagrams showing how the major subsystems relate to each other. For details on any individual subsystem, follow the links to the relevant child pages throughout this document.
rsnano-node is a Rust implementation of a Nano cryptocurrency node. It maintains a local ledger replica, participates in Open Representative Voting (ORV) consensus, synchronizes with the network via bootstrap protocols, and exposes RPC/WebSocket interfaces.
The codebase is a Cargo workspace. The central orchestrator is the Node struct (node/src/node.rs107-170), which composes all major subsystems including the Ledger, ActiveElectionsContainer, BlockProcessor, Bootstrapper, and network transport layer. See Project Structure and Crate Architecture for the complete workspace layout.
Sources: node/src/node.rs107-170 Cargo.toml1-61
| Crate | Primary Types | Purpose |
|---|---|---|
rsnano_node | Node, BlockProcessor, ActiveElectionsContainer, Bootstrapper | Orchestrates consensus, block processing, bootstrap, transport |
rsnano_ledger | Ledger, BlockValidator, BlockInserter, BlockCementer | Block validation, ledger state management, confirmation |
rsnano_store_lmdb | LmdbStore, BlockStore, AccountStore, ConfirmationHeightStore | LMDB persistence layer |
rsnano_messages | Message, Publish, ConfirmReq, ConfirmAck, Keepalive | Network message wire formats |
rsnano_network | Network, Channel, TcpListener, PeerConnector | TCP peer connection management |
rsnano_network_protocol | InboundMessageQueue, NanoDataReceiverFactory, HandshakeStats | Message ingestion, handshake protocol |
rsnano_types | Block, Account, Vote, BlockHash, Amount, PublicKey | Domain types |
rsnano_utils | Stats, ThreadPool, BackpressureChannel, ContainerInfo | Stats, threading, backpressure utilities |
rsnano_wallet | Wallets, WalletStore, ReceivableSearch | Key management, wallet operations |
rsnano_rpc_server | RPC command handlers | HTTP JSON-RPC server |
nanospam | SpamLogic, AccountMap | Load testing tool |
test_helpers | System, assertion helpers | Integration test framework |
Sources: node/Cargo.toml1-90 node/src/node.rs107-170 Cargo.toml1-61
The Node struct (node/src/node.rs107-170) composes these subsystems as struct fields:
| Subsystem | Key Struct Fields in Node | Primary Types | Module Path |
|---|---|---|---|
| Node orchestration | runtime, config, network_params, flags | Node, NodeArgs, NodeConfig, NetworkParams | node/src/node.rs |
| Block processing | block_processor, block_processor_queue, unchecked | BlockProcessor, BlockProcessorQueue, UncheckedMap | node/src/block_processing/ |
| Active elections | active, vote_processor, vote_processor_queue, election_schedulers | ActiveElectionsContainer, VoteProcessor, VoteApplier, ElectionSchedulers | node/src/consensus/ |
| Cementation | confirming_set | ConfirmingSet, BlockCementer | node/src/cementation/, ledger/ |
| Bootstrap | bootstrapper, bootstrap_server | Bootstrapper, BootstrapServer, BlockInspector | node/src/bootstrap/ |
| Ledger & storage | ledger | Ledger, LmdbStore, BlockStore, AccountStore | ledger/, store_lmdb/ |
| Network transport | network, tcp_listener, peer_connector, inbound_message_queue | Network, TcpListener, PeerConnector, MessageFlooder | node/src/transport/, network/ |
| Representatives | online_reps, rep_tiers, rep_crawler | OnlineReps, CurrentRepTiers, RepCrawler | node/src/representatives/ |
| Wallets | wallets, vote_generators, wallet_reps | Wallets, VoteGenerators, WalletRepresentatives | node/src/wallets/, wallet/ |
| Backpressure | bounded_backlog, backlog_scan | BoundedBacklog, BacklogScan | node/src/block_processing/bounded_backlog/ |
| Ledger Snapshots | ledger_snapshots (feature) | LedgerSnapshots, Aggregator | node/src/ledger_snapshots/ |
Sources: node/src/node.rs107-170 node/src/node.rs172-194
This diagram maps major runtime subsystems to their concrete types in the Node struct and shows primary data flows.
Diagram: Node subsystems and data flows (code-level)
Sources: node/src/node.rs107-170 node/src/node.rs961-1015 node/src/transport/network_message_processor.rs1-100 node/src/block_processing/block_processor.rs1-50 node/src/consensus/vote_processor.rs1-50
The ActiveElectionsContainer implements Open Representative Voting (ORV) consensus. Blocks enter elections, accumulate votes from representatives, reach quorum, and transition to cemented state.
Diagram: Consensus pipeline from block to confirmation
Sources: node/src/consensus/active_elections/active_elections_container.rs99-178 node/src/consensus/vote_processor.rs1-120 node/src/consensus/vote_applier.rs15-116 node/src/aec_event_processor.rs28-187 node/src/cementation/confirming_set.rs1-200
Blocks from the network, RPC, bootstrap, or local wallets enter the BlockProcessorQueue, are processed in batches by BlockBatchProcessor, and pass through the Ledger for validation and insertion. Gap blocks (referring to unknown predecessors) park in UncheckedMap until their dependency arrives.
Diagram: Block processing pipeline (code-level)
Sources: node/src/block_processing/block_processor.rs54-135 node/src/block_processing/block_batch_processor.rs43-100 ledger/src/ledger.rs631-693 node/src/ledger_event_processor.rs1-90
The Ledger owns an LmdbStore, which is composed of individual named databases. All reads and writes go through LMDB transactions (ReadTransaction / WriteTransaction).
Diagram: Storage layer structure
Sources: ledger/src/ledger.rs120-130 ledger/src/ledger.rs234-266 ledger/src/ledger.rs450-462
Two systems keep the ledger synchronized with the network:
Bootstrapper) — proactively fetches missing blocks by scanning frontiers and following dependencies, using AscPullReq / AscPullAck messages.LedgerSnapshots, feature-gated) — an experimental multi-round consensus protocol where representatives exchange Preproposal → Proposal → ProposalVote messages to agree on a ledger snapshot, then roll back any forks that diverge from the agreed state.Diagram: Bootstrap and Ledger Snapshots (code-level)
Sources: node/src/bootstrap/bootstrapper.rs86-310 node/src/ledger_snapshots/mod.rs19-218
Subsystems communicate via backpressure-bounded channels to avoid tight coupling. Two primary event streams coordinate most inter-subsystem actions:
| Channel | Type | Created At | Producer | Key Consumers |
|---|---|---|---|---|
ledger_tx | Sender<LedgerPipelineEvent> | node/src/node.rs325-338 | Ledger, ConfirmingSet | LedgerEventProcessor → ElectionSchedulers, BoundedBacklog, LocalBlockBroadcaster |
aec_tx | Sender<AecEvent> | node/src/node.rs622-624 | ActiveElectionsContainer | AecEventProcessor → ConfirmingSet, VoteCache, ElectionSchedulers, WinnerBlockBroadcaster |
Backpressure handling: When aec_tx fills to 75% capacity, AecEventProcessor::cool_down() (node/src/aec_event_processor.rs51-57) sets a cooldown flag on the AEC to throttle election insertion. When it drains to 50%, recovered() (node/src/aec_event_processor.rs59-65) removes the cooldown. This prevents cascading queue growth.
Event types:
LedgerPipelineEvent: BlocksProcessed, BlocksConfirmed, BlocksRolledBack, UnconfirmedFoundAecEvent: ElectionStarted, ElectionConfirmed, ElectionEnded, VoteProcessed, BlockConfirmed, WinnerChangedSources: node/src/node.rs325-338 node/src/node.rs622-624 node/src/aec_event_processor.rs50-66 node/src/block_processing/ledger_pipeline_event.rs1-20 node/src/consensus/active_elections/mod.rs38-57
The Node::new() constructor (node/src/node.rs217-1028) builds all subsystems in dependency order, then Node::start() (node/src/node.rs1030-1141) activates background threads.
Construction order:
SteadyClock, ThreadFactorydata_path/data.ldb → construct Ledgerledger_tx and aec_tx backpressure channelsNetwork, TcpListener, PeerConnector, InboundMessageQueueOnlineReps, start OnlineWeightCalculation tickerVoteProcessorQueue, VoteApplier, ActiveElectionsContainer, ElectionSchedulers, VoteProcessorBlockProcessorQueue, BlockProcessor, ConfirmingSetBootstrapper with genesis accountLedgerEventProcessor plugins, set observers on AEC, wire vote cacheRepCrawler, LocalBlockBroadcaster, AecTickerStartup (Node::start()):
Sources: node/src/node.rs196-1141 node/src/node.rs217-1028
| Topic | Page |
|---|---|
| Crate layout and inter-crate dependencies | Project Structure and Crate Architecture |
Node struct lifecycle and wiring | Node Orchestration and Lifecycle |
| Elections, vote tallying, quorum | Active Elections Container, Vote Processing and Application |
| Block processing queue and gap handling | BlockProcessor and Fair Queue |
| Ledger validation and insertion | Block Validation and Insertion |
| LMDB store internals | LMDB Storage Architecture |
| Ascending bootstrap protocol | Bootstrap System |
| Ledger snapshot consensus | Ledger Snapshots Consensus |
| Testing infrastructure | Testing Framework and Helpers |