From 8a3d7dddea7b08b5e293a4ad896b877c93d42a40 Mon Sep 17 00:00:00 2001 From: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> Date: Thu, 16 Sep 2021 02:44:10 -0700 Subject: [PATCH] docs: distribution client spec (#10159) ## Description Ref: #9707 Add `client.md` page to `distribution` module spec. --- ### Author Checklist *All items are required. Please add a note to the item if the item is not applicable and please add links to any relevant follow up issues.* I have... - [x] included the correct `docs:` prefix in the PR title - [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting)) - [x] provided a link to the relevant issue or specification - [x] followed the [documentation writing guidelines](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOC_WRITING_GUIDELINES.md) - [x] reviewed "Files changed" and left comments if necessary - [ ] confirmed all CI checks have passed ### Reviewers Checklist *All items are required. Please add a note if the item is not applicable and please add your handle next to the items reviewed if you only reviewed selected items.* I have... - [ ] confirmed the correct `docs:` prefix in the PR title - [ ] confirmed all author checklist items have been addressed - [ ] confirmed that this PR only changes documentation - [ ] reviewed content for consistency - [ ] reviewed content for thoroughness - [ ] reviewed content for spelling and grammar - [ ] tested instructions (if applicable) --- x/distribution/spec/08_client.md | 469 +++++++++++++++++++++++++++++++ x/distribution/spec/README.md | 3 + 2 files changed, 472 insertions(+) create mode 100644 x/distribution/spec/08_client.md diff --git a/x/distribution/spec/08_client.md b/x/distribution/spec/08_client.md new file mode 100644 index 000000000..0e80a2f2d --- /dev/null +++ b/x/distribution/spec/08_client.md @@ -0,0 +1,469 @@ + + +# Client + +## CLI + +A user can query and interact with the `distribution` module using the CLI. + +### Query + +The `query` commands allow users to query `distribution` state. + +``` +simd query distribution --help +``` + +#### commission + +The `commission` command allows users to query validator commission rewards by address. + +``` +simd query distribution commission [address] [flags] +``` + +Example: + +``` +simd query distribution commission cosmosvaloper1.. +``` + +Example Output: + +``` +commission: +- amount: "1000000.000000000000000000" + denom: stake +``` + +#### community-pool + +The `community-pool` command allows users to query all coin balances within the community pool. + +``` +simd query distribution community-pool [flags] +``` + +Example: + +``` +simd query distribution community-pool +``` + +Example Output: + +``` +pool: +- amount: "1000000.000000000000000000" + denom: stake +``` + +#### params + +The `params` command allows users to query the parameters of the `distribution` module. + +``` +simd query distribution params [flags] +``` + +Example: + +``` +simd query distribution params +``` + +Example Output: + +``` +base_proposer_reward: "0.010000000000000000" +bonus_proposer_reward: "0.040000000000000000" +community_tax: "0.020000000000000000" +withdraw_addr_enabled: true +``` + +#### rewards + +The `rewards` command allows users to query delegator rewards. Users can optionally include the validator address to query rewards earned from a specific validator. + +``` +simd query distribution rewards [delegator-addr] [validator-addr] [flags] +``` + +Example: + +``` +simd query distribution rewards cosmos1.. +``` + +Example Output: + +``` +rewards: +- reward: + - amount: "1000000.000000000000000000" + denom: stake + validator_address: cosmosvaloper1.. +total: +- amount: "1000000.000000000000000000" + denom: stake +``` + +#### slashes + +The `slashes` command allows users to query all slashes for a given block range. + +``` +simd query distribution slashes [validator] [start-height] [end-height] [flags] +``` + +Example: + +``` +simd query distribution slashes cosmosvaloper1.. 1 1000 +``` + +Example Output: + +``` +pagination: + next_key: null + total: "0" +slashes: +- validator_period: 20, + fraction: "0.009999999999999999" +``` + +#### validator-outstanding-rewards + +The `validator-outstanding-rewards` command allows users to query all outstanding (un-withdrawn) rewards for a validator and all their delegations. + +``` +simd query distribution validator-outstanding-rewards [validator] [flags] +``` + +Example: + +``` +simd query distribution validator-outstanding-rewards cosmosvaloper1.. +``` + +Example Output: + +``` +rewards: +- amount: "1000000.000000000000000000" + denom: stake +``` + +### Transactions + +The `tx` commands allow users to interact with the `distribution` module. + +``` +simd tx distribution --help +``` + +#### fund-community-pool + +The `fund-community-pool` command allows users to send funds to the community pool. + +``` +simd tx distribution fund-community-pool [amount] [flags] +``` + +Example: + +``` +simd tx distribution fund-community-pool 100stake --from cosmos1.. +``` + +#### set-withdraw-addr + +The `set-withdraw-addr` command allows users to set the withdraw address for rewards associated with a delegator address. + +``` +simd tx distribution set-withdraw-addr [withdraw-addr] [flags] +``` + +Example: + +``` +simd tx distribution set-withdraw-addr cosmos1.. --from cosmos1.. +``` + +#### withdraw-all-rewards + +The `withdraw-all-rewards` command allows users to withdraw all rewards for a delegator. + +``` +simd tx distribution withdraw-all-rewards [flags] +``` + +Example: + +``` +simd tx distribution withdraw-all-rewards --from cosmos1.. +``` + +#### withdraw-rewards + +The `withdraw-rewards` command allows users to withdraw all rewards from a given delegation address, +and optionally withdraw validator commission if the delegation address given is a validator operator and the user proves the `--commision` flag. + +``` +simd tx distribution withdraw-rewards [validator-addr] [flags] +``` + +Example: + +``` +simd tx distribution withdraw-rewards cosmosvaloper1.. --from cosmos1.. --commision +``` + +## gRPC + +A user can query the `distribution` module using gRPC endpoints. + +### Params + +The `Params` endpoint allows users to query parameters of the `distribution` module. + +Example: + +``` +grpcurl -plaintext \ + localhost:9090 \ + cosmos.distribution.v1beta1.Query/Params +``` + +Example Output: + +``` +{ + "params": { + "communityTax": "20000000000000000", + "baseProposerReward": "10000000000000000", + "bonusProposerReward": "40000000000000000", + "withdrawAddrEnabled": true + } +} +``` + +### ValidatorOutstandingRewards + +The `ValidatorOutstandingRewards` endpoint allows users to query rewards of a validator address. + +Example: + +``` +grpcurl -plaintext \ + -d '{"validator_address":"cosmosvalop1.."}' \ + localhost:9090 \ + cosmos.distribution.v1beta1.Query/ValidatorOutstandingRewards +``` + +Example Output: + +``` +{ + "rewards": { + "rewards": [ + { + "denom": "stake", + "amount": "1000000000000000" + } + ] + } +} +``` + +### ValidatorCommission + +The `ValidatorCommission` endpoint allows users to query accumulated commission for a validator. + +Example: + +``` +grpcurl -plaintext \ + -d '{"validator_address":"cosmosvalop1.."}' \ + localhost:9090 \ + cosmos.distribution.v1beta1.Query/ValidatorCommission +``` + +Example Output: + +``` +{ + "commission": { + "commission": [ + { + "denom": "stake", + "amount": "1000000000000000" + } + ] + } +} +``` + +### ValidatorSlashes + +The `ValidatorSlashes` endpoint allows users to query slash events of a validator. + +Example: + +``` +grpcurl -plaintext \ + -d '{"validator_address":"cosmosvalop1.."}' \ + localhost:9090 \ + cosmos.distribution.v1beta1.Query/ValidatorSlashes +``` + +Example Output: + +``` +{ + "slashes": [ + { + "validator_period": "20", + "fraction": "0.009999999999999999" + } + ], + "pagination": { + "total": "1" + } +} +``` + +### DelegationRewards + +The `DelegationRewards` endpoint allows users to query the total rewards accrued by a delegation. + +Example: + +``` +grpcurl -plaintext \ + -d '{"delegator_address":"cosmos1..","validator_address":"cosmosvalop1.."}' \ + localhost:9090 \ + cosmos.distribution.v1beta1.Query/DelegationRewards +``` + +Example Output: + +``` +{ + "rewards": [ + { + "denom": "stake", + "amount": "1000000000000000" + } + ] +} +``` + +### DelegationTotalRewards + +The `DelegationTotalRewards` endpoint allows users to query the total rewards accrued by each validator. + +Example: + +``` +grpcurl -plaintext \ + -d '{"delegator_address":"cosmos1.."}' \ + localhost:9090 \ + cosmos.distribution.v1beta1.Query/DelegationTotalRewards +``` + +Example Output: + +``` +{ + "rewards": [ + { + "validatorAddress": "cosmosvaloper1..", + "reward": [ + { + "denom": "stake", + "amount": "1000000000000000" + } + ] + } + ], + "total": [ + { + "denom": "stake", + "amount": "1000000000000000" + } + ] +} +``` + +### DelegatorValidators + +The `DelegatorValidators` endpoint allows users to query all validators for given delegator. + +Example: + +``` +grpcurl -plaintext \ + -d '{"delegator_address":"cosmos1.."}' \ + localhost:9090 \ + cosmos.distribution.v1beta1.Query/DelegatorValidators +``` + +Example Output: + +``` +{ + "validators": [ + "cosmosvaloper1.." + ] +} +``` + +### DelegatorWithdrawAddress + +The `DelegatorWithdrawAddress` endpoint allows users to query the withdraw address of a delegator. + +Example: + +``` +grpcurl -plaintext \ + -d '{"delegator_address":"cosmos1.."}' \ + localhost:9090 \ + cosmos.distribution.v1beta1.Query/DelegatorWithdrawAddress +``` + +Example Output: + +``` +{ + "withdrawAddress": "cosmos1.." +} +``` + +### CommunityPool + +The `CommunityPool` endpoint allows users to query the community pool coins. + +Example: + +``` +grpcurl -plaintext \ + localhost:9090 \ + cosmos.distribution.v1beta1.Query/CommunityPool +``` + +Example Output: + +``` +{ + "pool": [ + { + "denom": "stake", + "amount": "1000000000000000000" + } + ] +} +``` diff --git a/x/distribution/spec/README.md b/x/distribution/spec/README.md index 868b42590..992c87821 100644 --- a/x/distribution/spec/README.md +++ b/x/distribution/spec/README.md @@ -101,3 +101,6 @@ to set up a script to periodically withdraw and rebond rewards. - [BeginBlocker](06_events.md#beginblocker) - [Handlers](06_events.md#handlers) 7. **[Parameters](07_params.md)** +8. **[Parameters](07_params.md)** + - [CLI](08_client.md#cli) + - [gRPC](08_client.md#grpc) \ No newline at end of file