zkEVM, integrate 0xPolygon#47

Author: nadimkobeissi

docs/zkEVM/architecture/protocol/index.md

@@ -0,0 +1,68 @@
+Various Layer 2 solutions aimed at improving the scalability of the Ethereum network, primarily transaction throughput, have been developed over the past years. The ultimate and intended benefit for Ethereum network users is a reduction in gas fees, while maintaining decentralisation and security.
+
+Polygon zkEVM is a Layer 2 Rollup solution that combines data availability and execution verification in Layer 1 of the Ethereum blockchain to ensure L2 state transition security and reliability.
+
+This section will describe the infrastructure that Polygon designed and implemented for its zkEVM, with a focus on providing an overview of the components used in the development of the zkEVM Protocol.
+
+## Components
+
+This section describes the components used in the Polygon zkEVM to enable transaction finality while ensuring the correctness of state transitions.
+
+The three main components of zkEVM protocol are:
+
+- Trusted sequencer
+- Trusted aggregator, and
+- Consensus Contract (PolygonZkEVM.sol, deployed on L1)
+
+### Trusted sequencer
+
+The Trusted sequencer component is in charge of receiving L2 transactions from users, ordering them, generating batches, and submitting them to the Consensus contract's storage slots in the form of sequences.
+
+The sequencer executes and broadcasts batches of transactions to L2 network nodes in order to achieve fast finality and reduce costs associated with high network usage. That's before even submitting them to L1.
+
+The Trusted sequencer must run a zkEVM node in sequencer mode and be in control of a Consensus Contract-enforced Ethereum account.
+
+### Trusted aggregator
+
+The Trusted aggregator component can compute the L2 State based on batches of L2 transactions executed by the Trusted sequencer.
+
+The main role of the Trusted aggregator, on the other hand, is to take the L2 batches committed by the Trusted sequencer and generate Zero-Knowledge proofs attesting to the batches' computational integrity. These ZK proofs are generated by the aggregator using a special off-chain EVM interpreter.
+
+The Consensus Contract's logic validates the Zero-Knowledge proofs, resulting in the zkEVM inheriting the L1 security. Verification is required before committing new L2 State roots to the Consensus Contract. A verified proof is an irrefutable evidence that a given sequence of batches led to a specific L2 State.
+
+!!!info
+     L2 State Root
+
+     An L2 State root is a concise cryptographic digest of the L2 State. In case you want to read more about State roots, please check out [<ins>this article</ins>](https://ethereum.org/en/developers/docs/scaling/zk-rollups/#state-commitments).
+
+The Trusted aggregator should run a zkEVM node in aggregator mode and must control a specific Ethereum account enforced in a Consensus Contract.
+
+### Consensus contract
+
+The Consensus Contract used by both the Trusted sequencer and the Trusted aggregator in their interactions with L1 is the PolygonZkEVM.sol contract.
+
+The Trusted sequencer can commit batch sequences to L1 and store them in the `PolygonZkEVM.sol` contract, creating a historical repository of sequences.
+
+The `PolygonZkEVM.sol` Contract also enables the aggregator to publicly verify transitions from one L2 State root to the next. The Consensus Contract accomplishes this by validating the aggregator's ZK-proofs, which attest to the proper execution of transaction batches.
+
+## zkEVM node execution modes
+
+zkEVM node is a software package containing all components needed to run zkEVM network. It can be run in three different modes; as a sequencer, an aggregator, or RPC.
+
+### Sequencer mode
+
+In the sequencer mode, the node holds an instance of L2 State, manages batch broadcasting to other L2 network nodes, and has a built-in API to handle L2 user interactions (transaction requests and L2 State queries).
+
+There is also a database to temporarily store transactions that have not yet been ordered and executed (pending transactions pool), as well as all the components required to interact with L1 in order to sequence transaction batches and keep its local L2 State up to date.
+
+### Aggregator mode
+
+In the aggregator mode, the node has all the components needed to execute transaction batches, compute the resulting L2 State and generate the Zero-Knowledge proofs of computational integrity.
+
+Also, has all the components needed to fetch transaction batches committed in L1 by the Trusted sequencer and call the functions to publicly verify the L2 State transitions on L1.
+
+### RPC mode
+
+In the RPC mode, the zKEVM node has a limited functionality. It primarily maintains an up-to-date instance of L2 State, initially with respect to batches broadcast by the Trusted sequencer, and later with sequences of batches fetched from the Consensus Contract.
+
+The node continuously interacts with L1 in order to keep the local L2 State up to date, as well as to check the synchronization of L2 State roots. The default syncing rate for the synchroniser is every 2 seconds, unless stipulated otherwise in the configuration.

docs/zkEVM/architecture/protocol/introduction.md

@@ -6,7 +6,7 @@ The LXLY Bridge SC (or [PolygonZkEVMBridgeV2](https://github.com/0xPolygonHermez
 
 Its modular design capacitates projects to deploy their own rollups and connect them to the Polygon ecosystem.
 
-## Ideal Attributes
+## Ideal attributes
 
 The LXLY Bridge is deployed in the Polygon ecosystem so as to attain the following features and functionalities;
 
@@ -31,7 +31,7 @@ Version-1 consists mainly of three (3) smart contracts;
 
 Interaction of these three contracts has been detailed [here](zkevm-bridge/flow-of-assets.md).
 
-### Global Exit Trees Review
+### Global exit trees Review
 
 Critical to the design of the LXLY Bridge are Exit Trees and the Global Exit Tree.
 
@@ -54,7 +54,7 @@ Observe, in the above figure, that the Consensus Contract (PolygonZkEVM.sol) is
 - Retrieve the Global Exit Root from the mainnet, and make it available in L2, and
 - Update the Exit Tree Root in the Global Exit Tree Root manager.
 
-## LXLY Bridge Version-2 Design
+## LXLY bridge version-2 design
 
 Multiple zk-rollups such as zkEVMs, zk-Validiums or zk-VMs, can be created and connected through the same LXLY Bridge.
 
@@ -78,7 +78,7 @@ Once sequenced batches have been verified, the _Global Exit Tree_ gets updated,
 
 ![Figure 2: New version of bridge](../../../img/zkEVM/lxly-2-new-bridge-design.png)
 
-### Rollup Manager's Role
+### Rollup manager's role
 
 The Rollup Manager manages the following lists of availability;
 
@@ -107,7 +107,7 @@ The [Rollup Manager SC](https://github.com/0xPolygonHermez/zkevm-contracts/blob/
   - Governance SC invokes the Rollup Manager's `AddNewRollupType()` function,
   - Once, a rollup is created, the transfer of assets can be processed in the usual manner.
 
-### Overall Flow of Events
+### Overall flow of events
 
 The below diagram captures the following flow of events, most of which are handled by the Rollup Manager SC;
 

docs/zkEVM/architecture/protocol/lxly-bridge.md

@@ -15,7 +15,7 @@ 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`:
 
@@ -41,15 +41,15 @@ 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 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 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`.
 

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

@@ -8,19 +8,19 @@ The following functions will be disabled while in the emergency state:
 - `sequenceForceBatches`
 - `proveNonDeterministicPendingState`
 
-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.
+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?
 
-The emergency state can only be triggered by **two contract functions**:
+The emergency state can only be triggered by two contract functions:
 
 1. It can be directly activated by calling the `activateEmergencyState` function by contract owner.
 
 2. It can also be called by anyone after a `HALT AGGREGATION TIMEOUT` constant delay (of one week) has passed. The timeout begins when the batch corresponding to the `sequencedBatchNum` argument has been sequenced but not yet verified.
 
-This situation directly implies that **no one can aggregate batch sequences**. The objective is to **temporarily stop the protocol until aggregation activity resumes**.
+This situation directly implies that no one can aggregate batch sequences. The objective is to temporarily stop the protocol until aggregation activity resumes.
 
 ```
 function activateEmergencyState(uint64 sequencedBatchNum) external
@@ -64,7 +64,7 @@ function overridePendingState(
 
 To successfully override a pending state, the Trusted Aggregator must submit a proof that will be verified in the same way, as in the `proveNonDeterministicPendingState` function. If the proof is successfully verified, the pending state transition is wiped and a new one is directly consolidated.
 
-To summarize, **the emergency state can only be activated**:
+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