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>

x/README.md

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

x/feemarket/spec/01_concepts.md

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

x/feemarket/spec/02_state.md

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

x/feemarket/spec/03_begin_block.md

@@ -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
+
+```

x/feemarket/spec/04_end_block.md

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

x/feemarket/spec/05_keeper.md

@@ -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
+}
+
+```

x/feemarket/spec/06_events.md

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

x/feemarket/spec/07_params.md

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

x/feemarket/spec/08_client.md

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

x/feemarket/spec/09_future_improvements.md

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

x/feemarket/spec/README.md

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

x/feemarket/types/keys.go

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