docs: runtime docs (backport #22816) (#22824)

Co-authored-by: Julien Robert <[email protected]>

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

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
 ```

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
 

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
 
-<!-- TODO(@julienrbrt), in next follow up introduce runtime, then app anatomy within runtime doc -->
+The first thing defined in `app.go` is the `type` of the application. It is generally comprised of the following parts:
 
-<!-- The first thing defined in `app.go` is the `type` of the application. It is generally comprised of the following parts:
-
-* **A reference to [`baseapp`](../advanced/00-baseapp.md).** The custom application defined in `app.go` is an extension of `baseapp`. When a transaction is relayed by CometBFT to the application, `app` uses `baseapp`'s methods to route them to the appropriate module. `baseapp` implements most of the core logic for the application, including all the [ABCI methods](https://docs.cometbft.com/v1.0/spec/abci/) and the [routing logic](../advanced/00-baseapp.md#service-routers).
-* **A list of store keys**. The [store](../advanced/04-store.md), which contains the entire state, is implemented as a [`multistore`](../advanced/04-store.md#multistore) (i.e. a store of stores) in the Cosmos SDK. Each module uses one or multiple stores in the multistore to persist their part of the state. These stores can be accessed with specific keys that are declared in the `app` type. These keys, along with the `keepers`, are at the heart of the [object-capabilities model](../advanced/10-ocap.md) of the Cosmos SDK.
-* **A list of module's `keeper`s.** Each module defines an abstraction called [`keeper`](../../build/building-modules/06-keeper.md), which handles reads and writes for this module's store(s). The `keeper`'s methods of one module can be called from other modules (if authorized), which is why they are declared in the application's type and exported as interfaces to other modules so that the latter can only access the authorized functions.
+* **Embeding [runtime.App](../../build/building-apps/00-runtime.md)** The runtime package manages the application's core components and modules through dependency injection. It provides declarative configuration for module management, state storage, and ABCI handling.
+    * `Runtime` wraps `baseapp`, meaning when a transaction is relayed by CometBFT to the application, `app` uses `runtime`'s methods to route them to the appropriate module. Baseapp implements all the [ABCI methods](https://docs.cometbft.com/v1.0/spec/abci/) and the [routing logic](../advanced/00-baseapp.md#service-routers).
+    * It configures automatically the **[module manager](../../build/building-modules/01-module-manager.md#manager)** based on the app wiring configuration. The module manager facilitates operations related to these modules, like registering their [`Msg` service](../../build/building-modules/03-msg-services.md) and [gRPC `Query` service](#grpc-query-services), or setting the order of execution between modules for various functions like [`InitChainer`](#initchainer), [`PreBlocker`](#preblocker) and [`BeginBlocker` and `EndBlocker`](#beginblocker-and-endblocker).
+* [**An App Wiring configuration file**](../../build/building-apps/00-runtime.md) The app wiring configuration file contains the list of application's modules that `runtime` must instantiate. The instantiation of the modules are done using `depinject`. It contains as well at which order the modules `InitGenesis`, `Pre/Begin/EndBlocker` should be executed.
 * **A reference to an [`appCodec`](../advanced/05-encoding.md).** The application's `appCodec` is used to serialize and deserialize data structures in order to store them, as stores can only persist `[]bytes`. The default codec is [Protocol Buffers](../advanced/05-encoding.md).
 * **A reference to a [`legacyAmino`](../advanced/05-encoding.md) codec.** Some parts of the Cosmos SDK have not been migrated to use the `appCodec` above, and are still hardcoded to use Amino. Other parts explicitly use Amino for backwards compatibility. For these reasons, the application still holds a reference to the legacy Amino codec. Please note that the Amino codec will be removed from the SDK in the upcoming releases.
-* **A reference to a [module manager](../../build/building-modules/01-module-manager.md#manager)**. The module manager is an object that contains a list of the application's modules. It facilitates operations related to these modules, like registering their [`Msg` service](../../build/building-modules/03-msg-services.md) and [gRPC `Query` service](#grpc-query-services), or setting the order of execution between modules for various functions like [`InitChainer`](#initchainer), [`PreBlocker`](#preblocker) and [`BeginBlocker` and `EndBlocker`](#beginblocker-and-endblocker).
 
 See an example of application type definition from `simapp`, the Cosmos SDK's own app used for demo and testing purposes:
 
 ```go reference
-https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/simapp/app.go#L145-L186
-``` -->
+https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/app_di.go#L58-L83
+```
 
 ### Constructor Function