docs: distribution client spec (#10159)

## Description

Ref: #9707

<!-- Add a description of the changes that this PR introduces and the files that
are the most critical to review. -->

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

@@ -0,0 +1,469 @@
+<!--
+order: 8
+-->
+
+# 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"
+    }
+  ]
+}
+```

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)