Xian Documentation

Appearance

Installation and Setup ​

The maintained operator path uses xian-cli, xian-stack, and xian-configs in a sibling workspace.

Requirements ​

  • macOS or Linux
  • Python 3.14
  • uv
  • Docker with Compose
  • Git

Typical layout:

text
~/xian/
  xian-cli/
  xian-stack/
  xian-abci/
  xian-configs/
  xian-contracting/
  xian-py/

Prepare the Workspace ​

bash
cd ~/xian/xian-cli
uv sync --group dev

cd ../xian-stack
make validate

For an isolated operator installation:

bash
uv tool install xian-tech-cli
xian --help

Node lifecycle still requires access to compatible xian-stack and xian-configs assets.

Create a Local Node ​

Interactive setup:

bash
xian setup node

Explicit local setup:

bash
xian network create local-dev \
  --chain-id xian-local-1 \
  --template single-node-dev \
  --generate-validator-key \
  --init-node

xian node start local-dev
xian node status local-dev
xian node endpoints local-dev
xian node health local-dev

single-node-dev enables the self-contained development surface by default: BDS/Postgres indexing, the read-only GraphQL endpoint and GraphiQL browser UI, the dashboard, Prometheus, and Grafana. Run xian node endpoints local-dev for the effective loopback URLs and xian node health local-dev to verify every enabled service. Five-second periodic blocks keep contract time moving while an interactive development node is idle.

IntentKit, DEX automation, the shielded relayer, product contract deployment, state sync, and speculative parallel execution remain explicit choices because they require extra repositories, credentials, product bootstrap, a peer network, or a dedicated test scenario.

Use --plan or --dry-run where supported to inspect paths and actions before writing files.

Join an Operator-Managed Network ​

Generate validator material, then join from an accepted manifest:

bash
xian keys validator generate --out-dir ./keys/validator-1

xian network join validator-1 \
  --network private-net \
  --network-manifest /path/to/network/manifest.json \
  --template single-node-indexed \
  --validator-key-ref ./keys/validator-1/validator_key_info.json \
  --stack-dir ../xian-stack

xian node init validator-1

Verify the manifest, genesis hash, image digests, peers, snapshot trust, chain ID, and operator contact process before starting. The current codebase has no active public testnet or mainnet; the checked-in mainnet manifest is a rehearsal asset.

Image Mode ​

For agent-assisted setup, the first-node guide covers a fresh operator-managed testnet, a separate treasury funded through the standard genesis bundle, and a verified public handoff. Share the participant guide with that handoff to join a full node and optionally request validator admission. These guides do not identify an already-live public network. Both guides default to BDS/PostgreSQL, read-only GraphQL/GraphiQL, and the node dashboard, with private host bindings and serial transaction execution. The pinned Ansible runtime deploys BDS and the dashboard; the guides include an explicit PostGraphile companion because enabling BDS there does not itself deploy a GraphQL server. Prometheus/Grafana remain optional.

  • registry uses immutable image references supplied by a manifest/profile.
  • local_build builds from sibling source checkouts and is intended for local development or unreleased testing.

Release deployments should use digest-pinned images and retain the embedded release provenance.

Pin the controller's CLI commit and resolved dependencies alongside the node release. A CLI package version can remain unchanged while its dependency lock is refreshed; an older tag's frozen lock may not match the selected runtime. Verify native VM/compiler builds and the controller's SDK separately from the server image. Execution-changing runtime fixes require coordinated upgrade and replay validation for an existing network, without regenerating genesis.

Remote Hosts ​

Use xian-deploy for supported Ansible-based Linux deployment:

bash
ansible-playbook playbooks/bootstrap.yml
ansible-playbook playbooks/push-home.yml
ansible-playbook playbooks/deploy.yml
ansible-playbook playbooks/health.yml

Remote configuration runs with a Python entrypoint override so the integrated image's supervisor and validator services start only with the Compose runtime. Use a deployment revision that includes this override.

Store inventory secrets in Ansible Vault, SOPS, CI secrets, or another secret manager. Do not commit validator keys, database passwords, or rendered secret files.

Next Steps ​