92 lines
4.4 KiB
Protocol Buffer
92 lines
4.4 KiB
Protocol Buffer
|
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;
|
||
|
|
}
|