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:
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_end_block.md` - specify any end-block operations
|
||||||
- `XX_hooks.md` - describe available hooks to be called by/from this module
|
- `XX_hooks.md` - describe available hooks to be called by/from this module
|
||||||
- `XX_events.md` - list and describe event tags used
|
- `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_params.md` - list all module parameters, their types (in JSON) and examples
|
||||||
- `XX_future_improvements.md` - describe future improvements of this module
|
- `XX_future_improvements.md` - describe future improvements of this module
|
||||||
- `XX_appendix.md` - supplementary details referenced elsewhere within the spec
|
- `XX_appendix.md` - supplementary details referenced elsewhere within the spec
|
||||||
|
|
|
@ -179,7 +179,7 @@ Examples:
|
||||||
|
|
||||||
func NewCmdRevokeAuthorization() *cobra.Command {
|
func NewCmdRevokeAuthorization() *cobra.Command {
|
||||||
cmd := &cobra.Command{
|
cmd := &cobra.Command{
|
||||||
Use: "revoke [grantee] [msg_type] --from=[granter]",
|
Use: "revoke [grantee] [msg-type-url] --from=[granter]",
|
||||||
Short: "revoke authorization",
|
Short: "revoke authorization",
|
||||||
Long: strings.TrimSpace(
|
Long: strings.TrimSpace(
|
||||||
fmt.Sprintf(`revoke authorization from a granter to a grantee:
|
fmt.Sprintf(`revoke authorization from a granter to a grantee:
|
||||||
|
@ -212,7 +212,7 @@ Example:
|
||||||
|
|
||||||
func NewCmdExecAuthorization() *cobra.Command {
|
func NewCmdExecAuthorization() *cobra.Command {
|
||||||
cmd := &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",
|
Short: "execute tx on behalf of granter account",
|
||||||
Long: strings.TrimSpace(
|
Long: strings.TrimSpace(
|
||||||
fmt.Sprintf(`execute tx on behalf of granter account:
|
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)
|
- [MsgExec](03_messages.md#MsgExec)
|
||||||
4. **[Events](04_events.md)**
|
4. **[Events](04_events.md)**
|
||||||
- [Keeper](04_events.md#Keeper)
|
- [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