-
Notifications
You must be signed in to change notification settings - Fork 46
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: add x/supply spec #836
Merged
Merged
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
df4263a
docs: add x/supply spec
RiccardoM b3418b7
updated client
RiccardoM 971cb8c
Update x/supply/spec/02_client.md
RiccardoM 1489cd7
Update x/supply/spec/02_client.md
RiccardoM f0d800f
added missing REST examples
RiccardoM 64f60a1
Update x/supply/spec/02_client.md
RiccardoM 6f32e31
added details about the divider exponent
RiccardoM 8d409f1
Merge branch 'master' into riccardo/supply-spec
mergify[bot] File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
<!-- | ||
order: 1 | ||
--> | ||
|
||
# Concepts | ||
|
||
## Total Supply | ||
The total supply of a token is defined as _the overall number of tokens having a given denomination that currently exists inside a chain_. | ||
|
||
The total supply of a token is fetched directly from the `bank` module, which properly tracks such amount each time a new token is created (due to inflation or other) or burned. | ||
|
||
## Circulating Supply | ||
The circulating supply of a token is defined as _the number of tokens having a given denomination that can be transferred freely from one user to another_. | ||
|
||
Based on this definition, the circulating supply of a token is computed using the following formula: | ||
``` | ||
circulating_supply = total_supply - community_pool - sum(vested_amount) | ||
``` | ||
|
||
This is due to the fact that the following amounts are considered as non circulating: | ||
|
||
* the amount of a token inside the _community pool_, since such tokens can be transferred to a user only after a `CommunitySpendPropsal` passes. As soon as some tokens are transferred from the community pool to a user, they become immediately part of the circulating supply; | ||
* the amount of vested tokens, since those are subject to a lock period. As soon as such period ends, they become immediately part of the circulating supply. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,143 @@ | ||
<!-- | ||
order: 2 | ||
--> | ||
|
||
# Client | ||
|
||
## CLI | ||
|
||
A user can query the `supply` module using the CLI. | ||
|
||
### Query | ||
|
||
The `query` commands allow users to query the `supply` state. | ||
|
||
``` | ||
desmos query supply --help | ||
``` | ||
|
||
##### About the divider exponent | ||
Both the `total` and the `circulating` queries allow to specify an optional `divider exponent`. | ||
If provided, such exponent will be used to divide the resulting amount by `10^(divider exponent)`. | ||
|
||
Example: | ||
``` | ||
supply = 1.000.000 | ||
divider_exponent = 3 | ||
result = 1.000.000 / 10^3 = 1.000 | ||
``` | ||
|
||
#### total | ||
The `total` command allows users to query the total supply of a token given a denomination and an optional divider exponent. | ||
If a divider exponent is provided, the resulting supply amount will be divided by `10^(divider_exponent)`. | ||
|
||
```bash | ||
desmos query supply total [denom] [[divider_exponent]] [flags] | ||
``` | ||
|
||
Example: | ||
```bash | ||
desmos query supply total udsm 2 | ||
``` | ||
|
||
Example Output: | ||
```yaml | ||
total_supply: "100003895600953035670" | ||
``` | ||
|
||
#### circulating | ||
The `circulating` command allows users to query the circulating supply of a token given a denomination. | ||
|
||
```bash | ||
desmos query supply circulating [denom] [[divider_exponent]] [flags] | ||
``` | ||
|
||
Example: | ||
```bash | ||
desmos query supply circulating udsm 2 | ||
``` | ||
|
||
Example Output: | ||
```yaml | ||
circulating_supply: "100003882303991703831" | ||
``` | ||
|
||
## gRPC | ||
A user can query the `supply` module gRPC endpoints. | ||
|
||
### Total | ||
The `Total` endpoint allows users to query for the total supply of a token given a denomination. | ||
|
||
```bash | ||
desmos.supply.v1.Query/Total | ||
``` | ||
|
||
Example: | ||
```bash | ||
grpcurl -plaintext \ | ||
-d '{"denom": "stake", "divider_exponent": "2"}' localhost:9090 desmos.supply.v1.Query/Total | ||
``` | ||
|
||
Example Output: | ||
```json | ||
{ | ||
"totalSupply": "1000040727987145688" | ||
} | ||
``` | ||
|
||
### Circulating | ||
The `Circulating` endpoint allows users to query for the circulating supply of a token given a denomination. | ||
|
||
```bash | ||
desmos.supply.v1.Query/Circulating | ||
``` | ||
|
||
Example: | ||
```bash | ||
grpcurl -plaintext \ | ||
-d '{"denom": "stake", "divider_exponent": "2"}' localhost:9090 desmos.supply.v1.Query/Circulating | ||
``` | ||
|
||
Example Output: | ||
```json | ||
{ | ||
"circulatingSupply": "1000040236507203206" | ||
} | ||
``` | ||
|
||
## REST | ||
A user can query the `supply` module using REST endpoints. | ||
|
||
### Total | ||
The `/total` endpoint allows users to query for the total supply of a token given a denomination. | ||
|
||
```bash | ||
/supply/total/{denom} | ||
``` | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It is missing example here, it should be like: Example:
Example Output: 1000040727987145688 |
||
Example: | ||
```bash | ||
curl localhost:1317/supply/total/stake?divider-exponent=2 | ||
``` | ||
|
||
Example Output: | ||
```json | ||
1000040727987145688 | ||
``` | ||
|
||
### Circulating | ||
The `/circulating` endpoint allows users to query for the circulating supply of a token given a denomination. | ||
|
||
```bash | ||
/supply/circulating/{denom} | ||
``` | ||
|
||
Example: | ||
```bash | ||
curl localhost:1317/supply/circulating/stake?divider-exponent=2 | ||
```` | ||
|
||
Example Output: | ||
```json | ||
1000040236507203206 | ||
``` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. As above. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
<!-- | ||
order: 0 | ||
title: Supply Overview | ||
parent: | ||
title: "supply" | ||
--> | ||
|
||
# `supply` | ||
|
||
## Abstract | ||
|
||
This document specifies the supply module of the Cosmos SDK. | ||
|
||
The supply module exposes some query endpoints that can be used by price aggregator services such as [CoinGecko](https://coingecko.com) and [CoinMarketCap](https://coinmarketcap.com) to easily get the total and circulating supply of a token. | ||
|
||
## Concepts | ||
1. **[Concepts](01_concepts.md)** | ||
- [Total Supply](01_concepts.md#total-supply) | ||
- [Circulating Supply](01_concepts.md#circulating-supply) | ||
2. **[Client](02_client.md)** | ||
- [CLI](02_client.md#cli) | ||
- [gRPC](02_client.md#grpc) | ||
- [REST](02_client.md#rest) |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
as above