docs: add x/supply spec

x/supply/spec/01_concepts.md

@@ -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. 

x/supply/spec/02_client.md

@@ -0,0 +1,131 @@
+<!--
+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
+```
+
+#### total
+The `total` command allows users to query the total supply of a token given a denomination. 
+
+```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 `profiles` 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}
+```
+
+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
+```

x/supply/spec/README.md

@@ -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)