From d47a35a93aacfff733310699a52aa293b3bbbfd1 Mon Sep 17 00:00:00 2001 From: Tyler <48813565+technicallyty@users.noreply.github.com> Date: Tue, 1 Apr 2025 11:01:05 -0700 Subject: [PATCH] docs: v0.53.x upgrade guide (#24245) Co-authored-by: Alex | Interchain Labs --- UPGRADING.md | 179 +++++++++++++++++++++++++++------------------------ 1 file changed, 95 insertions(+), 84 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index 563d7d4685..be3ed4ad42 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -1,110 +1,121 @@ -# Upgrading Cosmos SDK +# Upgrading Cosmos SDK [v0.53.x](https://github.com/cosmos/cosmos-sdk/releases/tag/v0.53.0) -This guide provides instructions for upgrading to specific versions of Cosmos SDK. -Note, always read the **SimApp** section for more information on application wiring updates. +This guide provides instructions for upgrading from `v0.50.x` to `v0.53.x` of Cosmos SDK. -## [v0.53.x](https://github.com/cosmos/cosmos-sdk/releases/tag/v0.53.0) +Note, always read the **App Wiring Changes** section for more information on application wiring updates. -#### Unordered Transactions +🚨Upgrading to v0.53.x will require a **coordinated** chain upgrade.🚨 -The Cosmos SDK now supports unordered transactions. This means that transactions -can be executed in any order and doesn't require the client to deal with or manage -nonces. This also means the order of execution is not guaranteed. +### TLDR; -Unordered transactions are automatically enabled when using `depinject` / app di, simply supply the `servertypes.AppOptions` in `app.go`: +Unordered transactions, `x/protocolpool`, and `x/epoch` are the major new features added in v0.53.x. -```diff - depinject.Supply( -+ // supply the application options -+ appOpts, - // supply the logger - logger, - ) +We also added the ability to add a `CheckTx` handler and enabled ed25519 signature verification. + +For a full list of changes, see the [Changelog](https://github.com/cosmos/cosmos-sdk/blob/release/v0.53.x/CHANGELOG.md). + +### Unordered Transactions + +The Cosmos SDK now supports unordered transactions. _This is an opt-in feature_. + +Clients that use this feature may now submit their transactions in a fire-and-forget manner to chains that enabled unordered transactions. + +To submit an unordered transaction, clients must set the `unordered` flag to +`true` and ensure a reasonable `timeout_timestamp` is set. The `timeout_timestamp` is +used as a TTL for the transaction and provides replay protection. Each transaction's `timeout_timestamp` must be +unique to the account; however, the difference may be as small as a nanosecond. See [ADR-070](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-070-unordered-transactions.md) for more details. + +#### Enabling Unordered Transactions + +To enable unordered transactions, set the new `UnorderedNonceManager` field in the `x/auth` `ante.HandlerOptions`. + +```go +ante.HandlerOptions{ + UnorderedNonceManager: app.AccountKeeper, // NEW +} ``` -
-Step-by-step Wiring -If you are still using the legacy wiring, you must enable unordered transactions manually: +By default, unordered transactions use a transaction timeout duration of 10 minutes and a default gas charge of 2240 gas. +To modify these default values, pass in the corresponding options to the new `UnorderedTxOptions` field in `x/auth's` `ante.HandlerOptions`. -* Update the `App` constructor to create, load, and save the unordered transaction - manager. +```go +ante.HandlerOptions{ + UnorderedNonceManager: app.AccountKeeper, + UnorderedTxOptions: []ante.UnorderedTxDecoratorOptions{ + ante.WithTimeoutDuration(XXXX * time.Minute), + ante.WithUnorderedTxGasCost(XXXX), + }, +} +``` - ```go - func NewApp(...) *App { - // ... +### App Wiring Changes - // create, start, and load the unordered tx manager - utxDataDir := filepath.Join(cast.ToString(appOpts.Get(flags.FlagHome)), "data") - app.UnorderedTxManager = unorderedtx.NewManager(utxDataDir) - app.UnorderedTxManager.Start() +In this section, we describe the required app wiring changes to run a v0.53.x Cosmos SDK application. - if err := app.UnorderedTxManager.OnInit(); err != nil { - panic(fmt.Errorf("failed to initialize unordered tx manager: %w", err)) - } - } - ``` +**These changes are directly applicable to your application wiring.** -* Add the decorator to the existing AnteHandler chain, which should be as early - as possible. +The `x/auth` module now contains a `PreBlocker` that _must_ be set in the module manager's `SetOrderPreBlockers` method. - ```go - anteDecorators := []sdk.AnteDecorator{ - ante.NewSetUpContextDecorator(), - // ... - ante.NewUnorderedTxDecorator(unorderedtx.DefaultMaxTimeoutDuration, options.TxManager, options.Environment), - // ... - } +```go +app.ModuleManager.SetOrderPreBlockers( + upgradetypes.ModuleName, + authtypes.ModuleName, // NEW +) +``` - return sdk.ChainAnteDecorators(anteDecorators...), nil - ``` +That's it. -* If the App has a SnapshotManager defined, you must also register the extension - for the TxManager. +### New Modules - ```go - if manager := app.SnapshotManager(); manager != nil { - err := manager.RegisterExtensions(unorderedtx.NewSnapshotter(app.UnorderedTxManager)) - if err != nil { - panic(fmt.Errorf("failed to register snapshot extension: %w", err)) - } - } - ``` +Below are some **optional** new modules you can include in your chain. +To see a full example of wiring these modules, please check out the [SimApp](https://github.com/cosmos/cosmos-sdk/blob/release/v0.53.x/simapp/app.go). -* Create or update the App's `Preblocker()` method to call the unordered tx - manager's `OnNewBlock()` method. +#### Epochs - ```go - ... - app.SetPreblocker(app.PreBlocker) - ... +⚠️Adding this module requires a `StoreUpgrade`⚠️ - func (app *SimApp) PreBlocker(ctx sdk.Context, req *abci.RequestFinalizeBlock) (*sdk.ResponsePreBlock, error) { - app.UnorderedTxManager.OnNewBlock(ctx.BlockTime()) - return app.ModuleManager.PreBlock(ctx, req) - } - ``` +The new, supplemental `x/epochs` module provides Cosmos SDK modules functionality to register and execute custom logic at fixed time-intervals. -* Create or update the App's `Close()` method to close the unordered tx manager. - Note, this is critical as it ensures the manager's state is written to file - such that when the node restarts, it can recover the state to provide replay - protection. +Required wiring: +- Keeper Instantiation +- StoreKey addition +- Hooks Registration +- App Module Registration +- entry in SetOrderBeginBlockers +- entry in SetGenesisModuleOrder +- entry in SetExportModuleOrder - ```go - func (app *App) Close() error { - // ... +#### ProtocolPool - // close the unordered tx manager - if e := app.UnorderedTxManager.Close(); e != nil { - err = errors.Join(err, e) - } +⚠️Adding this module requires a `StoreUpgrade`⚠️ - return err - } - ``` +The new, supplemental `x/protocolpool` module provides extended functionality for managing and distributing block reward revenue. -
+Required wiring: +- Module Account Permissions + - protocolpooltypes.ModuleName (nil) + - protocolpooltypes.ProtocolPoolEscrowAccount (nil) +- Keeper Instantiation +- StoreKey addition +- Passing the keeper to the Distribution Keeper + - `distrkeeper.WithExternalCommunityPool(app.ProtocolPoolKeeper)` +- App Module Registration +- entry in SetOrderBeginBlockers +- entry in SetOrderEndBlockers +- entry in SetGenesisModuleOrder +- entry in SetExportModuleOrder **before `x/bank`** -To submit an unordered transaction, the client must set the `unordered` flag to -`true` and ensure a reasonable `timeout_height` is set. The `timeout_height` is -used as a TTL for the transaction and is used to provide replay protection. See -[ADR-070](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-070-unordered-transactions.md) for more details. +### Misc Changes + +#### Testnet's init-files Command + +Some changes were made to `testnet`'s `init-files` command to support our new testing framework, `Systemtest`. + +##### Flag Changes + +- The flag for validator count was changed from `--v` to `--validator-count`(shorthand: `-v`). + +##### Flag Additions +- `--staking-denom` allows changing the default stake denom, `stake`. +- `--commit-timeout` enables changing the commit timeout of the chain. +- `--single-host` enables running a multi-node network on a single host. This bumps each subsequent node's network addresses by 1. For example, node1's gRPC address will be 9090, node2's 9091, etc... \ No newline at end of file