syntax = "proto3"; package cosmos.app.v1alpha1; import "google/protobuf/descriptor.proto"; extend google.protobuf.MessageOptions { // 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 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. It is required to make debugging // of configuration errors easier for users. 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 files containing the // text "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; }