Xian Node

Set up and manage Xian blockchain nodes. Use when deploying a Xian node to join mainnet/testnet, creating a new Xian network, or managing running nodes. Covers Docker-based setup via xian-stack, CometBFT configuration, and node monitoring.

Security Scan

The skill's files and runtime instructions are consistent with its stated purpose (deploying and managing Xian blockchain nodes); nothing in the bundle requests unrelated credentials or contains clandestine network exfiltration.

Purpose & Capability

Name/description (Xian node management) aligns with included content: SKILL.md contains build/run/config instructions and the two helper Python scripts match expected tooling (key generation, RPC status). No unrelated env vars, binaries, or config paths are requested.

Instruction Scope

Instructions stay within node setup/management scope. Minor concerns: SKILL.md shows example commands that embed a validator private key on the command line (risk of leaking to shell history or logs) and includes a hard-coded seed-node IP address — both are operational details users should verify before use.

Install Mechanism

No install spec — instruction-only plus two small scripts. This minimizes persistent install risk; scripts are simple and local-only (no remote downloads or extract steps).

Credentials

Skill requests no environment variables or credentials. The generate_validator_key script intentionally prints private keys for validator use; the skill does not attempt to collect or transmit secrets.

Persistence & Privilege

Skill does not request always-on or elevated privileges. It is user-invocable only and contains no code that modifies other skills or system-wide agent settings.

Assessment

This skill appears coherent for running Xian nodes, but take normal operational precautions before using it: 1) Verify the upstream xian-stack repository and the seed-node IP (the skill references a specific IP) so you aren't pointed to an untrusted peer. 2) Avoid pasting validator private keys directly into shell commands (use stdin, a protected file, or an interactive prompt) to prevent leakage in shell history or process lists. 3) Inspect the Docker images and any cloned repository before running them, and run builds in an isolated environment if possible. 4) Use the included scripts locally only — generate keys offline and keep private keys secret. If you want higher assurance, confirm the skill's author/source or compare these instructions to the official Xian docs/repository first.

Xian Node Skill

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

Quick Reference

Task	Command
Join mainnet	make setup && make core-build && make core-up && make init && make configure CONFIGURE_ARGS='--genesis-file-name genesis-mainnet.json --seed-node-address <seed> --copy-genesis'
Start node	make core-shell then make up inside container
View logs	pm2 logs --lines 100 (inside container)
Stop node	make down (inside container) or make core-down (stop container)
Check sync	curl -s localhost:26657/status | jq '.result.sync_info'

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

Command	Description
make up	Start xian + cometbft via pm2
make down	Stop all pm2 processes
make restart	Restart node
make logs	View pm2 logs
make wipe	Clear node data (keeps config)
make dwu	Down + wipe + init + up (full reset)

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

Command	Description
make core-up	Start container
make core-down	Stop container
make core-shell	Enter container shell
make core-bds-up	Start with BDS (PostgreSQL + GraphQL)

Ports

Port	Service
26656	P2P (peering)
26657	RPC (queries)
26660	Prometheus metrics
5000	GraphQL (BDS only)

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

Path	Contents
.cometbft/	CometBFT data + config
.cometbft/config/genesis.json	Network genesis
.cometbft/config/config.toml	Node configuration
.cometbft/data/	Blockchain data
xian-core/	Xian ABCI application
xian-contracting/	Python contracting engine

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