Metadata-Version: 2.4
Name: HieraChain
Version: 0.0.5
Summary: HieraChain - The Hierarchical Blockchain Enterprise Ledger
Author-email: Nguyễn Lê Văn Dũng <dungnguyen2661@gmail.com>
License: Apache-2.0 OR MIT
Project-URL: Homepage, https://github.com/VanDung-dev/HieraChain
Project-URL: Bug Reports, https://github.com/VanDung-dev/HieraChain/issues
Project-URL: Source, https://github.com/VanDung-dev/HieraChain
Project-URL: License-Apache, https://github.com/VanDung-dev/HieraChain/blob/main/LICENSE-APACHE
Project-URL: License-MIT, https://github.com/VanDung-dev/HieraChain/blob/main/LICENSE-MIT
Project-URL: Security Policy, https://github.com/VanDung-dev/HieraChain/blob/main/SECURITY.md
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: Office/Business
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Requires-Dist: aiohttp>=3.14.1
Requires-Dist: boto3>=1.43.28
Requires-Dist: boto3-stubs>=1.43.28
Requires-Dist: click>=8.4.1
Requires-Dist: cryptography>=48.0.1
Requires-Dist: fastapi>=0.136.3
Requires-Dist: graphene>=3.4.3
Requires-Dist: httpx>=0.28.1
Requires-Dist: hvac>=2.4.0
Requires-Dist: kubernetes>=36.0.2
Requires-Dist: prometheus-client>=0.25.0
Requires-Dist: psutil>=7.2.2
Requires-Dist: pyarrow>=24.0.0
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pynacl>=1.6.2
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: pyzmq>=27.1.0
Requires-Dist: redis>=8.0.0
Requires-Dist: sqlalchemy>=2.0.50
Requires-Dist: starlette>=1.3.1
Requires-Dist: uvicorn[standard]>=0.49.0
Requires-Dist: urllib3>=2.7.0
Requires-Dist: idna>=3.18
Requires-Dist: httptools>=0.8.0
Requires-Dist: watchfiles>=1.2.0
Provides-Extra: doc
Requires-Dist: zensical>=0.0.43; extra == "doc"
Requires-Dist: polib>=1.2.0; extra == "doc"
Requires-Dist: pymdown-extensions>=10.21.3; extra == "doc"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-asyncio>=1.4.0; extra == "dev"
Requires-Dist: pytest-benchmark>=5.2.3; extra == "dev"
Requires-Dist: pytest-html>=4.2.0; extra == "dev"
Requires-Dist: pytest-rerunfailures>=16.3; extra == "dev"
Requires-Dist: hypothesis>=6.155.2; extra == "dev"
Requires-Dist: build>=1.5.0; extra == "dev"
Requires-Dist: twine>=6.2.0; extra == "dev"
Requires-Dist: websockets>=16.0; extra == "dev"
Dynamic: license-file

# HieraChain - The Hierarchical Blockchain Enterprise Ledger

![Python Versions](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13-blue)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE-APACHE)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE-MIT)
[![PyPI version](https://img.shields.io/pypi/v/HieraChain.svg)](https://pypi.org/project/HieraChain/)

**English** | [Tiếng Việt](README_vi.md)

## Overview

HieraChain is an enterprise ledger built on hierarchical blockchain technology, designed specifically for business applications without any cryptocurrency concepts. Rather than being a general-purpose blockchain platform focused on digital currencies, HieraChain provides a secure, hierarchical ledger structure for managing business operations and processes.

This ledger implements a multi-layer hierarchical architecture where Main Chains supervise Sub-Chains, enabling scalable and secure business process management. All operations within the system are referred to as "events" rather than "transactions," emphasizing its focus on business applications.

## Key Features

* **Hierarchical Structure**: Multi-layer architecture with Main Chains (supervisors) and Sub-Chains (domain experts).
* **Consensus Mechanisms**: Supports Proof of Authority (PoA), Proof of Federation (PoF), and Byzantine Fault Tolerant (BFT) consensus.
* **High Performance**: Columnar storage with Apache Arrow, hybrid caching, and parallel event processing.
* **Reliability & Recovery**: Durable transaction journaling, automated failure recovery, and state rollback capabilities.
* **Comprehensive Security Architecture**: An omnipresent, enterprise-grade security philosophy extending across the entire system lifecycle (not just a single module), built on 6 core pillars:

    * **Authorization** (ABAC Policy Engine & MSP)
    * **Lockdown & Logging** (Quorum-based Voting & Tamper-evident Logs)
    * **Fault-tolerance** (BFT & Federation)
    * **Risk Analyzer** (Real-time Z-score activity monitoring)
    * **Encryption** (AES-256-GCM for storage, Ed25519 for signatures)
    * **Decentralized Zero-Knowledge Proofs** (ZK Verifier for trustless chain anchoring)

## Documentation

Comprehensive documentation is available at our official website **[docs.hierachain.org](https://docs.hierachain.org/)**:

* [Getting Started](https://docs.hierachain.org/getting-started/install/) - Installation and basic setup
* [Architecture](https://docs.hierachain.org/architecture/overview/) - System design and hierarchical model
* [Core Modules](https://docs.hierachain.org/modules/core/) - Detailed breakdown of system components
* [Guides & How-To](https://docs.hierachain.org/how-to/integrate-web2/) - Step-by-step implementation guides
* [API Reference](https://docs.hierachain.org/reference/code-map/) - REST API and configuration details

## Quick Start

### Installation

**Via PIP (recommended)**

```bash
pip install HieraChain
```

**From source (for development)**

*Traditional `pip` method:*

```bash
git clone https://github.com/VanDung-dev/HieraChain.git
cd HieraChain
python -m venv venv
source venv/bin/activate  # Linux/macOS (or venv\Scripts\activate on Windows)

# Install dependencies and project in dev mode
pip install -e .[dev]
```

*Modern fast method with `uv` (recommended):*

```bash
git clone https://github.com/VanDung-dev/HieraChain.git
cd HieraChain

# Install uv if not installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Auto create venv + install ALL dependencies in one command
uv sync

source .venv/bin/activate
```

### Basic Usage

```python
from hierachain.hierarchical import HierarchyManager

manager = HierarchyManager()
manager.create_sub_chain("supply_chain")

# Add an event
manager.add_event("supply_chain", {
    "entity_id": "PROD-001",
    "event": "production_complete",
    "timestamp": 1703088000.0,
    "details": {"quantity": 100}
})

# Submit proof to main chain
manager.submit_proof("supply_chain")
```

API Server:

```bash
python -m hierachain
```

API available at `http://localhost:2661/docs`

## Technical Specifications

| Metric | Value                  |
|--------|------------------------|
| Test Cases | >700                   |
| Python Support | 3.10, 3.11, 3.12, 3.13 |
| Consensus Types | PoA, PoF, BFT          |
| Signature Algorithm | Ed25519                |
| Encryption | AES-256-GCM            |

## License

This project is dual licensed under either the [Apache-2.0 License](LICENSE-APACHE) or the [MIT License](LICENSE-MIT). You may choose either license.
