From 721e83882c99e8551302e1995ea7048b268e42a3 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Wed, 11 Dec 2024 09:37:19 +0100 Subject: [PATCH] docs: runtime docs (backport #22816) (#22824) Co-authored-by: Julien Robert --- docs/build/building-apps/00-runtime.md | 142 +++++++++++++++++++++-- docs/build/building-apps/01-app-go-v2.md | 46 +++++--- docs/learn/advanced/12-simulation.md | 2 +- docs/learn/beginner/00-app-anatomy.md | 16 ++- 4 files changed, 170 insertions(+), 36 deletions(-) diff --git a/docs/build/building-apps/00-runtime.md b/docs/build/building-apps/00-runtime.md index 5f9ab6f9287f..5da91a65396e 100644 --- a/docs/build/building-apps/00-runtime.md +++ b/docs/build/building-apps/00-runtime.md @@ -4,24 +4,150 @@ sidebar_position: 1 # What is `runtime`? -The `runtime` package is the Cosmos SDK package that combines the building blocks of your blockchain together. It wires together the modules, the applications, the codecs, and the stores. +The `runtime` package in the Cosmos SDK provides a flexible framework for configuring and managing blockchain applications. It serves as the foundation for creating modular blockchain applications using a declarative configuration approach. + +## Overview + +The runtime package acts as a wrapper around the `BaseApp` and `ModuleManager`, offering a hybrid approach where applications can be configured both declaratively through configuration files and programmatically through traditional methods. It is a layer of abstraction between `baseapp` and the application modules that simplifies the process of building a Cosmos SDK application. -## Modules wiring +## Core Components + +### App Structure + +The runtime App struct contains several key components: + +```go +type App struct { + *baseapp.BaseApp + ModuleManager *module.Manager + UnorderedTxManager *unorderedtx.Manager + configurator module.Configurator + config *runtimev1alpha1.Module + storeKeys []storetypes.StoreKey + // ... other fields +} +``` + +It is the struct that any Cosmos SDK application should embed to leverage the runtime module. + +```go reference +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/app_di.go#L61-L62 +``` + +### Configuration + +The runtime module is configured using App Wiring. The main configuration object is the [`Module` message](https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/proto/cosmos/app/runtime/v1alpha1/module.proto), which supports the following key settings: + +* `app_name`: The name of the application +* `begin_blockers`: List of module names to call during BeginBlock +* `end_blockers`: List of module names to call during EndBlock +* `init_genesis`: Order of module initialization during genesis +* `export_genesis`: Order for exporting module genesis data +* `pre_blockers`: Modules to execute before block processing + +Learn more about wiring `runtime` in the [next section](./01-app-go-di.md). + +#### Store Configuration + +By default, the runtime module uses the module name as the store key. +However it provides a flexible store key configuration through: + +* `override_store_keys`: Allows customizing module store keys +* `skip_store_keys`: Specifies store keys to skip during keeper construction + +Example configuration: + +```go reference +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/v2/app_config.go#L138-L147 +``` + +## Key Features + +### 1. BaseApp and other Core SDK components integration + +The runtime module integrates with the `BaseApp` and other core SDK components to provide a seamless experience for developers. + +The developer only needs to embed the `App` struct in their application to leverage the runtime module. +The configuration of the module manager and other core components is handled internally via the [`AppBuilder`](#4-application-building). + +### 2. Module Registration + +Runtime has built-in support for [`depinject`-enabled modules](../building-modules/15-depinject.md). +Such modules can be registered through the configuration file (often named `app_config.go`), with no additional code required. -Runtime is responsible for wiring the modules together. It uses `depinject` to inject the dependencies of the modules. +```go reference +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/app_config.go#L210-L215 +``` -## App wiring +Additionally, the runtime package facilitates manual module registration through the `RegisterModules` method. This is the primary integration point for modules not registered via configuration. -Runtime is the base boilerplate of a Cosmos SDK application. -A user only needs to import `runtime` in their `app.go` and instantiate a `runtime.App`. +:::warning +Even when using manual registration, the module should still be configured in the `Module` message in AppConfig. +::: + +```go +func (a *App) RegisterModules(modules ...module.AppModule) error +``` -## Services +The SDK recommends using the declarative approach with `depinject` for module registration whenever possible. -Modules have access to a multitude of services that are provided by the runtime. +### 3. Service Registration + +Runtime registers all [core services](../../learn/advanced/02-core.md) required by modules. These services include the `store`, the `event manager`, the `context`, and the `logger`. As runtime is doing the wiring of modules, it can ensure that the services are scoped to their respective modules. ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/runtime/module.go#L250-L279 ``` + +Additionally, runtime provides automatic registration of other essential (f.e gRPC routes) services, available to the App: + +* AutoCLI Query Service +* Reflection Service +* Custom module services + +```go reference +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/runtime/builder.go#L74-L77 +``` + +### 4. Application Building + +The `AppBuilder` type provides a structured way to build applications: + +```go reference +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/runtime/builder.go#L22-L29 +``` + +Key building steps: + +1. Configuration loading +2. Module registration +3. Service setup +4. Store mounting +5. Router configuration + +An application only needs to call `AppBuilder.Build` to create a fully configured application (`runtime.App`). + +```go reference +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/runtime/builder.go#L36-L80 +``` + +More information on building applications can be found in the [next section](./02-app-building.md). + +## Best Practices + +1. **Module Order**: Carefully consider the order of modules in begin_blockers and end_blockers +2. **Store Keys**: Use override_store_keys only when necessary to maintain clarity +3. **Genesis Order**: Maintain correct initialization order in init_genesis +4. **Migration Management**: Use order_migrations to control upgrade paths + +### Migration Considerations + +When upgrading between versions: + +1. Review the migration order specified in `order_migrations` +2. Ensure all required modules are included in the configuration +3. Validate store key configurations +4. Test the upgrade path thoroughly diff --git a/docs/build/building-apps/01-app-go-v2.md b/docs/build/building-apps/01-app-go-v2.md index d77899d26e6d..872124e49625 100644 --- a/docs/build/building-apps/01-app-go-v2.md +++ b/docs/build/building-apps/01-app-go-v2.md @@ -6,16 +6,17 @@ sidebar_position: 1 :::note Synopsis -The Cosmos SDK allows much easier wiring of an `app.go` thanks to App Wiring and [`depinject`](../packages/01-depinject.md). +The Cosmos SDK allows much easier wiring of an `app.go` thanks to [runtime](./00-runtime.md) and app wiring. Learn more about the rationale of App Wiring in [ADR-057](../architecture/adr-057-app-wiring.md). ::: :::note Pre-requisite Readings -* [ADR 057: App Wiring](../architecture/adr-057-app-wiring.md) -* [Depinject Documentation](../packages/01-depinject.md) +* [What is `runtime`?](./00-runtime.md) +* [Depinject documentation](../packages/01-depinject.md) * [Modules depinject-ready](../building-modules/15-depinject.md) +* [ADR 057: App Wiring](../architecture/adr-057-app-wiring.md) ::: @@ -28,30 +29,39 @@ The `app_config.go` file is the single place to configure all modules parameters 1. Create the `AppConfig` variable: ```go reference - https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app_config.go#L103 + https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/app_di.go#L93-L99 ``` -2. Configure the `runtime` module: + Where the `appConfig`, combine the [runtime](./00-runtime.md) and the modules configuration. ```go reference - https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app_config.go#L103-L167 + https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/app_config.go#L107-L111 ``` -3. Configure the modules defined in the `PreBlocker`, `BeginBlocker` and `EndBlocker` and the `tx` module: +2. Configure the `runtime` module: + + In this configuration, the order at which the modules are defined is important. + They are named in the order they should be executed by the module manager. ```go reference - https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app_config.go#L112-L129 + https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/app_config.go#L110-L187 ``` +3. Wire the other modules: + + Next to runtime, the other (depinject-enabled) modules are wired in the `AppConfig`: + ```go reference - https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app_config.go#L200-L203 + https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/app_config.go#L196-L215 ``` -### Complete `app_config.go` + Note: the `tx` isn't a module, but a configuration. It should be wired in the `AppConfig` as well. -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app_config.go -``` + ```go reference + https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/app_config.go#L188-L195 + ``` + +See the complete `app_config.go` file for `SimApp` [here](https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/app_config.go). ### Alternative formats @@ -93,15 +103,15 @@ modules: "@type": cosmos.tx.config.v1.Config ``` -A more complete example of `app.yaml` can be found [here](https://github.com/cosmos/cosmos-sdk/blob/91b1d83f1339e235a1dfa929ecc00084101a19e3/simapp/app.yaml). +A more complete example of `app.yaml` can be found [here](https://github.com/cosmosregistry/chain-minimal/blob/mini-v050.2/app/app.yaml). ## `app_di.go` `app_di.go` is the place where `SimApp` is constructed. `depinject.Inject` facilitates that by automatically wiring the app modules and keepers, provided an application configuration `AppConfig` is provided. `SimApp` is constructed, when calling the injected `*runtime.AppBuilder`, with `appBuilder.Build(...)`. -In short `depinject` and the [`runtime` package](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/runtime) abstract the wiring of the app, and the `AppBuilder` is the place where the app is constructed. [`runtime`](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/runtime) takes care of registering the codecs, KV store, subspaces and instantiating `baseapp`. +In short `depinject` and the [`runtime` package](./00-runtime.md) abstract the wiring of the app, and the `AppBuilder` is the place where the app is constructed. [`runtime`](./00-runtime.md) takes care of registering the codecs, KV store, subspaces and instantiating `baseapp`. ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app_v2.go#L101-L245 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/app_di.go#L101-L290 ``` :::warning @@ -115,7 +125,7 @@ In this case, use `depinject.Configs` for combining the extra configuration and More information on how work `depinject.Configs` and `depinject.Supply` can be found in the [`depinject` documentation](https://pkg.go.dev/cosmossdk.io/depinject). ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app_v2.go#L114-L146 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/app_di.go#L117-L161 ``` ### Registering non app wiring modules @@ -150,5 +160,5 @@ Note that in the complete `SimApp` `app_di.go` file, testing utilities are also ::: ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app_v2.go +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/app.go ``` diff --git a/docs/learn/advanced/12-simulation.md b/docs/learn/advanced/12-simulation.md index 6a43bb10ff51..efe51694e347 100644 --- a/docs/learn/advanced/12-simulation.md +++ b/docs/learn/advanced/12-simulation.md @@ -7,7 +7,7 @@ sidebar_position: 1 The Cosmos SDK offers a full fledged simulation framework to [fuzz test](https://en.wikipedia.org/wiki/Fuzzing) every message defined by a module. -On the Cosmos SDK, this functionality is provided by [`SimApp`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app_v2.go), which is a `Baseapp` application that is used for running the [`simulation`](https://github.com/cosmos/cosmos-sdk/blob/23cf89cce1882ba9c8280e64735ae200504bfdce/simsx/README.md#L1) package. This package defines all the simulation logic as well as the operations for randomized parameters like accounts, balances etc. +On the Cosmos SDK, this functionality is provided by [`SimApp`](https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/app_di.go), which is a `Baseapp` application that is used for running the [`simulation`](https://github.com/cosmos/cosmos-sdk/blob/23cf89cce1882ba9c8280e64735ae200504bfdce/simsx/README.md#L1) package. This package defines all the simulation logic as well as the operations for randomized parameters like accounts, balances etc. ## Goals diff --git a/docs/learn/beginner/00-app-anatomy.md b/docs/learn/beginner/00-app-anatomy.md index a8b576839f40..056a107f2190 100644 --- a/docs/learn/beginner/00-app-anatomy.md +++ b/docs/learn/beginner/00-app-anatomy.md @@ -57,22 +57,20 @@ In general, the core of the state-machine is defined in a file called `app.go`. ### Type Definition of the Application - +The first thing defined in `app.go` is the `type` of the application. It is generally comprised of the following parts: - +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/app_di.go#L58-L83 +``` ### Constructor Function