From 2d598e8e9f62b9e04420ea084041bab5509a0732 Mon Sep 17 00:00:00 2001 From: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> Date: Fri, 17 Sep 2021 02:09:18 -0700 Subject: [PATCH] docs: authz client spec (#10136) ## Description Ref: #9707 - 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) --- docs/spec/SPEC-SPEC.md | 1 + x/authz/client/cli/tx.go | 4 +- x/authz/spec/05_client.md | 172 ++++++++++++++++++++++++++++++++++++++ x/authz/spec/README.md | 4 + 4 files changed, 179 insertions(+), 2 deletions(-) create mode 100644 x/authz/spec/05_client.md diff --git a/docs/spec/SPEC-SPEC.md b/docs/spec/SPEC-SPEC.md index fb95c3ab9..4cfdc9fee 100644 --- a/docs/spec/SPEC-SPEC.md +++ b/docs/spec/SPEC-SPEC.md @@ -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 diff --git a/x/authz/client/cli/tx.go b/x/authz/client/cli/tx.go index f4117ee1c..c3157684d 100644 --- a/x/authz/client/cli/tx.go +++ b/x/authz/client/cli/tx.go @@ -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: diff --git a/x/authz/spec/05_client.md b/x/authz/spec/05_client.md new file mode 100644 index 000000000..2c40a6029 --- /dev/null +++ b/x/authz/spec/05_client.md @@ -0,0 +1,172 @@ + + +# 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 --from [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 +} +``` \ No newline at end of file diff --git a/x/authz/spec/README.md b/x/authz/spec/README.md index 814d474f6..4c62d9429 100644 --- a/x/authz/spec/README.md +++ b/x/authz/spec/README.md @@ -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)