Upgrading

Xian upgrades should preserve runtime alignment across the validator set. The details vary slightly by execution engine, but the operator goal is always the same: move validators onto the same supported runtime without introducing application divergence.

Safe Upgrade Sequence

1. confirm the target version, image, or release bundle the network intends to run
2. stop the node cleanly
3. update the workspace or pull the pinned immutable image
4. validate the runtime locally
5. start the node again and confirm status, height, and runtime health

Example sibling-workspace flow:

cd ~/xian/xian-stack
make validate
make smoke-cli

cd ../xian-cli
uv run xian node stop validator-1
uv run xian node start validator-1
uv run xian node status validator-1
uv run xian node health validator-1

What Must Stay Aligned

Always keep aligned:

• xian-abci and xian-contracting
• canonical network manifests and pinned release images, when the network uses them
• the execution engine selected by the network

For xian_vm_v1, keep aligned:

• xian-abci and xian-contracting
• native VM runtime support
• deployment artifacts for submitted contracts

Preflight Checks

Before upgrading a validator fleet, use the maintained safety nets:

• make validate
• make smoke
• make smoke-cli
• localnet runs when the change touches execution, networking, or rollout logic

Validate the VM path whenever a change touches execution behavior.

Config And State Safety

• keep backups or restorable snapshots before high-risk upgrades
• prefer schema-validated manifest/profile rewrites through xian-cli
• avoid hand-editing canonical manifests on live validators
• keep governed state-patch bundles separate from normal upgrade artifacts

After Restart

After the node comes back:

• confirm it is healthy and not stuck
• confirm it is on the expected height and chain
• confirm the runtime posture matches the intended execution engine
• confirm any optional BDS and sidecar components recover cleanly if they are part of your deployment