From 8166f8511de8d89e7011b3177ceba572f2177491 Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Fri, 4 Oct 2024 10:46:27 +0200 Subject: [PATCH] docs: remove invariants --- .../building-modules/01-module-manager.md | 11 --- docs/build/building-modules/07-invariants.md | 92 ------------------- docs/learn/beginner/00-app-anatomy.md | 1 - x/epochs/keeper/epoch.go | 4 +- 4 files changed, 1 insertion(+), 107 deletions(-) delete mode 100644 docs/build/building-modules/07-invariants.md diff --git a/docs/build/building-modules/01-module-manager.md b/docs/build/building-modules/01-module-manager.md index d5e0aac04da..4614429928a 100644 --- a/docs/build/building-modules/01-module-manager.md +++ b/docs/build/building-modules/01-module-manager.md @@ -125,16 +125,6 @@ Previously the `module.AppModule` interface was containing all the methods that https://github.com/cosmos/cosmos-sdk/blob/28fa3b8/core/appmodule/v2/module.go#L14-L20 ``` -### `HasInvariants` - -This interface defines one method. It allows to checks if a module can register invariants. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/module/module.go#L202-L205 -``` - -* `RegisterInvariants(sdk.InvariantRegistry)`: Registers the [`invariants`](./07-invariants.md) of the module. If an invariant deviates from its predicted value, the [`InvariantRegistry`](./07-invariants.md#registry) triggers appropriate logic (most often the chain will be halted). - ### `HasServices` This interface defines one method. It allows to checks if a module can register invariants. @@ -238,7 +228,6 @@ The module manager is used throughout the application whenever an action on a co * `SetOrderPrecommiters(moduleNames ...string)`: Sets the order in which the `Precommit()` function of each module will be called during commit of each block. This function is generally called from the application's main [constructor function](../../learn/beginner/00-app-anatomy.md#constructor-function). * `SetOrderPrepareCheckStaters(moduleNames ...string)`: Sets the order in which the `PrepareCheckState()` function of each module will be called during commit of each block. This function is generally called from the application's main [constructor function](../../learn/beginner/00-app-anatomy.md#constructor-function). * `SetOrderMigrations(moduleNames ...string)`: Sets the order of migrations to be run. If not set then migrations will be run with an order defined in `DefaultMigrationsOrder`. -* `RegisterInvariants(ir sdk.InvariantRegistry)`: Registers the [invariants](./07-invariants.md) of module implementing the `HasInvariants` interface. * `RegisterServices(cfg Configurator)`: Registers the services of modules implementing the `HasServices` interface. * `InitGenesis(ctx context.Context, genesisData map[string]json.RawMessage)`: Calls the [`InitGenesis`](./08-genesis.md#initgenesis) function of each module when the application is first started, in the order defined in `OrderInitGenesis`. Returns an `abci.InitChainResponse` to the underlying consensus engine, which can contain validator updates. * `ExportGenesis(ctx context.Context)`: Calls the [`ExportGenesis`](./08-genesis.md#exportgenesis) function of each module, in the order defined in `OrderExportGenesis`. The export constructs a genesis file from a previously existing state, and is mainly used when a hard-fork upgrade of the chain is required. diff --git a/docs/build/building-modules/07-invariants.md b/docs/build/building-modules/07-invariants.md deleted file mode 100644 index 2e8edfcada6..00000000000 --- a/docs/build/building-modules/07-invariants.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Invariants - - - -:::note Synopsis -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 - -* [Keepers](./06-keeper.md) - -::: - -## Implementing `Invariant`s - -An `Invariant` is a function that checks for a particular invariant within a module. Module `Invariant`s must follow the `Invariant` type: - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/invariant.go#L9 -``` - -The `string` return value is the invariant message, which can be used when printing logs, and the `bool` return value is the actual result of the invariant check. - -In practice, each module implements `Invariant`s in a `keeper/invariants.go` file within the module's folder. The standard is to implement one `Invariant` function per logical grouping of invariants with the following model: - -```go -// Example for an Invariant that checks balance-related invariants - -func BalanceInvariants(k Keeper) sdk.Invariant { - return func(ctx context.Context) (string, bool) { - // Implement checks for balance-related invariants - } -} -``` - -Additionally, module developers should generally implement an `AllInvariants` function that runs all the `Invariant`s functions of the module: - -```go -// AllInvariants runs all invariants of the module. -// In this example, the module implements two Invariants: BalanceInvariants and DepositsInvariants - -func AllInvariants(k Keeper) sdk.Invariant { - - return func(ctx context.Context) (string, bool) { - res, stop := BalanceInvariants(k)(ctx) - if stop { - return res, stop - } - - return DepositsInvariant(k)(ctx) - } -} -``` - -Finally, module developers need to implement the `RegisterInvariants` method as part of the [`AppModule` interface](./01-module-manager.md#appmodule). Indeed, the `RegisterInvariants` method of the module, implemented in the `module/module.go` file, typically only defers the call to a `RegisterInvariants` method implemented in the `keeper/invariants.go` file. The `RegisterInvariants` method registers a route for each `Invariant` function in the [`InvariantRegistry`](#invariant-registry): - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/staking/keeper/invariants.go#L12-L22 -``` - -For more, see an example of [`Invariant`s implementation from the `staking` module](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/staking/keeper/invariants.go). - -## Invariant Registry - -The `InvariantRegistry` is a registry where the `Invariant`s of all the modules of an application are registered. There is only one `InvariantRegistry` per **application**, meaning module developers need not implement their own `InvariantRegistry` when building a module. **All module developers need to do is to register their modules' invariants in the `InvariantRegistry`, as explained in the section above**. The rest of this section gives more information on the `InvariantRegistry` itself, and does not contain anything directly relevant to module developers. - -At its core, the `InvariantRegistry` is defined in the Cosmos SDK as an interface: - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/invariant.go#L14-L17 -``` - -Typically, this interface is implemented in the `keeper` of a specific module. The most used implementation of an `InvariantRegistry` can be found in the `crisis` module: - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/crisis/keeper/keeper.go#L48-L50 -``` - -The `InvariantRegistry` is therefore typically instantiated by instantiating the `keeper` of the `crisis` module in the [application's constructor function](../../learn/beginner/00-app-anatomy.md#constructor-function). - -`Invariant`s can be checked manually via [`message`s](./02-messages-and-queries.md), but most often they are checked automatically at the end of each block. Here is an example from the `crisis` module: - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/crisis/abci.go#L13-L23 -``` - -In both cases, if one of the `Invariant`s returns false, the `InvariantRegistry` can trigger special logic (e.g. have the application panic and print the `Invariant`s message in the log). diff --git a/docs/learn/beginner/00-app-anatomy.md b/docs/learn/beginner/00-app-anatomy.md index 9757e7e95af..4cc675d6211 100644 --- a/docs/learn/beginner/00-app-anatomy.md +++ b/docs/learn/beginner/00-app-anatomy.md @@ -87,7 +87,6 @@ Here are the main actions performed by this function: * Instantiate all the [`keeper`](#keeper) objects defined in the application's `type` using the `NewKeeper` function of each of the application's modules. Note that keepers must be instantiated in the correct order, as the `NewKeeper` of one module might require a reference to another module's `keeper`. * Instantiate the application's [module manager](../../build/building-modules/01-module-manager.md#manager) with the [`AppModule`](#application-module-interface) object of each of the application's modules. * With the module manager, initialize the application's [`Msg` services](../advanced/00-baseapp.md#msg-services), [gRPC `Query` services](../advanced/00-baseapp.md#grpc-query-services), [legacy `Msg` routes](../advanced/00-baseapp.md#routing), and [legacy query routes](../advanced/00-baseapp.md#query-routing). When a transaction is relayed to the application by CometBFT via the ABCI, it is routed to the appropriate module's [`Msg` service](#msg-services) using the routes defined here. Likewise, when a gRPC query request is received by the application, it is routed to the appropriate module's [`gRPC query service`](#grpc-query-services) using the gRPC routes defined here. The Cosmos SDK still supports legacy `Msg`s and legacy CometBFT queries, which are routed using the legacy `Msg` routes and the legacy query routes, respectively. -* With the module manager, register the [application's modules' invariants](../../build/building-modules/07-invariants.md). Invariants are variables (e.g. total supply of a token) that are evaluated at the end of each block. The process of checking invariants is done via a special module called the [`InvariantsRegistry`](../../build/building-modules/07-invariants.md#invariant-registry). The value of the invariant should be equal to a predicted value defined in the module. Should the value be different than the predicted one, special logic defined in the invariant registry is triggered (usually the chain is halted). This is useful to make sure that no critical bug goes unnoticed, producing long-lasting effects that are hard to fix. * With the module manager, set the order of execution between the `InitGenesis`, `PreBlocker`, `BeginBlocker`, and `EndBlocker` functions of each of the [application's modules](#application-module-interface). Note that not all modules implement these functions. * Set the remaining application parameters: * [`InitChainer`](#initchainer): used to initialize the application when it is first started. diff --git a/x/epochs/keeper/epoch.go b/x/epochs/keeper/epoch.go index c655dac5484..f743227ed5b 100644 --- a/x/epochs/keeper/epoch.go +++ b/x/epochs/keeper/epoch.go @@ -5,12 +5,10 @@ import ( "fmt" "cosmossdk.io/x/epochs/types" - - sdk "github.com/cosmos/cosmos-sdk/types" ) // GetEpochInfo returns epoch info by identifier. -func (k Keeper) GetEpochInfo(ctx sdk.Context, identifier string) (types.EpochInfo, error) { +func (k Keeper) GetEpochInfo(ctx context.Context, identifier string) (types.EpochInfo, error) { return k.EpochInfo.Get(ctx, identifier) }