Upgrading

Xian upgrades should preserve runtime alignment across the validator set. The current supported node path uses the fixed xian_vm_v1 runtime, so the operator goal is to move validators onto the same supported runtime, compiler, and source-to-IR validation stack 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 fixed xian_vm_v1 runtime path
• native VM runtime support and its fixed gas schedule
• canonical source-to-IR compilation 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 node reports the intended xian_vm_v1 runtime versions
• confirm any optional BDS and sidecar components recover cleanly if they are part of your deployment