LaconicNetwork/cosmos-sdk
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity

docs: runtime docs (#22816)

Browse Source
This commit is contained in:
Julien Robert
2024-12-11 08:10:45 +00:00
committed by GitHub
parent c08ab17de6
commit aa8266e702
10 changed files with 174 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/build/building-apps/00-runtime.md
Vendored
+134 -8
View File
@@ -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
Runtime is responsible for wiring the modules together. It uses `depinject` to inject the dependencies of the modules.
### App Structure
## App wiring
The runtime App struct contains several key components:
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`.
```go
type App struct {
*baseapp.BaseApp
ModuleManager *module.Manager
UnorderedTxManager *unorderedtx.Manager
configurator module.Configurator
config *runtimev1alpha1.Module
storeKeys []storetypes.StoreKey
// ... other fields
}
```
## Services
It is the struct that any Cosmos SDK application should embed to leverage the runtime module.
Modules have access to a multitude of services that are provided by the runtime.
```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.
```go reference
https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/app_config.go#L210-L215
```
Additionally, the runtime package facilitates manual module registration through the `RegisterModules` method. This is the primary integration point for modules not registered via configuration.
:::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
```
The SDK recommends using the declarative approach with `depinject` for module registration whenever possible.
### 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-di.md
Vendored
+30 -20
View File
@@ -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
```
Where the `appConfig`, combine the [runtime](./00-runtime.md) and the modules configuration.
```go reference
https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/app_config.go#L107-L111
```
2. Configure the `runtime` module:
```go reference
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app_config.go#L103-L167
```
3. Configure the modules defined in the `PreBlocker`, `BeginBlocker` and `EndBlocker` and the `tx` 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
```