You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This section of the docs provides a detailed analysis of the full topology of the Polygon zero-knowledge system architecture.
6
4
7
5
Tailored for CDK stacks and using zkEVM technology, these documents explore the contents, layout, and interactions among component systems and functions. They offer in-depth descriptions of the components that constitute the larger system, with references to relevant code bases.
Copy file name to clipboardExpand all lines: docs/zkEVM/architecture/protocol/admin-role.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -45,7 +45,7 @@ The Admin can schedule and commit maintenance operations transactions in L1 usin
45
45
46
46
**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.
47
47
48
-
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.
48
+
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.
49
49
50
50
The zKEVM Protocol’s Admin role is set to an instance of **PolygonZkEVMTimelock.sol** contract address since the deployment of the zk-rollup.
Copy file name to clipboardExpand all lines: docs/zkEVM/architecture/protocol/incentive-mechanism.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
In order to ensure the system's sustainability, actors must be compensated for correctly performing their roles and giving the protocol finality.
2
2
3
-
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).
3
+
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).
The following expression represents **the total amount of ETH value that the Aggregator will earn for the aggregation of a sequence of batches**:
47
+
The following expression represents **the total amount of ETH value that the Aggregator earns for the aggregation of a sequence of batches**:
48
48
49
49
$$
50
50
\mathtt{\textit{`` }Aggregator net Ether income\textit{''}= \frac{batchReward ∗ nBatches}{MATIC/ETH} − L1AggTxGasFee}
@@ -61,7 +61,7 @@ where:
61
61
62
62
The `batchFee` is automatically adjusted with every aggregation of a sequence by an independent Aggregator.
63
63
64
-
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.
64
+
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.
65
65
66
66
An internal method called `_updateBatchFee`, is used to adjust `batchFee` storage variable.
67
67
@@ -71,8 +71,8 @@ function _updateBatchFee(uint64 newLastVerifiedBatch) internal
71
71
72
72
The admin defines two storage variables that are used to **tune the fee adjustment function**:
73
73
74
-
-`veryBatchTimeTarget`: it is **the targeted time of the verification of a batch**, so the `batchFee` variable will be updated to achieve this target, and
75
-
-`multiplierBatchFee`: it is the batch fee multiplier, with 3 decimals that **ranges from 1000 to 1024**.
74
+
-`veryBatchTimeTarget`, which is **the targeted time of the verification of a batch**, so the `batchFee` variable is updated to achieve this target, and
75
+
-`multiplierBatchFee`, which is the batch fee multiplier, with 3 decimals ranging from 1000 to 1024.
76
76
77
77
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.
78
78
@@ -82,7 +82,7 @@ The `diffBatches` variable represents the difference between late batches and th
82
82
83
83
### Case 1
84
84
85
-
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:
85
+
If there are more late batches than early batches in the sequence being aggregated, the following formula is applied to the `batchFee` storage variable:
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.
1
+
Over the past few years, several L2 solutions have been developed to enhance the scalability of the Ethereum network, with a focus on increasing transaction throughput. The benefit for users of the Ethereum network is to lower gas fees without compromising decentralization and security.
2
2
3
-
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.
3
+
Polygon zkEVM is an L2 rollup solution that combines data availability and execution verification on L1, the Ethereum network, in order to ensure security and reliability of each L2 state transition.
4
4
5
-
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.
5
+
This section describes the overall design of the Polygon zkEVM. It thus provides an architectural overview of its protocol.
6
6
7
7
## Components
8
8
9
-
This section describes the components used in the Polygon zkEVM to enable transaction finality while ensuring the correctness of state transitions.
9
+
It takes three main components of the Polygon zkEVM protocol to enable transaction finality while ensuring the correctness of state transitions:
10
10
11
-
The three main components of zkEVM protocol are:
12
-
13
-
- Trusted sequencer.
14
-
- Trusted aggregator.
15
-
- Consensus contract (PolygonZkEVM.sol, deployed on L1).
11
+
- The trusted sequencer.
12
+
- The trusted aggregator.
13
+
- The consensus contract (`PolygonZkEVM.sol`, deployed on L1).
16
14
17
15
### Trusted sequencer
18
16
19
-
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.
17
+
The trusted sequencer receives L2 transactions from users, orders them, generates blocks of trasactions, fills batches, and submits them to the consensus contract's storage slots in the form of sequences.
20
18
21
-
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.
19
+
The trusted sequencer processes batches and distributes them to L2 network nodes to achieve immediate finality and reduce costs associated with high network usage, all before submitting them to L1.
22
20
23
-
The Trusted sequencer must run a zkEVM node in sequencer mode and be in control of a consensus contract-enforced Ethereum account.
21
+
The trusted sequencer runs a zkEVM node in sequencer mode and controls an Ethereum account regulated by a consensus contract.
24
22
25
23
### Trusted aggregator
26
24
27
-
The trusted aggregator component can compute the L2 State based on batches of L2 transactions executed by the trusted sequencer.
25
+
The trusted aggregator computes the L2 state based on batches of L2 transactions executed by the trusted sequencer.
28
26
29
-
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.
27
+
On the other hand, the primary function of the trusted aggregator is to receive the L2 batches validated by the trusted sequencer and produce zero-knowledge proofs verifying the computational integrity of these batches. The aggregator achieves this by employing a specialized off-chain EVM interpreter to generate the ZK proofs.
30
28
31
-
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.
29
+
The logic within the consensus contract verifies the zero-knowledge proofs, thereby endowing the zkEVM with the security of Layer 1. Before committing new L2 state roots to the consensus contract, verification is essential. A validated proof serves as undeniable evidence that a particular sequence of batches resulted in a specific L2 state.
32
30
33
31
!!!info
34
32
L2 state root
35
33
36
-
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 [this article](https://ethereum.org/en/developers/docs/scaling/zk-rollups/#state-commitments).
34
+
An L2 state root is a cryptographic hash value of the L2 state. In case you want to read more about state roots, please check out [this article](https://ethereum.org/en/developers/docs/scaling/zk-rollups/#state-commitments).
37
35
38
-
The trusted aggregator should run a zkEVM node in aggregator mode and must control a specific Ethereum account enforced in a consensus contract.
36
+
The trusted aggregator runs a zkEVM node in aggregator mode and controls an Ethereum account regulated by a consensus contract.
39
37
40
38
### Consensus contract
41
39
42
40
The consensus contract used by both the trusted sequencer and the trusted aggregator in their interactions with L1 is the `PolygonZkEVM.sol` contract.
43
41
44
42
The trusted sequencer can commit batch sequences to L1 and store them in the `PolygonZkEVM.sol` contract, creating a historical repository of sequences.
45
43
46
-
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.
44
+
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 proper execution of transaction batches.
47
45
48
46
## zkEVM node execution modes
49
47
@@ -59,10 +57,10 @@ There is also a database to temporarily store transactions that have not yet bee
59
57
60
58
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.
61
59
62
-
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.
60
+
Also, it 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.
63
61
64
62
### RPC mode
65
63
66
-
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.
64
+
In this mode, the zKEVM node has limited functionality. It primarily maintains an up-to-date instance of the L2 state, initially with respect to batches broadcast by the trusted sequencer, and later with sequences of batches fetched from the consensus contract.
67
65
68
-
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 synchronizer is every 2 seconds, unless stipulated otherwise in the configuration.
66
+
The RPC node continuously interacts with L1 to keep the local L2 state up-to-date and to verify the synchronization of L2 state roots. By default, the synchronizer updates every 2 seconds, unless a different interval is specified in the configuration.
Copy file name to clipboardExpand all lines: docs/zkEVM/architecture/protocol/malfunction-resistance/aggregator-resistance.md
+10-10Lines changed: 10 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
-
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.
1
+
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.
2
2
3
-
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.
3
+
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.
4
4
5
5
```pil
6
6
function verifyBatches(
@@ -15,14 +15,14 @@ function verifyBatches(
15
15
) public ifNotEmergencyState
16
16
```
17
17
18
-
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.
18
+
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 pending state.
19
19
20
20
Along with the conditions required in the `trustedVerifyBatches` function, the following conditions must also be met in `verifyBatches`:
21
21
22
22
- The contract must not be in an emergency state
23
23
- 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.
24
24
25
-
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`.
25
+
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`.
26
26
27
27
```
28
28
// pendingStateNumber --> PendingState
@@ -41,24 +41,24 @@ struct PendingState {
41
41
}
42
42
```
43
43
44
-
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.
44
+
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.
45
45
46
-
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.
46
+
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.
47
47
48
-
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.
48
+
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.
49
49
50
50
51
51
52
52
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.
53
53
54
-
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`.
54
+
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`.
55
55
56
56
If there are any pending state transitions, this function returns the index of the last batch in that state; otherwise, it returns the `lastVerifiedBatch`.
57
57
58
58
```
59
59
function getLastVerifiedBatch() public view returns (uint64)
60
60
```
61
61
62
-
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.
62
+
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.
63
63
64
-
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.
64
+
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.
0 commit comments