BlockSimPy

A discrete event simulator for blockchain networks supporting Proof-of-Work and Proof-of-Stake consensus mechanisms. Models mining competition, validator selection, block propagation, difficulty adjustment, and economic incentives. Includes attack simulations (selfish mining, 51% attacks, eclipse attacks) for security research and education. Enables controlled experimentation with blockchain protocols without operating live cryptocurrency nodes.

Supported chains: Bitcoin, Bitcoin Cash, Litecoin, Dogecoin, Ethereum 2.0

Features:

• PoW consensus with exponential mining time distribution
• PoS consensus with stake-weighted validator selection
• Network propagation with configurable topology and peer connections
• Difficulty adjustment algorithms and reward halving schedules
• Attack simulations: selfish mining, 51% double-spend, eclipse attacks
• Metrics export, checkpoint/resume, and reproducible simulations

Installation

pip install blocksimpy

Quick Start

Simulate Bitcoin for 100 blocks:

blocksimpy --chain btc --blocks 100

Simulate Ethereum 2.0 Proof-of-Stake:

blocksimpy --chain eth2 --blocks 100

Create custom blockchain with specific parameters:

blocksimpy --blocktime 30 --blocks 50 --miners 5

Short alias available:

bsim --chain btc --blocks 100

Attack Simulations

Selfish mining attack where adversary withholds blocks to gain unfair mining rewards:

blocksimpy --chain btc --blocks 100 --attack selfish --attacker-hashrate 0.3

51% double-spend attack where majority hashrate reverses confirmed transactions:

blocksimpy --chain btc --blocks 100 --attack double-spend --attacker-hashrate 0.51

Eclipse attack isolating victim nodes from the honest network:

blocksimpy --chain btc --blocks 100 --attack eclipse --victim-nodes 2

Testing

Run validation tests that verify simulator accuracy against known blockchain metrics:

python tests/test_validation.py

Documentation

Architecture

Configuration guide

License

Apache License 2.0 - see LICENSE for details.