Metadata-Version: 2.4
Name: pybc-engine
Version: 0.1.0
Summary: A modular, production-ready blockchain engine built from scratch.
Author-email: Abdul Sabur <alsabur20@gmail.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"

# 📦 pybc-engine

[![PyPI version](https://badge.fury.io/py/pybc-engine.svg)](https://badge.fury.io/py/pybc-engine)
[![Python Versions](https://img.shields.io/pypi/pyversions/pybc-engine.svg)](https://pypi.org/project/pybc-engine/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A production-ready, modular blockchain engine built entirely from scratch in Python.

`pybc-engine` focuses on clean architecture, pluggable storage layers, and strict type safety. It serves as an excellent foundation for understanding distributed ledger technology, building local simulations, or extending into custom decentralized applications.

---

## ✨ Features

- **Modular Architecture:** Complete separation of concerns between Blocks, Transactions, Consensus, and Storage.
- **Pluggable Storage System:** Drop-in support for different databases. Includes both volatile (`MemoryStorage`) and persistent (`SQLiteStorage`) out of the box.
- **Proof-of-Work Consensus:** Implements a difficulty-based, deterministic mining algorithm.
- **Cryptographic Integrity:** Built-in validation utilities to guarantee the mathematical validity of the chain and prevent data tampering.
- **Production Quality:** 100% strictly type-hinted and highly optimized.

---

## 🚀 Installation

Install `pybc-engine` directly from PyPI using pip:

```bash
pip install pybc-engine
```

Requires Python 3.9 or higher.

## 💻 Quick Start

Building and mining your first local blockchain requires only a few lines of code:

```python
from pybc import Blockchain, ProofOfWork
from pybc.storage.memory import MemoryStorage

# 1. Initialize your pluggable components
storage = MemoryStorage()
consensus = ProofOfWork(difficulty=4)

# 2. Start the engine
engine = Blockchain(storage=storage, consensus=consensus)

# 3. Add transactions to the mempool
engine.add_transaction(sender="Alice", receiver="Bob", amount=150.50)

# 4. Mine the block
new_block = engine.mine_new_block()

if new_block:
    print(f"Mined Block #{new_block.index} with hash: {new_block.compute_hash()}")
    print(f"Transactions recorded: {len(new_block.transactions)}")
```

## 🛠️ Advanced Usage: Persistent Storage

If you want your blockchain to persist across sessions, simply swap out the MemoryStorage for the SQLiteStorage backend. The engine handles the rest.

```python
from pybc.storage.sqlite import SQLiteStorage

# This will automatically create and manage 'blockchain.db'
persistent_storage = SQLiteStorage(db_path="blockchain.db")
engine = Blockchain(storage=persistent_storage, consensus=consensus)
```

## 🤝 Contributing

Contributions are welcome! If you want to run the engine locally for development:

1. Clone the repository.

2. Install with development dependencies: pip install -e ".[dev]"

3. Run the test suite: pytest -v

4. Run type checking: mypy pybc

