blocksimpy 1.3.1

A high-fidelity blockchain discrete event simulator for research and education

BlockSimPy

A discrete event simulator for blockchain networks that models mining competition, block propagation, difficulty adjustment, and economic incentives. The simulator enables controlled experimentation with blockchain protocols without operating live cryptocurrency nodes.

Supported chains: Bitcoin, Bitcoin Cash, Litecoin, Dogecoin

Features:

• Proof-of-Work mining simulation with realistic exponential timing
• Network propagation with configurable topology
• Difficulty adjustment and halving events
• Attack simulations (selfish mining, 51% double-spend, eclipse)
• Checkpoint/resume and metrics export

Installation

pip install blocksimpy

Quick Start

Run a Bitcoin simulation for 100 blocks:

blocksimpy --chain btc --blocks 100

or

bsim --chain btc --blocks 100

Run a custom blockchain:

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

See all options:

blocksimpy --help

Attack Simulations

Simulate known blockchain attacks for research and education:

# Selfish mining - attacker withholds blocks to gain unfair rewards
blocksimpy --chain btc --blocks 100 --attack selfish --attacker-hashrate 0.3

# 51% double-spend - attacker reverses confirmed payments
blocksimpy --chain btc --blocks 100 --attack double-spend --attacker-hashrate 0.51

# Eclipse - isolate victim nodes from honest network
blocksimpy --chain btc --blocks 100 --attack eclipse --victim-nodes 2

Testing

Validate the simulator works correctly:

python tests/test_validation.py

This runs simulations for Bitcoin, Litecoin, Dogecoin, and Bitcoin Cash, validating that metrics match expected values.

Documentation

Architecture

Configuration guide

License

Apache License 2.0 - see LICENSE for details.