Upgrading a network
A CenterChain release that changes consensus behaviour is applied at a block height through a software-upgrade plan, not by restarting nodes at a moment of the operator's choosing. Every validator must be running the new binary at the same height, or the network splits.
This page describes the mechanism. The release-specific changes are in the v1.1 notes.
Why the height matters
If half the validators accept a message the other half rejects, the two halves
compute different state and the chain forks. v1.1 is such a change: an old binary
accepts MsgForceTransfer, a new one rejects it. A block that contains one is
valid to one node set and invalid to the other.
The chain therefore does not rely on operators swapping binaries in time. It reads the plan on chain and switches every node at the height the plan names.
Registered plans
A node can only apply a plan its binary knows. The registered plan names are compiled in:
| Plan name | Purpose |
|---|---|
v0.55 | The first Cosmos SDK v0.55 state upgrade. |
v1.1 | Holder asset protection and single-leg authorizations. |
A node whose binary does not carry the handler for a plan that reaches its height cannot apply the upgrade and will stop. Building the binary from the release commit is what puts the handler there.
What the handler does
The handler is the same for every plan: it runs the module manager's migrations
with the version map the chain carried in. For v1.1 that means tokenfactory
migrates from consensus version 2 to 3, binding every pre-existing authorization
to SWAP. The store loader installs an empty store upgrade — no store is
added, renamed, or deleted.
Before the height
- Get the artifact. A release is a
v*tag whose workflow produces Linuxamd64/arm64archives and a SHA-256 checksum manifest, then signs the manifest with Cosign. Verify it before deploying:cosign verify-blobagainst the manifest, and compare the archive's SHA-256 to the manifest. - Back up the node home. State and the consensus key. An upgrade that goes wrong is recovered from a backup; there is no rewind.
- Stage, do not run. Put the new binary where the supervisor will find it at
the height and leave the old one running:
cosmovisor/upgrades/v1.1/bin/centerchaind. Cosmovisor is required in production so the switch happens at the height rather than when an operator is awake. - Submit the plan. A governance proposal carrying
MsgSoftwareUpgrade{Name: "v1.1", Height: H, Info: "<release-url> sha256=<hash>"}. The voting period and deposit are the network's governance parameters.
At the height
The node stops producing and applying blocks, the supervisor starts the staged binary, the store loader runs, the module migrations run, and the chain continues.
A chain that runs the binary inside its container image, with no supervisor, depends on operator action to restart at the height. That is a testnet convenience, not a production design: the halt lasts as long as the operator takes. When the plan is applied, stopping the containers before the height prevents the plan from ever being reached.
Rollback
A plan can be cancelled by governance only before its height. After the height there is no safe rollback: reverting the binary would re-interpret state the new code already wrote, and the chain cannot rewind. The only correct recovery is forward, to another release.
Verifying
Check the release notes' verification list after the height. For v1.1 the concrete checks are in v1.1 § Verifying the result.
Where this fits
- Network status — which networks exist and what each proves.
- Security and governance — the authority that signs an upgrade plan.