Protocol Upgrades Overview

Managing Protocol Upgrades

This is a high-level meta-overview of protocol upgrades.

❗ If you need to trigger a protocol upgrade, see the Protocol Upgrade Release Procedure section ❗

Pocket Network evolves through protocol upgrades that keep the network secure, efficient, and up-to-date. These upgrades are coordinated by the DAO (offchain governance) and executed by validators (onchain).

Operators can apply upgrades automatically with Cosmovisor or manually otherwise.

Table of Contents

• What is a Protocol Upgrade?
• Where to Find Upgrade Info
• When is a Protocol Upgrade Needed?
• Types of Upgrades
  • Consensus-Breaking vs. Non-breaking
  • Planned vs. Unplanned
  • Manual Interventions
• Identifying Consensus-Breaking Changes
• High Level Protocol & Software Process

What is a Protocol Upgrade?

A protocol upgrade changes the onchain software to:

• Add new features
• Improve or fix existing functionality
• Address critical issues

Where to Find Upgrade Info

• GitHub Releases: All software updates and release notes
• Upgrade List: Details on each upgrade, breaking changes, and manual steps

Not All Releases Are Upgrades

Not every GitHub release triggers a protocol upgrade.

When is a Protocol Upgrade Needed?

Update Type	Protocol Upgrade	GitHub Release	Consensus-Breaking	Example
Consensus-breaking changes	Yes	Yes	✅	Changes to business logic in state machine
State-breaking changes	Yes	Yes	✅	Changes to protobufs/onchain state
Node (onchain) release	Optional	Yes	❌	Performance improvements
Offchain software release	No	Yes	❌	New CLI utilities

State vs Consensus Breaking

All state-breaking changes are consensus-breaking, but not all consensus-breaking changes are state-breaking.

Types of Upgrades

Consensus-Breaking vs. Non-breaking

• Consensus-breaking: All validators must upgrade to avoid chain splits.
• Non-breaking: Backward compatible; no immediate action required.

Planned vs. Unplanned

• Planned: Scheduled and announced (features, improvements, maintenance)
• Unplanned: Urgent, for bugs/security/chain halts; may require manual steps and can cause a hard fork.

Manual Interventions

• Some upgrades need manual steps from node operators or validators.
• Always review upgrade notes for manual intervention requirements.

Identifying Consensus-Breaking Changes

To spot consensus-breaking changes, check:

1. PRs with the consensus-breaking label since the last release
2. .proto files for breaking protobuf changes
3. x/ directories for breaking source code changes
4. New onchain parameters or authorizations

If a network fork is needed (e.g., non-deterministic state), an upgrade notice will be issued requiring manual intervention by users/validators to protect network integrity.

Not Exhaustive

This list is not exhaustive; protocol expertise is required to identify all possible consensus-breaking changes.

High Level Protocol & Software Process

For any consensus-breaking change, upgrades follow this path:

1. Proposal: DAO drafts and discusses the upgrade offchain.
2. Implementation: Changes are made in the codebase.
3. Testing: All changes are tested in devnet/testnet before mainnet.
4. Announcement: Upgrade details are shared with the community.
5. Deployment: Upgrade transaction is sent; Cosmovisor users upgrade automatically at the set block height.
6. Monitoring: Network is monitored post-upgrade for issues.