Merge pull request 0xPolygon#396 from 0xPolygon/edit-user-fees

Edit zkEVM - effective gas docs

Author: EmpieichO

docs/img/zkEVM/gas-price-flows-i.png

@@ -0,0 +1,76 @@
+In this section we provide an elaborate discussion on how Polygon zkEVM network ensures transactions are executed with the best gas price for the user, while incurring minimal or no losses.
+
+You will learn how to sign transactions with the appropriate gas price ensuring:
+
+- There is minimal likelihood for your transactions to be reverted.
+- The sequencer prioritizes your transactions for execution.
+
+## How to avert rejection of transactions
+
+The first step is to ensure that users sign transactions with sufficient gas price, and thus ensure the transactions are included in the L2's pool of transactions.
+
+Polygon zkEVM's strategy is to use pre-execution of transactions so as to estimate each transaction's possible gas costs.
+
+### Suggested gas prices
+
+Due to fluctuations in the L1 gas price, the L2 network polls for L1 gas price every 5 seconds.
+
+The polled L1 gas prices are used to determine the appropriate L2 gas price to suggest to users.
+
+Since the L1 gas price is likely to change between when a user signs a transaction and when the transaction is pre-executed, the following parameters are put in place:
+
+-  A $5$-minute interval of several suggested gas prices, called $\texttt{MinAllowedPriceInterval}$.
+- During the $\texttt{MinAllowedPriceInterval}$, the user's transactions can be accepted for pre-execution, provided the $\texttt{SignedGasPrice}$ is higher than the lowest suggested gas price in the interval.
+- The lowest among the suggested gas prices is called $\texttt{L2MinGasPrice}$.
+
+![Figure: minimum allowed gas interval](../../../img/zkEVM/min-allowed-gas-interval.png)
+
+All transactions such that $\texttt{SignedGasPrice} > \texttt{L2MinGasPrice}$ are accepted for pre-execution.
+
+## How to avoid incurring losses in L2
+
+There are three measures put in place to help avoid incurring gas price-induced losses in the L2 network:
+
+- Pre-execution of transactions. 
+- The breakeven gas price: $\texttt{BreakEvenGasPrice}$.
+- The L2's net profit.
+
+### Transaction pre-execution
+
+You can use pre-execution to estimate the L2 resources each transaction will spend when processed.
+
+These resources are measured in terms of counters in the zkEVM's ROM, but are converted to gas units for better UX.
+
+This is the stage where transactions are either discarded or stored in the pool database, a pool of transactions waiting to be processed by the sequencer.
+
+The price of posting transaction data to L1 is charged to the zkEVM network at a full L1 price.
+
+Although computational costs in L2 may be accurately estimated, in cases where there is a reduction in such costs due to fewer L2 resources being spent, the user may be justified to sign a transaction with a very low gas price. But by signing such a low gas price, the user runs the risk of exhausting their wei reserves when transaction data is posted to L1.
+
+So then, if the use of $\texttt{L1GasPriceFactor = 0.04}$ is the only precautionary measure the L2 network takes in computing suggested gas prices, the L2 network will most likely incur losses.
+
+A $\texttt{suggestedFactor = 0.15}$ is therefore used to calculate each suggested gas price:
+
+$$
+\texttt{suggestedL2GasPrice} = \texttt{L1GasPrice} \cdot \texttt{suggestedFactor}
+$$
+
+The need for such a factor originates from the fact that the sequencer is obliged to process every transaction stored in the pool database, irrespective of its $\texttt{SignedGasPrice}$ and the prevailing L1 gas price.
+
+### Breakeven gas price
+
+Calculating the breakeven gas price is another measure used in the Polygon zkEVM network to mitigate possible losses.
+
+The breakeven gas price is calculated as a ratio of the total transaction cost and the amount of gas used:
+
+$$
+\texttt{BreakEvenGasPrice} = \frac{\texttt{TotalTxPrice}}{\texttt{GasUsed}}
+$$
+
+A marginal profit factor called $\texttt{NetProfit}$ is incorporated in the $\texttt{BreakEvenGasPrice}$ formula as a means of generating a fixed proportion of profit from the total gas fees. It is calculated as follows:
+
+$$
+\texttt{BreakEvenGasPrice} = \frac{\texttt{TotalTxPrice}}{\texttt{GasUsed}} \cdot \texttt{NetProfit}
+$$
+
+The breakeven gas price factor is set to $1.3$​, resulting in a 30% net profit.

docs/zkEVM/architecture/effective-gas/implement-egp-strat.md

@@ -0,0 +1,93 @@
+Here's how you can accurately determine the gas price to sign your transactions with when submitting transactions to the Polygon zkEVM network.
+
+Polygon zkEVM implements a mechanism called the Effective Gas Price (EGP) that guarantees fair gas fees in the interest of both the user and the network.
+
+Now that the EGP is in place, you can reduce any chance for a transaction revert, while making sure that accepted transactions receive your preferred prioritization. Meanwhile, the zkEVM network incurs minimal to no loss.
+
+## How gas fees work in Ethereum
+
+In Ethereum, gas fees for a transaction are decided using two adjustable parameters:
+
+- The $\texttt{gasLimit}$, which is the maximum amount of gas units the user is willing to buy in order for their transactions to be included in a block and processed on chain.
+- The $\texttt{gasPrice}$, that is, the amount of ETH a user is willing to pay for 1 gas unit. For instance, a gas price of 10 Gwei means the user is willing to pay 0.00000001 ETH for each unit of gas.
+
+At the beginning of each transaction, the amount of wei sufficient to cover transaction costs is deducted from the user's account balance. 
+
+That amount of wei is calculated as:
+
+$$
+\texttt{gasLimit} \cdot \texttt{gasPrice}
+$$
+
+The actual amount spent for the transaction is given by:
+
+$$
+\texttt{gasUsed} \cdot \texttt{gasPrice}
+$$
+
+And thus, any refund to the user is simply:
+
+$$
+\texttt{gasLimit} \cdot \texttt{gasPrice} - \texttt{gasUsed} \cdot \texttt{gasPrice}
+$$
+
+Transactions get reverted if the $\texttt{gasUsed}$ is greater than the $\texttt{gasLimit}$. Otherwise, the transaction is successful. 
+
+## Computing L2 gas fees
+
+The L2 gas price cannot simply be set to be the same as the L1 gas price (especially in the case of rollups where the goal is to reduce gas fees).
+
+Hence, we make the distinction between the two gas prices, and denote them as $\texttt{L2GasPrice}$ and $\texttt{L1GasPrice}$ respectively.
+
+It is important to calculate the appropriate L2 gas price while ensuring that transactions are successfully executed.
+
+Although the same formula is used, that is,
+
+$$
+\texttt{gasLimit} \cdot \texttt{gasPrice}
+$$
+
+and success is guaranteed if $\texttt{gasLimit}$ is greater than $\texttt{gasUsed}$, the gas used is determined by the gas cost for data availability plus the gas cost for transaction execution in L2.
+
+That is, 
+
+$$
+\texttt{gasUsed} = \texttt{DataCost} + (\texttt{L2 Execution gas cost})
+$$
+
+The total fees paid by the user is given by:
+
+$$
+\texttt{TotalTxPrice} = \texttt{DataCost} \cdot \texttt{L1GasPrice} + (\texttt{L2 Execution gas cost}) \cdot \texttt{L2GasPrice}
+$$
+
+Note that data availability is charged in L1 using the prevailing L1 gas price at the time of posting data.
+
+The main challenge is adjusting $\texttt{L2GasPrice}$ in terms of the $\texttt{L1GasPrice}$ to account for L2 resources spent when processing transactions.
+
+The general strategy is to use an $\texttt{L1GasPriceFactor}$ such that
+
+$$
+\texttt{L2GasPrice} = \texttt{L1GasPrice} \cdot \texttt{L1GasPriceFactor}
+$$
+
+### Example (L1 gas price factor)
+
+For a transaction with an L1 gas price of 20 Gwei, the L2 gas price in the Polygon zkEVM network is calculated using a 4% factor as follows:
+
+$$
+\texttt{L2GasPrice}\ =\ 20\ \text{Gwei}⋅0.04=0.8\ \text{Gwei}
+$$
+
+Current L2 fees can be viewed here [https://l2fees.info](https://l2fees.info/).
+
+The $\texttt{L1GasPriceFactor}$ is used in the Polygon zkEVM network and is set to $0.04$​. 
+
+There are a few complications that need to be carefully considered. 
+
+
+There are 3 scenarios we aim to avoid when determining the $\texttt{L2GasPrice}$ to sign transactions with:
+
+- Transactions getting rejected due to the $\texttt{SignedGasPrice}$ being less than L2's minimum expected gas price ($\texttt{L2MinGasPrice}$).
+- Incurring losses in the L2 network because of high transaction gas costs.
+- Transactions receiving the least priority for sequencing.

docs/zkEVM/architecture/effective-gas/index.md

@@ -0,0 +1,127 @@
+Users can sign transactions with gas prices higher than the suggested gas price for prioritized sequencing. That is,
+
+$$
+\texttt{SignedGasPrice} > \texttt{suggestedGasPrice}
+$$
+
+The priority ratio is defined as:
+
+$$
+\texttt{PriorityRatio} = \frac{\texttt{SignedGasPrice}}{\texttt{suggestedGasPrice}} - 1
+$$
+
+Any transaction with $\mathtt{SignedGasPrice \leq GasPriceSuggested}$, implies that the user has chosen not to have the transaction prioritized.
+
+## Computing effective gas price
+
+The computation of the effective gas price (or EGP) involves both the break even gas price and the priority ratio: 
+
+$$
+\texttt{EffectiveGasPrice} = \texttt{BreakEvenGasPrice} \cdot \big(1 + \texttt{PriorityRatio}\big)
+$$
+
+Among the transactions stored in the pool database, the transactions with higher $\texttt{effectiveGasPrice}$ are prioritized at the time of sequencing due to the added $\texttt{PriorityRatio}$.
+
+### Gas consumption deviations
+
+Since the actual gas consumed can deviate from the estimated gas consumption, we denote the estimated $\texttt{EGP}$ and the 'new' $\texttt{EGP}$ as $\texttt{EEGP}$ and $\texttt{NEGP}$, respectively.
+
+The extent of the deviation can be computed as a percentage:
+
+$$
+\frac{|{\texttt{NEGP} - \texttt{EEGP}}|}{\texttt{EEGP}} \cdot 100
+$$
+
+The deviation percentage is compared to a parameter called $\texttt{FinalDeviationParameter}$, which is set to $10$.
+
+This presents 2 scenarios and their corresponding consequences:
+
+1. If the percentage deviation is lower than the final deviation parameter,
+   
+   $$
+   \frac{|\texttt{NEGP} − \texttt{EEGP}|}{\texttt{EEGP}} \cdot 100 < \texttt{FinalDeviationParameter} = 10,
+   $$
+   
+   it indicates that there is minimal distinction between charging the user with $\texttt{NEGP}$ compared to $\texttt{EEGP}$.
+   
+   Despite potential losses to the network, the user gets charged the $\texttt{EEGP}$ amount as the gas price. 
+
+2. On the contrary, if the percentage deviation equals or exceeds the deviation parameter,
+   
+   $$
+   \frac{|\texttt{NEGP} − \texttt{EEGP}|}{\texttt{EEGP}} \cdot 100 ≥ \texttt{FinalDeviationParameter}  = 10,
+   $$
+   
+   the difference between executions can be so big it warrants adjustment of the gas price to be $\texttt{NEGP}$ to mitigate potential losses to the network.
+   
+### Effective percentage
+
+The last parameter called the $\texttt{EffectivePercentage}$ is used to measure the unused portion of the user's signed gas price. 
+
+In order to calculate the $\texttt{EffectivePercentage}$, one option is to consider pricing resources based on the number of consumed counters within the Polygon zkEVM's proving system.
+
+However, understanding this metric can be challenging for users because stating the efficiency through counters is a bit complicated.
+
+In favor of better UX, a formula involving gas is applied as it is more user-friendly.
+
+The primary objective is to compute $\texttt{EffectivePercentage}$ exclusively using gas, while allowing users to prioritize their transactions through the use of gas price, without the need for complex considerations such as used ROM counters.
+
+The effective percentage is computed as follows:
+
+$$
+\texttt{EffectivePercentage} = \frac{ \texttt{GasPriceFinal}}{ \texttt{SignedGasPrice}}
+$$
+
+where $\texttt{GasPriceFinal}$ is the gas price charged at the end of the entire processing by the sequencer. 
+
+Note that the amount of wei that the user is charged for processing their transactions can be adjusted by modifying $\texttt{GasPriceFinal}$.
+
+This $\texttt{EffectivePercentage}$ is provided by the sequencer as a single byte:
+
+$$
+\texttt{EffectivePercentageByte} \in \{ 0, 1, . . . , 255 \}
+$$
+
+which is computed from the $\texttt{EffectivePercentage}$ as follows:
+
+$$
+\texttt{EffectivePercentageByte} = \lfloor \texttt{EffectivePercentage} · 256 \rfloor − 1
+$$
+
+Since having $\texttt{EffectivePercentage}$ implies having $\texttt{EffectivePercentageByte}$ and vice versa, the two terms are used interchangeably. 
+
+So, $\texttt{EffectivePercentageByte}$ is often referred to as $\texttt{EffectivePercentage}$.
+
+**Example (Effective percentage)**
+
+Setting an $\texttt{EffectivePercentageByte}$ of $255\ (= \texttt{0xFF})$ means the $\texttt{EffectivePercentage} = 1$. 
+
+In which case the user would pay the gas price they signed with, when sending the transaction, in total. That is:
+
+$$
+\texttt{GasPriceFinal} = \texttt{SignedGasPrice}
+$$
+
+In contrast, setting $\texttt{EffectivePercentageByte}$ to $127$ means:
+
+$$
+\texttt{EffectivePercentage} = 0.5
+$$
+
+Thus, only half of the gas price the user signed with gets charged as the transaction cost:
+
+$$
+\texttt{GasPriceFinal} = \frac{\texttt{SignedGasPrice}}{2}
+$$
+
+The transaction execution incurs only half of the signed gas price.
+
+## Concluding remarks
+
+The effective gas price scheme, as outlined above, although steeped in details, takes all necessary factors and eventualities into consideration.
+
+Ultimately, the scheme is accurate and fair to both the users and the zkEVM network.
+
+Check out this [repo](https://github.com/0xPolygonHermez/zkevm-rom/issues/316) for a detailed example of how the effective gas price is calculated.
+
+A more elaborate and expanded documentation of the EGP scheme can be found in the specifications section [here](../../spec/user-fees/index.md).

docs/zkEVM/architecture/effective-gas/tx-prioritization-egp.md

@@ -0,0 +1,9 @@
+Next, we provide a concise description of Polygon zkEVM's approach to calculating the effective gas price.
+
+It's an overview of the end-to-end flow of transactions, commencing from users signing transactions and submitting them at the RPC level, to when the sequencer executes them.
+
+It's a quicker way to go through all involved formulas or criteria, but without explanatory examples.
+
+You will find more elaborate discussions, with ample examples, in the [Specifications section](../../../spec/user-fees/index.md).
+
+The end-to-end flow of transactions occurs in two phases: the RPC flow, and the sequencer flow.

docs/zkEVM/architecture/effective-gas/user-tx-flow/index.md

@@ -0,0 +1,57 @@
+The RPC flow phase of transactions consists of two stages:
+
+- The gas price suggestion.
+- Pre-execution of transactions. 
+
+This flow ends with transactions being stored in a pool waiting to be executed by the sequencer.
+
+## Gas price suggestion
+
+The L2 network (the zkEVM) polls for L1 gas price values and uses them to:
+
+- Suggest L2 gas price to users as per user requests.
+- Sets the minimum acceptable L2 gas price, denoted by $\texttt{L2MinGasPrice}$.
+
+The user then signs transactions with the appropriate gas price, called $\texttt{GasPriceSigned}$, based on the suggested L2 gas price, $\texttt{GasPriceSuggested}$.
+
+Transactions are accepted for pre-execution only if
+
+$$
+\texttt{GasPriceSigned} > \texttt{L2MinGasPrice}
+$$
+
+## Pre-execution of transactions
+
+Pre-execution of transactions, which happens at the RPC level, involves estimating the gas required for processing the transactions submitted by the users. 
+
+This is internally measured (internal to the zkEVM) in terms of resources spent to execute the transactions. These resources are the numbers of counters used up in the zkEVM ROM. 
+
+A transaction is said to be _out of counters_ (OOC) if the signed gas price is insufficient to pay for the required gas units.
+
+OOC transactions get rejected straight away, while those with no OOC stand a chance to be added to the pool.
+
+At this stage of the flow, the RPC also computes the "breakeven gas price", denoted by $\texttt{BreakEvenGasPriceRPC}$. That is, 
+
+$$
+  \texttt{BreakEvenGasPrice} = \frac{\texttt{TotalTxPrice}}{\texttt{GasUsedRPC}} \cdot \texttt{NetProfit},
+$$
+
+ where $\texttt{NetProfit}$ is the L2's marginal profit  for transaction processing.   
+
+Transactions with no OOC get added to the pool of transactions if,
+
+- Either $\texttt{GasPriceSigned} > \texttt{BreakEvenGasPriceRPC} \cdot \texttt{BreakEvenFactor}$.
+  
+  where $\texttt{GasUsedRPC}$ is the RPC's estimated gas cost.
+  
+- Or $\texttt{GasPriceSigned} \geq \texttt{GasPriceSuggested}$.
+
+The total fees paid by the user is given by:
+
+$$
+\texttt{TotalTxPrice} = \texttt{DataCost} \cdot \texttt{L1GasPrice} + (\texttt{L2 Execution gas cost}) \cdot \texttt{L2GasPrice}
+$$
+
+The RPC flow is summarized in the figure below.
+
+![Figure: RPC flow](../../../../img/zkEVM/gas-price-flows-i.png)