docs(x/accounts): improve comments (#22339)

(cherry picked from commit 98be2b8)

# Conflicts:
#	api/cosmos/accounts/defaults/lockup/v1/tx.pulsar.go
#	api/cosmos/accounts/defaults/multisig/v1/multisig.pulsar.go
#	server/v2/api/telemetry/config.go
#	simapp/go.mod

server/v2/api/telemetry/config.go

@@ -0,0 +1,61 @@
+package telemetry
+
+func DefaultConfig() *Config {
+	return &Config{
+		Enable:                  true,
+		Address:                 "localhost:1327",
+		ServiceName:             "",
+		EnableHostname:          false,
+		EnableHostnameLabel:     false,
+		EnableServiceLabel:      false,
+		PrometheusRetentionTime: 0,
+		GlobalLabels:            nil,
+		MetricsSink:             "",
+		StatsdAddr:              "",
+		DatadogHostname:         "",
+	}
+}
+
+type Config struct {
+	// 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 bool `mapstructure:"enable" toml:"enable" comment:"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."`
+
+	// Address defines the API server to listen on
+	Address string `mapstructure:"address" toml:"address" comment:"Address defines the metrics server address to bind to."`
+
+	// Prefixed with keys to separate services
+	ServiceName string `mapstructure:"service-name" toml:"service-name" comment:"Prefixed with keys to separate services."`
+
+	// Enable prefixing gauge values with hostname
+	EnableHostname bool `mapstructure:"enable-hostname" toml:"enable-hostname" comment:"Enable prefixing gauge values with hostname."`
+
+	// Enable adding hostname to labels
+	EnableHostnameLabel bool `mapstructure:"enable-hostname-label" toml:"enable-hostname-label" comment:"Enable adding hostname to labels."`
+
+	// Enable adding service to labels
+	EnableServiceLabel bool `mapstructure:"enable-service-label" toml:"enable-service-label" comment:"Enable adding service to labels."`
+
+	// PrometheusRetentionTime, when positive, enables a Prometheus metrics sink.
+	// It defines the retention duration in seconds.
+	PrometheusRetentionTime int64 `mapstructure:"prometheus-retention-time" toml:"prometheus-retention-time" comment:"PrometheusRetentionTime, when positive, enables a Prometheus metrics sink. It defines the retention duration in seconds."`
+
+	// GlobalLabels defines a global set of name/value label tuples applied to all
+	// metrics emitted using the wrapper functions defined in telemetry package.
+	//
+	// Example:
+	// [["chain_id", "cosmoshub-1"]]
+	GlobalLabels [][]string `mapstructure:"global-labels" toml:"global-labels" comment:"GlobalLabels defines a global set of name/value label tuples applied to all metrics emitted using the wrapper functions defined in telemetry package.\n Example:\n  [[\"chain_id\", \"cosmoshub-1\"]]"`
+
+	// MetricsSink defines the type of metrics backend to use.
+	MetricsSink string `mapstructure:"type" toml:"metrics-sink" comment:"MetricsSink defines the type of metrics backend to use. Default is in memory"`
+
+	// StatsdAddr defines the address of a statsd server to send metrics to.
+	// Only utilized if MetricsSink is set to "statsd" or "dogstatsd".
+	StatsdAddr string `mapstructure:"statsd-addr" toml:"stats-addr" comment:"StatsdAddr defines the address of a statsd server to send metrics to. Only utilized if MetricsSink is set to \"statsd\" or \"dogstatsd\"."`
+
+	// DatadogHostname defines the hostname to use when emitting metrics to
+	// Datadog. Only utilized if MetricsSink is set to "dogstatsd".
+	DatadogHostname string `mapstructure:"datadog-hostname" toml:"data-dog-hostname" comment:"DatadogHostname defines the hostname to use when emitting metrics to Datadog. Only utilized if MetricsSink is set to \"dogstatsd\"."`
+}

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
@@ -45,11 +46,18 @@ require (
 	github.com/spf13/pflag v1.0.5
 	github.com/spf13/viper v1.19.0
 	github.com/stretchr/testify v1.9.0
+<<<<<<< HEAD
 	google.golang.org/grpc v1.67.1
 	google.golang.org/protobuf v1.35.1
 )
 
 require cosmossdk.io/x/accounts/defaults/multisig v0.0.0-00010101000000-000000000000
+=======
+	go.uber.org/mock v0.5.0
+	google.golang.org/grpc v1.67.1
+	google.golang.org/protobuf v1.35.1
+)
+>>>>>>> 98be2b855 (docs(x/accounts): improve comments (#22339))
 
 require (
 	buf.build/gen/go/cometbft/cometbft/protocolbuffers/go v1.34.2-20240701160653-fedbb9acfd2f.2 // indirect

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.

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
 

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 <account_address> <query-request-type-url> $querycontents --from owner
+simd tx accounts query <account_address> <query-request-type-url> $querycontents
 ```
 
 ### Query account info

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;
 

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