Skip to content

Commit

Permalink
docs: add x/fees spec (#833)
Browse files Browse the repository at this point in the history
## Description

This PR adds the spec folder to the x/fees module, containing the whole specifications.

Depends-On: #834
Depends-On: #842

---

### 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 [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
- [x] 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
- [x] reviewed "Files changed" and left comments if necessary
- [x] 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
RiccardoM authored May 16, 2022
1 parent ce5e1d1 commit be95a13
Show file tree
Hide file tree
Showing 6 changed files with 189 additions and 0 deletions.
16 changes: 16 additions & 0 deletions x/fees/spec/01_concepts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<!--
order: 1
-->

# Concepts

## Minimum fees
A minimum fee represents the minimum amount of `sdk.Coins` that must be present inside the transaction fees when broadcasting a message of a given type. Setting a minimum fee of `100token` for a message types means that users will need to pay at least `100token` for each message of that type they broadcast. Trying to broadcast a transaction with multiple message of such types will require the user to pay `n * min_fee` fees or above.

For each message type, there can only be a single minimum fee amount that needs to be paid at any given time.

A single minimum fee amount can be made of multiple coin amounts, so that if a minimum fee amount is set to `100tokenA,50tokenB` this means that for each message of such type the user will have to pay at least 100 `tokenA` **and** 50 `tokenB` to make sure the transaction is valid.

If a transaction contains multiple messages of different kinds, each one having a custom minimum fee amount, the overall transaction fee must be greater or equal to the sum of all the minimum fee amounts. So that if a transaction contains one message which minimum fee amount is `100tokenA` and other one which minimum fee is `100tokenB`, the overall transaction fee will have to be `100tokenA + 100tokenB` or greater.

Failing to provide a transaction fee amount that is not enough to satisfy all the minimum fee requirements will lead to an invalid transaction.
6 changes: 6 additions & 0 deletions x/fees/spec/02_state.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
<!--
order: 2
-->

# State
The `fees` module does not store any state. Instead, it relies on the `params` module to store the [parameters](04_parameters.md).
16 changes: 16 additions & 0 deletions x/fees/spec/03_antehandlers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<!--
order: 3
-->

# AnteHandlers

The `fees` module presently has no transaction handlers of its own, but does expose the special `AnteHandler`, used for performing a validity check on a transaction, such that it could be thrown out of the mempool.
The `AnteHandler` can be seen as a set of decorators that check transactions within the current context, per [ADR 010](https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-alpha1/docs/architecture/adr-010-modular-antehandler.md).

Note that the `AnteHandler` is called on both `CheckTx` and `DeliverTx`, as Tendermint proposers presently have the ability to include in their proposed block transactions which fail `CheckTx`.

## Decorators

The fees module provides the following `AnteDecorator`:

* `MinFeeDecorator`: Checks if the `tx` fee is greater or equal to the minimum fee amount computed looking the messages present inside the transaction itself.
19 changes: 19 additions & 0 deletions x/fees/spec/04_parameters.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<!--
order: 4
-->

# Parameters

The fees module contains the following parameters:

| Key | Type | Example |
|---------|----------|-----------------------------------------------------------------------------------------------------------------|
| MinFees | []MinFee | `[{ "message_type": "/desmos.profiles.v2.SaveProfile", "amount": [ { "amount": "100", "denom": "tokenA" } ] }]` |

## MinFees
The `MinFees` is an array of `MinFee` object, each one made of two different fields:

* `MessageType` (string), representing the type url of the message which the min fees refer to
* `Amount` (`[]Coin`), representing the amount of min fees associated with the message

Inside the `MinFees`, there can only be a single entry for each `MessageType`.
107 changes: 107 additions & 0 deletions x/fees/spec/05_client.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
<!--
order: 5
-->

# Client

## CLI

A user can query the `fees` module using the CLI.

### Query

The `query` commands allow users to query the `fees` state.

```
desmos query fees --help
```

#### parameters
The `parameters` command allows users to get hte currently set parameters.

```bash
desmos query fees parameters [flags]
```

Example:
```bash
desmos query fees parameters
```

Example Output:
```yaml
params:
min_fees:
- message_type: /desmos.profiles.v2.SaveProfile
amount:
- amount: "100"
denom: "stake"
```
## gRPC
A user can query the `fees` module gRPC endpoints.

### Params
The `Params` endpoint allows users to query the current params of the `fees` module.

```bash
desmos.fees.v1.Query/Params
```

Example:
```bash
grpcurl localhost:9090 desmos.fees.v1.Query/Params
```

Example Output:
```json
{
"params": {
"min_fees": [
{
"message_type": "/desmos.profiles.v2.SaveProfile",
"amount": [
{
"amount": "100",
"denom": "stake"
}
]
}
]
}
}
```

## REST
A user can query the `fees` module using REST endpoints.

### Params
The `params` endpoint allows users to query for the module parameters.

```bash
/desmos/fees/v1/params
```

Example:
```bash
curl localhost:1317/desmos/fees/v1/params
```

Example Output:
```json
{
"params": {
"min_fees": [
{
"message_type": "/desmos.profiles.v2.SaveProfile",
"amount": [
{
"amount": "100",
"denom": "stake"
}
]
}
]
}
}
```
25 changes: 25 additions & 0 deletions x/fees/spec/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
<!--
order: 0
title: Fees Overview
parent:
title: "fees"
-->

# `fees`

## Abstract

This document specified the fees module of Desmos.

The module allows on-chain governance to specify a minimum amount of fees that users need to pay when broadcasting specific message types.

## Contents
1. **[Concepts](01_concepts.md)**
- [Minimum Fee](01_concepts.md#minimum-fees)
2. **[State](02_state.md)**
3. **[AnteHandlers](03_antehandlers.md)**
4. **[Parameters](04_parameters.md)**
5. **[Client](05_client.md)**
- [CLI](05_client.md#cli)
- [gRPC](05_client.md#grpc)
- [REST](05_client.md#rest)

0 comments on commit be95a13

Please sign in to comment.