iblock: C++ Bitcoin Network Simulator

• iblock is a C++ library for simulating Bitcoin networks, accurately reproducing protocol layers from peer-to-peer communication to block mining.
• It employs OMNeT++ modules that mirror real Bitcoin operations, enabling detailed modeling of transaction propagation, mempool dynamics, and proof-of-work mining.
• Scalability evaluations show iblock outperforms previous simulators in memory efficiency and execution time, supporting comprehensive blockchain research and testing.

iblock is a comprehensive C++ library for simulating Bitcoin networks, designed to leverage the OMNeT++ discrete-event simulation platform. Its primary aim is to achieve high accuracy and scalability for blockchain research, substantially exceeding the efficiency of prior high-level language-based simulators while offering seamless integration with a broad range of OMNeT++ ecosystem modules. iblock is architected as a modular system capturing the full Bitcoin network stack, from peer-to-peer communication and mempool dynamics to block propagation and mining under Proof-of-Work, and it is validated both via theoretical models and observed performance under real and adversarial conditions (Scatena et al., 23 Dec 2025).

1. Architecture and Core Components

iblock is implemented as a set of OMNeT++ compound and simple modules, structured to mirror the actual layered architecture of Bitcoin nodes.

• Global Modules:
  • GlobalBlockchainManager (GBM): Central registry holding a canonical data structure per unique block, responsible for genesis block creation, epoch-based difficulty retargeting, and pruning of abandoned branches.
  • NodeManager: Directory service tracking all current nodes.
  • WalletManager: Maintains associations between wallet addresses and nodes for transaction generation.
• Node Model:
  • Each node is an OMNeT++ compound module with configurable application modules, all inheriting from a common AppBase. The main subcomponents include:
  • BlockchainManager: Maintains a node’s local blockchain, handling fork selection, reorganizations, difficulty adjustment, and block propagation with synthetic delays.
  • MempoolManager: Manages a priority queue of unconfirmed transactions, ordered by fee rate (fee/size), simulating incoming message delays to model real network dissemination.
  • Wallet: Optional unless a node generates or spends coins; records the node’s UTXO set and transaction confirmations.
  • Miner: Optionally schedules block mining as a Poisson process (see Section 2), assembles candidate blocks, and issues new blocks to the network.
  • TransactionGenerator: Issues new transactions at a controlled rate by selecting UTXOs, choosing random recipients, and broadcasting outputs.
• Inter-Module Communication:
  • Intra-node communication uses Direct Method Calls (DMCs) for efficient invocation between applications.
  • Inter-node communication is achieved via OMNeT++ gates, with block and transaction messages subject to stochastic delays for realism.

2. Design Details and Implementation

2.1 Data Structures

• Block Storage: GBM stores unique blocks in memory only once. Nodes keep pointers to their current branch heads, minimizing duplication.
• Mempool: Maintained per node as a max-heap or balanced tree keyed by transaction fee rate.
• Wallet Management: UTXO sets are managed as hash maps mapping UTXO IDs to value and confirmation status.

2.2 Mining and Block Creation

• Mining Model: Each miner follows a Poisson block discovery process with instantaneous rate $\lambda = H / D$, where $H$ is miner hashrate and $D$ is current mining difficulty. The aggregate network block rate is $\Lambda = \sum_{i} \lambda_i = H_{total} / D$.
• Scheduling: Mining events are scheduled by exponential random intervals, consistent with the expected Poisson process for block discovery.

2.3 Block and Transaction Propagation

• Block and transaction messages to peers are delayed according to a configurable distribution $F_\Delta$ (e.g., exponential, empirical). Typical parameters reflect real Bitcoin propagation: mean delay $\approx$ 400 ms, standard deviation $\approx$ 200 ms.

2.4 Attack Scenarios and Metrics

• Selfish Mining: The selfish miner’s reward, $R(\alpha)$, is measured as the attacker's fraction of block rewards when controlling hash power share $\alpha$. The simulation captures the transition threshold (theoretical $\alpha_0 \approx 0.33$, $R(\alpha)>\alpha$ for $\alpha>0.33$ under $\gamma=0$).
• Orphan Rate Measurement: Orphaned blocks ($\rho$) are recorded, with rates staying $<5\%$ in honest operation and spiking up to $\sim12\%$ under selfish mining.

3. OMNeT++ Ecosystem Integration

iblock is developed as a native OMNeT++ project (NED + C++ + INI). It supports integration with:

• INET: TCP/IP protocol stack for detailed network simulation.
• Simu5G: 5G wireless network modules, allowing study of mobile and vehicular Bitcoin networks.
• Veins/Artery: Vehicular and mobility simulation frameworks, enabling deployment of nodes in scenarios reflecting real-world node movement or partitioning.

Simulation parameters at the gate level (bandwidth, latency) inherit from OMNeT++ connection configurations. All stochastic elements (e.g., mining, propagation, transaction generation) leverage OMNeT++’s RNG streams for reproducibility.

4. Scalability and Performance Evaluation

Performance assessments cover both absolute efficiency and comparative results with existing simulators. On a testbed (Intel i7-8705G, 4.1 GHz, 16 GB RAM, Linux), core findings are:

• Node Count Scalability: With $N$ nodes ($N=10$–$50$), execution time per simulated hour decreases slightly as more nodes are added due to more efficient wallet operations; memory usage grows linearly with $N$.
• Transaction Rate Scaling: Increasing the transaction rate (1–10 tx/s for 30 nodes) results in execution time and memory usage growing roughly linearly.
• Combined Scale: Scaling both $N$ and per-node tx rate increases runtime and memory more than linearly.
• BlockSim Comparison:
  • Memory: iblock uses $\sim$60 MB for 6 hours of simulation, vs. BlockSim $>$4 GB (and out-of-memory at longer durations).
  • Execution time: iblock completes 6 hours in 10 seconds; BlockSim requires 7 hours and 17 minutes.
  • CPU load for iblock remains well below single-core saturation, leaving significant resources for concurrent OMNeT++ component simulation.

5. Empirical Validation and Attack Scenario Analysis

5.1 Validation: Normal Operation

In normal operation (62 nodes, 10 miners, 3 days, 30 independent random seeds), measured statistics include:

• Mined blocks per miner track theoretical expectation $\alpha_i \cdot \Lambda \cdot T$ (with 95% confidence intervals containing the predicted number).
• Total block output and reward distributions align closely with predictedsix-blocks-per-hour mining schedule and proportional reward for mining share.

5.2 Validation: Selfish Mining

Configurations with a single selfish miner among otherwise honest miners ($\alpha$ varied from 10% to 40%, 2-day runs, 20 seeds) exhibit:

• Selfish rewards $R_s(\alpha)$ matching the theoretical Eyal & Sirer curve ($R_s<\alpha$ for $\alpha<0.33$, $R_s>\alpha$ above that threshold for $\gamma=0$).
• Orphan rate remains $<5\%$ honestly, rising to $\sim12\%$ in adversarial runs due to abandoned private chains.

6. Reproducibility and Availability

Source code and detailed experiment recipes are available at https://github.com/SpeedJack/iblock. Required dependencies are OMNeT++ 6.x and optionally complementary libraries (INET, Simu5G, Artery). All stochastic processes are initializable via OMNeT++-style seed controls. Experiment reproduction steps are scripted: clone repository, configure, build, select scenario INI files, run batched simulations, and extract results using native OMNeT++ tools or included Python scripts. All key metrics (block shares, orphan rates, etc.) are repeatable for any random seed, supporting rigorous scientific evaluation.

---

iblock demonstrates an efficient, modular design mapped closely to the actual Bitcoin protocol, supporting both rapid, large-scale experimentation and fine-grained validation of blockchain protocols and attacks. Its use of C++/OMNeT++ provides both the raw performance necessary for scaling and a flexible environment for incorporating network effects, wireless/mobile scenarios, and protocol extensions (Scatena et al., 23 Dec 2025).