# Upgrade Overview

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

{% hint style="warning" %}
❗ If you need to trigger a protocol upgrade, see the [Protocol Upgrade Release Procedure](https://docs.pocket.network/building-on-the-pocket-network/welcome-to-pokt-roll/core-developers/protocol-upgrades/upgrade-preparation) section ❗
{% endhint %}

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](https://docs.pocket.network/building-on-the-pocket-network/welcome-to-pokt-roll/infra-operators/introduction-guides-and-walkthroughs-advanced/full-node-binary-30-min) or manually otherwise.

## 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](https://github.com/pokt-network/poktroll/releases): All software updates and release notes
* [Upgrade List](https://docs.pocket.network/building-on-the-pocket-network/welcome-to-pokt-roll/core-developers/protocol-upgrades/protocol-upgrade-list): Details on each upgrade, breaking changes, and manual steps

{% hint style="info" %}
Not All Releases Are Upgrades — Not every [GitHub release](https://github.com/pokt-network/poktroll/releases) triggers a protocol upgrade.
{% endhint %}

## 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 the following:

{% stepper %}
{% step %}

### Check PRs

Look for [PRs with the `consensus-breaking` label](https://github.com/pokt-network/poktroll/issues?q=label%3Aconsensus-breaking+) since the last release.
{% endstep %}

{% step %}

### Inspect protobufs

Review `.proto` files for breaking protobuf changes.
{% endstep %}

{% step %}

### Review source dirs

Examine `x/` directories for breaking source code changes.
{% endstep %}

{% step %}

### Look for onchain changes

Watch for new onchain parameters or authorizations.
{% endstep %}
{% endstepper %}

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:

{% stepper %}
{% step %}

### Proposal

DAO drafts and discusses the upgrade offchain.
{% endstep %}

{% step %}

### Implementation

Changes are made in the codebase.
{% endstep %}

{% step %}

### Testing

All changes are tested in devnet/testnet before mainnet.
{% endstep %}

{% step %}

### Announcement

Upgrade details are shared with the community.
{% endstep %}

{% step %}

### Deployment

Upgrade transaction is sent; Cosmovisor users upgrade automatically at the set block height.
{% endstep %}

{% step %}

### Monitoring

Network is monitored post-upgrade for issues.
{% endstep %}
{% endstepper %}
