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

Type	Description
Planned	Scheduled via governance proposals
Unplanned	Emergency or ad hoc updates coordinated manually
Breaking/Non-breaking	Based on semantic versioning and compatibility impact
Data Reset	Requires complete state reset and resync

---

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.

Proposals require a full voting period before execution.

---

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:

bitnetd start --halt-height <target_height>

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

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:

Version	Impact
Major (X)	State machine or API breaking – full migration required
Minor (Y)	Backward-compatible features – may require state migration
Patch (Z)	Bug fixes and small updates – restart only

Upgrade Instructions

Major Upgrade

1. Export genesis file

2. Migrate application state

3. Install new binary

4. Restart node

Minor Upgrade

1. Migrate state (if required)

2. Restart node

Patch Upgrade

1. Stop node

2. Install patch binary

3. Restart node

---

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

Validators should choose a method that fits their operational model and risk tolerance.