From 5e98404654ab4b30016aed913fa346e4bc27bc26 Mon Sep 17 00:00:00 2001 From: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> Date: Thu, 16 Sep 2021 04:08:28 -0700 Subject: [PATCH] docs: bank client spec (#10147) ## Description Ref: #9707 Add `client.md` page to `bank` 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/bank/spec/06_client.md | 390 +++++++++++++++++++++++++++++++++++++++ x/bank/spec/README.md | 3 + 2 files changed, 393 insertions(+) create mode 100644 x/bank/spec/06_client.md diff --git a/x/bank/spec/06_client.md b/x/bank/spec/06_client.md new file mode 100644 index 000000000..077e950e8 --- /dev/null +++ b/x/bank/spec/06_client.md @@ -0,0 +1,390 @@ + + +# Client + +## CLI + +A user can query and interact with the `bank` module using the CLI. + +### Query + +The `query` commands allow users to query `bank` state. + +``` +simd query bank --help +``` + +#### balances + +The `balances` command allows users to query account balances by address. + +``` +simd query bank balances [address] [flags] +``` + +Example: + +``` +simd query bank balances cosmos1.. +``` + +Example Output: + +``` +balances: +- amount: "1000000000" + denom: stake +pagination: + next_key: null + total: "0" +``` + +#### denom-metadata + +The `denom-metadata` command allows users to query metadata for coin denominations. A user can query metadata for a single denomination using the `--denom` flag or all denominations without it. + +``` +simd query bank denom-metadata [flags] +``` + +Example: + +``` +simd query bank denom-metadata --denom stake +``` + +Example Output: + +``` +metadata: + base: stake + denom_units: + - aliases: + - STAKE + denom: stake + description: native staking token of simulation app + display: stake + name: SimApp Token + symbol: STK +``` + +#### total + +The `total` command allows users to query the total supply of coins. A user can query the total supply for a single coin using the `--denom` flag or all coins without it. + +``` +simd query bank total [flags] +``` + +Example: + +``` +simd query bank total --denom stake +``` + +Example Output: + +``` +amount: "10000000000" +denom: stake +``` + +### Transactions + +The `tx` commands allow users to interact with the `bank` module. + +``` +simd tx bank --help +``` + +#### send + +The `send` command allows users to send funds from one account to another. + +``` +simd tx bank send [from_key_or_address] [to_address] [amount] [flags] +``` + +Example: + +``` +simd tx bank send cosmos1.. cosmos1.. 100stake +``` + +## gRPC + +A user can query the `bank` module using gRPC endpoints. + +### Balance + +The `Balance` endpoint allows users to query account balance by address for a given denomination. + +``` +cosmos.bank.v1beta1.Query/Balance +``` + +Example: + +``` +grpcurl -plaintext \ + -d '{"address":"cosmos1..","denom":"stake"}' \ + localhost:9090 \ + cosmos.bank.v1beta1.Query/Balance +``` + +Example Output: + +``` +{ + "balance": { + "denom": "stake", + "amount": "1000000000" + } +} +``` + +### AllBalances + +The `AllBalances` endpoint allows users to query account balance by address for all denominations. + +``` +cosmos.bank.v1beta1.Query/AllBalances +``` + +Example: + +``` +grpcurl -plaintext \ + -d '{"address":"cosmos1.."}' \ + localhost:9090 \ + cosmos.bank.v1beta1.Query/AllBalances +``` + +Example Output: + +``` +{ + "balances": [ + { + "denom": "stake", + "amount": "1000000000" + } + ], + "pagination": { + "total": "1" + } +} +``` + +### DenomMetadata + +The `DenomMetadata` endpoint allows users to query metadata for a single coin denomination. + +``` +cosmos.bank.v1beta1.Query/DenomMetadata +``` + +Example: + +``` +grpcurl -plaintext \ + -d '{"denom":"stake"}' \ + localhost:9090 \ + cosmos.bank.v1beta1.Query/DenomMetadata +``` + +Example Output: + +``` +{ + "metadata": { + "description": "native staking token of simulation app", + "denomUnits": [ + { + "denom": "stake", + "aliases": [ + "STAKE" + ] + } + ], + "base": "stake", + "display": "stake", + "name": "SimApp Token", + "symbol": "STK" + } +} +``` + +### DenomsMetadata + +The `DenomsMetadata` endpoint allows users to query metadata for all coin denominations. + +``` +cosmos.bank.v1beta1.Query/DenomsMetadata +``` + +Example: + +``` +grpcurl -plaintext \ + localhost:9090 \ + cosmos.bank.v1beta1.Query/DenomsMetadata +``` + +Example Output: + +``` +{ + "metadatas": [ + { + "description": "native staking token of simulation app", + "denomUnits": [ + { + "denom": "stake", + "aliases": [ + "STAKE" + ] + } + ], + "base": "stake", + "display": "stake", + "name": "SimApp Token", + "symbol": "STK" + } + ], + "pagination": { + "total": "1" + } +} +``` + +### DenomOwners + +The `DenomOwners` endpoint allows users to query metadata for a single coin denomination. + +``` +cosmos.bank.v1beta1.Query/DenomOwners +``` + +Example: + +``` +grpcurl -plaintext \ + -d '{"denom":"stake"}' \ + localhost:9090 \ + cosmos.bank.v1beta1.Query/DenomOwners +``` + +Example Output: + +``` +{ + "denomOwners": [ + { + "address": "cosmos1..", + "balance": { + "denom": "stake", + "amount": "5000000000" + } + }, + { + "address": "cosmos1..", + "balance": { + "denom": "stake", + "amount": "5000000000" + } + }, + ], + "pagination": { + "total": "2" + } +} +``` + +### TotalSupply + +The `TotalSupply` endpoint allows users to query the total supply of all coins. + +``` +cosmos.bank.v1beta1.Query/TotalSupply +``` + +Example: + +``` +grpcurl -plaintext \ + localhost:9090 \ + cosmos.bank.v1beta1.Query/TotalSupply +``` + +Example Output: + +``` +{ + "supply": [ + { + "denom": "stake", + "amount": "10000000000" + } + ], + "pagination": { + "total": "1" + } +} +``` + +### SupplyOf + +The `SupplyOf` endpoint allows users to query the total supply of a single coin. + +``` +cosmos.bank.v1beta1.Query/SupplyOf +``` + +Example: + +``` +grpcurl -plaintext \ + -d '{"denom":"stake"}' \ + localhost:9090 \ + cosmos.bank.v1beta1.Query/SupplyOf +``` + +Example Output: + +``` +{ + "amount": { + "denom": "stake", + "amount": "10000000000" + } +} +``` + +### Params + +The `Params` endpoint allows users to query the parameters of the `bank` module. + +``` +cosmos.bank.v1beta1.Query/Params +``` + +Example: + +``` +grpcurl -plaintext \ + localhost:9090 \ + cosmos.bank.v1beta1.Query/Params +``` + +Example Output: + +``` +{ + "params": { + "defaultSendEnabled": true + } +} +``` diff --git a/x/bank/spec/README.md b/x/bank/spec/README.md index 9a1a0afb6..53b68c7d7 100644 --- a/x/bank/spec/README.md +++ b/x/bank/spec/README.md @@ -100,3 +100,6 @@ The available permissions are: 4. **[Events](04_events.md)** - [Handlers](04_events.md#handlers) 5. **[Parameters](05_params.md)** +6. **[Client](06_client.md)** + - [CLI](06_client.md#cli) + - [gRPC](06_client.md#grpc) \ No newline at end of file