docs: add spec for feemarket module (#889)

* add spec for feemarket

* update spec from comments

* update spec

* update abstract

* update with grpc query

* add more content for tip section

* update specs with latest behavior

* cleanup unused store prefix

* Update x/feemarket/spec/01_concepts.md

* Apply suggestions from code review

Co-authored-by: Federico Kunze Küllmer <31522760+fedekunze@users.noreply.github.com>
This commit is contained in:
Thomas Nguy 2022-02-25 21:49:18 +09:00 committed by GitHub
parent 6095794cf0
commit a2c26208ed
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 308 additions and 3 deletions

10
x/README.md Normal file
View File

@ -0,0 +1,10 @@
<!--
order: 0
-->
# List of Modules
Here are the modules required in Ethermint :
- [EVM](evm/spec/README.md) - Implement the EVM as a Cosmos SDK module.
- [Fee Market](feemarket/spec/README.md) - Define a global variable fee for Cosmos transactions based on EIP-1559.

View File

@ -0,0 +1,35 @@
<!--
order: 1
-->
# Concepts
## Base fee
The base fee is a global base fee defined at the consensus level. It is adjusted for each block based on the total gas used in the previous block and gas target (block gas limit divided by elasticity multiplier)
- it increases when blocks are above the gas target
- it decreases when blocks are below the gas target
Unlike the Cosmos SDK local `minimal-gas-prices`, this value is stored as a module parameter which provides a reliable value for validators to agree upon.
## Tip
In EIP-1559, the `tip` is a value that can be added to the `baseFee` in order to incentive transaction prioritization.
The transaction fee in Ethereum is calculated using the following the formula :
`transaction fee = (baseFee + tip) * gas units (limit)`
In Cosmos SDK there is no notion of prioritization, thus the tip for an EIP-1559 transaction in Ethermint should be zero (`MaxPriorityFeePerGas` JSON-RPC endpoint returns `0`)
## EIP-1559
A transaction pricing mechanism introduced in Ethereum that includes fixed-per-block network fee that is burned and dynamically expands/contracts block sizes to deal with transient congestion.
Transactions specify a maximum fee per gas they are willing to pay total (aka: max fee), which covers both the priority fee and the block's network fee per gas (aka: base fee)
Reference: [EIP1559](https://eips.ethereum.org/EIPS/eip-1559)

View File

@ -0,0 +1,14 @@
<!--
order: 2
-->
# State
The x/feemarket module keeps in the state variable needed to the fee calculation:
Only BlockGasUsed in previous block needs to be tracked in state for the next base fee calculation.
| | Description | Key | Value | Store |
| ----------- | ------------------------------ | ---------------| ------------------- | --------- |
| BlockGasUsed | gas used in the block | `[]byte{1}` | `[]byte{gas_used}` | KV |

View File

@ -0,0 +1,54 @@
<!--
order: 3
-->
# Begin block
The base fee is calculated at the beginning of each block.
## Base Fee
### Disabling base fee
We introduce two parameters : `NoBaseFee`and `EnableHeight`
`NoBaseFee` controls the feemarket base fee value. If set to true, no calculation is done and the base fee returned by the keeper is zero.
`EnableHeight` controls the height we start the calculation.
- If `NoBaseFee = false` and `height < EnableHeight`, the base fee value will be equal to `base_fee` defined in the genesis and the `BeginBlock` will return without further computation.
- If `NoBaseFee = false` and `height >= EnableHeight`, the base fee is dynamically calculated upon each block at `BeginBlock`.
Those parameters allow us to introduce a static base fee or activate the base fee at a later stage.
### Enabling base fee
To enable EIP1559 with the EVM, the following parameters should be set :
- NoBaseFee should be false
- EnableHeight should be set to a positive integer >= upgrade height. It defines at which height the chain starts the base fee adjustment
- LondonBlock evm's param should be set to a positive integer >= upgrade height. It defines at which height the chain start to accept EIP1559 transactions
### Calculation
The base fee is initialized at `EnableHeight` to the `InitialBaseFee` value defined in the genesis file.
The base fee is after adjusted according to the total gas used in the previous block.
```golang
parent_gas_target = parent_gas_limit / ELASTICITY_MULTIPLIER
if EnableHeight == block.number
base_fee = INITIAL_BASE_FEE
else if parent_gas_used == parent_gas_target:
base_fee = parent_base_fee
else if parent_gas_used > parent_gas_target:
gas_used_delta = parent_gas_used - parent_gas_target
base_fee_delta = max(parent_base_fee * gas_used_delta / parent_gas_target / BASE_FEE_MAX_CHANGE_DENOMINATOR, 1)
base_fee = parent_base_fee + base_fee_delta
else:
gas_used_delta = parent_gas_target - parent_gas_used
base_fee_delta = parent_base_fee * gas_used_delta / parent_gas_target / BASE_FEE_MAX_CHANGE_DENOMINATOR
base_fee = parent_base_fee - base_fee_delta
```

View File

@ -0,0 +1,13 @@
<!--
order: 4
-->
# End block
The block_gas_used value is updated at the end of each block.
## Block Gas Used
The total gas used by current block is stored in the KVStore at `EndBlock`.
It is initialized to `block_gas` defined in the genesis.

View File

@ -0,0 +1,15 @@
<!--
order: 5
-->
# Keeper
The feemarket module provides this exported keeper that can be passed to other modules that need to get access to the base fee value
```go
type Keeper interface {
GetBaseFee(ctx sdk.Context) *big.Int
}
```

View File

@ -0,0 +1,19 @@
<!--
order: 6 -->
# Events
The `x/feemarket` module emits the following events:
## BeginBlocker
| Type | Attribute Key | Attribute Value |
| ---------- | --------------- | --------------- |
| fee_market | base_fee | {baseGasPrices} |
## EndBlocker
| Type | Attribute Key | Attribute Value |
| ---------- | --------------- | --------------- |
| block_gas | height | {blockHeight} |
| block_gas | amount | {blockGasUsed} |

View File

@ -0,0 +1,14 @@
<!--
order: 7 -->
# Parameters
The `x/feemarket` module contains the following parameters:
| Key | Type | Default Values | Description |
| ----------------------------- | ------ | ----------- |------------- |
| NoBaseFee | bool | false | control the base fee adjustment |
| BaseFeeChangeDenominator | uint32 | 8 | bounds the amount the base fee that can change between blocks |
| ElasticityMultiplier | uint32 | 2 | bounds the threshold which the base fee will increase or decrease depending on the total gas used in the previous block|
| BaseFee | uint32 | 1000000000 | base fee for EIP-1559 blocks |
| EnableHeight | uint32 | 0 | height which enable fee adjustment |

View File

@ -0,0 +1,92 @@
<!--
order: 8 -->
# Client
## CLI
A user can query and interact with the `feemarket` module using the CLI.
### Queries
The `query` commands allow users to query `feemarket` state.
```go
ethermintd query feemarket --help
```
#### Base Fee
The `base-fee` command allows users to query the block base fee by height.
```
ethermintd query feemarket base-fee [height] [flags]
```
Example:
```
ethermintd query feemarket base-fee 5...
```
Example Output:
```
base_fee: "512908936"
```
#### Block Gas
The `block-gas` command allows users to query the block gas by height.
```
ethermintd query feemarket block-gas [height] [flags]
```
Example:
```
ethermintd query feemarket block-gas 5...
```
Example Output:
```
gas: "21000"
```
#### Params
The `params` command allows users to query the module params.
```
ethermintd query params subspace [subspace] [key] [flags]
```
Example:
```
ethermintd query params subspace feemarket ElasticityMultiplier ...
```
Example Output:
```
key: ElasticityMultiplier
subspace: feemarket
value: "2"
```
## gRPC
### Queries
| Verb | Method | Description |
| ------ | ---------------------------------------------------- | -------------------------------------------------------------------------- |
| `gRPC` | `ethermint.feemarket.v1.Query/Params` | Get the module params |
| `gRPC` | `ethermint.feemarket.v1.Query/BaseFee` | Get the block base fee |
| `gRPC` | `ethermint.feemarket.v1.Query/BlockGas` | Get the block gas used |
| `GET` | `/feemarket/evm/v1/params` | Get the module params |
| `GET` | `/feemarket/evm/v1/base_fee` | Get the block base fee |
| `GET` | `/feemarket/evm/v1/block_gas` | Get the block gas used |

View File

@ -0,0 +1,7 @@
<!--
order: 9 -->
# Future Improvements
- The feemarket module has been designed mainly to support EIP-1559 on EVM-based chain on cosmos, supporting non-EVM chain could be done as a future improvements.

View File

@ -0,0 +1,34 @@
<!--
order: 0
title: Feemarket Overview
parent:
title: "feemarket"
-->
# Feemarket
## Abstract
This document specifies the feemarket module which allows to define a global transaction fee for the network.
This module has been designed to support EIP1559 in cosmos-sdk.
The `MempoolFeeDecorator` in `x/auth` module needs to be overrided to check the `baseFee` along with the `minimal-gas-prices` allowing to implement a global fee mechanism which vary depending on the network activity.
For more reference to EIP1559:
https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md
## Contents
1. **[Concepts](01_concepts.md)**
2. **[State](02_state.md)**
3. **[Begin Block](03_begin_block.md)**
4. **[End Block](04_end_block.md)**
5. **[Keeper](05_keeper.md)**
6. **[Events](06_events.md)**
7. **[Params](07_params.md)**
8. **[Client](08_client.md)**
9. **[Future Improvements](09_future_improvements.md)**

View File

@ -12,14 +12,12 @@ const (
RouterKey = ModuleName
)
// prefix bytes for the EVM persistent store
// prefix bytes for the feemarket persistent store
const (
prefixBlockGasUsed = iota + 1
prefixBaseFee
)
// KVStore key prefixes
var (
KeyPrefixBlockGasUsed = []byte{prefixBlockGasUsed}
KeyPrefixBaseFee = []byte{prefixBaseFee}
)