Docs: add module specs (#278)

* patch: docs (spec): updated documentation

- fixed incorrect comments;
- added some missing comments;
- removed superflous comments;
- updated airdrop spec;
- added claimsmanager spec;
- added spec template for interchainqueries;
- fixed event emission in interchainstaking;
- added interchainstaking spec;
- added spec module template;
- added participationrewards spec;

* patch: docs: update module specifications

proto/quicksilver/claimsmanager/v1/query.proto

@@ -11,31 +11,35 @@ option go_package = "github.com/ingenuity-build/quicksilver/x/claimsmanager/type
 
 // Query provides defines the gRPC querier service.
 service Query {
-  // Params returns the total set of participation rewards parameters.
-
+  // Claims returns all zone claims from the current epoch.
   rpc Claims(QueryClaimsRequest) returns (QueryClaimsResponse) {
     option (google.api.http).get = "/quicksilver/claimsmanager/v1/claims/{chain_id}";
   }
 
+  // LastEpochClaims returns all zone claims from the last epoch.
   rpc LastEpochClaims(QueryClaimsRequest) returns (QueryClaimsResponse) {
     option (google.api.http).get = "/quicksilver/claimsmanager/v1/previous_epoch_claims/{chain_id}";
   }
 
+  // UserClaims returns all zone claims for a given address from the current epoch.
   rpc UserClaims(QueryClaimsRequest) returns (QueryClaimsResponse) {
     option (google.api.http).get = "/quicksilver/claimsmanager/v1/user/{address}/claims";
   }
 
+  // UserLastEpochClaims returns all zone claims for a given address from the last epoch.
   rpc UserLastEpochClaims(QueryClaimsRequest) returns (QueryClaimsResponse) {
     option (google.api.http).get = "/quicksilver/claimsmanager/v1/user/{address}/previous_epoch_claims";
   }
 }
 
+// QueryClaimsRequest is the request type for the Query/Claims RPC method.
 message QueryClaimsRequest {
   string chain_id = 1 [ (gogoproto.moretags) = "yaml:\"chain_id\"" ];
   string address = 2 [ (cosmos_proto.scalar) = "cosmos.AddressString" ];
   cosmos.base.query.v1beta1.PageRequest pagination = 3;
 }
 
+// QueryClaimsResponse is the response type for the Query/Claims RPC method.
 message QueryClaimsResponse {
   repeated Claim claims = 1 [ (gogoproto.nullable) = false ];
   cosmos.base.query.v1beta1.PageResponse pagination = 2;

proto/quicksilver/participationrewards/v1/query.proto

@@ -15,6 +15,7 @@ service Query {
         "/quicksilver/participationrewards/v1/params";
   }
 
+  // ProtocolData returns the requested protocol data.
   rpc ProtocolData(QueryProtocolDataRequest)
       returns (QueryProtocolDataResponse) {
     option (google.api.http).get =

x/airdrop/spec/README.md

@@ -68,7 +68,7 @@ Any claims completed are recorded against the `ClaimRecord` and claimed amounts
 
 ### Action
 
-```
+```go
 // Action is used as an enum to denote specific actions or tasks.
 type Action int32
 
@@ -128,7 +128,7 @@ var Action_value = map[string]int32{
 
 ### Status
 
-```
+```go
 // Status is used as an enum to denote zone status.
 type Status int32
 
@@ -153,7 +153,7 @@ var Status_value = map[string]int32{
 
 ### ZoneDrop
 
-```
+```go
 KeyPrefixZoneDrop    = []byte{0x01}
 
 func GetKeyZoneDrop(chainID string) []byte {
@@ -174,7 +174,7 @@ type ZoneDrop struct {
 
 ### ClaimRecord
 
-```
+```go
 KeyPrefixClaimRecord = []byte{0x02}
 
 func GetKeyClaimRecord(chainID string, addr sdk.AccAddress) []byte {
@@ -199,7 +199,7 @@ type ClaimRecord struct {
 
 ### CompletedAction
 
-```
+```go
 // CompletedAction represents a claim action completed by the user.
 type CompletedAction struct {
 	CompleteTime time.Time `protobuf:"bytes,1,opt,name=complete_time,json=completeTime,proto3,stdtime" json:"complete_time" yaml:"complete_time"`
@@ -211,7 +211,7 @@ type CompletedAction struct {
 
 Description of message types that trigger state transitions;
 
-```
+```protobuf
 // Msg defines the airdrop Msg service.
 service Msg {
   rpc Claim(MsgClaim) returns (MsgClaimResponse) {
@@ -227,14 +227,12 @@ service Msg {
 
 Claim the airdrop for the given action in the given zone.
 
-Use: `claim [chainID] [action]`
-
-```
+```go
 type MsgClaim struct {
-	ChainId string `protobuf:"bytes,1,opt,name=chain_id,json=chainId,proto3" json:"chain_id,omitempty" yaml:"chain_id"`
-	Action  int32  `protobuf:"varint,2,opt,name=action,proto3" json:"action,omitempty" yaml:"action"`
-	Address string `protobuf:"bytes,3,opt,name=address,proto3" json:"address,omitempty" yaml:"address"`
-	Proof   []byte `protobuf:"bytes,4,opt,name=proof,proto3" json:"proof,omitempty" yaml:"proof"`
+	ChainId string         `protobuf:"bytes,1,opt,name=chain_id,json=chainId,proto3" json:"chain_id,omitempty" yaml:"chain_id"`
+	Action  int64          `protobuf:"varint,2,opt,name=action,proto3" json:"action,omitempty" yaml:"action"`
+	Address string         `protobuf:"bytes,3,opt,name=address,proto3" json:"address,omitempty" yaml:"address"`
+	Proofs  []*types.Proof `protobuf:"bytes,4,rep,name=proofs,proto3" json:"proofs,omitempty" yaml:"proofs"`
 }
 
 type MsgClaimResponse struct {
@@ -246,6 +244,16 @@ type MsgClaimResponse struct {
 
 Description of transactions that collect messages in specific contexts to trigger state transitions;
 
+### claim
+
+Claim airdrop for the given action in the given zone.
+
+`claim [chainID] [action]`
+
+Example:
+
+`$ quicksilverd tx airdrop claim cosmoshub-4 ActionDelegateStake`
+
 ## Events
 
 Events emitted by module for tracking messages and index transactions;
@@ -268,13 +276,13 @@ Events emitted by module for tracking messages and index transactions;
 
 ## Hooks
 
-Description of hook functions that may be used by other modules to execute operations at specific points within this module;
+N/A
 
 ## Queries
 
 Description of available information request queries;
 
-```
+```protobuf
 service Query {
   // Params returns the total set of airdrop parameters.
   rpc Params(QueryParamsRequest) returns (QueryParamsResponse) {
@@ -316,7 +324,7 @@ Query the current airdrop module parameters.
 
 Use: `params`
 
-```
+```go
 // QueryParamsRequest is the request type for the Query/Params RPC method.
 type QueryParamsRequest struct {
 }
@@ -334,7 +342,7 @@ Query the airdrop details of the specified zone.
 
 Use: `zone [chain_id]`
 
-```
+```go
 // QueryZoneDropRequest is the request type for Query/ZoneDrop RPC method.
 type QueryZoneDropRequest struct {
 	// chain_id identifies the zone.
@@ -353,7 +361,7 @@ Returns the airdrop module account balance of the specified zone.
 
 Use: `account-balance [chain_id]`
 
-```
+```go
 // QueryAccountBalanceRequest is the request type for Query/AccountBalance RPC
 // method.
 type QueryAccountBalanceRequest struct {
@@ -374,7 +382,7 @@ Query all airdrops of the specified status.
 
 Use: `zone-drops [status]`
 
-```
+```go
 // QueryZoneDropsRequest is the request type for Query/ZoneDrops RPC method.
 type QueryZoneDropsRequest struct {
 	// status enables to query zone airdrops matching a given status:
@@ -398,7 +406,7 @@ Query airdrop claim record details of the given address for the given zone.
 
 Use: `claim-record [chain_id] [address]`
 
-```
+```go
 // QueryClaimRecordRequest is the request type for Query/ClaimRecord RPC method.
 type QueryClaimRecordRequest struct {
 	ChainId string `protobuf:"bytes,1,opt,name=chain_id,json=chainId,proto3" json:"chain_id,omitempty" yaml:"chain_id"`
@@ -414,7 +422,7 @@ type QueryClaimRecordResponse struct {
 
 ## Keepers
 
-Keepers exposed by module;
+https://pkg.go.dev/github.com/ingenuity-build/quicksilver/x/airdrop/keeper
 
 ## Parameters
 
@@ -431,7 +439,7 @@ Description of parameters:
 
 Register a zone airdrop proposal.
 
-```
+```go
 type RegisterZoneDropProposal struct {
 	Title        string    `protobuf:"bytes,1,opt,name=title,proto3" json:"title,omitempty"`
 	Description  string    `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"`
@@ -442,11 +450,9 @@ type RegisterZoneDropProposal struct {
 
 ## Begin Block
 
-Description of logic executed with optional methods or external hooks;
+N/A
 
 ## End Block
 
-Description of logic executed with optional methods or external hooks;
-
 At the end of every block the module iterates through all unconcluded airdrops (expired but not yet concluded) and calls `EndZoneDrop` for each instance, that deletes all associated `ClaimRecord`s.
 

x/claimsmanager/keeper/claims.go

@@ -180,7 +180,7 @@ func (k Keeper) IterateAllLastEpochClaims(ctx sdk.Context, fn func(index int64,
 	}
 }
 
-// IterateUserClaims iterates through zone claims for a given address.
+// IterateAllClaims iterates through all claims.
 func (k Keeper) IterateAllClaims(ctx sdk.Context, fn func(index int64, key []byte, data types.Claim) (stop bool)) {
 	// noop
 	if fn == nil {
@@ -257,7 +257,7 @@ func (k Keeper) AllZoneLastEpochUserClaims(ctx sdk.Context, chainID string, addr
 	return claims
 }
 
-// ClearClaims deletes all the claims of the given zone.
+// ClearClaims deletes all the current epoch claims of the given zone.
 func (k Keeper) ClearClaims(ctx sdk.Context, chainID string) {
 	store := ctx.KVStore(k.storeKey)
 	iterator := sdk.KVStorePrefixIterator(store, types.GetPrefixClaim(chainID))
@@ -269,7 +269,7 @@ func (k Keeper) ClearClaims(ctx sdk.Context, chainID string) {
 	}
 }
 
-// ClearClaims deletes all the claims of the given zone.
+// ClearLastEpochClaims deletes all the last epoch claims of the given zone.
 func (k Keeper) ClearLastEpochClaims(ctx sdk.Context, chainID string) {
 	store := ctx.KVStore(k.storeKey)
 	iterator := sdk.KVStorePrefixIterator(store, types.GetPrefixLastEpochClaim(chainID))
@@ -281,7 +281,7 @@ func (k Keeper) ClearLastEpochClaims(ctx sdk.Context, chainID string) {
 	}
 }
 
-// ClearClaims deletes all the claims of the given zone.
+// ArchiveAndGarbageCollectClaims deletes all the last epoch claims and moves the current epoch claims to the last epoch store.
 func (k Keeper) ArchiveAndGarbageCollectClaims(ctx sdk.Context, chainID string) {
 	k.ClearLastEpochClaims(ctx, chainID)