> For the complete documentation index, see [llms.txt](https://bitnet-whitepaper.gitbook.io/developer-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bitnet-whitepaper.gitbook.io/developer-docs/upgrades-overview/upgrades.md).

# Upgrades

### Upgrade Procedures for BitNet Nodes

BitNet supports a robust and flexible upgrade framework, enabling validators and full node operators to smoothly manage software updates while maintaining chain integrity. Upgrades fall into several categories and can be applied manually or automatically.

***

#### Categories of Upgrades

<table data-header-hidden><thead><tr><th width="216.1484375"></th><th></th></tr></thead><tbody><tr><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td><strong>Planned</strong></td><td>Scheduled via governance proposals</td></tr><tr><td><strong>Unplanned</strong></td><td>Emergency or ad hoc updates coordinated manually</td></tr><tr><td><strong>Breaking/Non-breaking</strong></td><td>Based on semantic versioning and compatibility impact</td></tr><tr><td><strong>Data Reset</strong></td><td>Requires complete state reset and resync</td></tr></tbody></table>

***

#### Planned Upgrades (Governance-Based)

Planned upgrades are coordinated using on-chain governance. A **SoftwareUpgradeProposal** sets the target upgrade height and migration logic. Once the proposal passes, nodes auto-halt and perform the upgrade at the scheduled block.

{% hint style="info" %}
*Proposals require a full voting period before execution.*
{% endhint %}

***

#### Hard Forks (Urgent Upgrades)

Hard forks are triggered without waiting for governance voting. Instead, a **patch release** contains upgrade logic in its `BeginBlock`, which takes effect once a **2/3 validator quorum** installs the patch. At the target height, the network halts and resumes under the new binary.

***

#### Unplanned Upgrades

Unplanned upgrades require validators to halt their nodes manually using:

```bash
bitnetd start --halt-height <target_height>
```

In breaking upgrades, the genesis file and application state may need migration using:

```bash
bitnetd export > new_genesis.json
```

These changes impact explorers, RPC nodes, and infrastructure tools that require historical access.

***

#### Semantic Versioning in BitNet

Upgrade type is determined by versioning format `vX.Y.Z`:

<table data-header-hidden><thead><tr><th width="135.09765625"></th><th></th></tr></thead><tbody><tr><td><strong>Version</strong></td><td><strong>Impact</strong></td></tr><tr><td><strong>Major (X)</strong></td><td>State machine or API breaking – full migration required</td></tr><tr><td><strong>Minor (Y)</strong></td><td>Backward-compatible features – may require state migration</td></tr><tr><td><strong>Patch (Z)</strong></td><td>Bug fixes and small updates – restart only</td></tr></tbody></table>

**Upgrade Instructions**

{% tabs %}
{% tab title="Major Upgrade" %}

1. Export genesis file
2. Migrate application state
3. Install new binary
4. Restart node
   {% endtab %}

{% tab title="Minor Upgrade" %}

1. Migrate state (if required)
2. Restart node
   {% endtab %}

{% tab title="Patch Upgrade" %}

1. Stop node
2. Install patch binary
3. Restart node
   {% endtab %}
   {% endtabs %}

***

#### Data Reset Upgrades

Some upgrades require a complete reset of blockchain data:

* Delete local data
* Use original validator keys
* Resync from genesis or snapshot

Used in rollback, hard forks, or when consensus errors are unrecoverable.

***

#### Automatic vs. Manual Upgrades

Validators can choose between:

**Automatic (via Cosmovisor or process manager):**

* Monitors upgrade plans
* Halts and restarts node with new binary

**Manual:**

* Operator downloads binary
* Halts and restarts manually

{% hint style="info" %}
Validators should choose a method that fits their operational model and risk tolerance.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bitnet-whitepaper.gitbook.io/developer-docs/upgrades-overview/upgrades.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.