diff --git a/docs/architecture/adr-057-app-wiring.md b/docs/architecture/adr-057-app-wiring.md index eeb06447f3..2e37ced664 100644 --- a/docs/architecture/adr-057-app-wiring.md +++ b/docs/architecture/adr-057-app-wiring.md @@ -149,7 +149,7 @@ to decode the app config in separate phases: 3. decode the app config as proto JSON using the protobuf type registry Because in [ADR 054: Protobuf Semver Compatible Codegen](https://github.com/cosmos/cosmos-sdk/pull/11802), each module -should use `internal` generated code which is not registered with the global protobuf registry, this code should provide +might use `internal` generated code which is not registered with the global protobuf registry, this code should provide an alternate way to register protobuf types with a type registry. In the same way that `.pb.go` files currently have a `var File_foo_proto protoreflect.FileDescriptor` for the file `foo.proto`, generated code should have a new member `var Types_foo_proto TypeInfo` where `TypeInfo` is an interface or struct with all the necessary info to register both @@ -216,7 +216,7 @@ In cases where required modules are not loaded at runtime, it may be possible to through a global Cosmos SDK module registry. The `*appmodule.Handler` type referenced above is a replacement for the legacy `AppModule` framework, and -described in [ADR 061: Core Module API](./adr-061-core-module-api.md). +described in [ADR 063: Core Module API](./adr-063-core-module-api.md). ### New `app.go` @@ -246,7 +246,7 @@ func main() { So far we have described a system which is largely agnostic to the specifics of the SDK such as store keys, `AppModule`, `BaseApp`, etc. Improvements to these parts of the framework that integrate with the general app wiring framework -defined here are described in [ADR 061: Core Module API](./adr-061-core-module-api.md). +defined here are described in [ADR 063: Core Module API](./adr-063-core-module-api.md). ### Registration of Inter-Module Hooks @@ -299,6 +299,35 @@ generated. This will allow: Code generation requires that all providers and invokers and their parameters are exported and in non-internal packages. +### Module Semantic Versioning + +When we start creating semantically versioned SDK modules that are in standalone go modules, a state machine breaking +change to a module should be handled as follows: +- the semantic major version should be incremented, and +- a new semantically versioned module config protobuf type should be created. + +For instance, if we have the SDK module for bank in the go module `cosmossdk.io/x/bank` with the module config type +`cosmos.bank.module.v1.Module`, and we want to make a state machine breaking change to the module, we would: +- create a new go module `cosmossdk.io/x/bank/v2`, +- with the module config protobuf type `cosmos.bank.module.v2.Module`. + +This _does not_ mean that we need to increment the protobuf API version for bank. Both modules can support +`cosmos.bank.v1`, but `cosmossdk.io/x/bank/v2` will be a separate go module with a separate module config type. + +This practice will eventually allow us to use appconfig to load new versions of a module via a configuration change. + +Effectively, there should be a 1:1 correspondence between a semantically versioned go module and a +versioned module config protobuf type, and major versioning bumps should occur whenever state machine breaking changes +are made to a module. + +NOTE: SDK modules that are standalone go modules _should not_ adopt semantic versioning until the concerns described in +[ADR 054: Module Semantic Versioning](./adr-054-semver-compatible-modules.md) are +addressed. The short-term solution for this issue was left somewhat unresolved. However, the easiest tactic is +likely to use a standalone API go module and follow the guidelines described in this comment: https://github.com/cosmos/cosmos-sdk/pull/11802#issuecomment-1406815181. For the time-being, it is recommended that +Cosmos SDK modules continue to follow tried and true [0-based versioning](https://0ver.org) until an officially +recommended solution is provided. This section of the ADR will be updated when that happens and for now, this section +should be considered as a design recommendation for future adoption of semantic versioning. + ## Consequences ### Backwards Compatibility @@ -337,4 +366,4 @@ light of code generation. It may be better to do this type registration with a D * https://github.com/google/wire * https://pkg.go.dev/github.com/cosmos/cosmos-sdk/container * https://github.com/cosmos/cosmos-sdk/pull/11802 -* [ADR 061](./adr-061-core-module-api.md) +* [ADR 063: Core Module API](./adr-063-core-module-api.md) diff --git a/docs/architecture/adr-063-core-module-api.md b/docs/architecture/adr-063-core-module-api.md index e3dcaa2b12..d5e0d06b7c 100644 --- a/docs/architecture/adr-063-core-module-api.md +++ b/docs/architecture/adr-063-core-module-api.md @@ -444,6 +444,51 @@ should check this compatibility version and return an error if the current `Runt than the version of the core API that this runtime version can support. When new features are adding to the `core` module API that runtime modules are required to support, this version should be incremented. +### Runtime Modules + +The initial `runtime` module will simply be created within the existing `github.com/cosmos/cosmos-sdk` go module +under the `runtime` package. This module will be a small wrapper around the existing `BaseApp`, `sdk.Context` and +module manager and follow the Cosmos SDK's existing [0-based versioning](https://0ver.org). To move to semantic +versioning as well as runtime modularity, new officially supported runtime modules will be created under the +`cosmossdk.io/runtime` prefix. For each supported consensus engine a semantically-versioned go module should be created +with a runtime implementation for that consensus engine. For example: +- `cosmossdk.io/runtime/comet` +- `cosmossdk.io/runtime/comet/v2` +- `cosmossdk.io/runtime/rollkit` +- etc. + +These runtime modules should attempt to be semantically versioned even if the underlying consensus engine is not. Also, +because a runtime module is also a first class Cosmos SDK module, it should have a protobuf module config type. +A new semantically versioned module config type should be created for each of these runtime module such that there is a +1:1 correspondence between the go module and module config type. This is the same practice should be followed for every +semantically versioned Cosmos SDK module as described in [ADR 057: App Wiring](./adr-057-app-wiring.md). + +Currently, `github.com/cosmos/cosmos-sdk/runtime` uses the protobuf config type `cosmos.app.runtime.v1alpha1.Module`. +When we have a standalone v1 comet runtime, we should use a dedicated protobuf module config type such as +`cosmos.runtime.comet.v1.Module1`. When we release v2 of the comet runtime (`cosmossdk.io/runtime/comet/v2`) we should +have a corresponding `cosmos.runtime.comet.v2.Module` protobuf type. + +In order to make it easier to support different consensus engines that support the same core module functionality as +described in this ADR, a common go module should be created with shared runtime components. The easiest runtime components +to share initially are probably the message/query router, inter-module client, service register, and event router. +This common runtime module should be created initially as the `cosmossdk.io/runtime/common` go module. + +When this new architecture has been implemented, the main dependency for a Cosmos SDK module would be +`cosmossdk.io/core` and that module should be able to be used with any supported consensus engine (to the extent +that it does not explicitly depend on consensus engine specific functionality such as Comet's block headers). An +app developer would then be able to choose which consensus engine they want to use by importing the corresponding +runtime module. The current `BaseApp` would be refactored into the `cosmossdk.io/runtime/comet` module, the router +infrastructure in `baseapp/` would be refactored into `cosmossdk.io/runtime/common` and support ADR 033, and eventually +a dependency on `github.com/cosmos/cosmos-sdk` would no longer be required. + +In short, modules would depend primarily on `cosmossdk.io/core`, and each `cosmossdk.io/runtime/{consensus-engine}` +would implement the `cosmossdk.io/core` functionality for that consensus engine. + +On additional piece that would need to be resolved as part of this architecture is how runtimes relate to the server. +Likely it would make sense to modularize the current server architecture so that it can be used with any runtime even +if that is based on a consensus engine besides Comet. This means that eventually the Comet runtime would need to +encapsulate the logic for starting Comet and the ABCI app. + ### Testing A mock implementation of all services should be provided in core to allow for unit testing of modules