docs: improve proto vesting docs about time attributes (#15474)

## Description

Added a little bit more comments to note about the meaning / type of the numeric time values.

When I'm creating the vesting accounts, I always have to  double check it, and end up looking at the code.
This commit is contained in:
Robert Zaremba 2023-03-20 17:40:19 +01:00 committed by GitHub
parent a8dceddad9
commit 5612bb815b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 97 additions and 82 deletions

View File

@ -3124,7 +3124,7 @@ type MsgCreateVestingAccount struct {
FromAddress string `protobuf:"bytes,1,opt,name=from_address,json=fromAddress,proto3" json:"from_address,omitempty"`
ToAddress string `protobuf:"bytes,2,opt,name=to_address,json=toAddress,proto3" json:"to_address,omitempty"`
Amount []*v1beta1.Coin `protobuf:"bytes,3,rep,name=amount,proto3" json:"amount,omitempty"`
// end of vesting as unix time
// end of vesting as unix time (in seconds).
EndTime int64 `protobuf:"varint,4,opt,name=end_time,json=endTime,proto3" json:"end_time,omitempty"`
Delayed bool `protobuf:"varint,5,opt,name=delayed,proto3" json:"delayed,omitempty"`
}
@ -3306,7 +3306,7 @@ type MsgCreatePeriodicVestingAccount struct {
FromAddress string `protobuf:"bytes,1,opt,name=from_address,json=fromAddress,proto3" json:"from_address,omitempty"`
ToAddress string `protobuf:"bytes,2,opt,name=to_address,json=toAddress,proto3" json:"to_address,omitempty"`
// start of vesting as unix time
// start of vesting as unix time (in seconds).
StartTime int64 `protobuf:"varint,3,opt,name=start_time,json=startTime,proto3" json:"start_time,omitempty"`
VestingPeriods []*Period `protobuf:"bytes,4,rep,name=vesting_periods,json=vestingPeriods,proto3" json:"vesting_periods,omitempty"`
}

View File

@ -3453,7 +3453,8 @@ type BaseVestingAccount struct {
OriginalVesting []*v1beta1.Coin `protobuf:"bytes,2,rep,name=original_vesting,json=originalVesting,proto3" json:"original_vesting,omitempty"`
DelegatedFree []*v1beta1.Coin `protobuf:"bytes,3,rep,name=delegated_free,json=delegatedFree,proto3" json:"delegated_free,omitempty"`
DelegatedVesting []*v1beta1.Coin `protobuf:"bytes,4,rep,name=delegated_vesting,json=delegatedVesting,proto3" json:"delegated_vesting,omitempty"`
EndTime int64 `protobuf:"varint,5,opt,name=end_time,json=endTime,proto3" json:"end_time,omitempty"`
// Vesting end time, as unix timestamp (in seconds).
EndTime int64 `protobuf:"varint,5,opt,name=end_time,json=endTime,proto3" json:"end_time,omitempty"`
}
func (x *BaseVestingAccount) Reset() {
@ -3519,7 +3520,8 @@ type ContinuousVestingAccount struct {
unknownFields protoimpl.UnknownFields
BaseVestingAccount *BaseVestingAccount `protobuf:"bytes,1,opt,name=base_vesting_account,json=baseVestingAccount,proto3" json:"base_vesting_account,omitempty"`
StartTime int64 `protobuf:"varint,2,opt,name=start_time,json=startTime,proto3" json:"start_time,omitempty"`
// Vesting start time, as unix timestamp (in seconds).
StartTime int64 `protobuf:"varint,2,opt,name=start_time,json=startTime,proto3" json:"start_time,omitempty"`
}
func (x *ContinuousVestingAccount) Reset() {
@ -3600,6 +3602,7 @@ type Period struct {
sizeCache protoimpl.SizeCache
unknownFields protoimpl.UnknownFields
// Period duration in seconds.
Length int64 `protobuf:"varint,1,opt,name=length,proto3" json:"length,omitempty"`
Amount []*v1beta1.Coin `protobuf:"bytes,2,rep,name=amount,proto3" json:"amount,omitempty"`
}

View File

@ -33,9 +33,9 @@ message MsgRequest {
repeated bool bools = 21;
repeated uint32 uints = 22;
repeated string strings = 23;
repeated testpb.Enum enums = 24;
repeated google.protobuf.Duration durations = 25;
repeated testpb.AMessage some_messages = 26;
repeated testpb.Enum enums = 24;
repeated google.protobuf.Duration durations = 25;
repeated testpb.AMessage some_messages = 26;
int32 positional1 = 27;
string positional2 = 28;
@ -46,8 +46,6 @@ message MsgRequest {
bool hidden_bool = 32;
}
message MsgResponse {
MsgRequest request = 1;
}

View File

@ -14,31 +14,37 @@ message Module {
go_import: "github.com/cosmos/orm/model/ormdb"
};
option (cosmos.orm.v1alpha1.module_schema) = {
schema_file: {
id: 1
proto_file_name: "testpb/bank.proto"
}
schema_file: {id: 1 proto_file_name: "testpb/bank.proto"}
};
}
message Balance {
option (cosmos.orm.v1.table) = {
id: 1;
primary_key: {fields: "address,denom"}
index: {id: 1 fields: "denom"}
};
primary_key: {
fields:
"address,denom"
}
index: {
id:
1 fields: "denom"
}
};
string address = 1;
string denom = 2;
uint64 amount = 3;
string address = 1;
string denom = 2;
uint64 amount = 3;
}
message Supply {
option (cosmos.orm.v1.table) = {
id: 2;
primary_key: {fields: "denom"}
};
string denom = 1;
uint64 amount = 2;
primary_key: {
fields:
"denom"
}
};
string denom = 1;
uint64 amount = 2;
}

View File

@ -42,7 +42,7 @@ message ListBalanceRequest {
// denom specifies the value of the Denom index key to use in the query.
Denom denom = 2;
}
message AddressDenom {
// address is the value of the address field in the index.
// It can be omitted to query for all valid values of that field in this segment of the index.
@ -51,14 +51,14 @@ message ListBalanceRequest {
// It can be omitted to query for all valid values of that field in this segment of the index.
optional string denom = 2;
}
message Denom {
// denom is the value of the denom field in the index.
// It can be omitted to query for all valid values of that field in this segment of the index.
optional string denom = 1;
}
}
// query specifies the type of query - either a prefix or range query.
oneof query {
// prefix_query specifies the index key value to use for the prefix query.
@ -68,7 +68,7 @@ message ListBalanceRequest {
}
// pagination specifies optional pagination parameters.
cosmos.base.query.v1beta1.PageRequest pagination = 3;
// RangeQuery specifies the from/to index keys for a range query.
message RangeQuery {
// from is the index key to use for the start of the range query.
@ -110,14 +110,14 @@ message ListSupplyRequest {
// denom specifies the value of the Denom index key to use in the query.
Denom denom = 1;
}
message Denom {
// denom is the value of the denom field in the index.
// It can be omitted to query for all valid values of that field in this segment of the index.
optional string denom = 1;
}
}
// query specifies the type of query - either a prefix or range query.
oneof query {
// prefix_query specifies the index key value to use for the prefix query.
@ -127,7 +127,7 @@ message ListSupplyRequest {
}
// pagination specifies optional pagination parameters.
cosmos.base.query.v1beta1.PageRequest pagination = 3;
// RangeQuery specifies the from/to index keys for a range query.
message RangeQuery {
// from is the index key to use for the start of the range query.
@ -147,4 +147,3 @@ message ListSupplyResponse {
// pagination is the pagination response.
cosmos.base.query.v1beta1.PageResponse pagination = 2;
}

View File

@ -15,13 +15,17 @@ service TestSchemaQueryService {
// ListExampleTable queries the ExampleTable table using prefix and range queries against defined indexes.
rpc ListExampleTable(ListExampleTableRequest) returns (ListExampleTableResponse) {}
// Get queries the ExampleAutoIncrementTable table by its primary key.
rpc GetExampleAutoIncrementTable(GetExampleAutoIncrementTableRequest) returns (GetExampleAutoIncrementTableResponse) {}
rpc GetExampleAutoIncrementTable(GetExampleAutoIncrementTableRequest) returns (GetExampleAutoIncrementTableResponse) {
}
// GetExampleAutoIncrementTableByX queries the ExampleAutoIncrementTable table by its X index
rpc GetExampleAutoIncrementTableByX(GetExampleAutoIncrementTableByXRequest) returns (GetExampleAutoIncrementTableByXResponse) {}
// ListExampleAutoIncrementTable queries the ExampleAutoIncrementTable table using prefix and range queries against defined indexes.
rpc ListExampleAutoIncrementTable(ListExampleAutoIncrementTableRequest) returns (ListExampleAutoIncrementTableResponse) {}
rpc GetExampleAutoIncrementTableByX(GetExampleAutoIncrementTableByXRequest)
returns (GetExampleAutoIncrementTableByXResponse) {}
// ListExampleAutoIncrementTable queries the ExampleAutoIncrementTable table using prefix and range queries against
// defined indexes.
rpc ListExampleAutoIncrementTable(ListExampleAutoIncrementTableRequest)
returns (ListExampleAutoIncrementTableResponse) {}
// GetExampleSingleton queries the ExampleSingleton singleton.
rpc GetExampleSingleton (GetExampleSingletonRequest) returns (GetExampleSingletonResponse) {}
rpc GetExampleSingleton(GetExampleSingletonRequest) returns (GetExampleSingletonResponse) {}
// Get queries the ExampleTimestamp table by its primary key.
rpc GetExampleTimestamp(GetExampleTimestampRequest) returns (GetExampleTimestampResponse) {}
// ListExampleTimestamp queries the ExampleTimestamp table using prefix and range queries against defined indexes.
@ -34,7 +38,8 @@ service TestSchemaQueryService {
rpc ListSimpleExample(ListSimpleExampleRequest) returns (ListSimpleExampleResponse) {}
// Get queries the ExampleAutoIncFieldName table by its primary key.
rpc GetExampleAutoIncFieldName(GetExampleAutoIncFieldNameRequest) returns (GetExampleAutoIncFieldNameResponse) {}
// ListExampleAutoIncFieldName queries the ExampleAutoIncFieldName table using prefix and range queries against defined indexes.
// ListExampleAutoIncFieldName queries the ExampleAutoIncFieldName table using prefix and range queries against
// defined indexes.
rpc ListExampleAutoIncFieldName(ListExampleAutoIncFieldNameRequest) returns (ListExampleAutoIncFieldNameResponse) {}
}
@ -80,7 +85,7 @@ message ListExampleTableRequest {
// bz_str specifies the value of the BzStr index key to use in the query.
BzStr bz_str = 4;
}
message U32I64Str {
// u32 is the value of the u32 field in the index.
// It can be omitted to query for all valid values of that field in this segment of the index.
@ -92,7 +97,7 @@ message ListExampleTableRequest {
// It can be omitted to query for all valid values of that field in this segment of the index.
optional string str = 3;
}
message U64Str {
// u64 is the value of the u64 field in the index.
// It can be omitted to query for all valid values of that field in this segment of the index.
@ -101,7 +106,7 @@ message ListExampleTableRequest {
// It can be omitted to query for all valid values of that field in this segment of the index.
optional string str = 2;
}
message StrU32 {
// str is the value of the str field in the index.
// It can be omitted to query for all valid values of that field in this segment of the index.
@ -110,7 +115,7 @@ message ListExampleTableRequest {
// It can be omitted to query for all valid values of that field in this segment of the index.
optional uint32 u32 = 2;
}
message BzStr {
// bz is the value of the bz field in the index.
// It can be omitted to query for all valid values of that field in this segment of the index.
@ -120,7 +125,7 @@ message ListExampleTableRequest {
optional string str = 2;
}
}
// query specifies the type of query - either a prefix or range query.
oneof query {
// prefix_query specifies the index key value to use for the prefix query.
@ -130,7 +135,7 @@ message ListExampleTableRequest {
}
// pagination specifies optional pagination parameters.
cosmos.base.query.v1beta1.PageRequest pagination = 3;
// RangeQuery specifies the from/to index keys for a range query.
message RangeQuery {
// from is the index key to use for the start of the range query.
@ -184,20 +189,20 @@ message ListExampleAutoIncrementTableRequest {
// x specifies the value of the X index key to use in the query.
X x = 2;
}
message Id {
// id is the value of the id field in the index.
// It can be omitted to query for all valid values of that field in this segment of the index.
optional uint64 id = 1;
}
message X {
// x is the value of the x field in the index.
// It can be omitted to query for all valid values of that field in this segment of the index.
optional string x = 1;
}
}
// query specifies the type of query - either a prefix or range query.
oneof query {
// prefix_query specifies the index key value to use for the prefix query.
@ -207,7 +212,7 @@ message ListExampleAutoIncrementTableRequest {
}
// pagination specifies optional pagination parameters.
cosmos.base.query.v1beta1.PageRequest pagination = 3;
// RangeQuery specifies the from/to index keys for a range query.
message RangeQuery {
// from is the index key to use for the start of the range query.
@ -229,8 +234,7 @@ message ListExampleAutoIncrementTableResponse {
}
// GetExampleSingletonRequest is the TestSchemaQuery/GetExampleSingletonRequest request type.
message GetExampleSingletonRequest {
}
message GetExampleSingletonRequest {}
// GetExampleSingletonResponse is the TestSchemaQuery/GetExampleSingletonResponse request type.
message GetExampleSingletonResponse {
@ -260,20 +264,20 @@ message ListExampleTimestampRequest {
// ts specifies the value of the Ts index key to use in the query.
Ts ts = 2;
}
message Id {
// id is the value of the id field in the index.
// It can be omitted to query for all valid values of that field in this segment of the index.
optional uint64 id = 1;
}
message Ts {
// ts is the value of the ts field in the index.
// It can be omitted to query for all valid values of that field in this segment of the index.
optional google.protobuf.Timestamp ts = 1;
}
}
// query specifies the type of query - either a prefix or range query.
oneof query {
// prefix_query specifies the index key value to use for the prefix query.
@ -283,7 +287,7 @@ message ListExampleTimestampRequest {
}
// pagination specifies optional pagination parameters.
cosmos.base.query.v1beta1.PageRequest pagination = 3;
// RangeQuery specifies the from/to index keys for a range query.
message RangeQuery {
// from is the index key to use for the start of the range query.
@ -337,20 +341,20 @@ message ListSimpleExampleRequest {
// unique specifies the value of the Unique index key to use in the query.
Unique unique = 2;
}
message Name {
// name is the value of the name field in the index.
// It can be omitted to query for all valid values of that field in this segment of the index.
optional string name = 1;
}
message Unique {
// unique is the value of the unique field in the index.
// It can be omitted to query for all valid values of that field in this segment of the index.
optional string unique = 1;
}
}
// query specifies the type of query - either a prefix or range query.
oneof query {
// prefix_query specifies the index key value to use for the prefix query.
@ -360,7 +364,7 @@ message ListSimpleExampleRequest {
}
// pagination specifies optional pagination parameters.
cosmos.base.query.v1beta1.PageRequest pagination = 3;
// RangeQuery specifies the from/to index keys for a range query.
message RangeQuery {
// from is the index key to use for the start of the range query.
@ -402,14 +406,14 @@ message ListExampleAutoIncFieldNameRequest {
// foo specifies the value of the Foo index key to use in the query.
Foo foo = 1;
}
message Foo {
// foo is the value of the foo field in the index.
// It can be omitted to query for all valid values of that field in this segment of the index.
optional uint64 foo = 1;
}
}
// query specifies the type of query - either a prefix or range query.
oneof query {
// prefix_query specifies the index key value to use for the prefix query.
@ -419,7 +423,7 @@ message ListExampleAutoIncFieldNameRequest {
}
// pagination specifies optional pagination parameters.
cosmos.base.query.v1beta1.PageRequest pagination = 3;
// RangeQuery specifies the from/to index keys for a range query.
message RangeQuery {
// from is the index key to use for the start of the range query.
@ -439,4 +443,3 @@ message ListExampleAutoIncFieldNameResponse {
// pagination is the pagination response.
cosmos.base.query.v1beta1.PageResponse pagination = 2;
}

View File

@ -46,7 +46,7 @@ message MsgCreateVestingAccount {
(gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"
];
// end of vesting as unix time
// end of vesting as unix time (in seconds).
int64 end_time = 4;
bool delayed = 5;
}
@ -90,7 +90,7 @@ message MsgCreatePeriodicVestingAccount {
string from_address = 1;
string to_address = 2;
// start of vesting as unix time
// start of vesting as unix time (in seconds).
int64 start_time = 3;
repeated Period vesting_periods = 4 [(gogoproto.nullable) = false, (amino.dont_omitempty) = true];
}

View File

@ -33,6 +33,7 @@ message BaseVestingAccount {
(amino.encoding) = "legacy_coins",
(gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"
];
// Vesting end time, as unix timestamp (in seconds).
int64 end_time = 5;
}
@ -43,7 +44,8 @@ message ContinuousVestingAccount {
option (gogoproto.goproto_getters) = false;
BaseVestingAccount base_vesting_account = 1 [(gogoproto.embed) = true];
int64 start_time = 2;
// Vesting start time, as unix timestamp (in seconds).
int64 start_time = 2;
}
// DelayedVestingAccount implements the VestingAccount interface. It vests all
@ -58,6 +60,7 @@ message DelayedVestingAccount {
// Period defines a length of time and amount of coins that will vest.
message Period {
// Period duration in seconds.
int64 length = 1;
repeated cosmos.base.v1beta1.Coin amount = 2 [
(gogoproto.nullable) = false,

View File

@ -41,10 +41,10 @@ message TestNullableFields {
message IntAsString {
string int_as_string = 1 [
(cosmos_proto.scalar) = "cosmos.Int",
(cosmos_proto.scalar) = "cosmos.Int",
(gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
(amino.dont_omitempty) = true,
(gogoproto.nullable) = false
(gogoproto.nullable) = false
];
}

View File

@ -39,7 +39,7 @@ type MsgCreateVestingAccount struct {
FromAddress string `protobuf:"bytes,1,opt,name=from_address,json=fromAddress,proto3" json:"from_address,omitempty"`
ToAddress string `protobuf:"bytes,2,opt,name=to_address,json=toAddress,proto3" json:"to_address,omitempty"`
Amount github_com_cosmos_cosmos_sdk_types.Coins `protobuf:"bytes,3,rep,name=amount,proto3,castrepeated=github.com/cosmos/cosmos-sdk/types.Coins" json:"amount"`
// end of vesting as unix time
// end of vesting as unix time (in seconds).
EndTime int64 `protobuf:"varint,4,opt,name=end_time,json=endTime,proto3" json:"end_time,omitempty"`
Delayed bool `protobuf:"varint,5,opt,name=delayed,proto3" json:"delayed,omitempty"`
}
@ -261,7 +261,7 @@ var xxx_messageInfo_MsgCreatePermanentLockedAccountResponse proto.InternalMessag
type MsgCreatePeriodicVestingAccount struct {
FromAddress string `protobuf:"bytes,1,opt,name=from_address,json=fromAddress,proto3" json:"from_address,omitempty"`
ToAddress string `protobuf:"bytes,2,opt,name=to_address,json=toAddress,proto3" json:"to_address,omitempty"`
// start of vesting as unix time
// start of vesting as unix time (in seconds).
StartTime int64 `protobuf:"varint,3,opt,name=start_time,json=startTime,proto3" json:"start_time,omitempty"`
VestingPeriods []Period `protobuf:"bytes,4,rep,name=vesting_periods,json=vestingPeriods,proto3" json:"vesting_periods"`
}

View File

@ -34,7 +34,8 @@ type BaseVestingAccount struct {
OriginalVesting github_com_cosmos_cosmos_sdk_types.Coins `protobuf:"bytes,2,rep,name=original_vesting,json=originalVesting,proto3,castrepeated=github.com/cosmos/cosmos-sdk/types.Coins" json:"original_vesting"`
DelegatedFree github_com_cosmos_cosmos_sdk_types.Coins `protobuf:"bytes,3,rep,name=delegated_free,json=delegatedFree,proto3,castrepeated=github.com/cosmos/cosmos-sdk/types.Coins" json:"delegated_free"`
DelegatedVesting github_com_cosmos_cosmos_sdk_types.Coins `protobuf:"bytes,4,rep,name=delegated_vesting,json=delegatedVesting,proto3,castrepeated=github.com/cosmos/cosmos-sdk/types.Coins" json:"delegated_vesting"`
EndTime int64 `protobuf:"varint,5,opt,name=end_time,json=endTime,proto3" json:"end_time,omitempty"`
// Vesting end time, as unix timestamp (in seconds).
EndTime int64 `protobuf:"varint,5,opt,name=end_time,json=endTime,proto3" json:"end_time,omitempty"`
}
func (m *BaseVestingAccount) Reset() { *m = BaseVestingAccount{} }
@ -74,7 +75,8 @@ var xxx_messageInfo_BaseVestingAccount proto.InternalMessageInfo
// continuously vests by unlocking coins linearly with respect to time.
type ContinuousVestingAccount struct {
*BaseVestingAccount `protobuf:"bytes,1,opt,name=base_vesting_account,json=baseVestingAccount,proto3,embedded=base_vesting_account" json:"base_vesting_account,omitempty"`
StartTime int64 `protobuf:"varint,2,opt,name=start_time,json=startTime,proto3" json:"start_time,omitempty"`
// Vesting start time, as unix timestamp (in seconds).
StartTime int64 `protobuf:"varint,2,opt,name=start_time,json=startTime,proto3" json:"start_time,omitempty"`
}
func (m *ContinuousVestingAccount) Reset() { *m = ContinuousVestingAccount{} }
@ -152,6 +154,7 @@ var xxx_messageInfo_DelayedVestingAccount proto.InternalMessageInfo
// Period defines a length of time and amount of coins that will vest.
type Period struct {
// Period duration in seconds.
Length int64 `protobuf:"varint,1,opt,name=length,proto3" json:"length,omitempty"`
Amount github_com_cosmos_cosmos_sdk_types.Coins `protobuf:"bytes,2,rep,name=amount,proto3,castrepeated=github.com/cosmos/cosmos-sdk/types.Coins" json:"amount"`
}

View File

@ -6,57 +6,57 @@ option go_package = "cosmossdk.io/x/tx/internal/testpb";
message SimpleSigner {
option (cosmos.msg.v1.signer) = "signer";
string signer = 1;
string signer = 1;
}
message RepeatedSigner {
option (cosmos.msg.v1.signer) = "signer";
repeated string signer = 1;
repeated string signer = 1;
}
message NestedSigner {
option (cosmos.msg.v1.signer) = "inner";
Inner inner = 1;
Inner inner = 1;
message Inner {
option (cosmos.msg.v1.signer) = "signer";
string signer = 1;
string signer = 1;
}
}
message RepeatedNestedSigner {
option (cosmos.msg.v1.signer) = "inner";
repeated Inner inner = 1;
repeated Inner inner = 1;
message Inner {
option (cosmos.msg.v1.signer) = "signer";
string signer = 1;
string signer = 1;
}
}
message NestedRepeatedSigner {
option (cosmos.msg.v1.signer) = "inner";
Inner inner = 1;
Inner inner = 1;
message Inner {
option (cosmos.msg.v1.signer) = "signer";
repeated string signer = 1;
repeated string signer = 1;
}
}
message RepeatedNestedRepeatedSigner {
option (cosmos.msg.v1.signer) = "inner";
repeated Inner inner = 1;
repeated Inner inner = 1;
message Inner {
option (cosmos.msg.v1.signer) = "signer";
repeated string signer = 1;
repeated string signer = 1;
}
}
message BadSigner {
option (cosmos.msg.v1.signer) = "signer";
bytes signer = 1;
bytes signer = 1;
}
message NoSignerOption {
bytes signer = 1;