Xian Node Skill

Deploy and manage Xian blockchain nodes — an L1 with native Python smart contracts on CometBFT.

Quick Reference

Setup: Join Existing Network

1. Clone and Build

git clone https://github.com/xian-network/xian-stack.git
cd xian-stack
make setup CORE_BRANCH=mainnet CONTRACTING_BRANCH=mainnet
make core-build
make core-up

2. Initialize CometBFT

make init

3. Configure Node

Mainnet:

make configure CONFIGURE_ARGS='--moniker "my-node" --genesis-file-name "genesis-mainnet.json" --seed-node-address "c3861ffd16cf6708aef6683d3d0471b6dedb3116@152.53.18.220" --copy-genesis'

Testnet:

make configure CONFIGURE_ARGS='--moniker "my-node" --genesis-file-name "genesis-testnet.json" --seed-node-address "<testnet-seed>" --copy-genesis'

Validator node (add private key):

make configure CONFIGURE_ARGS='--moniker "my-validator" --genesis-file-name "genesis-mainnet.json" --validator-privkey "<your-privkey>" --seed-node-address "..." --copy-genesis'

Service node (with BDS - Blockchain Data Service):

make configure CONFIGURE_ARGS='--moniker "my-service" --genesis-file-name "genesis-mainnet.json" --seed-node-address "..." --copy-genesis --service-node'

4. Start Node

make core-shell   # Enter container
make up           # Start pm2 processes
pm2 logs          # Watch sync progress
exit              # Leave shell (node keeps running)

Setup: Create New Network

1. Build Stack

git clone https://github.com/xian-network/xian-stack.git
cd xian-stack
make setup CORE_BRANCH=mainnet CONTRACTING_BRANCH=mainnet
make core-build
make core-up
make init

2. Generate Validator Keys

Inside container (make core-shell):

# Generate new validator key
python -c "
from nacl.signing import SigningKey
import secrets
sk = SigningKey(secrets.token_bytes(32))
print(f'Private key: {sk.encode().hex()}')
print(f'Public key:  {sk.verify_key.encode().hex()}')
"

3. Create Genesis File

Create genesis.json with initial validators and state. See references/genesis-template.md.

4. Configure as Genesis Validator

make configure CONFIGURE_ARGS='--moniker "genesis-validator" --genesis-file-name "genesis-custom.json" --validator-privkey "<privkey>"'

5. Start Network

make core-shell
make up

Other nodes join using your node as seed.

Node Management

Inside Container Commands

Monitoring

Sync status:

curl -s localhost:26657/status | jq '.result.sync_info'

Response fields:

• latest_block_height: Current height
• catching_up: true if still syncing
• earliest_block_height: Lowest available block

Node info:

curl -s localhost:26657/status | jq '.result.node_info'
make node-id   # Get node ID for peering

Validators:

curl -s localhost:26657/validators | jq '.result.validators'

Docker Commands

Ports

Troubleshooting

Database lock error (resource temporarily unavailable):

# Duplicate pm2 processes - clean up:
pm2 delete all
make up

Sync stuck:

# Check peer connections
curl -s localhost:26657/net_info | jq '.result.n_peers'

# Verify seed node is reachable
make wipe
make init
# Re-run configure with correct seed

Container not starting:

make core-down
make core-build --no-cache
make core-up

File Locations

Test Your Node

After syncing, verify your node works with xian-py:

pip install xian-py

from xian_py import Xian, Wallet

# Connect to your local node
xian = Xian('http://localhost:26657')

# Query balance
balance = xian.get_balance('your_address')
print(f"Balance: {balance}")

# Get contract state
state = xian.get_state('currency', 'balances', 'some_address')
print(f"State: {state}")

# Create wallet and send transaction
wallet = Wallet()  # or Wallet('your_private_key')
xian = Xian('http://localhost:26657', wallet=wallet)
result = xian.send(amount=10, to_address='recipient_address')

For full SDK docs (contracts, HD wallets, async) — see xian-py.

Resources

• xian-network/xian-stack — Docker setup
• xian-network/xian-core — Core node
• xian-network/xian-py — Python SDK
• CometBFT docs — Consensus engine
• xian.org — Project site