Xian Network Node

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

Requirements

• Python 3.11.11 (other versions are not officially supported)
• CometBFT 0.38 (specifically 0.38.x, not 0.37.x or 1.0.x)
• PostgreSQL (for Blockchain Data Service)
• PM2 (for process management)

Dependencies Installation

Python Installation

Xian Node requires Python 3.11.11 specifically. We recommend using pyenv to manage Python versions.

Installing pyenv

• macOS/Linux: Follow the installation instructions at https://github.com/pyenv/pyenv#installation
• Windows: Use pyenv-win with instructions at https://github.com/pyenv-win/pyenv-win#installation

Installing Python 3.11.11 with pyenv

Once pyenv is installed, you can install and set up Python 3.11.11:

# Install Python 3.11.11
pyenv install 3.11.11

# Set it as your global Python version (optional)
pyenv global 3.11.11

# Verify the installation
python --version  # Should output Python 3.11.11

Installing CometBFT 0.38

Xian Node requires CometBFT 0.38.x specifically (not 0.37.x or 1.0.x). Follow these steps to install it:

1. Download the appropriate binary for your platform from the CometBFT releases page

   • Make sure to select a release with version 0.38.x (e.g., v0.38.0, v0.38.1, etc.)

2. For Linux/macOS:

   # Example for Linux amd64, adjust the version number and OS/arch as needed
   wget https://github.com/cometbft/cometbft/releases/download/v0.38.0/cometbft_0.38.0_linux_amd64.tar.gz
   
   # Extract the tarball
   tar -xzf cometbft_0.38.0_linux_amd64.tar.gz
   
   # Move the binary to your PATH
   sudo mv cometbft /usr/local/bin/
   
   # Verify the installation
   cometbft version  # Should output v0.38.x

3. For Windows:

   • Download the appropriate Windows zip file
   • Extract the contents
   • Add the extracted directory to your PATH environment variable
   • Verify installation by running cometbft version in Command Prompt or PowerShell

Remember, it's crucial to use CometBFT 0.38.x as other versions are not compatible with Xian Node.

Installation and Usage

There are multiple ways to set up and run Xian Node:

Method 1: Production Installation (via PyPI)

# Ensure you're using Python 3.11.11
pyenv local 3.11.11

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

# Install the package
pip install xian-node

# Initialize the node
xian-node init

# Start the node (standard mode)
xian-node up

# Start the node with Blockchain Data Service (BDS)
xian-node up --bds

# View logs
xian-node logs

# Stop the node
xian-node down

Additional commands:

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

Method 2: Installation with Poetry

Poetry is a dependency management and packaging tool for Python. To install Poetry, follow the instructions at https://python-poetry.org/docs/#installation.

# Ensure pyenv is set to Python 3.11.11
pyenv local 3.11.11

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

# Configure Poetry to use Python 3.11.11
poetry env use $(pyenv which python)

# Install dependencies with Poetry
poetry install

# Use Poetry to run commands
poetry run xian-node init
poetry run xian-node up

# Or activate the Poetry virtual environment and run directly
poetry shell
xian-node init
xian-node up

Method 3: Development Installation (from source)

# Ensure you're using Python 3.11.11
pyenv local 3.11.11

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

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

# Install in development mode
pip install -e .

# Initialize CometBFT
make init

# Start the node (standard mode)
make up

# Start the node with Blockchain Data Service (BDS)
make up-bds

# View logs
make logs

# Stop all services
make down

Additional Makefile commands:

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

Blockchain Data Service (BDS)

The Blockchain Data Service provides additional data storage and querying capabilities:

• Store blockchain data in a PostgreSQL database
• Enable advanced querying and indexing of blockchain state
• Enhance performance for complex data retrieval

Starting with BDS

To start the node with the Blockchain Data Service enabled, use:

# In PyPI installation
xian-node up --bds

# In development mode
make up-bds

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:

# 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

# Run tests
python -m pytest tests/

License

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

Related Projects

• xian-stack: Complete blockchain stack deployment packaged as a Docker container
• xian-contracting: Smart contract engine used by xian-node
• xian-js: JavaScript SDK for xian-node
• xian-py: Python SDK for xian-node

Repository Stats