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)**
|
4. **[Events](04_events.md)**
|
||||||
- [Handlers](04_events.md#handlers)
|
- [Handlers](04_events.md#handlers)
|
||||||
5. **[Parameters](05_params.md)**
|
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