diff --git a/orm/go.mod b/orm/go.mod new file mode 100644 index 0000000000..84ea35c9d2 --- /dev/null +++ b/orm/go.mod @@ -0,0 +1,3 @@ +module github.com/cosmos/cosmos-sdk/orm + +go 1.17 diff --git a/proto/cosmos/orm/v1alpha1/orm.proto b/proto/cosmos/orm/v1alpha1/orm.proto new file mode 100644 index 0000000000..52f06fe260 --- /dev/null +++ b/proto/cosmos/orm/v1alpha1/orm.proto @@ -0,0 +1,116 @@ +syntax = "proto3"; + +package cosmos.orm.v1alpha1; + +import "google/protobuf/descriptor.proto"; + +option go_package = "github.com/cosmos/cosmos-sdk/orm/types/ormpb"; + +extend google.protobuf.MessageOptions { + + // table specifies that this message will be used as an ORM table. It cannot + // be used together with the singleton option. + TableDescriptor table = 104503790; + + // singleton specifies that this message will be used as an ORM singleton. It cannot + // be used together with the table option. + SingletonDescriptor singleton = 104503791; +} + +// TableDescriptor describes an ORM table. +message TableDescriptor { + + // primary_key defines the primary key for the table. + PrimaryKeyDescriptor primary_key = 1; + + // index defines one or more secondary indexes. + repeated SecondaryIndexDescriptor index = 2; + + // id is a non-zero integer ID that must be unique within the + // tables and singletons in this file. It may be deprecated in the future when this + // can be auto-generated. + uint32 id = 3; +} + +// PrimaryKeyDescriptor describes a table primary key. +message PrimaryKeyDescriptor { + + // fields is a comma-separated list of fields in the primary key. Spaces are + // not allowed. Supported field types, their encodings, and any applicable constraints + // are described below. + // - uint32, uint64 are encoded as big-endian fixed width bytes and support + // sorted iteration. + // - string's are encoded as raw bytes in terminal key segments and null-terminated + // in non-terminal segments. Null characters are thus forbidden in strings. + // string fields support sorted iteration. + // - bytes are encoded as raw bytes in terminal segments and length-prefixed + // with a single byte in non-terminal segments. Because of this byte arrays + // longer than 255 bytes cannot be used in keys and bytes fields should not + // be assumed to be lexically sorted. + // - int32, sint32, int64, sint64 are encoding as fixed width bytes with + // an encoding that enables sorted iteration. + // - google.protobuf.Timestamp and google.protobuf.Duration are encoded + // as 12 bytes using an encoding that enables sorted iteration. + // - enum fields are encoded using varint encoding and do not support sorted + // iteration. + // - bool fields are encoded as a single byte 0 or 1. + // + // All other fields types are unsupported in keys including repeated and + // oneof fields. + // + // Primary keys are prefixed by the varint encoded table id and the byte 0x0 + // plus any additional prefix specified by the schema. + string fields = 1; + + // auto_increment specifies that the primary key is generated by an + // auto-incrementing integer. If this is set to true fields must only + // contain one field of that is of type uint64. + bool auto_increment = 2; + + // references specifies that this primary key references the primary key + // of another table. See the documentation for the SecondaryIndexDescriptor.references + // field for more details. An additional constraint placed on primary keys + // which reference another table is that those references cannot be circular. + string references = 3; +} + +// PrimaryKeyDescriptor describes a table secondary index. +message SecondaryIndexDescriptor { + + // fields is a comma-separated list of fields in the index. The supported + // field types are the same as those for PrimaryKeyDescriptor.fields. + // Index keys are prefixed by the varint encoded table id and the varint + // encoded index id plus any additional prefix specified by the schema. + // + // In addition the the field segments, non-unique index keys are suffixed with + // any additional primary key fields not present in the index fields so that the + // primary key can be reconstructed. Unique indexes instead of being suffixed + // store the remaining primary key fields in the value.. + string fields = 1; + + // id is a non-zero integer ID that must be unique within the indexes for this + // table. It may be deprecated in the future when this can be auto-generated. + uint32 id = 2; + + // unique specifies that this an unique index. + bool unique = 3; + + // references specifies that this index references another table defined in the same + // proto file. Currently references are not support to tables with composite + // primary keys, therefore fields must reference one field and its type must + // be the same type as the primary key field of the referenced table. + // References to tables in defined by different proto files are not supported + // to avoid tight coupling of dependencies. Beyond validating that the reference + // is valid key constraints are currently not enforced, but references should + // be used by clients to perform automatic joins. + string references = 4; +} + +// TableDescriptor describes an ORM singleton table which has at most one instance. +message SingletonDescriptor { + + // id is a non-zero integer ID that must be unique within the + // tables and singletons in this file. It may be deprecated in the future when this + // can be auto-generated. + uint32 id = 1; +} \ No newline at end of file diff --git a/proto/cosmos/orm/v1alpha1/schema.proto b/proto/cosmos/orm/v1alpha1/schema.proto new file mode 100644 index 0000000000..612043332e --- /dev/null +++ b/proto/cosmos/orm/v1alpha1/schema.proto @@ -0,0 +1,45 @@ +syntax = "proto3"; + +package cosmos.orm.v1alpha1; + +import "google/protobuf/descriptor.proto"; + +option go_package = "github.com/cosmos/cosmos-sdk/orm/types/ormpb"; + +// SchemaDescriptor describes an ORM schema that contains all the information +// needed for a dynamic client to decode the stored data. +message SchemaDescriptor { + + // files is the set of all FileDescriptorProto's needed to decode the stored data. + // A schema imposes the constraint that every file and every table within that + // schema have at most one instance in the store. + google.protobuf.FileDescriptorSet files = 1; + + // modules is the set of modules in the schema. + repeated ModuleEntry modules = 2; + + // ModuleEntry describes a single module's schema. + message ModuleEntry { + // name is the name of the module. In the multi-store model this name is + // used to locate the module's store. + string name = 1; + + // prefix is an optional prefix that precedes all keys in this module's + // store. + bytes prefix = 2; + + // files describes the schema files used in this module. + repeated FileEntry files = 3; + } + + // FileEntry describes an ORM file used in a module. + message FileEntry { + // id is a prefix that will be varint encoded and prepended to all the + // table keys specified in the file's tables. + uint32 id = 1; + + // file_name is the name of a file in the FileDescriptor set that contains + // table definitions. + string file_name = 2; + } +}