feat: init ORM proto (#10579)

* feat: init ORM proto

* docs

* package fix

* add SchemaDescriptor, unique, references and docs

* move schema

* update docs, add go.mod

orm/go.mod

@@ -0,0 +1,3 @@
+module github.com/cosmos/cosmos-sdk/orm
+
+go 1.17

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;
+}

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;
+  }
+}