Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add ginger upgrade to docs, update links #1758

Merged
merged 3 commits into from
Oct 22, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion how-to-guides/arabica-devnet.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,4 +183,4 @@ Join our [Telegram announcement channel](https://t.me/+smSFIA7XXLU4MjJh)
for network upgrades.

See the [network upgrade process page](./network-upgrade-process.md) to learn more
about specific upgrades like the [Lemongrass network upgrade](./network-upgrade-process.md#lemongrass-network-upgrade).
about specific upgrades like the [Ginger network upgrade](./network-upgrade-process.md#ginger-network-upgrade).
2 changes: 1 addition & 1 deletion how-to-guides/mainnet.md
Original file line number Diff line number Diff line change
Expand Up @@ -303,4 +303,4 @@ There are a few ways to stay informed about network upgrades on Mainnet Beta:
- Discord [Mainnet Beta announcements](https://discord.com/channels/638338779505229824/1169237690114388039)

See the [network upgrade process page](./network-upgrade-process.md) to learn more
about specific upgrades like the [Lemongrass network upgrade](./network-upgrade-process.md#lemongrass-network-upgrade).
about specific upgrades like the [Ginger network upgrade](./network-upgrade-process.md#ginger-network-upgrade).
2 changes: 1 addition & 1 deletion how-to-guides/mocha-testnet.md
Original file line number Diff line number Diff line change
Expand Up @@ -243,4 +243,4 @@ There are a few ways to stay informed about network upgrades on Mocha testnet:
- Discord [Mocha announcements](https://discord.com/channels/638338779505229824/979037494735691816)

See the [network upgrade process page](./network-upgrade-process.md) to learn more
about specific upgrades like the [Lemongrass network upgrade](./network-upgrade-process.md#lemongrass-network-upgrade).
about specific upgrades like the [Ginger network upgrade](./network-upgrade-process.md#ginger-network-upgrade).
75 changes: 39 additions & 36 deletions how-to-guides/network-upgrade-process.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,55 +4,58 @@ description: Overview of the Celestia network upgrade process.

# Celestia network upgrade process

Blockchain networks often times need to upgrade with new features
which require coordination work among the validators prior to activating
the 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.

This process is called a network upgrade, which can be breaking or non-breaking.
During planned network upgrades, the Celestia Labs team will coordinate
with the validators to prepare for the upcoming network upgrade.
## Network upgrade coordination

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 after the network upgrades.
As of the Lemongrass upgrade in September 2024, Celestia has implemented [CIP-10](https://cips.celestia.org/cip-10.html), which establishes two methods for coordinating network upgrades:

Non-breaking network upgrades are backward-compatible and require less coordination.
1. **Pre-programmed height**: Used for the Lemongrass network upgrade (v2)
2. **In-protocol signaling**: Used for all subsequent upgrades (v3+)

## General process
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 has signaled for the same version.

The general process can be broken down into several components:
## Upgrade process

- Network upgrade specifications and features (defined by description of features
and code implementation of those features).
- Binary used to add those features. A new binary release with those features
will be provided by Celestia Labs team in order for validators to upgrade
their nodes to the new binary.
- A block number for when the breaking network upgrade. Even if validators upgrade
their binary to be network upgrade ready, the network upgrade does not happen right
away, but some short time in the future at a specific block number.
- Testing of the features, which happens on testnets first prior to activating on
Mainnet Beta in order to ensure the network can upgrade securely.
The upgrade process can be broken down into a few steps:
1. [Celestia Improvement Proposals](https://cips.celestia.org) (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.
1. Celestia core developer teams implement the features defined in the CIPs.
1. A new binary is released with the new features to be tested on testnets.
1. Validators upgrade their nodes to the new binary, on [Arabica devnet](./arabica-devnet.md), [Mocha testnet](./mocha-testnet.md), and finally on Celestia [Mainnet Beta](./mainnet.md).
- 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

The two testnets where network upgrades are deployed are:
### Upcoming upgrade

- [Arabica devnet](./arabica-devnet.md)
- [Mocha testnet](./mocha-testnet.md)
#### Ginger network upgrade

### Lemongrass network upgrade
The Ginger network upgrade (v3) will be the first to use the new in-protocol signaling mechanism defined in [CIP-10](https://cips.celestia.org/cip-10.html). This upgrade includes changes defined in [CIP-25](https://cips.celestia.org/cip-25.html):

The Lemongrass network upgrade is the first consensus layer breaking change since Celestia's Mainnet Beta genesis block. The Lemongrass network upgrade includes all of the CIPs listed in [CIP-17](https://github.com/celestiaorg/CIPs/blob/main/cips/cip-17.md). The Lemongrass network upgrade will be executed on Arabica, then Mocha, then Mainnet Beta. The network upgrade will take place at an "upgrade height" that will be coordinated offline on a per-network basis. The upgrade heights will be announced in advance (see [network upgrades channels](./participate#network-upgrades)) to give node operators time to download and start a compatible binary prior to the upgrade height.
Key features include:
- [CIP-21](https://cips.celestia.org/cip-21.html): Introduce blob type with verified signer
- [CIP-24](https://cips.celestia.org/cip-24.html): Versioned Gas Scheduler Variables
- [CIP-26](https://cips.celestia.org/cip-26.html): Versioned timeouts
- [CIP-27](https://cips.celestia.org/cip-27.html): Block limits for number of PFBs and non-PFBs
- [CIP-28](https://cips.celestia.org/cip-28.html): Transaction size limit

- If you are a consensus node or validator operator: you will need to download and run a celestia-app binary >= v2.0.0 prior to the `--v2-upgrade-height` to remain on the canonical chain.
- If you are a DA node operator, you will need to download and run a compatible celestia-node binary >= v0.16.0-rc0 prior to the upgrade height.
Unlike the Lemongrass upgrade, there will not be a pre-programmed upgrade height. Instead, validators will signal their readiness for v3 through in-protocol signaling, and the upgrade will automatically activate one week after 5/6 of voting power have signaled for a particular version.

Network | Chain ID | Date and approximate time | `--v2-upgrade-height`
-------------|------------|------------------------------------------|----------------------
Arabica | arabica-11 | 2024/08/19 @ 14:00 UTC | 1751707
Mocha | mocha-4 | 2024/08/28 @ 14:00 UTC | 2585031
Mainnet Beta | celestia | 2024/09/18 @ 14:00 UTC | 2371495
:::info
Validators should ensure they are running a v3 binary before signaling support for the upgrade.
:::

:::warning
You do not need to use a tool like [cosmovisor](https://docs.cosmos.network/main/build/tooling/cosmovisor) to upgrade the binary. Please upgrade your binary before signaling support for the new version.
:::

You do not need to use a tool like [cosmovisor](https://docs.cosmos.network/main/build/tooling/cosmovisor) to upgrade the binary at the upgrade height. Please upgrade your binary several blocks before the upgrade height.
### Past Upgrades

:::
#### Lemongrass network upgrade

The Lemongrass network upgrade (v2) was the first consensus layer breaking change since Celestia's Mainnet Beta genesis block. The Lemongrass network upgrade included all of the CIPs listed in [CIP-17](https://github.com/celestiaorg/CIPs/blob/main/cips/cip-17.md) and implemented CIP-10 for future upgrades.

Network | Chain ID | Date and time | Upgrade height
-------------|------------|-----------------------------|-----------------
Arabica | arabica-11 | 2024/08/19 @ 14:00 UTC | 1751707
Mocha | mocha-4 | 2024/08/28 @ 14:00 UTC | 2585031
Mainnet Beta | celestia | 2024/09/18 @ 14:00 UTC | 2371495
2 changes: 1 addition & 1 deletion how-to-guides/participate.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,4 +61,4 @@ There are a few ways to stay informed about network upgrades:
- Discord [Mocha announcements](https://discord.com/channels/638338779505229824/979037494735691816)

See the [network upgrade process page](./network-upgrade-process.md) to learn more
about specific upgrades like the [Lemongrass network upgrade](./network-upgrade-process.md#lemongrass-network-upgrade).
about specific upgrades like the [Ginger network upgrade](./network-upgrade-process.md#ginger-network-upgrade).
Loading