update specs with latest behavior

x/feemarket/spec/01_concepts.md

@@ -11,18 +11,19 @@ The base fee is a global base fee defined at the consensus level. It is adjusted
 - 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 persisted in the KVStore which provides a reliable value for validators to agree upon.
+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
 
-To be consistent with EIP-1559, the `tip` is a local value that each node can define and be added to the `baseFee` in order to incentive transaction prioritization.
+In EIP-1559, the `tip` is a value that can be added to the `baseFee` in order to incentive transaction prioritization.
 
-In Cosmos SDK there is no notion of prioritization, but there is a notion of minimum gas fee that does not exist in the Ethereum.
-To comply with both design, we decided to make the tip equals to the `minimal-gas-prices` value defined locally by each validator nodes.
+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 transactions in Ethermint should be zero (MaxPriorityFeePerGas endpoint returns 0)
 
-The transaction fee is calculated using the following the formula :
 
-`transaction fee = (baseFee + tip) * gas units (limit)` 
 
 ## EIP-1559
 

x/feemarket/spec/02_state.md

@@ -4,11 +4,11 @@ order: 2
 
 # State
 
-The x/feemarket module keeps state in two primary objects:
+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        |
-| BaseFee          | block's base fee               | `[]byte{2}`    | `[]byte(baseFee)`   | KV        |

x/feemarket/spec/03_begin_block.md

@@ -12,7 +12,11 @@ The base fee is calculated at the beginning of each block.
 
 We introduce two parameters : `NoBaseFee`and `EnableHeight`
 
-In case `NoBaseFee = true` or `height < EnableHeight`, the base fee value will be equal to `base_fee` defined in the genesis and the `BeginBlock` will return without further computation.
+`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.
 

x/feemarket/spec/07_params.md

@@ -9,6 +9,6 @@ The `x/feemarket` module contains the following parameters:
 | ----------------------------- | ------ | ----------- |------------- |
 | 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 maximum gas limit an EIP-1559 block may have |
-| InitialBaseFee                | uint32 | 1000000000  | initial base fee for EIP-1559 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/README.md

@@ -13,7 +13,7 @@ This document specifies the feemarket module which allows to define a global tra
 
 This module has been designed to support EIP1559 in cosmos-sdk.
 
-The `MempoolFeeDecorator` in `x/auth` module can be override to check the `baseFee` along with the `minimal-gas-prices` allowing to implement a global fee mechanism which vary depending on the network activity. 
+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: