From d72e1f05d53e87ca2a5e4dfb82c650a7b90b4d40 Mon Sep 17 00:00:00 2001 From: jcstein <46639943+jcstein@users.noreply.github.com> Date: Mon, 21 Oct 2024 22:18:11 -0400 Subject: [PATCH 1/3] docs: add ginger upgrade to docs, update links --- how-to-guides/arabica-devnet.md | 2 +- how-to-guides/mainnet.md | 2 +- how-to-guides/mocha-testnet.md | 2 +- how-to-guides/network-upgrade-process.md | 79 ++++++++++++------------ how-to-guides/participate.md | 2 +- 5 files changed, 43 insertions(+), 44 deletions(-) diff --git a/how-to-guides/arabica-devnet.md b/how-to-guides/arabica-devnet.md index 367960a32f8..a32763e04f6 100644 --- a/how-to-guides/arabica-devnet.md +++ b/how-to-guides/arabica-devnet.md @@ -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). diff --git a/how-to-guides/mainnet.md b/how-to-guides/mainnet.md index 7b111d759a0..610e72d6cff 100644 --- a/how-to-guides/mainnet.md +++ b/how-to-guides/mainnet.md @@ -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). diff --git a/how-to-guides/mocha-testnet.md b/how-to-guides/mocha-testnet.md index 06246247195..7abc82010df 100644 --- a/how-to-guides/mocha-testnet.md +++ b/how-to-guides/mocha-testnet.md @@ -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). diff --git a/how-to-guides/network-upgrade-process.md b/how-to-guides/network-upgrade-process.md index ab9762cd128..b25457240b6 100644 --- a/how-to-guides/network-upgrade-process.md +++ b/how-to-guides/network-upgrade-process.md @@ -1,58 +1,57 @@ ---- -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). + - For upgrades using pre-programmed height (v2): A block number for when the breaking network upgrade occurs + - For upgrades using in-protocol signaling (v3+): Reaching 5/6 validator consensus on the new 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 once 5/6 of validators have signaled support. -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 diff --git a/how-to-guides/participate.md b/how-to-guides/participate.md index 8695d0e4d32..ac7f3d3cdc6 100644 --- a/how-to-guides/participate.md +++ b/how-to-guides/participate.md @@ -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). From 38c18f67f2ebd8be6e8d823de94bce5ca3b6c59a Mon Sep 17 00:00:00 2001 From: jcstein <46639943+jcstein@users.noreply.github.com> Date: Mon, 21 Oct 2024 22:19:22 -0400 Subject: [PATCH 2/3] docs: add back description --- how-to-guides/network-upgrade-process.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/how-to-guides/network-upgrade-process.md b/how-to-guides/network-upgrade-process.md index b25457240b6..44873e0688c 100644 --- a/how-to-guides/network-upgrade-process.md +++ b/how-to-guides/network-upgrade-process.md @@ -1,3 +1,7 @@ +--- +description: Overview of the Celestia network upgrade process. +--- + # Celestia network upgrade process 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. From 936f8cc72a1f55fc5b6e701d2e0af7b4bfdc23e9 Mon Sep 17 00:00:00 2001 From: Josh Stein <46639943+jcstein@users.noreply.github.com> Date: Tue, 22 Oct 2024 13:06:09 -0400 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Rootul P --- how-to-guides/network-upgrade-process.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/how-to-guides/network-upgrade-process.md b/how-to-guides/network-upgrade-process.md index 44873e0688c..a1f169d6d7f 100644 --- a/how-to-guides/network-upgrade-process.md +++ b/how-to-guides/network-upgrade-process.md @@ -22,8 +22,8 @@ The upgrade process can be broken down into a few steps: 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). - - For upgrades using pre-programmed height (v2): A block number for when the breaking network upgrade occurs - - For upgrades using in-protocol signaling (v3+): Reaching 5/6 validator consensus on the new version + - 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 ### Upcoming upgrade @@ -38,7 +38,7 @@ Key features include: - [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 -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 once 5/6 of validators have signaled support. +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. :::info Validators should ensure they are running a v3 binary before signaling support for the upgrade.