Metadata-Version: 2.4
Name: blocksimpy
Version: 1.4.0
Summary: A high-fidelity blockchain discrete event simulator for research and education
Author-email: Bekmukhamed Tursunbayev <bekmukhamed.tursunbayev@gmail.com>
Project-URL: Homepage, https://btursunbayev.github.io/
Project-URL: Repository, https://github.com/btursunbayev/blocksimpy.git
Keywords: blockchain,simulation,discrete-event,cryptocurrency,bitcoin,mining,research,education,network,consensus
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: simpy>=4.1.0
Requires-Dist: PyYAML>=6.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: sphinx>=5.0.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
Requires-Dist: myst-parser>=0.18.0; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Dynamic: license-file

# BlockSimPy

[![PyPI version](https://img.shields.io/pypi/v/blocksimpy.svg)](https://pypi.org/project/blocksimpy/)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)

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

```bash
pip install blocksimpy
```

## Quick Start

Simulate Bitcoin for 100 blocks:

```bash
blocksimpy --chain btc --blocks 100
```

Simulate Ethereum 2.0 Proof-of-Stake:

```bash
blocksimpy --chain eth2 --blocks 100
```

Create custom blockchain with specific parameters:

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

Short alias available:

```bash
bsim --chain btc --blocks 100
```

## Attack Simulations

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

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

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

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

Eclipse attack isolating victim nodes from the honest network:

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

## Testing

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

```bash
python tests/test_validation.py
```

## Documentation

[Architecture](docs/ARCHITECTURE.md)

[Configuration guide](src/blocksimpy/config/CONFIGURATION_GUIDE.md)


## License

Apache License 2.0 - see [LICENSE](LICENSE) for details.
