c00cedb142
## 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)
94 lines
4.5 KiB
Protocol Buffer
94 lines
4.5 KiB
Protocol Buffer
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;
|
|
}
|