From 43d6ddf18857d3b45c802139538b16f5c1464760 Mon Sep 17 00:00:00 2001 From: Leonardo Bragagnolo Date: Wed, 23 Mar 2022 06:19:20 +0000 Subject: [PATCH] docs(adr): ADR-009: Supply module (#786) ## Description Closes: #XXXX ADR-009 for supply module implementation. --- ### 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... - [ ] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [ ] added `!` to the type prefix if API or client breaking change - [ ] targeted the correct branch (see [PR Targeting](https://github.com/desmos-labs/desmos/blob/master/CONTRIBUTING.md#pr-targeting)) - [ ] provided a link to the relevant issue or specification - [ ] followed the guidelines for [building modules](https://docs.cosmos.network/v0.44/building-modules/intro.html) - [ ] included the necessary unit and integration [tests](https://github.com/desmos-labs/desmos/blob/master/CONTRIBUTING.md#testing) - [ ] added a changelog entry to `CHANGELOG.md` - [ ] included comments for [documenting Go code](https://blog.golang.org/godoc) - [ ] updated the relevant documentation or specification - [ ] 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 [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [ ] confirmed `!` in the type prefix if API or client breaking change - [ ] confirmed all author checklist items have been addressed - [ ] reviewed state machine logic - [ ] reviewed API design and naming - [ ] reviewed documentation is accurate - [ ] reviewed tests and test coverage - [ ] manually tested (if applicable) --- docs/architecture/adr-009-supply-module.md | 51 ++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/architecture/adr-009-supply-module.md diff --git a/docs/architecture/adr-009-supply-module.md b/docs/architecture/adr-009-supply-module.md new file mode 100644 index 0000000000..94ffd461dc --- /dev/null +++ b/docs/architecture/adr-009-supply-module.md @@ -0,0 +1,51 @@ +# ADR 009: Supply module + +## Changelog + +- March 21, 2022: Initial draft; +- March 21, 2022: First review; +- March 21, 2022: Second review. + +## Status + +DRAFTED + +## Abstract + +This ADR defines the `x/supply` module which will expose a set of APIs that can be called by data aggregator websites (such as CoinGecko and CoinMarketCap) in order to fetch updated data about a specific supply. + +## Context + +Currently, inside our [CoinGecko](https://www.coingecko.com/en/coins/desmos) and [CoinMarketCap](https://coinmarketcap.com/currencies/desmos/) some important information about current and total supply are missing or not correctly updated. To solve this, we can implement a series of APIs that read those data from the chain. Data aggregator websites that have the token listed can later use them. + +## Decision + +The APIs will be exposed in a new module called `x/supply` that will have the purpose to fetch the given information using different Cosmos SDK modules (namely `x/bank`, `x/distribution`, `x/staking`) and apply some conversions on them in order to display them the best way possible for the client. + +### Queries + +All the following APIs will have a custom param named `multiplier` that allows to set the multiplier to be used when returning the values. A `multiplier` of `0` will identify the whole token amount, while a multiplier of `1.000.000` will make the result display the values in millionth of units. + +#### Total Supply + +This query will fetch the total supply of a given token `denom`. + +#### Current supply + +This query will return the circulating supply by subtracting the total vested tokens amount and community pool amount from the total supply of the given token. + +## Consequences + +### Positive +- All the chain nodes will expose these APIs automatically after their node updates; +- No state-breaking changes introduced; +- Easily extensible. + +## Test Cases + +- Check API to correctly return the converted total Supply from millionth to non-millionth representation; +- Check API to correctly return the current supply. + +## References + +- Issue [#733](https://github.com/desmos-labs/desmos/issues/773). \ No newline at end of file