feat: introduce cosmos.app proto files as foundation for app wiring w…

…ork (cosmos#11074)

## Description

This PR introduces protobuf definitions for the upcoming app wiring work and forms the foundation for a new app module to host the declarative "app config".



---

### Author Checklist

*All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.*

I have...

- [ ] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] added `!` to the type prefix if API or client breaking change
- [ ] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting))
- [ ] provided a link to the relevant issue or specification
- [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules)
- [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing)
- [ ] added a changelog entry to `CHANGELOG.md`
- [ ] included comments for [documenting Go code](https://blog.golang.org/godoc)
- [ ] updated the relevant documentation or specification
- [ ] reviewed "Files changed" and left comments if necessary
- [ ] confirmed all CI checks have passed

### Reviewers Checklist

*All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.*

I have...

- [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] confirmed `!` in the type prefix if API or client breaking change
- [ ] confirmed all author checklist items have been addressed 
- [ ] reviewed state machine logic
- [ ] reviewed API design and naming
- [ ] reviewed documentation is accurate
- [ ] reviewed tests and test coverage
- [ ] manually tested (if applicable)

proto/cosmos/app/module/v1alpha1/module.proto

@@ -0,0 +1,15 @@
+syntax = "proto3";
+
+package cosmos.app.module.v1alpha1;
+
+import "cosmos/app/v1alpha1/module.proto";
+
+// Module is the module config object for the cosmos.app v1 app module.
+message Module {
+  option (cosmos.app.v1alpha1.is_module) = {
+    go_import: "github.com/cosmos/cosmos-sdk/app"
+    use_package: {
+      name: "cosmos.app.v1alpha1"
+    }
+  };
+}

proto/cosmos/app/v1alpha1/config.proto

@@ -0,0 +1,36 @@
+syntax = "proto3";
+
+package cosmos.app.v1alpha1;
+
+import "google/protobuf/any.proto";
+
+// Config represents the configuration for a Cosmos SDK ABCI app.
+// It is intended that all state machine logic including the version of
+// baseapp and tx handlers (and possibly even Tendermint) that an app needs
+// can be described in a config object. For compatibility, the framework should
+// allow a mixture of declarative and imperative app wiring, however, apps
+// that strive for the maximum ease of maintainability should be able to describe
+// their state machine with a config object alone.
+message Config {
+  // modules are the module configurations for the app.
+  repeated ModuleConfig modules = 1;
+}
+
+// ModuleConfig is a module configuration for an app.
+message ModuleConfig {
+  // name is the unique name of the module within the app. It should be a name
+  // that persists between different versions of a module so that modules
+  // can be smoothly upgraded to new versions.
+  //
+  // For example, for the module cosmos.bank.module.v1.Module, we may chose
+  // to simply name the module "bank" in the app. When we upgrade to
+  // cosmos.bank.module.v2.Module, the app-specific name "bank" stays the same
+  // and the framework knows that the v2 module should receive all the same state
+  // that the v1 module had. Note: modules should provide info on which versions
+  // they can migrate from in the ModuleDescriptor.can_migration_from field.
+  string name = 1;
+
+  // config is the config object for the module. Module config messages should
+  // define a ModuleDescriptor using the cosmos.app.v1alpha1.is_module extension.
+  google.protobuf.Any config = 2;
+}

proto/cosmos/app/v1alpha1/module.proto

@@ -0,0 +1,93 @@
+syntax = "proto3";
+
+package cosmos.app.v1alpha1;
+
+import "google/protobuf/descriptor.proto";
+
+extend google.protobuf.MessageOptions {
+  // is_module indicates that this proto type is a config object for an app module
+  // and optionally provides other descriptive information about the module.
+  // It is recommended that a new module config object and go module is versioned
+  // for every state machine breaking version of a module. The recommended
+  // pattern for doing this is to put module config objects in a separate proto
+  // package from the API they expose. Ex: the cosmos.group.v1 API would be
+  // exposed by module configs cosmos.group.module.v1, cosmos.group.module.v2, etc.
+  ModuleDescriptor is_module = 57193479;
+}
+
+// ModuleDescriptor describes an app module.
+message ModuleDescriptor {
+  // go_import names the package that should be imported by an app to load the
+  // module in the runtime module registry. Either go_import must be defined here
+  // or the go_package option must be defined at the file level to indicate
+  // to users where to location the module implementation. go_import takes
+  // precedence over go_package when both are defined.
+  string go_import = 1;
+
+  // use_package refers to a protobuf package that this module
+  // uses and exposes to the world. In an app, only one module should "use"
+  // or own a single protobuf package. It is assumed that the module uses
+  // all of the .proto files in a single package.
+  repeated PackageReference use_package = 2;
+
+  // can_migrate_from defines which module versions this module can migrate
+  // state from. The framework will check that one module version is able to
+  // migrate from a previous module version before attempting to update its
+  // config. It is assumed that modules can transitively migrate from earlier
+  // versions. For instance if v3 declares it can migrate from v2, and v2
+  // declares it can migrate from v1, the framework knows how to migrate
+  // from v1 to v3, assuming all 3 module versions are registered at runtime.
+  repeated MigrateFromInfo can_migrate_from = 3;
+}
+
+// PackageReference is a reference to a protobuf package used by a module.
+message PackageReference {
+  // name is the fully-qualified name of the package.
+  string name = 1;
+
+  // revision is the optional revision of the package that is being used.
+  // Protobuf packages used in Cosmos should generally have a major version
+  // as the last part of the package name, ex. foo.bar.baz.v1.
+  // The revision of a package can be thought of as the minor version of a
+  // package which has additional backwards compatible definitions that weren't
+  // present in a previous version.
+  //
+  // A package should indicate its revision with a source code comment
+  // above the package declaration in one of its fields containing the
+  // test "Revision N" where N is an integer revision. All packages start
+  // at revision 0 the first time they are released in a module.
+  //
+  // When a new version of a module is released and items are added to existing
+  // .proto files, these definitions should contain comments of the form
+  // "Since Revision N" where N is an integer revision.
+  //
+  // When the module runtime starts up, it will check the pinned proto
+  // image and panic if there are runtime protobuf definitions that are not
+  // in the pinned descriptor which do not have
+  // a "Since Revision N" comment or have a "Since Revision N" comment where
+  // N is <= to the revision specified here. This indicates that the protobuf
+  // files have been updated, but the pinned file descriptor hasn't.
+  //
+  // If there are items in the pinned file descriptor with a revision
+  // greater than the value indicated here, this will also cause a panic
+  // as it may mean that the pinned descriptor for a legacy module has been
+  // improperly updated or that there is some other versioning discrepancy.
+  // Runtime protobuf definitions will also be checked for compatibility
+  // with pinned file descriptors to make sure there are no incompatible changes.
+  //
+  // This behavior ensures that:
+  // * pinned proto images are up-to-date
+  // * protobuf files are carefully annotated with revision comments which
+  //   are important good client UX
+  // * protobuf files are changed in backwards and forwards compatible ways
+  uint32 revision = 2;
+}
+
+// MigrateFromInfo is information on a module version that a newer module
+// can migrate from.
+message MigrateFromInfo {
+
+  // module is the fully-qualified protobuf name of the module config object
+  // for the previous module version, ex: "cosmos.group.module.v1.Module".
+  string module = 1;
+}

proto/cosmos/app/v1alpha1/query.proto

@@ -0,0 +1,22 @@
+syntax = "proto3";
+
+package cosmos.app.v1alpha1;
+
+import "cosmos/app/v1alpha1/config.proto";
+
+// Query is the app module query service.
+service Query {
+
+  // Config returns the current app config.
+  rpc Config(QueryConfigRequest) returns (QueryConfigResponse) {}
+}
+
+// QueryConfigRequest is the Query/Config request type.
+message QueryConfigRequest {}
+
+// QueryConfigRequest is the Query/Config response type.
+message QueryConfigResponse {
+
+  // config is the current app config.
+  Config config = 1;
+}

scripts/protocgen.sh

@@ -18,7 +18,7 @@ cd proto
 proto_dirs=$(find ./cosmos -path -prune -o -name '*.proto' -print0 | xargs -0 -n1 dirname | sort | uniq)
 for dir in $proto_dirs; do
   for file in $(find "${dir}" -maxdepth 1 -name '*.proto'); do
-    if grep go_package $file &> /dev/null ; then
+    if grep "option go_package" $file &> /dev/null ; then
       buf generate --template buf.gen.gogo.yaml $file
     fi
   done