docs: bank client spec (#10147)
## 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 `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)
This commit is contained in:
parent
5a72b5e02b
commit
5e98404654
|
@ -0,0 +1,390 @@
|
|||
<!--
|
||||
order: 6
|
||||
-->
|
||||
|
||||
# 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
|
||||
}
|
||||
}
|
||||
```
|
|
@ -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)
|
Loading…
Reference in New Issue