State-Breaking Change Catalog

A breaking change in the Cosmos SDK, IBC-Go, or CometBFT state machine will cause a hard fork if nodes run mismatched versions. The primary risk is an apphash mismatch at the upgrade height, leading to a chain halt. Operators must verify that the new binary produces identical state after applying all in-place store migrations. Chainscore can audit your custom migration handlers to ensure deterministic execution and prevent a consensus failure.

Changes to IBC light client verification, connection handshakes, or channel ordering semantics can break connections with counterparty chains. A breaking IBC-Go upgrade on one chain may require a coordinated upgrade or governance proposal on the counterparty to update the canonical client. Relayer operators must verify compatibility with new proof specs. Chainscore can perform an IBC compatibility audit to ensure your interchain connections survive the upgrade.

A state-breaking upgrade requires all validators to install the new binary and restart at the exact halt height. The operational risk is a subset of validators failing to upgrade, causing a liveness failure. Teams need a verified binary, a pre-signed upgrade plan, and automated monitoring for the UPGRADE_NEEDED consensus halt signal. Chainscore can design and test an automated upgrade monitoring and alerting system for your validator infrastructure.

A state-breaking change is activated via a SoftwareUpgradeProposal that specifies the plan name and halt height. Teams must monitor the governance lifecycle from submission to passage, and prepare the binary before the halt height is reached. A missed upgrade due to governance tracking failure results in downtime and potential slashing. Chainscore can build a governance monitoring dashboard to track active upgrade proposals and their activation timelines for your operations team.

Start with the Cosmos SDK release notes when a network upgrade introduces module migrations, store key changes, keeper interface changes, protobuf or Amino behavior changes, or altered begin-block/end-block logic. Appchain teams should compare the target SDK version against their current fork, then inspect migration code and module changelogs before writing an upgrade handler. Do not assume a minor version is safe for live state without checking whether migrations are required and whether downstream modules have pinned compatibility ranges.

Use IBC-Go release notes to identify changes that can affect light clients, packet lifecycle handling, channel and connection semantics, relayer behavior, or application modules such as transfer, Interchain Accounts, and callbacks. Relayer operators and counterparty chains should verify whether an upgrade changes client verification assumptions, message types, event formats, or timeout behavior. For any state-breaking IBC change, test packet submission, acknowledgement, timeout, and client update paths against the exact binary planned for mainnet.

Check CometBFT releases for consensus, mempool, P2P, ABCI, evidence, and state sync changes that may require coordinated validator action even when application migration logic is minimal. Validator and infrastructure teams should review database compatibility, configuration changes, consensus parameter handling, and any notes affecting replay, pruning, or state sync. A CometBFT upgrade can be operationally breaking without changing application state, so include it in the same readiness review as SDK and Gaia dependencies.

For Cosmos Hub-specific upgrades, Gaia release notes and repository history are the source of truth for binary requirements, upgrade handler names, module wiring, and Hub-specific migration behavior. Operators should verify the exact Gaia release required by the passed governance proposal and confirm whether the binary embeds the expected upgrade handler. Indexers, exchanges, and archival node teams should review Gaia changes for new message types, parameter initialization, module state migrations, and historical query behavior before the upgrade height.

Use the IBC specifications repository when a release note references a protocol-level change rather than an implementation-only patch. The specs help teams distinguish between changes to the IBC security model, client abstraction, packet commitments, application standards, or connection/channel protocol from changes limited to ibc-go internals. Architects should map implementation changes back to the relevant specification before approving upgrades that affect bridges, relayers, cross-chain accounts, or consumer-facing interoperability guarantees.