Network upgrades

Blockchain networks often need to upgrade with new features which require coordination work among the community of developers, validators, and node operators prior to activating the upgrades. This process is called a network upgrade, which can be breaking or non-breaking. During planned network upgrades the community will coordinate to prepare for the upcoming upgrade. Breaking network upgrades are not backward-compatible with older versions of the network software, which is why it is important that validators upgrade their software to continue validating on the network. Non-breaking network upgrades are backward-compatible and require less coordination.

Network upgrade coordination

As of the Lemongrass upgrade in September 2024, Celestia has implemented CIP-10 , which establishes two methods for coordinating network upgrades:

1. Pre-programmed height: Used for the Lemongrass network upgrade (v2)
2. In-protocol signaling: Used for all subsequent upgrades (v3+)

Under the in-protocol signaling mechanism, validators submit messages to signal their readiness and preference for the next version. The upgrade activates automatically once a quorum of 5/6 of validators have signaled for the same version.

Announcement channels

Follow the latest network upgrade announcements on:

• Telegram: Network-wide announcement channel 
• Discord
  • Mainnet Beta announcements 
  • Mocha announcements 

Upgrade process

The upgrade process can be broken down into a few steps:

1. Celestia Improvement Proposals  (CIPs) are created for consensus-breaking changes and features that impact user experience. These CIPs are included in a meta-CIP, which define the scope of the upgrade.
2. Celestia core developer teams implement the features defined in the CIPs.
3. A new binary is released with the new features to be tested on testnets.
4. Node operators upgrade to the new binary on Mocha testnet, and finally on Celestia Mainnet Beta.
   • Upgrades using pre-programmed height (v2) activate at a predetermined block number.
   • Upgrades using in-protocol signaling (v3+) activate one week after 5/6 of the voting power has signaled for a particular version

Configuration changes in v10

Existing configuration files

Replacing celestia-app does not add new settings or comments to existing configuration files. Missing settings use the binary’s defaults.

Starting with celestia-app v10.2.0, use config sync to add missing fields and their documentation to config/config.toml. Preview the additions first:

celestia-appd config sync --home ~/.celestia-app --dry-run
celestia-appd config sync --home ~/.celestia-app

Use your node’s home directory if different. The command preserves existing values and creates a backup before writing changes. It does not run automatically on startup. Use it instead of the deprecated update-config command for v10 configuration maintenance.

RPC and storage settings

These settings apply to celestia-app consensus nodes:

The RPC setting caps concurrent heavy requests such as block_results and tx_search; public RPC providers may want to raise it. Blockstore compaction is optional and does not enable pruning. When enabled, it compacts the pruned range in the background. To compact an existing blockstore once, stop the node and run celestia-appd compact-blockstore.

See the Mocha release upgrade instructions  for details. Follow the upgrade announcement for your network before replacing its binary.

Network upgrade history

v7 (Hibiscus) was skipped on Mainnet Beta due to a bug discovered after testnet activation; v8 (defined in CIP-49 ) was activated instead.

In the Mainnet Beta table, version links point to Celenium upgrade status pages for signaling upgrades (v3+). v2 used a pre-programmed height and does not have a Celenium signaling page.

Mocha testnet

Mocha-5

App version 10 activated on mocha-5 at the height specified in the activation announcement . Bonded validators can now start and register their Fibre servers.

Mocha-4 (historical)

The upgrades below happened on the mocha-4 chain. Celenium now indexes mocha-5, so explorer pages for these historical upgrades and heights are no longer available.

Mainnet Beta

Upcoming upgrades

Warning: You do not need to use a tool like cosmovisor  to upgrade the binary. Please upgrade your binary before signaling support for the new version.

Mocha has activated app version 10; see the Mocha-5 upgrade history. For upcoming upgrade schedules on each network, follow the network announcements .