Metadata-Version: 2.4
Name: blocksimpy
Version: 1.0.1
Summary: A high-fidelity blockchain discrete event simulator for research and education
Author-email: Bekmukhamed <bekmukhamed.tursunbayev@gmail.com>
Project-URL: Homepage, https://github.com/btursunbayev/blocksimpy
Project-URL: Repository, https://github.com/btursunbayev/blocksimpy.git
Project-URL: Bug Tracker, https://github.com/btursunbayev/blocksimpy/issues
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

[![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 that models mining competition, block propagation, difficulty adjustment, and economic incentives. The simulator enables controlled experimentation with blockchain protocols without operating live cryptocurrency nodes. Configurations for Bitcoin, Bitcoin Cash, Litecoin, and Dogecoin are provided.


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

## 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.
