From 3bb6b60cc53f1c6fa37a17fd22d4cfe1cd3d0b09 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Wed, 23 Oct 2024 13:02:51 +0200 Subject: [PATCH] docs(x/accounts): improve comments (backport #22339) (#22342) Co-authored-by: Julien Robert --- simapp/go.mod | 3 +- tools/confix/data/v2-app.toml | 2 +- x/accounts/README.md | 4 ++- x/accounts/defaults/lockup/TUTORIAL.md | 11 ++++--- x/accounts/defaults/lockup/v1/tx.pb.go | 7 ++--- .../defaults/multisig/v1/multisig.pb.go | 24 +++++++++----- .../accounts/defaults/lockup/v1/tx.proto | 31 ++++++------------- .../defaults/multisig/v1/multisig.proto | 18 +++++++++-- 8 files changed, 56 insertions(+), 44 deletions(-) diff --git a/simapp/go.mod b/simapp/go.mod index ff4ec8b202..f3c8bd373b 100644 --- a/simapp/go.mod +++ b/simapp/go.mod @@ -16,6 +16,7 @@ require ( cosmossdk.io/x/accounts v0.0.0-20240913065641-0064ccbce64e cosmossdk.io/x/accounts/defaults/base v0.0.0-00010101000000-000000000000 cosmossdk.io/x/accounts/defaults/lockup v0.0.0-20240417181816-5e7aae0db1f5 + cosmossdk.io/x/accounts/defaults/multisig v0.0.0-00010101000000-000000000000 cosmossdk.io/x/authz v0.0.0-00010101000000-000000000000 cosmossdk.io/x/bank v0.0.0-20240226161501-23359a0b6d91 cosmossdk.io/x/circuit v0.0.0-20230613133644-0a778132a60f @@ -49,8 +50,6 @@ require ( google.golang.org/protobuf v1.35.1 ) -require cosmossdk.io/x/accounts/defaults/multisig v0.0.0-00010101000000-000000000000 - require ( buf.build/gen/go/cometbft/cometbft/protocolbuffers/go v1.34.2-20240701160653-fedbb9acfd2f.2 // indirect buf.build/gen/go/cosmos/gogo-proto/protocolbuffers/go v1.34.2-20240130113600-88ef6483f90f.2 // indirect diff --git a/tools/confix/data/v2-app.toml b/tools/confix/data/v2-app.toml index 842dc0df56..e478eed360 100644 --- a/tools/confix/data/v2-app.toml +++ b/tools/confix/data/v2-app.toml @@ -85,7 +85,7 @@ skip-fast-storage-upgrade = true # Enable enables the application telemetry functionality. When enabled, an in-memory sink is also enabled by default. Operators may also enabled other sinks such as Prometheus. enable = true # Address defines the metrics server address to bind to. -address = 'localhost:1318' +address = 'localhost:1327' # Prefixed with keys to separate services. service-name = '' # Enable prefixing gauge values with hostname. diff --git a/x/accounts/README.md b/x/accounts/README.md index e885cd45b4..16d38c552c 100644 --- a/x/accounts/README.md +++ b/x/accounts/README.md @@ -360,7 +360,9 @@ To implement the `Authentication` interface in x/accounts, an account must expos The key message type for authentication is `MsgAuthenticate`, which is defined in the module's protocol buffer files: -[interfaces/account_abstraction/v1/interface.proto](./proto/cosmos/accounts/interfaces/account_abstraction/v1/interface.proto) +```go reference +https://github.com/cosmos/cosmos-sdk/blob/main/x/accounts/proto/cosmos/accounts/interfaces/account_abstraction/v1/interface.proto#L9-L24 +``` ### Authentication Mechanism diff --git a/x/accounts/defaults/lockup/TUTORIAL.md b/x/accounts/defaults/lockup/TUTORIAL.md index 1a308cbcea..f8ff4bdbee 100644 --- a/x/accounts/defaults/lockup/TUTORIAL.md +++ b/x/accounts/defaults/lockup/TUTORIAL.md @@ -1,14 +1,15 @@ # Using lockup account on Cosmos sdk -* [Setup](#setup) -* [Init](#init) -* [Execution](#execution) +* [Using lockup account on Cosmos sdk](#using-lockup-account-on-cosmos-sdk) + * [Setup](#setup) + * [Init](#init) + * [Execution](#execution) * [Delegate](#delegate) * [Undelegate](#undelegate) * [Withdraw reward](#withdraw-reward) * [Withdraw unlocked token](#withdraw-unlocked-token) * [Send coins](#send-coins) -* [Query](#query) + * [Query](#query) * [Query account info](#query-account-info) * [Query periodic lockup account locking periods](#query-periodic-lockup-account-locking-periods) @@ -207,7 +208,7 @@ To query a lockup account state, we can use the command below: ```bash querycontents=$(cat query.json) -simd tx accounts query $querycontents --from owner +simd tx accounts query $querycontents ``` ### Query account info diff --git a/x/accounts/defaults/lockup/v1/tx.pb.go b/x/accounts/defaults/lockup/v1/tx.pb.go index 3ce47aa3b9..eb831479e0 100644 --- a/x/accounts/defaults/lockup/v1/tx.pb.go +++ b/x/accounts/defaults/lockup/v1/tx.pb.go @@ -33,14 +33,13 @@ var _ = time.Kitchen // proto package needs to be updated. const _ = proto.GoGoProtoPackageIsVersion3 // please upgrade the proto package -// MsgInitLockupAccount defines a message that enables creating a lockup -// account. +// MsgInitLockupAccount defines a message that enables creating a lockup account. type MsgInitLockupAccount struct { // owner of the vesting account Owner string `protobuf:"bytes,1,opt,name=owner,proto3" json:"owner,omitempty"` - // end of lockup + // end_time is end of lockup EndTime time.Time `protobuf:"bytes,2,opt,name=end_time,json=endTime,proto3,stdtime" json:"end_time"` - // start of lockup + // start_time is start of lockup StartTime time.Time `protobuf:"bytes,3,opt,name=start_time,json=startTime,proto3,stdtime" json:"start_time"` } diff --git a/x/accounts/defaults/multisig/v1/multisig.pb.go b/x/accounts/defaults/multisig/v1/multisig.pb.go index 0cb432c87a..649a62b27f 100644 --- a/x/accounts/defaults/multisig/v1/multisig.pb.go +++ b/x/accounts/defaults/multisig/v1/multisig.pb.go @@ -98,8 +98,10 @@ func (VoteOption) EnumDescriptor() ([]byte, []int) { // MsgInit is used to initialize a multisig account. type MsgInit struct { + // members are the members of the multisig account. Members []*Member `protobuf:"bytes,1,rep,name=members,proto3" json:"members,omitempty"` - Config *Config `protobuf:"bytes,2,opt,name=config,proto3" json:"config,omitempty"` + // config is the configuration of the multisig account. + Config *Config `protobuf:"bytes,2,opt,name=config,proto3" json:"config,omitempty"` } func (m *MsgInit) Reset() { *m = MsgInit{} } @@ -603,8 +605,10 @@ func (m *Member) GetWeight() uint64 { // Config defines the configuration of the multisig account. type Config struct { + // threshold is the minimum weight required for a proposal to pass. Threshold int64 `protobuf:"varint,1,opt,name=threshold,proto3" json:"threshold,omitempty"` - Quorum int64 `protobuf:"varint,2,opt,name=quorum,proto3" json:"quorum,omitempty"` + // quorum is the minimum number of members that need to vote for a proposal to pass. + Quorum int64 `protobuf:"varint,2,opt,name=quorum,proto3" json:"quorum,omitempty"` // voting_period is the duration in seconds for the voting period. VotingPeriod int64 `protobuf:"varint,3,opt,name=voting_period,json=votingPeriod,proto3" json:"voting_period,omitempty"` // revote defines if members can change their vote. @@ -683,12 +687,16 @@ func (m *Config) GetEarlyExecution() bool { // Proposal defines the structure of a proposal. type Proposal struct { - Title string `protobuf:"bytes,1,opt,name=title,proto3" json:"title,omitempty"` - Summary string `protobuf:"bytes,2,opt,name=summary,proto3" json:"summary,omitempty"` + // title is the title of the proposal. + Title string `protobuf:"bytes,1,opt,name=title,proto3" json:"title,omitempty"` + // summary is the summary of the proposal. + Summary string `protobuf:"bytes,2,opt,name=summary,proto3" json:"summary,omitempty"` + // messages are the messages that will be executed Messages []*any.Any `protobuf:"bytes,3,rep,name=messages,proto3" json:"messages,omitempty"` // voting_period_end will be set by the account when the proposal is created. - VotingPeriodEnd int64 `protobuf:"varint,4,opt,name=voting_period_end,json=votingPeriodEnd,proto3" json:"voting_period_end,omitempty"` - Status ProposalStatus `protobuf:"varint,5,opt,name=status,proto3,enum=cosmos.accounts.defaults.multisig.v1.ProposalStatus" json:"status,omitempty"` + VotingPeriodEnd int64 `protobuf:"varint,4,opt,name=voting_period_end,json=votingPeriodEnd,proto3" json:"voting_period_end,omitempty"` + // status is the current status of the proposal. + Status ProposalStatus `protobuf:"varint,5,opt,name=status,proto3,enum=cosmos.accounts.defaults.multisig.v1.ProposalStatus" json:"status,omitempty"` } func (m *Proposal) Reset() { *m = Proposal{} } @@ -881,8 +889,10 @@ var xxx_messageInfo_QueryConfig proto.InternalMessageInfo // QueryConfigResponse returns the config of the account. type QueryConfigResponse struct { + // members are the current members of the account. Members []*Member `protobuf:"bytes,1,rep,name=members,proto3" json:"members,omitempty"` - Config *Config `protobuf:"bytes,2,opt,name=config,proto3" json:"config,omitempty"` + // config is the current config of the account. + Config *Config `protobuf:"bytes,2,opt,name=config,proto3" json:"config,omitempty"` } func (m *QueryConfigResponse) Reset() { *m = QueryConfigResponse{} } diff --git a/x/accounts/proto/cosmos/accounts/defaults/lockup/v1/tx.proto b/x/accounts/proto/cosmos/accounts/defaults/lockup/v1/tx.proto index e76b0e1e2c..980cc90c53 100644 --- a/x/accounts/proto/cosmos/accounts/defaults/lockup/v1/tx.proto +++ b/x/accounts/proto/cosmos/accounts/defaults/lockup/v1/tx.proto @@ -12,22 +12,17 @@ import "google/protobuf/timestamp.proto"; option go_package = "cosmossdk.io/x/accounts/defaults/lockup/v1"; -//-------------------------------------- INIT -------------------------------------- - -// MsgInitLockupAccount defines a message that enables creating a lockup -// account. +// MsgInitLockupAccount defines a message that enables creating a lockup account. message MsgInitLockupAccount { - option (amino.name) = "cosmos-sdk/MsgInitLockupAccount"; - + option (amino.name) = "cosmos-sdk/MsgInitLockupAccount"; option (gogoproto.equal) = true; // owner of the vesting account string owner = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; - - // end of lockup + // end_time is end of lockup google.protobuf.Timestamp end_time = 2 [(gogoproto.nullable) = false, (amino.dont_omitempty) = true, (gogoproto.stdtime) = true]; - // start of lockup + // start_time is start of lockup google.protobuf.Timestamp start_time = 3 [(gogoproto.nullable) = false, (amino.dont_omitempty) = true, (gogoproto.stdtime) = true]; } @@ -38,8 +33,7 @@ message MsgInitLockupAccountResponse {} // MsgInitPeriodicLockingAccount defines a message that enables creating a periodic locking // account. message MsgInitPeriodicLockingAccount { - option (amino.name) = "cosmos-sdk/MsgInitPeriodLockupAccount"; - + option (amino.name) = "cosmos-sdk/MsgInitPeriodLockupAccount"; option (gogoproto.equal) = false; // owner of the lockup account @@ -56,8 +50,7 @@ message MsgInitPeriodicLockingAccountResponse {} // MsgDelegate defines a message that enable lockup account to execute delegate message message MsgDelegate { - option (cosmos.msg.v1.signer) = "sender"; - + option (cosmos.msg.v1.signer) = "sender"; option (gogoproto.equal) = false; option (gogoproto.goproto_getters) = false; @@ -69,8 +62,7 @@ message MsgDelegate { // MsgUndelegate defines a message that enable lockup account to execute undelegate message message MsgUndelegate { - option (cosmos.msg.v1.signer) = "sender"; - + option (cosmos.msg.v1.signer) = "sender"; option (gogoproto.equal) = false; option (gogoproto.goproto_getters) = false; @@ -81,8 +73,7 @@ message MsgUndelegate { // MsgWithdrawReward defines a message that enable lockup account to execute withdraw reward message message MsgWithdrawReward { - option (cosmos.msg.v1.signer) = "sender"; - + option (cosmos.msg.v1.signer) = "sender"; option (gogoproto.equal) = false; option (gogoproto.goproto_getters) = false; @@ -92,8 +83,7 @@ message MsgWithdrawReward { // MsgSend defines a message that enable lockup account to execute send message message MsgSend { - option (cosmos.msg.v1.signer) = "sender"; - + option (cosmos.msg.v1.signer) = "sender"; option (gogoproto.equal) = false; option (gogoproto.goproto_getters) = false; @@ -115,8 +105,7 @@ message MsgExecuteMessagesResponse { // MsgWithdraw defines a message that the owner of the lockup can perform to withdraw unlocked token to an account of // choice message MsgWithdraw { - option (cosmos.msg.v1.signer) = "withdrawer"; - + option (cosmos.msg.v1.signer) = "withdrawer"; option (gogoproto.equal) = false; option (gogoproto.goproto_getters) = false; diff --git a/x/accounts/proto/cosmos/accounts/defaults/multisig/v1/multisig.proto b/x/accounts/proto/cosmos/accounts/defaults/multisig/v1/multisig.proto index 0d4a51e4df..dd425b253e 100644 --- a/x/accounts/proto/cosmos/accounts/defaults/multisig/v1/multisig.proto +++ b/x/accounts/proto/cosmos/accounts/defaults/multisig/v1/multisig.proto @@ -9,8 +9,10 @@ option go_package = "cosmossdk.io/x/accounts/defaults/multisig/v1"; // MsgInit is used to initialize a multisig account. message MsgInit { + // members are the members of the multisig account. repeated Member members = 1; - Config config = 2; + // config is the configuration of the multisig account. + Config config = 2; } // MsgInitResponse is the response returned after account initialization. @@ -68,8 +70,10 @@ message Member { // Config defines the configuration of the multisig account. message Config { + // threshold is the minimum weight required for a proposal to pass. int64 threshold = 1; + // quorum is the minimum number of members that need to vote for a proposal to pass. int64 quorum = 2; // voting_period is the duration in seconds for the voting period. @@ -84,13 +88,19 @@ message Config { // Proposal defines the structure of a proposal. message Proposal { - string title = 1; - string summary = 2; + // title is the title of the proposal. + string title = 1; + + // summary is the summary of the proposal. + string summary = 2; + + // messages are the messages that will be executed repeated google.protobuf.Any messages = 3; // voting_period_end will be set by the account when the proposal is created. int64 voting_period_end = 4; + // status is the current status of the proposal. ProposalStatus status = 5; } @@ -108,8 +118,10 @@ message QueryConfig {} // QueryConfigResponse returns the config of the account. message QueryConfigResponse { + // members are the current members of the account. repeated Member members = 1; + // config is the current config of the account. Config config = 2; }