Metadata-Version: 2.4
Name: blocksimpy
Version: 1.3.1
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.10+-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 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

```bash
pip install blocksimpy
```

## Quick Start

Run a Bitcoin simulation for 100 blocks:

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

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

Run a custom blockchain:

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

See all options:

```bash
blocksimpy --help
```

## Attack Simulations

Simulate known blockchain attacks for research and education:

```bash
# 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:

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

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

## Documentation

[Architecture](docs/ARCHITECTURE.md)

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


## License

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