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 transations with the gas price that ensures:
+
+- 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 above the least among the suggested gas prices in the interval.
+- The least of 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 basically three measures put in place to avoid incurring losses in the L2 network:
+
+- Pre-execution of transactions. 
+- The breakeven gas price: $\texttt{BreakEvenGasPrice}$.
+- The L2's net profit.
+
+### Transaction pre-execution
+
+Pre-execution of transactions is used to estimate L2 resources each transaction will spent 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{suggestFactor}
+$$
+
+Such a factor is justifiable considering 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}}
+$$
+
+In order to attain some profit for processing transactions, a marginal profit factor called $\texttt{NetProfit}$ is incorporated in the $\texttt{BreakEvenGasPrice}$ formula 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,92 @@
+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), so as to guarantee fair gas fees for the benefit 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 or no loss.
+
+## How gas fees work in Ethereum
+
+In Ethereum, users decide on two 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 completed.
+- The $\texttt{gasPrice}$, that is, the amount of wei a user is willing to pay for 1 gas unit.
+
+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, transaction succeed. 
+
+## Computing L2 gas fees
+
+The L2 gas price cannot be simply set to be the same as L1 gas price (more especially in the particular case of rollups, where the main benefit for using a rollup is to reduce gas fees).
+
+For this reason we henceforth distinguish between the two gas prices, and denote them as: $\texttt{L2GasPrice}$ and $\texttt{L1GasPrice}$.
+
+But how can you 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 the 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 "How to adjust $\texttt{L2GasPrice}$ in terms of the $\texttt{L1GasPrice}$, so as to account for L2 resources spent when processing the user's transaction?"
+
+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 obtained with 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/).
+
+Although this factor is used in the Polygon zkEVM network, in fact $\texttt{L1GasPriceFactor}$ is set to $0.04$​, there are a few complications that need to be carefully considered. 
+
+So the question remains: What gas price should the user sign transactions with?
+
+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 who want their transactions to be priotized for sequencing can sign their transactions with gas prices that are higher than the suggested gas price. 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)
+$$
+
+It’s important to observe that, among all the transactions stored in the pool database, those that are prioritized at the time of sequencing are those with higher $\texttt{effectiveGasPrice}$, due to the added $\texttt{PriorityRatio}$.
+
+### Gas consumption deviations
+
+Since the actual gas consumed can deviate from the estimated gas consumption, we can introduce the estimated $\texttt{EGP}$ and the 'new' $\texttt{EGP}$, and denote them 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 higher than the fixed 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}$​, and thus mitigate for potential losses to the network.
+   
+### Effective percentage
+
+The last parameter called the $\texttt{EffectivePercentage}$ is for measuring 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 intricate.
+
+For positive UX's sake, a better alternative is taken. 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. 
+
+Observe that, by modifying $\texttt{GasPriceFinal}$, the amount of wei that the user is charged for processing their sent transactions can be adjusted.
+
+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
+$$
+
+so, 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 takes 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 the Polygon zkEVM's approach to an effective gas price.
+
+It's an overview of the end-to-end flow of transactions, from when users sign transactions and submit 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 [here](../../../spec/user-fees/index.md).
+
+The end-to-end flow of transactions has 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 storing transactions in the pool, which is a pool of transactions 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, at the users' request.
+- 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}$.
+
+User's 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 user's transactions. 
+
+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 all the required gas units.
+
+Transactions with OOC get rejected, 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 "break-even-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)