Skip to content

Commit

Permalink
docs: runtime docs (backport #22816) (#22824)
Browse files Browse the repository at this point in the history 
Co-authored-by: Julien Robert <[email protected]>
  • Loading branch information
@mergify @julienrbrt
mergify[bot] and julienrbrt authored Dec 11, 2024
1 parent 3ba671f commit 721e838
Show file tree
Hide file tree
Showing 4 changed files with 170 additions and 36 deletions.
142 changes: 134 additions & 8 deletions docs/build/building-apps/00-runtime.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
46 changes: 28 additions & 18 deletions docs/build/building-apps/01-app-go-v2.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

:::

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
```
2 changes: 1 addition & 1 deletion docs/learn/advanced/12-simulation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
16 changes: 7 additions & 9 deletions docs/learn/beginner/00-app-anatomy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down

0 comments on commit 721e838

Please sign in to comment.