Review zkEVM docs upto exit trees

Author: EmpieichO

docs/zkEVM/architecture/protocol/admin-role.md

@@ -45,7 +45,7 @@ The Admin can schedule and commit maintenance operations transactions in L1 usin
 
 **The Polygon zkEVM team has decided to use the [OpenZeppelin's TimelockController.sol contract](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/governance/TimelockController.sol) to inherit security as well to avoid the lengthy and complicated audit process**. We have changed the `getMinDelay` method in the contract and this modified implementation is named **PolygonZkEVMTimelock.sol** contract.
 
-In the event that the zkEVM contract system is in [Emergency Mode](malfunction-resistance/emergency-state.md), the new `getMinDelay` will set the time `minDelay` to 0. This is when the Security Council Multisig takes control.
+In the event that the zkEVM contract system is in [Emergency Mode](malfunction-resistance/emergency-state.md), the new `getMinDelay` sets the time `minDelay` to 0. This is when the Security Council Multisig takes control.
 
 The zKEVM Protocol’s Admin role is set to an instance of **PolygonZkEVMTimelock.sol** contract address since the deployment of the zk-rollup.
 

docs/zkEVM/architecture/protocol/incentive-mechanism.md

@@ -1,6 +1,6 @@
 In order to ensure the system's sustainability, actors must be compensated for correctly performing their roles and giving the protocol finality.
 
-Unless otherwise specified, the measures and rules presented here apply to cases in which the Sequencer and Aggregator roles are decentralised (i.e., when there are no Trusted Sequencer and no Trusted Aggregator).
+Unless otherwise specified, the measures and rules presented here apply to cases in which the Sequencer and Aggregator roles are decentralised (i.e., when there are no trusted sequencer and no trusted aggregator).
 
 ## L2 transaction fees and sequencing fees
 
@@ -44,7 +44,7 @@ $$
     \mathtt{batchReward} =  { \dfrac{ \textit{``}contract\ MATIC\ balance\textit{''}}{\textit{``}Quantity\ of\ batches\ not\ aggregated\ yet \textit{''}}}
 $$
 
-The following expression represents **the total amount of ETH value that the Aggregator will earn for the aggregation of a sequence of batches**:
+The following expression represents **the total amount of ETH value that the Aggregator earns for the aggregation of a sequence of batches**:
 
 $$
 \mathtt{\textit{`` }Aggregator net Ether income\textit{''}= \frac{batchReward ∗ nBatches}{MATIC/ETH} − L1AggTxGasFee}
@@ -61,7 +61,7 @@ where:
 
 The `batchFee` is automatically adjusted with every aggregation of a sequence by an independent Aggregator.
 
-This happens when the Trusted Aggregator isn't working properly and the `batchFee` variable needs to be changed to encourage aggregation. Further information on the Trusted Aggregator's inactivity or malfunctioning is provided in upcoming sections.
+This happens when the trusted aggregator isn't working properly and the `batchFee` variable needs to be changed to encourage aggregation. Further information on the trusted aggregator's inactivity or malfunctioning is provided in upcoming sections.
 
 An internal method called `_updateBatchFee`, is used to adjust `batchFee` storage variable.
 
@@ -71,8 +71,8 @@ function _updateBatchFee(uint64 newLastVerifiedBatch) internal
 
 The admin defines two storage variables that are used to **tune the fee adjustment function**:
 
-- `veryBatchTimeTarget`: it is **the targeted time of the verification of a batch**, so the `batchFee` variable will be updated to achieve this target, and
-- `multiplierBatchFee`: it is the batch fee multiplier, with 3 decimals that **ranges from 1000 to 1024**.
+- `veryBatchTimeTarget`, which is **the targeted time of the verification of a batch**, so the `batchFee` variable is updated to achieve this target, and
+- `multiplierBatchFee`, which is the batch fee multiplier, with 3 decimals **ranging from 1000 to 1024**.
 
 The function `_updateBatchFee` first determines how many of the aggregated batches are late. That is, those who are in the sequence but have not yet been aggregated.
 
@@ -82,7 +82,7 @@ The `diffBatches` variable represents the difference between late batches and th
 
 ### Case 1
 
-If there are more late batches than early batches in the sequence being aggregated, the following formula will be applied to the `batchFee` storage variable:
+If there are more late batches than early batches in the sequence being aggregated, the following formula is applied to the `batchFee` storage variable:
 
 $$
 \textit{`` }\mathtt{

docs/zkEVM/architecture/protocol/malfunction-resistance/aggregator-resistance.md

@@ -1,6 +1,6 @@
-In the same way that the system cannot reach L2 State finality without an active and well-functioning Sequencer, there can be no finality without an active and well-functioning Aggregator.
+In the same way that the system cannot reach L2 state finality without an active and well-functioning Sequencer, there can be no finality without an active and well-functioning Aggregator.
 
-The absence or failure of the Trusted Aggregator means that the L2 State transitions are never updated in L1. For this reason, L1 `PolygonZkEVM.sol` contract has a function named `verifyBatches` that allows anyone to aggregate sequences of batches.
+The absence or failure of the trusted aggregator means that the L2 state transitions are never updated in L1. For this reason, L1 `PolygonZkEVM.sol` contract has a function named `verifyBatches` that allows anyone to aggregate sequences of batches.
 
 ```pil
 function verifyBatches(
@@ -15,14 +15,14 @@ function verifyBatches(
 ) public ifNotEmergencyState
 ```
 
-As previously stated, the `verifyBatches` function accepts the same arguments as the `trustedVerifyBatches` function. However, the `verifyBatches` function adds two additional constraints for a sequence to be aggregated, as well as a new L2 State stage called Pending State.
+As previously stated, the `verifyBatches` function accepts the same arguments as the `trustedVerifyBatches` function. However, the `verifyBatches` function adds two additional constraints for a sequence to be aggregated, as well as a new L2 state stage called Pending state.
 
 Along with the conditions required in the `trustedVerifyBatches` function, the following conditions must also be met in `verifyBatches`:
 
 - The contract must not be in an emergency state
 - A `trustedAggregatorTimeout` storage variable delay from the timestamp of the last batch in the sequence (when the batch was sequenced) must have been passed. The contract administrator configures the `trustedAggregatorTimeout` variable.
 
-The function verifies the Zero-Knowledge proof of computational integrity if all of the conditions are met. However, unlike the `trustedVerifyBatches` function case, if verification is successful, the sequence is not aggregated immediately. Rather, the verified sequence is added to the `pendingStateTransitions` mapping, where it will be aggregated after a time delay determined by the `pendingStateTimeout`.
+The function verifies the zero-knowledge proof of computational integrity if all conditions are met. However, unlike the `trustedVerifyBatches` function, if verification is successful, the sequence is not immediately aggregated. Instead, the verified sequence is added to the `pendingStateTransitions` mapping and is aggregated after a delay specified by the `pendingStateTimeout`.
 
 ```
 // pendingStateNumber --> PendingState
@@ -41,24 +41,24 @@ struct PendingState {
 }
 ```
 
-Verified batch sequences remain in an intermediate state known as Pending state, where their state transition has not yet been consolidated. While in this state, neither the new L2 State root nor the bridge's new `GlobalExitRoot` have been added to the `batchNumToStateRoot` mapping.
+Verified batch sequences remain in an intermediate state known as Pending state, where their state transition has not yet been consolidated. While in this state, neither the new L2 state root nor the bridge's new `GlobalExitRoot` have been added to the `batchNumToStateRoot` mapping.
 
-The `lastPendingState` storage variable is used to keep track of the number of pending state transitions that need to be consolidated and serves as the mapping's key of entry. The Aggregator will receive the aggregation reward once the Zero-Knowledge proof has been verified.
+The `lastPendingState` storage variable is used to keep track of the number of pending state transitions that need to be consolidated and serves as the mapping's key of entry. The Aggregator receives an aggregation reward once the zero-knowledge proof has been verified.
 
-The below figure shows the L2 Stages timeline from a batch perspective, and the actions that triggers its inclusion in the next L2 State stage, when a batch sequence is Aggregated through the `verifyBatches` function.
+The below figure shows the L2 Stages timeline from a batch perspective, and the actions that triggers its inclusion in the next L2 state stage, when a batch sequence is Aggregated through the `verifyBatches` function.
 
 ![L2 State stages timeline with pending state](../../../../img/zkEVM/11l2-stages-timeline-pending.png)
 
 The presence of batch sequences in pending state has no effect on the correct and proper functioning of the protocol. Non-forced batch sequences are verified before pending ones, and not all sequences enter the pending state.
 
-The storage variable `lastVerifiedBatch` keeps track of the index of the most recently verified and aggregated batch. As a result, even if a batch sequence is pretentiously verified, the index of the last verified batch will be queried via a function called `getLastVerifiedBatch`.
+The storage variable `lastVerifiedBatch` keeps track of the index of the most recently verified and aggregated batch. As a result, even if a batch sequence is pretentiously verified, the index of the last verified batch is queried via a function called `getLastVerifiedBatch`.
 
 If there are any pending state transitions, this function returns the index of the last batch in that state; otherwise, it returns the `lastVerifiedBatch`.
 
 ```
 function getLastVerifiedBatch() public view returns (uint64)
 ```
 
-When the `sequenceBatches` function is called, an attempt is made to consolidate the pending state by calling the internal function `_tryConsolidatePendingState`. If the `pendingStateTimeout` has elapsed since the pending batches verification, this function will consolidate the pending state transitions. There is no need to check the Zero-Knowledge proof again because it has already been verified.
+When the `sequenceBatches` function is called, an attempt is made to consolidate the pending state by calling the internal function `_tryConsolidatePendingState`. If the `pendingStateTimeout` has elapsed since the pending batches verification, this function consolidates the pending state transitions. There is no need to check the zero-knowledge proof again because it has already been verified.
 
-This mechanism is designed to help in the detection of any soundness vulnerabilities that could otherwise be exploited in the Zero-Knowledge proof verification system, thereby protecting assets from being bridged out to the L2 by malicious actors.
+This mechanism is designed to help in the detection of any soundness vulnerabilities that could otherwise be exploited in the zero-knowledge proof verification system, thereby protecting assets from being bridged out to the L2 by malicious actors.

docs/zkEVM/architecture/protocol/malfunction-resistance/emergency-state.md

@@ -10,7 +10,7 @@ The following functions will be disabled while in the emergency state:
 
 As a result, while the contract is in the emergency state, the Sequencer cannot sequence batches. Meanwhile, the trusted Aggregator will be able to consolidate additional state transitions or override a pending state transition that can be proven to be non-deterministic.
 
-When the same sequence of batches is successfully verified with two different resulting L2 State root values, a non-deterministic state transition occurs. This situation could arise if a soundness vulnerability in the verification of the Zero-Knowledge proof of computational integrity is exploited.
+When the same sequence of batches is successfully verified with two different resulting L2 state root values, a non-deterministic state transition occurs. This situation could arise if a soundness vulnerability in the verification of the zero-knowledge proof of computational integrity is exploited.
 
 ## When is the emergency state activated?
 
@@ -68,4 +68,4 @@ To summarize, the emergency state can only be activated:
 
 - when the contract owner deems it appropriate, or
 - when aggregation activity is halted due to a `HALT_AGGREGATION_TIMEOUT`, or
-- when anyone can demonstrate that a pending state is non-deterministic.
+- when anyone can demonstrate that a pending state is non-deterministic.

docs/zkEVM/architecture/protocol/malfunction-resistance/sequencer-resistance.md

@@ -1,4 +1,4 @@
-Users must rely on a Trusted Sequencer for their transactions to be executed in the L2. However, users can include their transactions in a forced batch if they are unable to execute them through the Trusted Sequencer.
+Users must rely on a trusted sequencer for their transactions to be executed in the L2. However, users can include their transactions in a forced batch if they are unable to execute them through the trusted sequencer.
 
 A forced batch is a collection of L2 transactions that users can commit to L1 to publicly declare their intent to execute those transactions.
 
@@ -13,11 +13,11 @@ mapping(uint64 => bytes32) public forcedBatches;
 ```
 
 !!!caution
-    The Trusted Sequencer will include these forced batches in future sequences to maintain its status as a trusted entity. Otherwise, users will be able to demonstrate that they are being censored, and the Trusted Sequencer's trusted status will be revoked.
+    The trusted sequencer include these forced batches in future sequences to maintain its status as a trusted entity. Otherwise, users can demonstrate that they are being censored, and the trusted sequencer's trusted status is revoked.
 
-Although the Trusted Sequencer is incentivized to sequence the forced batches published in the `forcedBatches` mapping, this does not guarantee finality of the transactions' execution in those batches.
+Although the trusted sequencer is incentivized to sequence the forced batches published in the `forcedBatches` mapping, this does not guarantee finality of the transactions' execution in those batches.
 
-In order to ensure finality in the case of Trusted Sequencer's malfunction, the L1 `PolygonZkEVM.sol` contract has an alternative batch sequencing function called `sequenceForceBatches`. This function allows anyone to sequence forced batches that have been published for a time period, specified by the public constant `forceBatchTimeout`, yet they have not been sequenced. The timeout is set to 5 days.
+In order to ensure finality in the case of trusted sequencer's malfunction, the L1 `PolygonZkEVM.sol` contract has an alternative batch sequencing function called `sequenceForceBatches`. This function allows anyone to sequence forced batches that have been published for a time period, specified by the public constant `forceBatchTimeout`, yet they have not been sequenced. The timeout is set to 5 days.
 
 Any user can publish a batch to be forced by directly calling `forceBatch` function:
 
@@ -34,11 +34,11 @@ function sequenceForceBatches(
 ) external virtual isSenderAllowedToForceBatches
 ```
 
-In order to successfully publish forced batch to the `forcedBatches` mapping, the following conditions must be met, otherwise the transaction will revert;
+In order to successfully publish a forced batch to the `forcedBatches` mapping, the following conditions must be met, otherwise the transaction reverts;
 
 - The contract must not be in emergency state,
 - The force batches must be allowed,
-- The `maticAmount` argument must be higher than the MATIC fee per batch. It is the maximum amount of MATIC tokens the user is willing to pay as a forced batch publication fee. The fee for publishing a forced batch is the same as the fee for sequencing, and it is therefore set in the `batchFee` storage variable. Since the fee is paid when a forced batch is published, it will not be paid again when the batch is sequenced.
+- The `maticAmount` argument must be higher than the MATIC fee per batch. It is the maximum amount of MATIC tokens the user is willing to pay as a forced batch publication fee. The fee for publishing a forced batch is the same as the fee for sequencing, and it is therefore set in the `batchFee` storage variable. Since the fee is paid when a forced batch is published, it is not be paid again when the batch is sequenced.
 - The length of the transactions byte array must be less than the value of `MAX_TRANSACTIONS_BYTE_LENGTH` constant (which is set at 120000).
 
 The forced batch is entered in `forcedBatches` mapping keyed by its force batch index.
@@ -67,7 +67,7 @@ Storage slots (mapping entries) are only used to store a commitment of the force
 
 The contract sets the `minTimestamp` to the L1 block timestamp, at which point the forced batch is published.
 
-In the extremely unlikely event that the Trusted Sequencer fails, any user can use the `sequenceForceBatches` function to sequence forced batches:
+In the extremely unlikely event that the trusted sequencer fails, any user can use the `sequenceForceBatches` function to sequence forced batches:
 
 ```
 function sequenceForceBatches(
@@ -79,16 +79,18 @@ The `sequenceForceBatches` function is similar to the `sequenceBatches` function
 
 The `sequenceForceBatches` function determines whether each batch in the submitted sequence has been published to the `forcedBatches` mapping for a period of time greater than the `forceBatchTimeout`.
 
-Because the MATIC batch fee was paid at the time of publication, it will not be required to be paid again.
+Because the MATIC batch fee was paid at the time of publication, it is not required to be paid again.
 
-If the sequence of forced batches meets all of the sequence conditions, it will be added to the `sequencedBatches` mapping as a regular one. As a result, a `sequenceForceBatches` event will be generated.
+If the sequence of forced batches meets all of the sequence conditions, it is added to the `sequencedBatches` mapping as a regular one. As a result, a `sequenceForceBatches` event is generated.
 
 ```
 event SequenceForceBatches(uint64 indexed numBatch);
 ```
 
-Note that since the sequences of forced batches sequenced using the `sequenceForceBatches` function will never be in a trusted state, there will be a divergence between the node’s local trusted L2 State and the virtual L2 State committed in the L1 PolygonZkEVM.sol contract.
+Note that since the sequences of forced batches, sequenced using the `sequenceForceBatches` function, never reaches a trusted state, a divergence occurs between the node’s local trusted L2 state and the virtual L2 state committed in the L1 `PolygonZkEVM.sol` contract.
 
-This situation has been detected and handled by the node software. It will reorganise its local L2 State instance based on the L2 State retrieved from L1. The diagram below depicts the distinctions between trusted and virtual L2 states that occur when a forced batch sequence is executed.
+This situation has been detected and handled by the node software. It reorganises its local L2 state instance based on the L2 state retrieved from L1. 
 
-![Differences between trusted and virtual L2 State](../../../../img/zkEVM/10l2-diff-trustd-virtual-state.png)
+The below diagram depicts the distinction between trusted and virtual L2 states that occur when a forced batch sequence is executed.
+
+![Differences between trusted and virtual L2 state](../../../../img/zkEVM/10l2-diff-trustd-virtual-state.png)