Metadata-Version: 2.1
Name: xian-core
Version: 1.0.1
Summary: Xian Network Python ABCI Server for CometBFT
Home-page: https://github.com/XianChain/xian
License: Apache-2.0
Keywords: blockchain,xian,cometbft,abci,python
Author: Xian Network
Author-email: info@xian.org
Requires-Python: >=3.11.0,<3.12.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: asyncpg
Requires-Dist: certifi (>=2022.12.7)
Requires-Dist: colorlog (>=3.1.4)
Requires-Dist: loguru
Requires-Dist: parameterized
Requires-Dist: protobuf (==3.20.3)
Requires-Dist: pyflakes
Requires-Dist: pynacl
Requires-Dist: requests
Requires-Dist: toml
Requires-Dist: urwid
Requires-Dist: xian-contracting
Requires-Dist: xian-py
Project-URL: Documentation, https://github.com/XianChain/xian
Project-URL: Repository, https://github.com/XianChain/xian
Description-Content-Type: text/markdown

# Xian Core

[![CI](https://github.com/xian-network/xian-core/actions/workflows/main.yml/badge.svg)](https://github.com/xian-network/xian-core/actions/workflows/main.yml)

Python-based ABCI (Application Blockchain Interface) server designed for CometBFT 0.38.12. This component serves as the core application layer for the Xian blockchain network.

## Requirements

- Python 3.11 (other versions are not supported)
- CometBFT 0.38.12
- PostgreSQL (for Blockchain Data Service)
- PM2 (for process management)

## Installation and Usage

There are two ways to set up and run Xian Core:

### Method 1: Production Installation (via PyPI)

```bash
# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate

# Install the package
pip install xian-core

# Initialize the node
xian init

# Start the node
xian up

# View logs
xian logs

# Stop the node
xian down
```

Additional commands:
```bash
xian node-id  # Get node ID
xian wipe     # Wipe blockchain data
xian help     # Show all available commands
```

### Method 2: Development Installation (from source)

```bash
# Clone the repository
git clone https://github.com/xian-network/xian-core.git
cd xian-core

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Initialize CometBFT
make init

# Start the node
make up

# View logs
make logs

# Stop all services
make down
```

Additional Makefile commands:
```bash
make dwu       # Down, wipe, init, up sequence
make node-id   # Show node ID
make ex-state  # Export state
```

## Key Features

- **ABCI Server**: Full implementation of CometBFT's ABCI protocol
- **Smart Contract Support**: Execution environment for Python-based smart contracts
- **State Management**: Advanced state handling with Hash and Variable storage types
- **Transaction Processing**: Comprehensive transaction validation and execution
- **Event System**: Rich event logging system for tracking contract and state changes
- **Blockchain Data Service (BDS)**: PostgreSQL-based service for storing and querying blockchain data
- **Validator Management**: Flexible validator set management
- **Rewards System**: Built-in system for handling transaction fees and rewards

## Architecture Components

- **ABCI Server**: Handles communication with CometBFT
- **Transaction Processor**: Manages transaction execution and state updates
- **Validator Handler**: Manages validator set changes
- **Rewards Handler**: Processes transaction fees and rewards
- **Nonce Manager**: Handles transaction ordering
- **Event System**: Tracks and logs blockchain events

## Configuration

The node uses several configuration files:

- CometBFT configuration: `~/.cometbft/config/config.toml`
- Genesis file: `~/.cometbft/config/genesis.json`
- BDS configuration: Located in the BDS service directory

## Query Interface

Examples of querying the node:

```bash
# Get contract state
curl "http://localhost:26657/abci_query?path=\"/get/currency.balances:ADDRESS\""

# Get node health
curl "http://localhost:26657/abci_query?path=\"/health\""

# Get next nonce
curl "http://localhost:26657/abci_query?path=\"/get_next_nonce/ADDRESS\""
```

## Development

### Testing
```bash
# Run tests
python -m pytest tests/
```

### Creating a Release
```bash
# Install required tools
pip install poetry

# Create a new release
./release.sh patch  # For bug fixes (0.1.0 -> 0.1.1)
./release.sh minor  # For new features (0.1.0 -> 0.2.0)
./release.sh major  # For breaking changes (0.1.0 -> 2.0.0)
```

## License

This project is licensed under the Apache License Version 2.0 - see the [LICENSE](LICENSE) file for details.

## Related Projects

- [xian-contracting](https://github.com/xian-network/xian-contracting): Smart contract engine
- [xian-stack](https://github.com/xian-network/xian-stack): Complete blockchain stack deployment
