docs: authz client spec (#10136)
## 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` to module specification. - Add `client.md` page to `authz` 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)
This commit is contained in:
Ryan Christoffersen
GitHub
parent
fffc2a6ede
commit
2d598e8e9f
|
|
@ -34,6 +34,7 @@ following list is nonbinding and all files are optional.
|
|||
- `XX_end_block.md` - specify any end-block operations
|
||||
- `XX_hooks.md` - describe available hooks to be called by/from this module
|
||||
- `XX_events.md` - list and describe event tags used
|
||||
- `XX_client.md` - list and describe CLI commands and gRPC and REST endpoints
|
||||
- `XX_params.md` - list all module parameters, their types (in JSON) and examples
|
||||
- `XX_future_improvements.md` - describe future improvements of this module
|
||||
- `XX_appendix.md` - supplementary details referenced elsewhere within the spec
|
||||
|
|
|
|||
|
|
@ -179,7 +179,7 @@ Examples:
|
|||
|
||||
func NewCmdRevokeAuthorization() *cobra.Command {
|
||||
cmd := &cobra.Command{
|
||||
Use: "revoke [grantee] [msg_type] --from=[granter]",
|
||||
Use: "revoke [grantee] [msg-type-url] --from=[granter]",
|
||||
Short: "revoke authorization",
|
||||
Long: strings.TrimSpace(
|
||||
fmt.Sprintf(`revoke authorization from a granter to a grantee:
|
||||
|
|
@ -212,7 +212,7 @@ Example:
|
|||
|
||||
func NewCmdExecAuthorization() *cobra.Command {
|
||||
cmd := &cobra.Command{
|
||||
Use: "exec [msg_tx_json_file] --from [grantee]",
|
||||
Use: "exec [tx-json-file] --from [grantee]",
|
||||
Short: "execute tx on behalf of granter account",
|
||||
Long: strings.TrimSpace(
|
||||
fmt.Sprintf(`execute tx on behalf of granter account:
|
||||
|
|
|
|||
|
|
@ -0,0 +1,172 @@
|
|||
<!--
|
||||
order: 5
|
||||
-->
|
||||
|
||||
# Client
|
||||
|
||||
## CLI
|
||||
|
||||
A user can query and interact with the `authz` module using the CLI.
|
||||
|
||||
### Query
|
||||
|
||||
The `query` commands allow users to query `authz` state.
|
||||
|
||||
```bash
|
||||
simd query authz --help
|
||||
```
|
||||
|
||||
#### grants
|
||||
|
||||
The `grants` command allows users to query grants for a granter-grantee pair. If the message type URL is set, it will select grants only for that message type.
|
||||
|
||||
```bash
|
||||
simd query authz grants [granter-addr] [grantee-addr] [msg-type-url]? [flags]
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
simd query authz grants cosmos1.. cosmos1.. /cosmos.bank.v1beta1.MsgSend
|
||||
```
|
||||
|
||||
Example Output:
|
||||
|
||||
```bash
|
||||
grants:
|
||||
- authorization:
|
||||
'@type': /cosmos.bank.v1beta1.SendAuthorization
|
||||
spend_limit:
|
||||
- amount: "100"
|
||||
denom: stake
|
||||
expiration: "2022-01-01T00:00:00Z"
|
||||
pagination: null
|
||||
```
|
||||
|
||||
### Transactions
|
||||
|
||||
The `tx` commands allow users to interact with the `authz` module.
|
||||
|
||||
```bash
|
||||
simd tx authz --help
|
||||
```
|
||||
|
||||
#### exec
|
||||
|
||||
The `exec` command allows a grantee to execute a transaction on behalf of granter.
|
||||
|
||||
```bash
|
||||
simd tx authz exec [tx-json-file] --from [grantee] [flags]
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
simd tx authz exec tx.json --from=cosmos1..
|
||||
```
|
||||
|
||||
#### grant
|
||||
|
||||
The `grant` command allows a granter to grant an authorization to a grantee.
|
||||
|
||||
```bash
|
||||
simd tx authz grant <grantee> <authorization_type="send"|"generic"|"delegate"|"unbond"|"redelegate"> --from <granter> [flags]
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
simd tx authz grant cosmos1.. send --spend-limit=100stake --from=cosmos1..
|
||||
```
|
||||
|
||||
#### revoke
|
||||
|
||||
The `revoke` command allows a granter to revoke an authorization from a grantee.
|
||||
|
||||
```bash
|
||||
simd tx authz revoke [grantee] [msg-type-url] --from=[granter] [flags]
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
simd tx authz revoke cosmos1.. /cosmos.bank.v1beta1.MsgSend --from=cosmos1..
|
||||
```
|
||||
|
||||
## gRPC
|
||||
|
||||
A user can query the `authz` module using gRPC endpoints.
|
||||
|
||||
### Grants
|
||||
|
||||
The `Grants` endpoint allows users to query grants for a granter-grantee pair. If the message type URL is set, it will select grants only for that message type.
|
||||
|
||||
```bash
|
||||
cosmos.authz.v1beta1.Query/Grants
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
grpcurl -plaintext \
|
||||
-d '{"granter":"cosmos1..","grantee":"cosmos1..","msg_type_url":"/cosmos.bank.v1beta1.MsgSend"}' \
|
||||
localhost:9090 \
|
||||
cosmos.authz.v1beta1.Query/Grants
|
||||
```
|
||||
|
||||
Example Output:
|
||||
|
||||
```bash
|
||||
{
|
||||
"grants": [
|
||||
{
|
||||
"authorization": {
|
||||
"@type": "/cosmos.bank.v1beta1.SendAuthorization",
|
||||
"spendLimit": [
|
||||
{
|
||||
"denom":"stake",
|
||||
"amount":"100"
|
||||
}
|
||||
]
|
||||
},
|
||||
"expiration": "2022-01-01T00:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## REST
|
||||
|
||||
A user can query the `authz` module using REST endpoints.
|
||||
|
||||
```bash
|
||||
/cosmos/authz/v1beta1/grants
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
curl "localhost:1317/cosmos/authz/v1beta1/grants?granter=cosmos1..&grantee=cosmos1..&msg_type_url=/cosmos.bank.v1beta1.MsgSend"
|
||||
```
|
||||
|
||||
Example Output:
|
||||
|
||||
```bash
|
||||
{
|
||||
"grants": [
|
||||
{
|
||||
"authorization": {
|
||||
"@type": "/cosmos.bank.v1beta1.SendAuthorization",
|
||||
"spend_limit": [
|
||||
{
|
||||
"denom": "stake",
|
||||
"amount": "100"
|
||||
}
|
||||
]
|
||||
},
|
||||
"expiration": "2022-01-01T00:00:00Z"
|
||||
}
|
||||
],
|
||||
"pagination": null
|
||||
}
|
||||
```
|
||||
|
|
@ -25,3 +25,7 @@ granting arbitrary privileges from one account (the granter) to another account
|
|||
- [MsgExec](03_messages.md#MsgExec)
|
||||
4. **[Events](04_events.md)**
|
||||
- [Keeper](04_events.md#Keeper)
|
||||
5. **[Client](05_client.md)**
|
||||
- [CLI](05_client.md#cli)
|
||||
- [gRPC](05_client.md#grpc)
|
||||
- [REST](05_client.md#rest)
|
||||
|
|
|
|||
Loading…
Reference in New Issue