From 280e51776cf0cb7c26781e74b44d5540fb4a2c82 Mon Sep 17 00:00:00 2001 From: Thomas Nguy Date: Fri, 7 Jan 2022 09:50:40 +0100 Subject: [PATCH 01/10] add spec for feemarket --- x/feemarket/spec/01_concepts.md | 20 +++++++++++++++ x/feemarket/spec/02_state.md | 45 +++++++++++++++++++++++++++++++++ x/feemarket/spec/03_keeper.md | 15 +++++++++++ x/feemarket/spec/04_events.md | 19 ++++++++++++++ x/feemarket/spec/05_params.md | 14 ++++++++++ x/feemarket/spec/README.md | 18 +++++++++++++ 6 files changed, 131 insertions(+) create mode 100644 x/feemarket/spec/01_concepts.md create mode 100644 x/feemarket/spec/02_state.md create mode 100644 x/feemarket/spec/03_keeper.md create mode 100644 x/feemarket/spec/04_events.md create mode 100644 x/feemarket/spec/05_params.md create mode 100644 x/feemarket/spec/README.md diff --git a/x/feemarket/spec/01_concepts.md b/x/feemarket/spec/01_concepts.md new file mode 100644 index 0000000000..6b2c48ddbd --- /dev/null +++ b/x/feemarket/spec/01_concepts.md @@ -0,0 +1,20 @@ + + +# 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. + +Unlike the Cosmos SDK local `minimal-gas-prices`, this value is persisted in the KVStore which make 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`. + +The transaction fee is calculated using the following the formula : + +`transaction fee = (baseFee + tip) * gas units (limit)` + diff --git a/x/feemarket/spec/02_state.md b/x/feemarket/spec/02_state.md new file mode 100644 index 0000000000..c92f3b5757 --- /dev/null +++ b/x/feemarket/spec/02_state.md @@ -0,0 +1,45 @@ + + +# State + +## 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. + +## Base Fee + +### NoBaseFee + +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. + +Those parameters allow us to introduce a static base fee or activate the base fee at a later stage. + +### 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 + +``` \ No newline at end of file diff --git a/x/feemarket/spec/03_keeper.md b/x/feemarket/spec/03_keeper.md new file mode 100644 index 0000000000..bde2b73256 --- /dev/null +++ b/x/feemarket/spec/03_keeper.md @@ -0,0 +1,15 @@ + + +# 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 +} + +``` \ No newline at end of file diff --git a/x/feemarket/spec/04_events.md b/x/feemarket/spec/04_events.md new file mode 100644 index 0000000000..601617c3fe --- /dev/null +++ b/x/feemarket/spec/04_events.md @@ -0,0 +1,19 @@ + + +# 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} | diff --git a/x/feemarket/spec/05_params.md b/x/feemarket/spec/05_params.md new file mode 100644 index 0000000000..569b240e9a --- /dev/null +++ b/x/feemarket/spec/05_params.md @@ -0,0 +1,14 @@ + + +# Parameters + +The `x/feemarket` module contains the following parameters: + +| Key | Type | Example | +| ----------------------------- | ------ | ----------- | +| NoBaseFee | bool | false | +| BaseFeeChangeDenominator | uint32 | 8 | +| ElasticityMultiplier | uint32 | 2 | +| InitialBaseFee | uint32 | 1000000000 | +| EnableHeight | uint32 | 0 | \ No newline at end of file diff --git a/x/feemarket/spec/README.md b/x/feemarket/spec/README.md new file mode 100644 index 0000000000..5d26e5ca14 --- /dev/null +++ b/x/feemarket/spec/README.md @@ -0,0 +1,18 @@ + + +# Feemarket + +## Abstract + +## Contents + +1. **[Concepts](01_concepts.md)** +2. **[State](02_state.md)** +3. **[Keeper](03_keeper.md)** +4. **[Events](04_events.md)** +5. **[Params](05_params.md)** \ No newline at end of file From 1d45e7a10fd353c2731c071764bec891de01ec06 Mon Sep 17 00:00:00 2001 From: Thomas Nguy Date: Mon, 10 Jan 2022 20:45:19 +0100 Subject: [PATCH 02/10] update spec from comments --- x/README.md | 10 +++ x/feemarket/spec/01_concepts.md | 16 +++- x/feemarket/spec/02_state.md | 43 ++-------- x/feemarket/spec/03_begin_block.md | 50 ++++++++++++ x/feemarket/spec/04_end_block.md | 13 ++++ .../spec/{03_keeper.md => 05_keeper.md} | 2 +- x/feemarket/spec/05_params.md | 14 ---- .../spec/{04_events.md => 06_events.md} | 2 +- x/feemarket/spec/07_params.md | 14 ++++ x/feemarket/spec/08_client.md | 78 +++++++++++++++++++ x/feemarket/spec/09_future_improvements.md | 7 ++ x/feemarket/spec/README.md | 12 ++- 12 files changed, 204 insertions(+), 57 deletions(-) create mode 100644 x/README.md create mode 100644 x/feemarket/spec/03_begin_block.md create mode 100644 x/feemarket/spec/04_end_block.md rename x/feemarket/spec/{03_keeper.md => 05_keeper.md} (96%) delete mode 100644 x/feemarket/spec/05_params.md rename x/feemarket/spec/{04_events.md => 06_events.md} (97%) create mode 100644 x/feemarket/spec/07_params.md create mode 100644 x/feemarket/spec/08_client.md create mode 100644 x/feemarket/spec/09_future_improvements.md diff --git a/x/README.md b/x/README.md new file mode 100644 index 0000000000..7ba8ba7992 --- /dev/null +++ b/x/README.md @@ -0,0 +1,10 @@ + + +# List of Modules + +Here are the modules required in Ethermint : + +- [Evm](evm/spec/README.md) - Implement the EVM as a Cosmos SDK module. +- [Feemarket](feemarket/spec/README.md) - Define a global variable fee for Cosmos transactions. \ No newline at end of file diff --git a/x/feemarket/spec/01_concepts.md b/x/feemarket/spec/01_concepts.md index 6b2c48ddbd..2d199b5eae 100644 --- a/x/feemarket/spec/01_concepts.md +++ b/x/feemarket/spec/01_concepts.md @@ -6,9 +6,12 @@ order: 1 ## 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. +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) -Unlike the Cosmos SDK local `minimal-gas-prices`, this value is persisted in the KVStore which make a reliable value for validators to agree upon. +- 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. ## Tip @@ -18,3 +21,12 @@ The transaction fee is calculated using the following the formula : `transaction fee = (baseFee + tip) * gas units (limit)` +## 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: +https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md + diff --git a/x/feemarket/spec/02_state.md b/x/feemarket/spec/02_state.md index c92f3b5757..24c9469770 100644 --- a/x/feemarket/spec/02_state.md +++ b/x/feemarket/spec/02_state.md @@ -4,42 +4,13 @@ order: 2 # State -## Block Gas Used +The x/feemarket module keeps state in two primary objects: + -The total gas used by current block is stored in the KVStore at `EndBlock`. +- block gas used + +`byte(1) -> byte(gas_used)` -It is initialized to `block_gas` defined in the genesis. +- base fee -## Base Fee - -### NoBaseFee - -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. - -Those parameters allow us to introduce a static base fee or activate the base fee at a later stage. - -### 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 - -``` \ No newline at end of file +`byte(2) -> byte(baseFee)` \ No newline at end of file diff --git a/x/feemarket/spec/03_begin_block.md b/x/feemarket/spec/03_begin_block.md new file mode 100644 index 0000000000..3de244f790 --- /dev/null +++ b/x/feemarket/spec/03_begin_block.md @@ -0,0 +1,50 @@ + + +# 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` + +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. + +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 + +``` \ No newline at end of file diff --git a/x/feemarket/spec/04_end_block.md b/x/feemarket/spec/04_end_block.md new file mode 100644 index 0000000000..efef3573c9 --- /dev/null +++ b/x/feemarket/spec/04_end_block.md @@ -0,0 +1,13 @@ + + +# 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. \ No newline at end of file diff --git a/x/feemarket/spec/03_keeper.md b/x/feemarket/spec/05_keeper.md similarity index 96% rename from x/feemarket/spec/03_keeper.md rename to x/feemarket/spec/05_keeper.md index bde2b73256..9fdc86894c 100644 --- a/x/feemarket/spec/03_keeper.md +++ b/x/feemarket/spec/05_keeper.md @@ -1,5 +1,5 @@ # Keeper diff --git a/x/feemarket/spec/05_params.md b/x/feemarket/spec/05_params.md deleted file mode 100644 index 569b240e9a..0000000000 --- a/x/feemarket/spec/05_params.md +++ /dev/null @@ -1,14 +0,0 @@ - - -# Parameters - -The `x/feemarket` module contains the following parameters: - -| Key | Type | Example | -| ----------------------------- | ------ | ----------- | -| NoBaseFee | bool | false | -| BaseFeeChangeDenominator | uint32 | 8 | -| ElasticityMultiplier | uint32 | 2 | -| InitialBaseFee | uint32 | 1000000000 | -| EnableHeight | uint32 | 0 | \ No newline at end of file diff --git a/x/feemarket/spec/04_events.md b/x/feemarket/spec/06_events.md similarity index 97% rename from x/feemarket/spec/04_events.md rename to x/feemarket/spec/06_events.md index 601617c3fe..2dbdc3e1d9 100644 --- a/x/feemarket/spec/04_events.md +++ b/x/feemarket/spec/06_events.md @@ -1,5 +1,5 @@ +order: 6 --> # Events diff --git a/x/feemarket/spec/07_params.md b/x/feemarket/spec/07_params.md new file mode 100644 index 0000000000..dc56981965 --- /dev/null +++ b/x/feemarket/spec/07_params.md @@ -0,0 +1,14 @@ + + +# Parameters + +The `x/feemarket` module contains the following parameters: + +| Key | Type | Example | Description | +| ----------------------------- | ------ | ----------- |------------- | +| NoBaseFee | bool | false | control the base fee adjustment | +| BaseFeeChangeDenominator | uint32 | 8 | parameter in the fee adjustment| +| ElasticityMultiplier | uint32 | 2 | parameter in the fee adjustment| +| InitialBaseFee | uint32 | 1000000000 | initial base fee when starting the adjustment | +| EnableHeight | uint32 | 0 | control the base fee adjustment| \ No newline at end of file diff --git a/x/feemarket/spec/08_client.md b/x/feemarket/spec/08_client.md new file mode 100644 index 0000000000..3fa48dab4f --- /dev/null +++ b/x/feemarket/spec/08_client.md @@ -0,0 +1,78 @@ + + +# 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" +``` \ No newline at end of file diff --git a/x/feemarket/spec/09_future_improvements.md b/x/feemarket/spec/09_future_improvements.md new file mode 100644 index 0000000000..ca73f9ccab --- /dev/null +++ b/x/feemarket/spec/09_future_improvements.md @@ -0,0 +1,7 @@ + + +# 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. + diff --git a/x/feemarket/spec/README.md b/x/feemarket/spec/README.md index 5d26e5ca14..730e589217 100644 --- a/x/feemarket/spec/README.md +++ b/x/feemarket/spec/README.md @@ -9,10 +9,16 @@ parent: ## Abstract +This document specifies the feemarket module which allows to define a global transaction fee for the network. + ## Contents 1. **[Concepts](01_concepts.md)** 2. **[State](02_state.md)** -3. **[Keeper](03_keeper.md)** -4. **[Events](04_events.md)** -5. **[Params](05_params.md)** \ No newline at end of file +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)** \ No newline at end of file From c9de1a93a060524fe1d6c08e37447ccc0e7ee60a Mon Sep 17 00:00:00 2001 From: Thomas Nguy Date: Fri, 14 Jan 2022 12:43:57 +0100 Subject: [PATCH 03/10] update spec --- x/README.md | 4 ++-- x/feemarket/spec/02_state.md | 10 ++++------ x/feemarket/spec/07_params.md | 10 +++++----- 3 files changed, 11 insertions(+), 13 deletions(-) diff --git a/x/README.md b/x/README.md index 7ba8ba7992..7a1ec07893 100644 --- a/x/README.md +++ b/x/README.md @@ -6,5 +6,5 @@ order: 0 Here are the modules required in Ethermint : -- [Evm](evm/spec/README.md) - Implement the EVM as a Cosmos SDK module. -- [Feemarket](feemarket/spec/README.md) - Define a global variable fee for Cosmos transactions. \ No newline at end of file +- [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. \ No newline at end of file diff --git a/x/feemarket/spec/02_state.md b/x/feemarket/spec/02_state.md index 24c9469770..90429c5c57 100644 --- a/x/feemarket/spec/02_state.md +++ b/x/feemarket/spec/02_state.md @@ -5,12 +5,10 @@ order: 2 # State The x/feemarket module keeps state in two primary objects: - -- block gas used - -`byte(1) -> byte(gas_used)` -- base fee -`byte(2) -> byte(baseFee)` \ No newline at end of file +| | 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 | diff --git a/x/feemarket/spec/07_params.md b/x/feemarket/spec/07_params.md index dc56981965..d0edbadf03 100644 --- a/x/feemarket/spec/07_params.md +++ b/x/feemarket/spec/07_params.md @@ -5,10 +5,10 @@ order: 7 --> The `x/feemarket` module contains the following parameters: -| Key | Type | Example | Description | +| Key | Type | Default Values | Description | | ----------------------------- | ------ | ----------- |------------- | | NoBaseFee | bool | false | control the base fee adjustment | -| BaseFeeChangeDenominator | uint32 | 8 | parameter in the fee adjustment| -| ElasticityMultiplier | uint32 | 2 | parameter in the fee adjustment| -| InitialBaseFee | uint32 | 1000000000 | initial base fee when starting the adjustment | -| EnableHeight | uint32 | 0 | control the base fee adjustment| \ No newline at end of file +| 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 | +| EnableHeight | uint32 | 0 | height which enable fee adjustment | \ No newline at end of file From 48f984ce8d61907e66d0ce1b8794ff41f8ebb446 Mon Sep 17 00:00:00 2001 From: Thomas Nguy Date: Fri, 14 Jan 2022 13:26:03 +0100 Subject: [PATCH 04/10] update abstract --- x/feemarket/spec/README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/x/feemarket/spec/README.md b/x/feemarket/spec/README.md index 730e589217..c19f741945 100644 --- a/x/feemarket/spec/README.md +++ b/x/feemarket/spec/README.md @@ -11,6 +11,16 @@ parent: This document specifies the feemarket module which allows to define a global transaction fee for the network. +This module has been designed to implement 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. + +For more reference to EIP1559: + +https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md + + + ## Contents 1. **[Concepts](01_concepts.md)** From e934b60a5467b292657ef0b16a4a04262e9ed009 Mon Sep 17 00:00:00 2001 From: Thomas Nguy Date: Fri, 14 Jan 2022 13:44:02 +0100 Subject: [PATCH 05/10] update with grpc query --- x/feemarket/spec/08_client.md | 16 +++++++++++++++- x/feemarket/spec/README.md | 2 +- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/x/feemarket/spec/08_client.md b/x/feemarket/spec/08_client.md index 3fa48dab4f..f42270c897 100644 --- a/x/feemarket/spec/08_client.md +++ b/x/feemarket/spec/08_client.md @@ -75,4 +75,18 @@ Example Output: key: ElasticityMultiplier subspace: feemarket value: "2" -``` \ No newline at end of file +``` + + +## 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 | diff --git a/x/feemarket/spec/README.md b/x/feemarket/spec/README.md index c19f741945..42bf40c803 100644 --- a/x/feemarket/spec/README.md +++ b/x/feemarket/spec/README.md @@ -11,7 +11,7 @@ parent: This document specifies the feemarket module which allows to define a global transaction fee for the network. -This module has been designed to implement EIP1559 in cosmos-sdk. +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. From 1ed1f9cc15d4678bc1bc29d560be427eb9cb665d Mon Sep 17 00:00:00 2001 From: Thomas Nguy Date: Mon, 17 Jan 2022 11:00:14 +0100 Subject: [PATCH 06/10] add more content for tip section --- x/feemarket/spec/01_concepts.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/x/feemarket/spec/01_concepts.md b/x/feemarket/spec/01_concepts.md index 2d199b5eae..912311b309 100644 --- a/x/feemarket/spec/01_concepts.md +++ b/x/feemarket/spec/01_concepts.md @@ -15,7 +15,10 @@ Unlike the Cosmos SDK local `minimal-gas-prices`, this value is persisted in the ## Tip -To be consistent with EIP-1559, the `tip` is a local value that each node can define and be added to the `baseFee`. +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 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 is calculated using the following the formula : From 9a0877634ed6bea6803d3ff1720a7c984655344a Mon Sep 17 00:00:00 2001 From: Thomas Nguy Date: Fri, 25 Feb 2022 11:00:31 +0900 Subject: [PATCH 07/10] update specs with latest behavior --- x/feemarket/spec/01_concepts.md | 13 +++++++------ x/feemarket/spec/02_state.md | 4 ++-- x/feemarket/spec/03_begin_block.md | 6 +++++- x/feemarket/spec/07_params.md | 4 ++-- x/feemarket/spec/README.md | 2 +- 5 files changed, 17 insertions(+), 12 deletions(-) diff --git a/x/feemarket/spec/01_concepts.md b/x/feemarket/spec/01_concepts.md index 912311b309..2f3314ae7e 100644 --- a/x/feemarket/spec/01_concepts.md +++ b/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 diff --git a/x/feemarket/spec/02_state.md b/x/feemarket/spec/02_state.md index 90429c5c57..9720c0a4d5 100644 --- a/x/feemarket/spec/02_state.md +++ b/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 | diff --git a/x/feemarket/spec/03_begin_block.md b/x/feemarket/spec/03_begin_block.md index 3de244f790..3db8ea5c79 100644 --- a/x/feemarket/spec/03_begin_block.md +++ b/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. diff --git a/x/feemarket/spec/07_params.md b/x/feemarket/spec/07_params.md index d0edbadf03..2a1c4cbaaa 100644 --- a/x/feemarket/spec/07_params.md +++ b/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 | \ No newline at end of file diff --git a/x/feemarket/spec/README.md b/x/feemarket/spec/README.md index 42bf40c803..5d4de798aa 100644 --- a/x/feemarket/spec/README.md +++ b/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: From b302783b98c6e5a3fe63ce808b90ea6224fd883a Mon Sep 17 00:00:00 2001 From: Thomas Nguy Date: Fri, 25 Feb 2022 16:38:31 +0900 Subject: [PATCH 08/10] cleanup unused store prefix --- x/feemarket/types/keys.go | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/x/feemarket/types/keys.go b/x/feemarket/types/keys.go index bfa6a9cfc1..26c122033b 100644 --- a/x/feemarket/types/keys.go +++ b/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} ) From 03d5d3bbfe31dc942003375d31c2c08f80960683 Mon Sep 17 00:00:00 2001 From: Thomas Nguy <81727899+thomas-nguy@users.noreply.github.com> Date: Fri, 25 Feb 2022 16:39:15 +0900 Subject: [PATCH 09/10] Update x/feemarket/spec/01_concepts.md --- x/feemarket/spec/01_concepts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/feemarket/spec/01_concepts.md b/x/feemarket/spec/01_concepts.md index 2f3314ae7e..32b65361a7 100644 --- a/x/feemarket/spec/01_concepts.md +++ b/x/feemarket/spec/01_concepts.md @@ -21,7 +21,7 @@ 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) +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) From 9c1bf439d2355ceef70801810433061b6433f1ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Federico=20Kunze=20K=C3=BCllmer?= <31522760+fedekunze@users.noreply.github.com> Date: Fri, 25 Feb 2022 09:42:54 -0300 Subject: [PATCH 10/10] Apply suggestions from code review --- x/feemarket/spec/01_concepts.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/x/feemarket/spec/01_concepts.md b/x/feemarket/spec/01_concepts.md index 32b65361a7..99d0e91ad8 100644 --- a/x/feemarket/spec/01_concepts.md +++ b/x/feemarket/spec/01_concepts.md @@ -21,7 +21,7 @@ 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) +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`) @@ -31,6 +31,5 @@ A transaction pricing mechanism introduced in Ethereum that includes fixed-per-b 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: -https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md +Reference: [EIP1559](https://eips.ethereum.org/EIPS/eip-1559)