From df08c9dfca1da67bc14357fdc963224ca72fabd4 Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Wed, 26 Jul 2023 10:53:08 +0200 Subject: [PATCH 1/2] docs: improve usage of `:::note` (#17132) (cherry picked from commit 2c5f36c259126b0d3836e4aa110cd78949f305f6) # Conflicts: # docs/docs/basics/01-tx-lifecycle.md # docs/docs/building-apps/03-app-upgrade.md # docs/docs/building-modules/14-simulator.md --- docs/docs/basics/01-tx-lifecycle.md | 4 + docs/docs/basics/02-query-lifecycle.md | 4 +- docs/docs/basics/03-accounts.md | 3 +- docs/docs/basics/04-gas-fees.md | 4 +- docs/docs/building-apps/01-app-go-v2.md | 4 +- docs/docs/building-apps/02-app-mempool.md | 4 +- docs/docs/building-apps/03-app-upgrade.md | 144 ++++++++++++++++++ docs/docs/building-modules/01-intro.md | 4 +- .../building-modules/01-module-manager.md | 4 +- .../02-messages-and-queries.md | 4 +- docs/docs/building-modules/03-msg-services.md | 4 +- .../building-modules/04-query-services.md | 4 +- .../05-beginblock-endblock.md | 4 +- docs/docs/building-modules/06-keeper.md | 4 +- docs/docs/building-modules/07-invariants.md | 4 +- docs/docs/building-modules/08-genesis.md | 4 +- .../building-modules/09-module-interfaces.md | 4 +- docs/docs/building-modules/10-autocli.md | 4 +- docs/docs/building-modules/13-upgrade.md | 4 +- docs/docs/building-modules/14-simulator.md | 4 + docs/docs/building-modules/15-depinject.md | 4 +- docs/docs/core/00-baseapp.md | 4 +- docs/docs/core/01-transactions.md | 4 +- docs/docs/core/02-context.md | 4 +- docs/docs/core/03-node.md | 4 +- docs/docs/core/04-store.md | 4 +- docs/docs/core/05-encoding.md | 4 +- docs/docs/core/08-events.md | 4 +- docs/docs/run-node/01-run-node.md | 4 +- docs/docs/run-node/02-interact-node.md | 4 +- x/auth/tx/README.md | 4 +- 31 files changed, 180 insertions(+), 83 deletions(-) diff --git a/docs/docs/basics/01-tx-lifecycle.md b/docs/docs/basics/01-tx-lifecycle.md index ed65607728a5..50346520fa6b 100644 --- a/docs/docs/basics/01-tx-lifecycle.md +++ b/docs/docs/basics/01-tx-lifecycle.md @@ -8,8 +8,12 @@ sidebar_position: 1 This document describes the lifecycle of a transaction from creation to committed state changes. Transaction definition is described in a [different doc](../core/01-transactions.md). The transaction is referred to as `Tx`. ::: +<<<<<<< HEAD :::note ### Pre-requisite Readings +======= +:::note Pre-requisite Readings +>>>>>>> 2c5f36c25 (docs: improve usage of `:::note` (#17132)) * [Anatomy of a Cosmos SDK Application](./00-app-anatomy.md) ::: diff --git a/docs/docs/basics/02-query-lifecycle.md b/docs/docs/basics/02-query-lifecycle.md index 27db1caf4e4f..6fe02c2b0fa7 100644 --- a/docs/docs/basics/02-query-lifecycle.md +++ b/docs/docs/basics/02-query-lifecycle.md @@ -8,9 +8,7 @@ sidebar_position: 1 This document describes the lifecycle of a query in a Cosmos SDK application, from the user interface to application stores and back. The query is referred to as `MyQuery`. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Transaction Lifecycle](./01-tx-lifecycle.md) ::: diff --git a/docs/docs/basics/03-accounts.md b/docs/docs/basics/03-accounts.md index a9f8733aee5b..1384c30fb0fe 100644 --- a/docs/docs/basics/03-accounts.md +++ b/docs/docs/basics/03-accounts.md @@ -8,9 +8,8 @@ sidebar_position: 1 This document describes the in-built account and public key system of the Cosmos SDK. ::: -:::note +:::note Pre-requisite Readings -### Pre-requisite Readings * [Anatomy of a Cosmos SDK Application](./00-app-anatomy.md) diff --git a/docs/docs/basics/04-gas-fees.md b/docs/docs/basics/04-gas-fees.md index 821fe9711ccb..27bee7f87edd 100644 --- a/docs/docs/basics/04-gas-fees.md +++ b/docs/docs/basics/04-gas-fees.md @@ -8,9 +8,7 @@ sidebar_position: 1 This document describes the default strategies to handle gas and fees within a Cosmos SDK application. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Anatomy of a Cosmos SDK Application](./00-app-anatomy.md) diff --git a/docs/docs/building-apps/01-app-go-v2.md b/docs/docs/building-apps/01-app-go-v2.md index 926d86dbbe4e..a30a202a4625 100644 --- a/docs/docs/building-apps/01-app-go-v2.md +++ b/docs/docs/building-apps/01-app-go-v2.md @@ -11,9 +11,7 @@ Learn more about the rationale of App Wiring in [ADR-057](../architecture/adr-05 ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [ADR 057: App Wiring](../architecture/adr-057-app-wiring.md) * [Depinject Documentation](../tooling/02-depinject.md) diff --git a/docs/docs/building-apps/02-app-mempool.md b/docs/docs/building-apps/02-app-mempool.md index b32b9654779e..3957c8a316ce 100644 --- a/docs/docs/building-apps/02-app-mempool.md +++ b/docs/docs/building-apps/02-app-mempool.md @@ -13,9 +13,7 @@ block building than previous versions. This change was enabled by [ABCI 1.0](https://github.com/cometbft/cometbft/blob/v0.37.0/spec/abci). Notably it introduces the `PrepareProposal` and `ProcessProposal` steps of ABCI++. -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [BaseApp](../core/00-baseapp.md) diff --git a/docs/docs/building-apps/03-app-upgrade.md b/docs/docs/building-apps/03-app-upgrade.md index d60e781177bc..4d26afe88fc5 100644 --- a/docs/docs/building-apps/03-app-upgrade.md +++ b/docs/docs/building-apps/03-app-upgrade.md @@ -12,6 +12,150 @@ This document describes how to upgrade your application. If you are looking spec This section is currently incomplete. Track the progress of this document [here](https://github.com/cosmos/cosmos-sdk/issues/11504). ::: +<<<<<<< HEAD +======= +:::note Pre-requisite Readings + +* [`x/upgrade` Documentation](https://docs.cosmos.network/main/modules/upgrade) + +::: + +## General Workflow + +Let's assume we are running v0.38.0 of our software in our testnet and want to upgrade to v0.40.0. +How would this look in practice? First of all, we want to finalize the v0.40.0 release candidate +and there install a specially named upgrade handler (eg. "testnet-v2" or even "v0.40.0"). An upgrade +handler should be defined in a new version of the software to define what migrations +to run to migrate from the older version of the software. Naturally, this is app-specific rather +than module specific, and must be defined in `app.go`, even if it imports logic from various +modules to perform the actions. You can register them with `upgradeKeeper.SetUpgradeHandler` +during the app initialization (before starting the abci server), and they serve not only to +perform a migration, but also to identify if this is the old or new version (eg. presence of +a handler registered for the named upgrade). + +Once the release candidate along with an appropriate upgrade handler is frozen, +we can have a governance vote to approve this upgrade at some future block height (e.g. 200000). +This is known as an upgrade.Plan. The v0.38.0 code will not know of this handler, but will +continue to run until block 200000, when the plan kicks in at `BeginBlock`. It will check +for existence of the handler, and finding it missing, know that it is running the obsolete software, +and gracefully exit. + +Generally the application binary will restart on exit, but then will execute this BeginBlocker +again and exit, causing a restart loop. Either the operator can manually install the new software, +or you can make use of an external watcher daemon to possibly download and then switch binaries, +also potentially doing a backup. The SDK tool for doing such, is called [Cosmovisor](https://docs.cosmos.network/main/tooling/cosmovisor). + +When the binary restarts with the upgraded version (here v0.40.0), it will detect we have registered the +"testnet-v2" upgrade handler in the code, and realize it is the new version. It then will run the upgrade handler +and *migrate the database in-place*. Once finished, it marks the upgrade as done, and continues processing +the rest of the block as normal. Once 2/3 of the voting power has upgraded, the blockchain will immediately +resume the consensus mechanism. If the majority of operators add a custom `do-upgrade` script, this should +be a matter of minutes and not even require them to be awake at that time. + +## Integrating With An App + +Setup an upgrade Keeper for the app and then define a `BeginBlocker` that calls the upgrade +keeper's BeginBlocker method: + +```go + func (app *myApp) BeginBlocker(ctx sdk.Context, req abci.RequestBeginBlock) (abci.ResponseBeginBlock, error) { + app.upgradeKeeper.BeginBlocker(ctx, req) + return abci.ResponseBeginBlock{}, nil + } +``` + +The app must then integrate the upgrade keeper with its governance module as appropriate. The governance module +should call ScheduleUpgrade to schedule an upgrade and ClearUpgradePlan to cancel a pending upgrade. + +## Performing Upgrades + +Upgrades can be scheduled at a predefined block height. Once this block height is reached, the +existing software will cease to process ABCI messages and a new version with code that handles the upgrade must be deployed. +All upgrades are coordinated by a unique upgrade name that cannot be reused on the same blockchain. In order for the upgrade +module to know that the upgrade has been safely applied, a handler with the name of the upgrade must be installed. +Here is an example handler for an upgrade named "my-fancy-upgrade": + +```go +app.upgradeKeeper.SetUpgradeHandler("my-fancy-upgrade", func(ctx sdk.Context, plan upgrade.Plan) { + // Perform any migrations of the state store needed for this upgrade +}) +``` + +This upgrade handler performs the dual function of alerting the upgrade module that the named upgrade has been applied, +as well as providing the opportunity for the upgraded software to perform any necessary state migrations. Both the halt +(with the old binary) and applying the migration (with the new binary) are enforced in the state machine. Actually +switching the binaries is an ops task and not handled inside the sdk / abci app. + +Here is a sample code to set store migrations with an upgrade: + +```go +// this configures a no-op upgrade handler for the "my-fancy-upgrade" upgrade +app.UpgradeKeeper.SetUpgradeHandler("my-fancy-upgrade", func(ctx sdk.Context, plan upgrade.Plan) { + // upgrade changes here +}) +upgradeInfo, err := app.UpgradeKeeper.ReadUpgradeInfoFromDisk() +if err != nil { + // handle error +} +if upgradeInfo.Name == "my-fancy-upgrade" && !app.UpgradeKeeper.IsSkipHeight(upgradeInfo.Height) { + storeUpgrades := store.StoreUpgrades{ + Renamed: []store.StoreRename{{ + OldKey: "foo", + NewKey: "bar", + }}, + Deleted: []string{}, + } + // configure store loader that checks if version == upgradeHeight and applies store upgrades + app.SetStoreLoader(upgrade.UpgradeStoreLoader(upgradeInfo.Height, &storeUpgrades)) +} +``` + +## Halt Behavior + +Before halting the ABCI state machine in the BeginBlocker method, the upgrade module will log an error +that looks like: + +```text + UPGRADE "" NEEDED at height : +``` + +where `Name` and `Info` are the values of the respective fields on the upgrade Plan. + +To perform the actual halt of the blockchain, the upgrade keeper simply panics which prevents the ABCI state machine +from proceeding but doesn't actually exit the process. Exiting the process can cause issues for other nodes that start +to lose connectivity with the exiting nodes, thus this module prefers to just halt but not exit. + +## Automation + +Read more about [Cosmovisor](https://docs.cosmos.network/main/tooling/cosmovisor), the tool for automating upgrades. + +## Canceling Upgrades + +There are two ways to cancel a planned upgrade - with on-chain governance or off-chain social consensus. +For the first one, there is a `CancelSoftwareUpgrade` governance proposal, which can be voted on and will +remove the scheduled upgrade plan. Of course this requires that the upgrade was known to be a bad idea +well before the upgrade itself, to allow time for a vote. If you want to allow such a possibility, you +should set the upgrade height to be `2 * (votingperiod + depositperiod) + (safety delta)` from the beginning of +the first upgrade proposal. Safety delta is the time available from the success of an upgrade proposal +and the realization it was a bad idea (due to external testing). You can also start a `CancelSoftwareUpgrade` +proposal while the original `SoftwareUpgrade` proposal is still being voted upon, as long as the voting +period ends after the `SoftwareUpgrade` proposal. + +However, let's assume that we don't realize the upgrade has a bug until shortly before it will occur +(or while we try it out - hitting some panic in the migration). It would seem the blockchain is stuck, +but we need to allow an escape for social consensus to overrule the planned upgrade. To do so, there's +a `--unsafe-skip-upgrades` flag to the start command, which will cause the node to mark the upgrade +as done upon hitting the planned upgrade height(s), without halting and without actually performing a migration. +If over two-thirds run their nodes with this flag on the old binary, it will allow the chain to continue through +the upgrade with a manual override. (This must be well-documented for anyone syncing from genesis later on). + +Example: + +```shell + start --unsafe-skip-upgrades ... +``` + +>>>>>>> 2c5f36c25 (docs: improve usage of `:::note` (#17132)) ## Pre-Upgrade Handling Cosmovisor supports custom pre-upgrade handling. Use pre-upgrade handling when you need to implement application config changes that are required in the newer version before you perform the upgrade. diff --git a/docs/docs/building-modules/01-intro.md b/docs/docs/building-modules/01-intro.md index bb45d5d13252..749a5ed04b36 100644 --- a/docs/docs/building-modules/01-intro.md +++ b/docs/docs/building-modules/01-intro.md @@ -8,9 +8,7 @@ sidebar_position: 1 Modules define most of the logic of Cosmos SDK applications. Developers compose modules together using the Cosmos SDK to build their custom application-specific blockchains. This document outlines the basic concepts behind SDK modules and how to approach module management. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md) * [Lifecycle of a Cosmos SDK transaction](../basics/01-tx-lifecycle.md) diff --git a/docs/docs/building-modules/01-module-manager.md b/docs/docs/building-modules/01-module-manager.md index 8003e37dda34..f59f4f0ec5dc 100644 --- a/docs/docs/building-modules/01-module-manager.md +++ b/docs/docs/building-modules/01-module-manager.md @@ -8,9 +8,7 @@ sidebar_position: 1 Cosmos SDK modules need to implement the [`AppModule` interfaces](#application-module-interfaces), in order to be managed by the application's [module manager](#module-manager). The module manager plays an important role in [`message` and `query` routing](../core/00-baseapp.md#routing), and allows application developers to set the order of execution of a variety of functions like [`BeginBlocker` and `EndBlocker`](../basics/00-app-anatomy.md#begingblocker-and-endblocker). ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Introduction to Cosmos SDK Modules](./01-intro.md) diff --git a/docs/docs/building-modules/02-messages-and-queries.md b/docs/docs/building-modules/02-messages-and-queries.md index 2021c7e967be..636863d079b6 100644 --- a/docs/docs/building-modules/02-messages-and-queries.md +++ b/docs/docs/building-modules/02-messages-and-queries.md @@ -8,9 +8,7 @@ sidebar_position: 1 `Msg`s and `Queries` are the two primary objects handled by modules. Most of the core components defined in a module, like `Msg` services, `keeper`s and `Query` services, exist to process `message`s and `queries`. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Introduction to Cosmos SDK Modules](./01-intro.md) diff --git a/docs/docs/building-modules/03-msg-services.md b/docs/docs/building-modules/03-msg-services.md index b1e9a54d336a..8b1f8273a30c 100644 --- a/docs/docs/building-modules/03-msg-services.md +++ b/docs/docs/building-modules/03-msg-services.md @@ -8,9 +8,7 @@ sidebar_position: 1 A Protobuf `Msg` service processes [messages](./02-messages-and-queries.md#messages). Protobuf `Msg` services are specific to the module in which they are defined, and only process messages defined within the said module. They are called from `BaseApp` during [`DeliverTx`](../core/00-baseapp.md#delivertx). ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Module Manager](./01-module-manager.md) * [Messages and Queries](./02-messages-and-queries.md) diff --git a/docs/docs/building-modules/04-query-services.md b/docs/docs/building-modules/04-query-services.md index cedeb092844c..94078fd9e1ec 100644 --- a/docs/docs/building-modules/04-query-services.md +++ b/docs/docs/building-modules/04-query-services.md @@ -8,9 +8,7 @@ sidebar_position: 1 A Protobuf Query service processes [`queries`](./02-messages-and-queries.md#queries). Query services are specific to the module in which they are defined, and only process `queries` defined within said module. They are called from `BaseApp`'s [`Query` method](../core/00-baseapp.md#query). ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Module Manager](./01-module-manager.md) * [Messages and Queries](./02-messages-and-queries.md) diff --git a/docs/docs/building-modules/05-beginblock-endblock.md b/docs/docs/building-modules/05-beginblock-endblock.md index 4cfdda370f05..1ac9a15f09aa 100644 --- a/docs/docs/building-modules/05-beginblock-endblock.md +++ b/docs/docs/building-modules/05-beginblock-endblock.md @@ -8,9 +8,7 @@ sidebar_position: 1 `BeginBlocker` and `EndBlocker` are optional methods module developers can implement in their module. They will be triggered at the beginning and at the end of each block respectively, when the [`BeginBlock`](../core/00-baseapp.md#beginblock) and [`EndBlock`](../core/00-baseapp.md#endblock) ABCI messages are received from the underlying consensus engine. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Module Manager](./01-module-manager.md) diff --git a/docs/docs/building-modules/06-keeper.md b/docs/docs/building-modules/06-keeper.md index 946eff6ff137..4ba7e021870b 100644 --- a/docs/docs/building-modules/06-keeper.md +++ b/docs/docs/building-modules/06-keeper.md @@ -8,9 +8,7 @@ sidebar_position: 1 `Keeper`s refer to a Cosmos SDK abstraction whose role is to manage access to the subset of the state defined by various modules. `Keeper`s are module-specific, i.e. the subset of state defined by a module can only be accessed by a `keeper` defined in said module. If a module needs to access the subset of state defined by another module, a reference to the second module's internal `keeper` needs to be passed to the first one. This is done in `app.go` during the instantiation of module keepers. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Introduction to Cosmos SDK Modules](./01-intro.md) diff --git a/docs/docs/building-modules/07-invariants.md b/docs/docs/building-modules/07-invariants.md index 4c53169d4277..a7f156055794 100644 --- a/docs/docs/building-modules/07-invariants.md +++ b/docs/docs/building-modules/07-invariants.md @@ -8,9 +8,7 @@ sidebar_position: 1 An invariant is a property of the application that should always be true. In the context of the Cosmos SDK, an `Invariant` is a function that checks for a particular invariant. These functions are useful to detect bugs early on and act upon them to limit their potential consequences (e.g. by halting the chain). They are also useful in the development process of the application to detect bugs via simulations. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Keepers](./06-keeper.md) diff --git a/docs/docs/building-modules/08-genesis.md b/docs/docs/building-modules/08-genesis.md index a63c8b11921b..38c604a49264 100644 --- a/docs/docs/building-modules/08-genesis.md +++ b/docs/docs/building-modules/08-genesis.md @@ -8,9 +8,7 @@ sidebar_position: 1 Modules generally handle a subset of the state and, as such, they need to define the related subset of the genesis file as well as methods to initialize, verify and export it. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Module Manager](./01-module-manager.md) * [Keepers](./06-keeper.md) diff --git a/docs/docs/building-modules/09-module-interfaces.md b/docs/docs/building-modules/09-module-interfaces.md index 12f290183b9f..b770a0663c6c 100644 --- a/docs/docs/building-modules/09-module-interfaces.md +++ b/docs/docs/building-modules/09-module-interfaces.md @@ -8,9 +8,7 @@ sidebar_position: 1 This document details how to build CLI and REST interfaces for a module. Examples from various Cosmos SDK modules are included. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Building Modules Intro](./01-intro.md) diff --git a/docs/docs/building-modules/10-autocli.md b/docs/docs/building-modules/10-autocli.md index 1629e3d65620..81a0f933753f 100644 --- a/docs/docs/building-modules/10-autocli.md +++ b/docs/docs/building-modules/10-autocli.md @@ -9,9 +9,7 @@ sidebar_position: 1 This document details how to build CLI and REST interfaces for a module. Examples from various Cosmos SDK modules are included. ::: -:::note - -## Pre-requisite Readings +:::note Pre-requisite Readings * [Building Modules Intro](./01-intro.md) diff --git a/docs/docs/building-modules/13-upgrade.md b/docs/docs/building-modules/13-upgrade.md index 18484c68c658..401113a1edc8 100644 --- a/docs/docs/building-modules/13-upgrade.md +++ b/docs/docs/building-modules/13-upgrade.md @@ -8,9 +8,7 @@ sidebar_position: 1 [In-Place Store Migrations](../core/15-upgrade.md) allow your modules to upgrade to new versions that include breaking changes. This document outlines how to build modules to take advantage of this functionality. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [In-Place Store Migration](../core/15-upgrade.md) diff --git a/docs/docs/building-modules/14-simulator.md b/docs/docs/building-modules/14-simulator.md index d3483cec676d..c98361abc90e 100644 --- a/docs/docs/building-modules/14-simulator.md +++ b/docs/docs/building-modules/14-simulator.md @@ -4,8 +4,12 @@ sidebar_position: 1 # Module Simulation +<<<<<<< HEAD :::note ### Pre-requisite Readings +======= +:::note Pre-requisite Readings +>>>>>>> 2c5f36c25 (docs: improve usage of `:::note` (#17132)) * [Cosmos Blockchain Simulator](../core/12-simulation.md) ::: diff --git a/docs/docs/building-modules/15-depinject.md b/docs/docs/building-modules/15-depinject.md index 96dd5dc398c7..1bb623e09b1b 100644 --- a/docs/docs/building-modules/15-depinject.md +++ b/docs/docs/building-modules/15-depinject.md @@ -4,9 +4,7 @@ sidebar_position: 1 # Dependency Injection -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Cosmos SDK Dependency Injection Framework](../tooling/02-depinject.md) diff --git a/docs/docs/core/00-baseapp.md b/docs/docs/core/00-baseapp.md index e18267116ce9..7ba24b50a047 100644 --- a/docs/docs/core/00-baseapp.md +++ b/docs/docs/core/00-baseapp.md @@ -8,9 +8,7 @@ sidebar_position: 1 This document describes `BaseApp`, the abstraction that implements the core functionalities of a Cosmos SDK application. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md) * [Lifecycle of a Cosmos SDK transaction](../basics/01-tx-lifecycle.md) diff --git a/docs/docs/core/01-transactions.md b/docs/docs/core/01-transactions.md index 8c1fa3f9e912..22e485844500 100644 --- a/docs/docs/core/01-transactions.md +++ b/docs/docs/core/01-transactions.md @@ -8,9 +8,7 @@ sidebar_position: 1 `Transactions` are objects created by end-users to trigger state changes in the application. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Anatomy of a Cosmos SDK Application](../basics/00-app-anatomy.md) diff --git a/docs/docs/core/02-context.md b/docs/docs/core/02-context.md index 74e4a7a24f12..21c99b8a4669 100644 --- a/docs/docs/core/02-context.md +++ b/docs/docs/core/02-context.md @@ -8,9 +8,7 @@ sidebar_position: 1 The `context` is a data structure intended to be passed from function to function that carries information about the current state of the application. It provides access to a branched storage (a safe branch of the entire state) as well as useful objects and information like `gasMeter`, `block height`, `consensus parameters` and more. ::: -:::note - -### Pre-requisites Readings +:::note Pre-requisite Readings * [Anatomy of a Cosmos SDK Application](../basics/00-app-anatomy.md) * [Lifecycle of a Transaction](../basics/01-tx-lifecycle.md) diff --git a/docs/docs/core/03-node.md b/docs/docs/core/03-node.md index 67eb018caa52..4e69028065ca 100644 --- a/docs/docs/core/03-node.md +++ b/docs/docs/core/03-node.md @@ -8,9 +8,7 @@ sidebar_position: 1 The main endpoint of a Cosmos SDK application is the daemon client, otherwise known as the full-node client. The full-node runs the state-machine, starting from a genesis file. It connects to peers running the same client in order to receive and relay transactions, block proposals and signatures. The full-node is constituted of the application, defined with the Cosmos SDK, and of a consensus engine connected to the application via the ABCI. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Anatomy of an SDK application](../basics/00-app-anatomy.md) diff --git a/docs/docs/core/04-store.md b/docs/docs/core/04-store.md index 239cec484af5..13c58469e34e 100644 --- a/docs/docs/core/04-store.md +++ b/docs/docs/core/04-store.md @@ -8,9 +8,7 @@ sidebar_position: 1 A store is a data structure that holds the state of the application. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md) diff --git a/docs/docs/core/05-encoding.md b/docs/docs/core/05-encoding.md index 55e889f98243..a7bf3be892a4 100644 --- a/docs/docs/core/05-encoding.md +++ b/docs/docs/core/05-encoding.md @@ -8,9 +8,7 @@ sidebar_position: 1 While encoding in the Cosmos SDK used to be mainly handled by `go-amino` codec, the Cosmos SDK is moving towards using `gogoprotobuf` for both state and client-side encoding. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md) diff --git a/docs/docs/core/08-events.md b/docs/docs/core/08-events.md index b07aaffd4025..e8b1d5c33384 100644 --- a/docs/docs/core/08-events.md +++ b/docs/docs/core/08-events.md @@ -7,9 +7,7 @@ sidebar_position: 1 `Event`s are objects that contain information about the execution of the application. They are mainly used by service providers like block explorers and wallet to track the execution of various messages and index transactions. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md) * [CometBFT Documentation on Events](https://docs.cometbft.com/v0.37/spec/abci/abci++_basic_concepts#events) diff --git a/docs/docs/run-node/01-run-node.md b/docs/docs/run-node/01-run-node.md index a040380272da..cce2bed5fa65 100644 --- a/docs/docs/run-node/01-run-node.md +++ b/docs/docs/run-node/01-run-node.md @@ -8,9 +8,7 @@ sidebar_position: 1 Now that the application is ready and the keyring populated, it's time to see how to run the blockchain node. In this section, the application we are running is called [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/main/simapp), and its corresponding CLI binary `simd`. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Anatomy of a Cosmos SDK Application](../basics/00-app-anatomy.md) * [Setting up the keyring](./00-keyring.md) diff --git a/docs/docs/run-node/02-interact-node.md b/docs/docs/run-node/02-interact-node.md index aaade7bcef14..855aa348be70 100644 --- a/docs/docs/run-node/02-interact-node.md +++ b/docs/docs/run-node/02-interact-node.md @@ -8,9 +8,7 @@ sidebar_position: 1 There are multiple ways to interact with a node: using the CLI, using gRPC or using the REST endpoints. ::: -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [gRPC, REST and CometBFT Endpoints](../core/06-grpc_rest.md) * [Running a Node](./01-run-node.md) diff --git a/x/auth/tx/README.md b/x/auth/tx/README.md index 45a5fa455283..5a9a64f40f12 100644 --- a/x/auth/tx/README.md +++ b/x/auth/tx/README.md @@ -4,9 +4,7 @@ sidebar_position: 1 # `x/auth/tx` -:::note - -### Pre-requisite Readings +:::note Pre-requisite Readings * [Transactions](https://docs.cosmos.network/main/core/transactions#transaction-generation) * [Encoding](https://docs.cosmos.network/main/core/encoding#transaction-encoding) From 19d9dea10f5a31d3ef1413be94cc9598a67df071 Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Wed, 26 Jul 2023 11:13:31 +0200 Subject: [PATCH 2/2] fix conflicts --- docs/docs/basics/01-tx-lifecycle.md | 5 - docs/docs/building-apps/03-app-upgrade.md | 144 --------------------- docs/docs/building-modules/14-simulator.md | 5 - 3 files changed, 154 deletions(-) diff --git a/docs/docs/basics/01-tx-lifecycle.md b/docs/docs/basics/01-tx-lifecycle.md index 50346520fa6b..ba78ec196077 100644 --- a/docs/docs/basics/01-tx-lifecycle.md +++ b/docs/docs/basics/01-tx-lifecycle.md @@ -8,12 +8,7 @@ sidebar_position: 1 This document describes the lifecycle of a transaction from creation to committed state changes. Transaction definition is described in a [different doc](../core/01-transactions.md). The transaction is referred to as `Tx`. ::: -<<<<<<< HEAD -:::note -### Pre-requisite Readings -======= :::note Pre-requisite Readings ->>>>>>> 2c5f36c25 (docs: improve usage of `:::note` (#17132)) * [Anatomy of a Cosmos SDK Application](./00-app-anatomy.md) ::: diff --git a/docs/docs/building-apps/03-app-upgrade.md b/docs/docs/building-apps/03-app-upgrade.md index 4d26afe88fc5..d60e781177bc 100644 --- a/docs/docs/building-apps/03-app-upgrade.md +++ b/docs/docs/building-apps/03-app-upgrade.md @@ -12,150 +12,6 @@ This document describes how to upgrade your application. If you are looking spec This section is currently incomplete. Track the progress of this document [here](https://github.com/cosmos/cosmos-sdk/issues/11504). ::: -<<<<<<< HEAD -======= -:::note Pre-requisite Readings - -* [`x/upgrade` Documentation](https://docs.cosmos.network/main/modules/upgrade) - -::: - -## General Workflow - -Let's assume we are running v0.38.0 of our software in our testnet and want to upgrade to v0.40.0. -How would this look in practice? First of all, we want to finalize the v0.40.0 release candidate -and there install a specially named upgrade handler (eg. "testnet-v2" or even "v0.40.0"). An upgrade -handler should be defined in a new version of the software to define what migrations -to run to migrate from the older version of the software. Naturally, this is app-specific rather -than module specific, and must be defined in `app.go`, even if it imports logic from various -modules to perform the actions. You can register them with `upgradeKeeper.SetUpgradeHandler` -during the app initialization (before starting the abci server), and they serve not only to -perform a migration, but also to identify if this is the old or new version (eg. presence of -a handler registered for the named upgrade). - -Once the release candidate along with an appropriate upgrade handler is frozen, -we can have a governance vote to approve this upgrade at some future block height (e.g. 200000). -This is known as an upgrade.Plan. The v0.38.0 code will not know of this handler, but will -continue to run until block 200000, when the plan kicks in at `BeginBlock`. It will check -for existence of the handler, and finding it missing, know that it is running the obsolete software, -and gracefully exit. - -Generally the application binary will restart on exit, but then will execute this BeginBlocker -again and exit, causing a restart loop. Either the operator can manually install the new software, -or you can make use of an external watcher daemon to possibly download and then switch binaries, -also potentially doing a backup. The SDK tool for doing such, is called [Cosmovisor](https://docs.cosmos.network/main/tooling/cosmovisor). - -When the binary restarts with the upgraded version (here v0.40.0), it will detect we have registered the -"testnet-v2" upgrade handler in the code, and realize it is the new version. It then will run the upgrade handler -and *migrate the database in-place*. Once finished, it marks the upgrade as done, and continues processing -the rest of the block as normal. Once 2/3 of the voting power has upgraded, the blockchain will immediately -resume the consensus mechanism. If the majority of operators add a custom `do-upgrade` script, this should -be a matter of minutes and not even require them to be awake at that time. - -## Integrating With An App - -Setup an upgrade Keeper for the app and then define a `BeginBlocker` that calls the upgrade -keeper's BeginBlocker method: - -```go - func (app *myApp) BeginBlocker(ctx sdk.Context, req abci.RequestBeginBlock) (abci.ResponseBeginBlock, error) { - app.upgradeKeeper.BeginBlocker(ctx, req) - return abci.ResponseBeginBlock{}, nil - } -``` - -The app must then integrate the upgrade keeper with its governance module as appropriate. The governance module -should call ScheduleUpgrade to schedule an upgrade and ClearUpgradePlan to cancel a pending upgrade. - -## Performing Upgrades - -Upgrades can be scheduled at a predefined block height. Once this block height is reached, the -existing software will cease to process ABCI messages and a new version with code that handles the upgrade must be deployed. -All upgrades are coordinated by a unique upgrade name that cannot be reused on the same blockchain. In order for the upgrade -module to know that the upgrade has been safely applied, a handler with the name of the upgrade must be installed. -Here is an example handler for an upgrade named "my-fancy-upgrade": - -```go -app.upgradeKeeper.SetUpgradeHandler("my-fancy-upgrade", func(ctx sdk.Context, plan upgrade.Plan) { - // Perform any migrations of the state store needed for this upgrade -}) -``` - -This upgrade handler performs the dual function of alerting the upgrade module that the named upgrade has been applied, -as well as providing the opportunity for the upgraded software to perform any necessary state migrations. Both the halt -(with the old binary) and applying the migration (with the new binary) are enforced in the state machine. Actually -switching the binaries is an ops task and not handled inside the sdk / abci app. - -Here is a sample code to set store migrations with an upgrade: - -```go -// this configures a no-op upgrade handler for the "my-fancy-upgrade" upgrade -app.UpgradeKeeper.SetUpgradeHandler("my-fancy-upgrade", func(ctx sdk.Context, plan upgrade.Plan) { - // upgrade changes here -}) -upgradeInfo, err := app.UpgradeKeeper.ReadUpgradeInfoFromDisk() -if err != nil { - // handle error -} -if upgradeInfo.Name == "my-fancy-upgrade" && !app.UpgradeKeeper.IsSkipHeight(upgradeInfo.Height) { - storeUpgrades := store.StoreUpgrades{ - Renamed: []store.StoreRename{{ - OldKey: "foo", - NewKey: "bar", - }}, - Deleted: []string{}, - } - // configure store loader that checks if version == upgradeHeight and applies store upgrades - app.SetStoreLoader(upgrade.UpgradeStoreLoader(upgradeInfo.Height, &storeUpgrades)) -} -``` - -## Halt Behavior - -Before halting the ABCI state machine in the BeginBlocker method, the upgrade module will log an error -that looks like: - -```text - UPGRADE "" NEEDED at height : -``` - -where `Name` and `Info` are the values of the respective fields on the upgrade Plan. - -To perform the actual halt of the blockchain, the upgrade keeper simply panics which prevents the ABCI state machine -from proceeding but doesn't actually exit the process. Exiting the process can cause issues for other nodes that start -to lose connectivity with the exiting nodes, thus this module prefers to just halt but not exit. - -## Automation - -Read more about [Cosmovisor](https://docs.cosmos.network/main/tooling/cosmovisor), the tool for automating upgrades. - -## Canceling Upgrades - -There are two ways to cancel a planned upgrade - with on-chain governance or off-chain social consensus. -For the first one, there is a `CancelSoftwareUpgrade` governance proposal, which can be voted on and will -remove the scheduled upgrade plan. Of course this requires that the upgrade was known to be a bad idea -well before the upgrade itself, to allow time for a vote. If you want to allow such a possibility, you -should set the upgrade height to be `2 * (votingperiod + depositperiod) + (safety delta)` from the beginning of -the first upgrade proposal. Safety delta is the time available from the success of an upgrade proposal -and the realization it was a bad idea (due to external testing). You can also start a `CancelSoftwareUpgrade` -proposal while the original `SoftwareUpgrade` proposal is still being voted upon, as long as the voting -period ends after the `SoftwareUpgrade` proposal. - -However, let's assume that we don't realize the upgrade has a bug until shortly before it will occur -(or while we try it out - hitting some panic in the migration). It would seem the blockchain is stuck, -but we need to allow an escape for social consensus to overrule the planned upgrade. To do so, there's -a `--unsafe-skip-upgrades` flag to the start command, which will cause the node to mark the upgrade -as done upon hitting the planned upgrade height(s), without halting and without actually performing a migration. -If over two-thirds run their nodes with this flag on the old binary, it will allow the chain to continue through -the upgrade with a manual override. (This must be well-documented for anyone syncing from genesis later on). - -Example: - -```shell - start --unsafe-skip-upgrades ... -``` - ->>>>>>> 2c5f36c25 (docs: improve usage of `:::note` (#17132)) ## Pre-Upgrade Handling Cosmovisor supports custom pre-upgrade handling. Use pre-upgrade handling when you need to implement application config changes that are required in the newer version before you perform the upgrade. diff --git a/docs/docs/building-modules/14-simulator.md b/docs/docs/building-modules/14-simulator.md index c98361abc90e..3cc871ad6034 100644 --- a/docs/docs/building-modules/14-simulator.md +++ b/docs/docs/building-modules/14-simulator.md @@ -4,12 +4,7 @@ sidebar_position: 1 # Module Simulation -<<<<<<< HEAD -:::note -### Pre-requisite Readings -======= :::note Pre-requisite Readings ->>>>>>> 2c5f36c25 (docs: improve usage of `:::note` (#17132)) * [Cosmos Blockchain Simulator](../core/12-simulation.md) :::