Skip to content

Commit

Permalink
docs(adr): ADR-009: Supply module (#786)
Browse files Browse the repository at this point in the history
## 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)
  • Loading branch information
leobragaz authored Mar 23, 2022
1 parent 73a6816 commit 43d6ddf
Showing 1 changed file with 51 additions and 0 deletions.
51 changes: 51 additions & 0 deletions docs/architecture/adr-009-supply-module.md
Original file line number Diff line number Diff line change
@@ -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).

0 comments on commit 43d6ddf

Please sign in to comment.