Skip to content

release-notes.md

Latest commit

 

History

History
406 lines (259 loc) · 18.2 KB

release-notes.md

File metadata and controls

406 lines (259 loc) · 18.2 KB

Release Notes

This guide provides notes for major version releases. These notes may be helpful for users when upgrading from previous major versions.

v7.0.0

Node Operators (v7.0.0)

Node operators MUST upgrade their binary to this version prior to the v7 activation height.

Validator Commission Rate Changes

v7 enforces new commission rate bounds:

  • Minimum commission rate: 20% (previously variable)
  • Maximum commission rate: 60%

Non-compliant validators will have their rates automatically adjusted at the upgrade height:

  • Validators with a commission rate below 20% will be set to 20%
  • Validators with a max commission rate below 60% will be set to 60%

No manual action is required, but validators should be aware of this change.

Horcrux Deprecation

Horcrux is deprecated starting in v7. Future upgrades will require validator keys for fibre, which demands very low signing latency. Horcrux adds signing latency due to threshold signing and network round trips between cosigner nodes, which may be incompatible with upcoming latency requirements. Validators using horcrux should plan to migrate to a local signing setup.

Config Changes

min-retain-blocks

v7 enforces a minimum min-retain-blocks value of 3000. This ensures nodes retain enough blocks for other nodes to sync from state sync snapshots. If min-retain-blocks in app.toml is set to a value between 1 and 2999, the node will log a warning and automatically override the value to 3000 on startup. Valid values:

  • 0 (default): retain all blocks (no pruning)
  • 1-2999: automatically overridden to 3000 with a log warning
  • >= 3000: retain at least that many blocks
Mempool Type

The mempool type field has been removed from new config.toml files because celestia-app only supports the CAT mempool. If your existing config.toml still contains a mempool type, it will be ignored and overridden to cat at startup with a warning. You can safely remove the type line from the [mempool] section of your config.toml.

State Machine Changes (v7.0.0)

Blocked Module Account Addresses

v7 prevents direct fund transfers to module accounts via MsgSend or bank send. Module accounts can still receive funds through protocol mechanisms (e.g., escrow). The governance module account is exempt from this restriction.

New Modules

x/forwarding (CIP-45):

Single-signature cross-chain transfers through Celestia via Hyperlane warp routes. Users send tokens to a deterministically derived forwarding address, and anyone can permissionlessly trigger forwarding to the committed destination.

  • MsgForward - Forwards tokens from a forwarding address to a committed destination via Hyperlane

See the x/forwarding README for details.

x/zkism:

Hyperlane Interchain Security Module (ISM) that authorizes Hyperlane message processing verified by SP1 Groth16 zero-knowledge proofs.

  • CreateInterchainSecurityModule - Create an ISM with initial state and verifier configuration
  • UpdateInterchainSecurityModule - Verify a state transition proof and update ISM state
  • SubmitMessages - Verify a membership proof and authorize Hyperlane message IDs

See the x/zkism README for details.

Store Migrations

v7 adds a new store key for the zkism module. This migration is handled automatically by the upgrade handler.

v6 - 128mb/6s

This section is specific to bumping from 32mb/6s in the v6 release to 128mb/6s. If you're upgrading from v5, please check the v6.0.0 first. And only then check this one.

Hardware requirements

After upgrading to 128mb/6s, specific validator hardware specifications are required to participate in consensus and propose blocks. Based on our validator survey, the following lists the CPUs that passed the benchmark and those that did not. If your CPU is not listed, please run the benchmark available tools/cpu_requirements.

Supported CPUs: - AMD Ryzen 9 7950X - AMD Ryzen 9 7950X3D - AMD Ryzen 9 9900X - AMD Ryzen 7 PRO 8700GE - AMD Ryzen 7 3700X - AMD Ryzen 3900X - AMD 7600 - AMD 7700X - AMD 7900X - AMD Ryzen 7900 - AMD EPYC 4344P - AMD EPYC 4464P - AMD EPYC 4545P - AMD EPYC 4584PX - AMD EPYC 7313P - AMD EPYC 7452 - AMD EPYC 7543P 32C/64T - AMD EPYC 9124 - AMD EPYC 9454P - AMD EPYC 9555P - 13th Gen Intel Core i5-13500 - Core i7-1270P - Intel Xeon-E 2386G
NOT supported CPUs: - AMD Ryzen 9 5950X - AMD EPYC 7443P 24-Core - Intel Xeon Platinum 8474C - Intel Xeon Gold 6254 - Intel(R) Xeon(R) Silver 4210 - Intel Xeon E5-1620 - Intel Dual Xeon Silver 4116

v6.0.0

This release contains all the changes from CIP-042. Notably:

  • Lowers the unbonding period to ~14 days
  • Increases maximum block, square, and transaction size
  • Removes the token filter for Hyperlane and IBC
  • Privval Interface Extension for Arbitrary Message Signing
  • Reduce issuance to 2.5% and increase minimum commission to 10%

Hardware Requirements

v6 changes the hardware requirements for consensus nodes. Please ensure your consensus node meets these requirements.

Binary Building

Validators should build binaries in freshly created environments or download pre-built binaries from official releases. Many validators have experienced issues due to building binaries in environments with outdated dependencies, conflicting libraries, or stale build artifacts.

Key Management Service (KMS) changes

This release introduces a new message type that needs to be signed by KMS. If you use Horcrux or TmKMS, you must use these versions to participate in consensus. If you use an alternative KMS, please reach out.

Disclaimer: (KMS) are third-party software. Validators are responsible for ensuring their own KMS setup is correctly configured. An incorrect setup may result in double signing, which can lead to slashing. So, any error log should be thoroughly investigated, even if the KMS appears to be signing normally.

Validators must also ensure they maintain a fast and reliable setup. Future network upgrades will require low signing latency, so server colocation can be explored to achieve faster signatures.

Validators choosing to run KMS do so at their own risk.

Horcrux

For horcrux, use v3.3.3-celestia. All the setups and configs remain the same.

TmKMS

For TmKMS, use v0.15.0. All the setups and configs remain the same. Using a prior version will not allow you to propose blocks.

Config changes

This release introduces a new block propagation reactor and configuration changes to accommodate the increased throughput. The relevant v6 configuration changes can be applied to existing config using the celestia-appd update-config command or by manually updating the config.toml and app.toml.

To modify your existing configs, the celestia-appd update-configs command can be used.

celestia-appd update-config

this uses version 6 and the default home (.celestia-app). Those can be changed or specified with flags as well.

celestia-appd update-config --app-version 6 --home ~/.celestia-app

To manually modify the configs, change the following values.

[rpc]
max_body_bytes = 436207616

[p2p]
send_rate = 25165824
recv_rate = 25165824

[mempool]
type = "cat"
max_tx_bytes = 8388608
ttl-duration = "0s"
ttl-num-blocks = 12
max-gossip-delay = "1m0s"

[consensus]
enable_legacy_block_prop = false

v5.0.0

This major upgrade is an expedited patch release, fixing the problem with failed IBC transfers caused by the incorrectly configured capability module. There should be no additional API breaking changes. This expedited release will have no upgrade delay. The moment 5/6ths signal and the MsgTryUpgrade is successful, the network will upgrade to v5.

v4.0.0

Node Operators (v4.0.0)

Node operators MUST upgrade their binary to this version prior to the v4 activation height. Node operators SHOULD NOT use cosmovisor to upgrade their binary.

Multiplexer

Celestia-app v4.0.0 introduces support for a multiplexer that makes it easier for node operators to run a consensus node that can sync from genesis. The multiplexer contains an embedded celestia-app v3.x.x binary that will be used to sync the node from genesis. After the chain advances to app version v4, the multiplexer will stop routing requests to the embedded celestia-app v3.x.x binary and will instead route requests to the v4.x.x state machine. Binaries that are installed from source (via make install) will include support for the multiplexer. To install Celestia without the multiplexer, you can use the make install-standalone target. Note that the standalone binary will only be able to run on networks that have already upgraded to app version v4.

proxy_app and address

  • The default ABCI client address is now tcp://127.0.0.1:36658 (configured via --proxy_app flag or proxy_app in config.toml).
  • The default ABCI server address is now tcp://127.0.0.1:36658 (configured via --address flag).

These two configs must match in order for the multiplexer to work correctly. Please update your config.toml to account for the new default

-proxy_app = "tcp://127.0.0.1:26658"
+proxy_app = "tcp://127.0.0.1:36658"

Custom build flags

make install currently downloads a v3.x binary with only one custom build flag, ledger. If you use any additional custom build flags (i.e. pebbledb, rocksdb, badgerdb, cleveldb, boltdb), you will need to build the v3.x binary from source (with custom build tags) and include it in the app's embedded binary directory (by default: ~/.celestia-app/bin/). The embedded binary directory layout:

$ tree bin
bin
└── v3.10.2-mocha
    ├── celestia-appd
    ├── LICENSE
    └── README.md

rpc.grpc_laddr

The rpc.grpc_laddr config option is now required when running the celestia-app binary with the multiplexer. This option can be set via CLI flag --rpc.grpc_laddr tcp://127.0.0.1:9098 or in the config.toml:

[rpc]

# TCP or UNIX socket address for the gRPC server to listen on
# NOTE: This server only supports /broadcast_tx_commit
grpc_laddr = "tcp://127.0.0.1:9098"

IAVL v1 Migration

Celestia-app v4 uses IAVL v1 for better performance. When upgrading to v4, the migration happens lazily over time. If you'd like to avoid the lazy migration, you can perform a fresh state sync so that your node uses IAVL v1 exclusively.

Cosmos SDK default addresses

The default addresses for the Cosmos SDK API server, GRPC server, and GRPC web server have changed from 0.0.0.0 to localhost. See cosmos-sdk#13778.

State Machine Changes (v4.0.0)

Celestia-app v4.0.0 includes significant state machine changes due to major dependency upgrades:

New Messages (Added Modules)

x/circuit Circuit Breaker Module (cosmos-sdk docs):

  • MsgAuthorizeCircuitBreaker - Grant circuit breaker permissions
  • MsgTripCircuitBreaker - Disable message execution
  • MsgResetCircuitBreaker - Re-enable message execution

x/consensus Consensus Parameters Module (cosmos-sdk docs):

  • MsgUpdateParams - Update consensus parameters via governance (replaces CometBFT consensus param updates)

Hyperlane:

  • hyperlane/core - Cross-chain messaging infrastructure
  • hyperlane/warp - Token bridging and routing

Removed Messages (Deprecated Modules)

x/crisis Module - Removed in Cosmos SDK v0.50.x

x/capability Module - Removed in Cosmos SDK v0.50.x:

  • IBC capability management integrated directly into IBC v8 modules

x/paramfilter Module - Celestia-specific module removed:

  • Parameter filtering functionality replaced by circuit breaker

Changed Messages and Logic

Parameter Management Migration:

  • Generic parameter proposals deprecated in favor of module-specific MsgUpdateParams messages
  • Consensus parameters moved from CometBFT to dedicated x/consensus module
  • All modules now use module-specific parameter update messages instead of legacy x/params proposals

IBC v6 to v8 Protocol Changes (v6 to v7, v7 to v8)

Library Consumers (v4.0.0)

Import Changes:

  • Add: cosmossdk.io/x/circuit, cosmossdk.io/x/consensus
  • Remove: x/capability, x/crisis, x/paramfilter
  • Update: github.com/cosmos/ibc-go/v8 (from v6)

API Breaking Changes (cosmos-sdk migration guide):

  • Module keepers now accept context.Context instead of sdk.Context
  • BeginBlock/EndBlock signatures changed
  • Parameter updates require module-specific MsgUpdateParams messages

v3.0.0

Node Operators (v3.0.0)

Node operators MUST upgrade their binary to this version prior to the v3 activation height. Node operators SHOULD NOT use cosmovisor to upgrade their binary.

Enabling BBR and MCTCP

Consensus node operators must enable the BBR (Bottleneck Bandwidth and Round-trip propagation time) congestion control algorithm. See #3774. If using Linux in Docker, Kubernetes, a VM or bare-metal, this can be done by calling

make enable-bbr

command on the host machine.

Configure Node for V3

Consensus node operators should update several configurations for v3. This can be done by calling:

make configure-v3

If the config file is not in the default spot, it can be provided using:

make configure-v3 CONFIG_FILE=path/to/other/config.toml

Alternatively, the configurations can be changed manually. This involves updating the mempool TTLs and the send and receive rates.

  • Configuring Bandwidth Settings
    • Update recv_rate and send_rate in your TOML config file to 10MiB (10485760)
  • Extend TTLs
    • Update ttl-num-blocks in your TOML config file to 12

Signaling Upgrades

  • Upgrades now use the x/signal module to coordinate the network to an upgrade height.

The following command can be used, if you are a validator in the active set, to signal to upgrade to v3:

celestia-appd tx signal signal 3 <plus transaction flags>

You can track the tally of signalling by validators using the following query

celestia-appd query signal tally 3

Once 5/6+ of the voting power have signalled, the upgrade will be ready. There is a hard coded delay between confirmation of the upgrade and execution to the new state machine.

To view the upcoming upgrade height use the following query:

celestia-appd query signal upgrade
> An upgrade is pending to app version 3 at height 2348907.

For more information refer to the module docs

Library Consumers (v3.0.0)

v2.0.0

Node Operators (v2.0.0)

If you are a consensus node operator, please follow the communication channels listed under network upgrades to learn when this release is recommended for each network (e.g. Mocha, Mainnet Beta).

Consensus node operators are expected to upgrade to this release prior to the Lemongrass hardfork if they intend to continue participating in the network. The command used to start the consensus node or validator node will accept an additional --v2-upgrade-height flag. See this table for upgrade heights for each network. Node operators SHOULD NOT use cosmovisor to upgrade their binary.

Consensus node operators should enable the BBR (Bottleneck Bandwidth and Round-trip propagation time) congestion control algorithm. See #3812.

Library Consumers (v2.0.0)

If you are a library consumer, a number of the Go APIs have changed since celestia-app v1.x.x. Some of the notable changes are:

  • Code pertaining to the original data square was extracted to celestiaorg/go-square.
    • celestia-app v1.x had a shares package. celestia-app v2.x uses go-square/shares
    • celestia-app v1.x had a blob.types package with CreateCommitment function. celestia-app v2.x uses CreateCommitment function from the go-square/inclusion.
  • celestia-app v1.x had a lot of functionality included in the signer. celestia-app v2.x splits a txClient from the signer. See #3433.