Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: add module specs #278

Merged
merged 2 commits into from
Jan 6, 2023
Merged

Docs: add module specs #278

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5fc12cb
patch: docs (spec): updated documentation
zanicar Jan 5, 2023
b7c2ea6
patch: docs: update module specifications
zanicar Jan 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions proto/quicksilver/claimsmanager/v1/query.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
1 change: 1 addition & 0 deletions proto/quicksilver/participationrewards/v1/query.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 =
Expand Down
56 changes: 31 additions & 25 deletions x/airdrop/spec/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -153,7 +153,7 @@ var Status_value = map[string]int32{

### ZoneDrop

```
```go
KeyPrefixZoneDrop = []byte{0x01}

func GetKeyZoneDrop(chainID string) []byte {
Expand All @@ -174,7 +174,7 @@ type ZoneDrop struct {

### ClaimRecord

```
```go
KeyPrefixClaimRecord = []byte{0x02}

func GetKeyClaimRecord(chainID string, addr sdk.AccAddress) []byte {
Expand All @@ -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"`
Expand All @@ -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) {
Expand All @@ -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 {
Expand All @@ -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;
Expand All @@ -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) {
Expand Down Expand Up @@ -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 {
}
Expand All @@ -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.
Expand All @@ -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 {
Expand All @@ -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:
Expand All @@ -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"`
Expand All @@ -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

Expand All @@ -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"`
Expand All @@ -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.

8 changes: 4 additions & 4 deletions x/claimsmanager/keeper/claims.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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))
Expand All @@ -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))
Expand All @@ -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)

Expand Down
Loading