---
title: 'iblock: C++ Bitcoin Network Simulator'
url: https://www.emergentmind.com/topics/iblock
type: topic
---

# iblock: C++ Bitcoin Network Simulator

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 [2512.20402].

## 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 [2512.20402].

Source: https://www.emergentmind.com/topics/iblock