Upgrades and downgrades

Roll new mx-chain-go binaries across nodes. Stale upgrade locks self-heal. Downgrade by re-pointing at any cached binary tag.

Shortest commands

mxnode upgrade                              # latest tag, every node, rolling
mxnode upgrade --binary-tag v1.11.5         # pin the tag
mxnode upgrade --binary-tag v1.11.4         # downgrade — uses cached binary if present

To downgrade, pass any --binary-tag T already in the binstore. The acquirer reuses the cached binary instead of re-acquiring it, so the operation collapses to a local symlink swap + restart per node.

Options

Flag	Default	Effect
`--binary-tag <T>`	resolved from GitHub	Pin the `mx-chain-go` tag.
`--config-tag <T>`	leave untouched	Pin the `mx-chain-mainnet-config` tag.
`--proxy-tag <T>`	leave untouched	Pin the proxy tag (only when a proxy is installed).
`--strategy rolling\|parallel`	`rolling`	Per-node ordering.
`--max-parallel N`	`1`	Cap when `--strategy parallel`.
`--select '<expr>'`	`--all`	Selector grammar. See lifecycle.
`--node N`	all	Limit to specific nodes (repeatable).
`--shard <S>`	all	Limit to one shard.
`--skip-validators`	off	Skip validator-role nodes.
`--dry-run`	off	Print the resolved plan without doing anything.

Examples

# Just shard 0
mxnode upgrade --binary-tag v1.11.5 --shard 0

# A single node
mxnode upgrade --binary-tag v1.11.5 --node 2

# Parallel up to 2 (faster, less safe)
mxnode upgrade --binary-tag v1.11.5 --strategy parallel --max-parallel 2

# Squad-aware upgrade (reapplies observer-shape config edits)
mxnode upgrade squad --binary-tag v1.11.5 --proxy-tag v1.3.4

# Proxy only
mxnode upgrade proxy --proxy-tag v1.3.4

Per-node steps

Each node goes through five idempotent steps:

Step	What
`Resolving`	Acquire the binary into the binstore (skipped if cached)
`Stopped`	`systemctl stop`
`ConfigApplied`	Re-stamp `prefs.toml` for squad / observer edits
`BinaryReplaced`	Atomic symlink swap of `<workdir>/node` to the new tag
`Started`	`systemctl start`
`NonceVerified`	Poll the local REST API until nonce is within 5 of siblings or `is-syncing == 0`

Idempotency means it’s safe to re-run after a crash — every step is a no-op when the desired state is already in place.

Downgrade

upgrade --binary-tag <older> reuses the binstore if the tag is cached, making the operation a local symlink swap + restart per node. If the tag isn’t cached, mxnode re-acquires it. Pruning policy is controlled by [install].binary_keep in config.toml; the default of 3 keeps the last three tags.

Self-healing inflight.toml

Every upgrade writes a ~/.local/state/mxnode/inflight.toml lock at the start, updates current_step as the orchestrator advances, and removes it on completion. The file records:

op, started_at, strategy, selected nodes
completed nodes, current node, current_step
target_binary_tag, target_config_tag, target_proxy_tag
[identity] — owner pid + start token

Two purposes: lock (a second upgrade won’t clobber a running one) and crash breadcrumb (cat inflight.toml after a death tells you what step the upgrade died on). When mxnode upgrade starts and finds an existing inflight.toml, it classifies the recorded pid:

Pid status	mxnode behaviour
Live	Refuse — another mxnode is genuinely running.
Dead	Clear the file, log `→ clearing stale inflight.toml from previous run …`, proceed.
Indeterminate	Same as dead.

A crashed upgrade therefore self-recovers on the next invocation; rerunning the same mxnode upgrade command is the recovery procedure. Every per-node step is idempotent, so steps that already ran become no-ops the second time.

Audit log

Every upgrade attempt appends a MigrationEntry to state.toml’s migrations.entries[]:

[[migrations.entries]]
at = "2026-04-26T18:37:04Z"
to_binary = "v1.11.5"
strategy = "rolling"
trigger = "cli"
result = "ok"           # or "partial", "rolled-back"
duration_secs = 142
nodes_done = [0, 1, 2, 3]
nodes_failed = []

Dry run

mxnode upgrade --binary-tag v1.11.5 --dry-run

Resolves tags, builds the plan, prints what would run, then exits without touching anything.

​Shortest commands

​Options

​Examples

​Per-node steps

​Downgrade

​Self-healing inflight.toml

​Audit log

​Dry run