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
Copy file name to clipboardExpand all lines: docs/zkEVM/architecture/high-level/overview.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,16 +12,16 @@ The diagram below is a full and detailed topological overview of the entire Poly
12
12
13
13
## Components
14
14
15
-
- Smart contracts: L1 and L2 Solidity smart contracts used for interacting with the whole stack. See the discussion on [zkEVM smart contracts](../../architecture/protocol/zkevm-bridge/smart-contracts.md) for more information.
16
-
- Exit root trees: Append-only sparse Merkle trees which record the current and historical state of the system. See the discussion on [zkEVM exit trees](../../architecture/protocol/zkevm-bridge/exit-tree.md) for more information.
15
+
- Smart contracts: L1 and L2 Solidity smart contracts used for interacting with the whole stack.
16
+
- Exit root trees: Append-only sparse Merkle trees which record the current and historical state of the system.
17
17
- CDK and zkEVM nodes containing:
18
18
- JSON RPC client: Exposes the read/write interfaces for interacting with a node/chain.
19
19
- Pool database: The pool database records transaction requests coming in from the JSON RPC client and sends them to the sequencer.
20
20
- State database: The state database responds to read requests from the JSON RPC client.
21
21
- Sequencer: Does the complex job of carefully sequencing transactions as they come in before sending them to the aggregator for batching. See the discussion on [sequencers](../../architecture/index.md#sequencer) for more information.
22
22
- Aggregator: Used for aggregating transaction batches to send to the prover. See the discussion on [aggregators](../../architecture/index.md#aggregator) for more information.
23
23
- Synchronizer: This component ensures a synchronized state between the node's systems and the L1 outside-world via the Etherman component and the state database.
24
-
- Etherman component: The Etherman helps the synchronizer maintain a synchronized state with L1 by communicating with the L1 Ethereum chain via smart contract methods.
24
+
- Etherman component: The Etherman helps the synchronizer maintain a synchronized state with L1 by communicating with the L1 Ethereum chain via smart contract functions.
25
25
- Bridge service component: Provides an API to perform bridge claims, i.e. asset and message transfers between L1/L2 and L2/L2.
26
26
- Prover component: System for calculating zero-knowledge proofs on transaction batches.
Bridge functionality allows token and message passing between L1 and L2.
1
+
The unified bridge transfers assets and messages between L1 and L2 networks by calling bridge and claim functions on the unified bridge smart contract.
2
2
3
-
The smart contract that manages bridging across L1 and L2 is the [PolygonZkEVMBridgeV2.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/main/contracts/v2/PolygonZkEVMBridgeV2.sol) contract.
Using the exit roots of the Merkle tree, referenced by the bridge contract and accessible to the `PolygonRollupManager` contract, the bridge contract synchronizes data across the L1 and L2 chains, the sequencer component, and the state db.
5
+
## Smart contract definition
6
6
7
-
!!! tip
8
-
- Read more about the bridge in our [bridging documentation](../../protocol/zkevm-bridge/index.md)
9
-
7
+
The smart contract that manages bridging and claiming across networks is the [PolygonZkEVMBridgeV2.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/main/contracts/v2/PolygonZkEVMBridgeV2.sol) contract. It is deployed on both L1 and L2 networks.
8
+
9
+
### Bridge and claim assets
10
+
11
+
Bridging and claiming assets is managed by the `bridgeAsset` and the `claimAsset` functions.
12
+
13
+
These functions allow data payloads to be sent across networks.
14
+
15
+
#### `bridgeAsset`
16
+
17
+
To send an asset from L1 to L2, the sender first transfers the token from the user into the bridge by locking the asset on the origin network (L1).
18
+
19
+
```solidity
20
+
IERC20Upgradeable(token).safeTransferFrom(
21
+
msg.sender,
22
+
address(this),
23
+
amount
24
+
);
25
+
```
26
+
27
+
From L2 to L1, the wrapped token is burnt on the L2 network:
28
+
29
+
```solidity
30
+
TokenWrapped(token).burn(msg.sender, amount);
31
+
```
32
+
33
+
#### `claimAsset`
34
+
35
+
From L1 to L2, the bridge smart contract mints an equivalent asset, called a wrapped token, on the destination network (L2).
Once minted, the recipient can claim the token on the destination network (L2).
44
+
45
+
In reverse, the bridge smart contract unlocks the original asset on the origin network (L1).
46
+
47
+
## Updating system state
48
+
49
+
The Polygon bridge smart contract uses exit trees to manage state.
50
+
51
+
On a successful transfer, the bridge contract adds an exit leaf to the relevant exit tree.
52
+
53
+
```solidity
54
+
_addLeaf(
55
+
getLeafValue(
56
+
_LEAF_TYPE_ASSET, // or _LEAF_TYPE_MESSAGE_
57
+
originNetwork,
58
+
originTokenAddress,
59
+
destinationNetwork,
60
+
destinationAddress,
61
+
leafAmount,
62
+
keccak256(metadata)
63
+
)
64
+
);
65
+
```
66
+
67
+
This triggers an update to the exit tree root which then propagates to an update on the global exit tree root.
68
+
69
+
Using these Merkle tree exit roots, referenced by the bridge contract and accessible to the `PolygonRollupManager` contract with getters, the bridge contract synchronizes data across L1 and L2, the sequencer component, and the state db.
70
+
71
+
The use of two distinct global exit root manager contracts for L1 and L2, as well as separate logic for the bridge contract and each of these global exit root managers, allows for extensive network interoperability.
72
+
73
+
Meanwhile, all asset transfers can be validated by any L1 and L2 node due to the accessibility of state data.
74
+
75
+
## Transaction flows
76
+
77
+
### L1 to L2
78
+
79
+
1. If a call to the `bridgeAsset` or `bridgeMessage` passes validation, the bridge contract appends an exit leaf to the L1 exit tree and computes the new L1 exit tree root.
80
+
81
+
2. The global exit root manager appends the new L1 exit tree root to the global exit tree and computes the global exit root.
82
+
83
+
3. The sequencer fetches the latest global exit root from the global exit root manager.
84
+
85
+
4. At the start of the transaction batch, the sequencer stores the global exit root in special storage slots of the L2 global exit root manager smart contract, allowing L2 users to access it.
86
+
87
+
5. A call to `claimAsset` or `claimMessage` provides a Merkle proof that validates the correct exit leaf in the global exit root.
88
+
89
+
6. The bridge contract validates the caller's Merkle proof against the global exit root. If the proof is valid, the bridging process succeeds; otherwise, the transaction fails.
90
+
91
+
### L2 to L1
92
+
93
+
1. If a `bridgeAsset` or `bridgeMessage` call on the L2 bridge contract validates, the bridge contract appends an exit leaf to the L2 exit tree and computes the new L2 exit tree root.
94
+
95
+
2. The L2 global exit root manager appends the new L2 exit tree toot to the global exit tree and computes the global exit root. At that point, the caller's bridge transaction is included in one of batches selected and sequenced by the sequencer.
96
+
97
+
3. The aggregator generates a zk-proof attesting to the computational integrity in the execution of sequenced batches which include the transaction.
98
+
99
+
4. For verification purposes, the aggregator sends the zk-proof together with all relevant batch information that led to the new L2 exit tree root (computed in step 2), to the consensus contract.
100
+
101
+
5. The consensus contract utilizes the `verifyBatches` function to verify validity of the received zk-proof. If valid, the contract sends the new L2 exit tree root to the global exit root manager in order to update the global exit tree.
102
+
103
+
6.`claimMessage` or `claimAsset` is then called on the bridge contract with Merkle proofs for correct validation of exit leaves.
104
+
105
+
7. The bridge contract retrieves the global exit root from the L1 global exit root manager and verifies validity of the Merkle proof. If the Merkle proof is valid, the bridge completes. Otherwise, the transaction is reverted.
106
+
107
+
### L2 to L2
108
+
109
+
1. When a batch of transactions is processed, the bridge contracts appends the L2 exit tree with a new leaf containing the batch information. This updates the L2 exit tree root.
110
+
111
+
2. The bridge contracts communicates the L2 exit tree root to the L2 global exit root manager. The L2 global exit root manager, however, does not update the global exit tree at this stage.
112
+
113
+
3. For proving and verification, the zk-proof-generating circuit obtains the L2 exit tree root from the L2 global exit root manager.
114
+
115
+
4. Only after the batch has been successfully proved and verified does the L2 global exit root manager append the L2 exit tree root to the global exit tree. As a result, the global exit root is updated.
116
+
117
+
The zk-proof-generating circuit also writes the L2 exit tree root to the mainnet. The L1 bridge contract can then finalize the transfer by using the `claim` function.
Copy file name to clipboardExpand all lines: docs/zkEVM/architecture/high-level/smart-contracts/exit-roots.md
+104-5Lines changed: 104 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ Whenever a token or message is bridged, the bridge contract appends an exit leaf
4
4
5
5
## Local exit trees
6
6
7
-
The bridge uses a special Merkle tree called a local exit tree for each network that participates in bridging and claiming.
7
+
The L2 bridge has a special Merkle tree called a local exit tree for each network that participates in bridging and claiming.
8
8
9
9
<center>
10
10
@@ -14,7 +14,7 @@ Data from `bridgeAsset()` and `bridgeMessage()` calls on the bridge is stored in
14
14
15
15
## Exit tree for rollups
16
16
17
-
The roots of the local exit trees feed into an exit tree for all participating L2 rollups.
17
+
The roots of the local exit trees feed into a single exit tree that manages state from all participating L2 rollups.
18
18
19
19
<center>
20
20
@@ -40,6 +40,105 @@ The GER is the fingerprint of the information stored in all trees, and thus repr
40
40
41
41
</center>
42
42
43
-
!!! tip
44
-
- Read more about exit trees in our [exit tree documentation](../../protocol/zkevm-bridge/exit-tree.md).
45
-
43
+
## Exit leaves
44
+
45
+
Two constants define leaf types in the bridge contract.
46
+
47
+
```solidity
48
+
// Leaf type asset
49
+
uint8 private constant _LEAF_TYPE_ASSET = 0;
50
+
51
+
// Leaf type message
52
+
uint8 private constant _LEAF_TYPE_MESSAGE = 1;
53
+
```
54
+
55
+
An exit leaf, in particular, is a Keccak256 hash of the ABI encoded packed structure with the following parameters:
56
+
57
+
- uint8 leafType: [0] asset, [1] message.
58
+
- int32 originNetwork: Origin network ID, where the original asset belongs.
59
+
- address originAddress: If `leafType = 0`, Origin network token address (`0x0000...0000`) is reserved for ether. If `leafType = 1`, `msg.sender` of the message.
- address destinationAddress: Address that receives the bridged asset in the destination network.
62
+
- uint256 amount: Amount of tokens/ether to bridge.
63
+
- bytes32 metadataHash: Hash of the metadata. This metadata contains information about asset transferred or the message payload.
64
+
65
+
When a user commits to transferring assets from one network to another, the bridge contract adds an exit leaf to that network's exit tree.
66
+
67
+
The Merkle root of an exit tree is known as the exit tree root, and it is the fingerprint of all the information recorded in the exit tree's leaf nodes.
68
+
69
+
As a result, given any network exit tree, whether L1 or L2, its exit tree root is the source of state truth for that network.
70
+
71
+
## Global exit tree
72
+
73
+
Consider a scenario of bridging assets between the L1 Mainnet and L2 network. The global exit tree is a binary Merkle tree whose leaf nodes are the L1 exit tree's Merkle root and the L2 exit tree's Merkle root. A global exit tree is depicted in the figure below.
74
+
75
+
76
+
77
+
The Merkle root of the global exit tree is called the global exit root.
78
+
79
+
Whenever a new exit leaf is added to an exit tree, a new root for that exit tree is calculated. Consequently, the global exit tree is updated with this new root. As a result, the global exit root always reflects the current state of both networks.
80
+
81
+
Since the Merkle root of each exit tree represents the true state of its respective network, the most recent global exit root consequently represents the true state of all networks, that is, both the L1 and L2 networks.
82
+
83
+
Once the global exit root is synchronized between the L1 and L2 networks, users can use a Merkle proof to verify the inclusion of the correct exit leaf, allowing them to claim their transferred assets.
84
+
85
+
This is how a complete asset transfer or cross-chain messaging is achieved: it starts with the bridge function in the origin network and concludes with the claim function in the destination network, with exit tree roots conveying the true state at both ends.
86
+
87
+
## Asset transfer scenarios
88
+
89
+
In this subsection, we present two scenarios to illustrate the role of exit trees and the global exit tree in the asset transfer process.
90
+
91
+
### Transfer from L1 to rollup L2
92
+
93
+
Consider a scenario where a user wants to transfer assets from the L1 Mainnet to the L2 Rollup.
94
+
95
+
Once the user commits to a transfer, a new exit leaf with the information of the assets being bridged is appended to the L1 exit tree. The transfer data typically looks like this:
96
+
97
+
```
98
+
Origin network: 0 (L1)
99
+
Origin address: 0x56566...
100
+
Dest Network: 1 (L2)
101
+
Dest Address: 0x12345...
102
+
Amount: 145
103
+
Metadata: 0x0...
104
+
```
105
+
106
+
With the newly added exit leaf, the L1 exit tree now has a new root. Updating the global exit tree with this new L1 exit tree root means changing the root of the global exit tree.
107
+
108
+
To claim the bridged assets on the destination L2 network, the global exit root is verified using a Merkle proof. This proof allows one to confirm whether an exit leaf, containing information about assets being bridged to L2, is represented in the global exit tree by the corresponding L1 exit tree root.
109
+
110
+
111
+
112
+
### Transfer from rollup L2 to L1
113
+
114
+
Transfers can also occur from an L2 Rollup to the L1 mainnet. In this scenario, the same procedure outlined in the previous example is followed, but in the reverse direction.
115
+
116
+
That is, once a user commits to a transfer, an exit leaf is added to the L2 exit tree with corresponding transfer information. The transfer data in this case looks as follows:
117
+
118
+
```
119
+
Origin network: 3 (L2)
120
+
Origin address: 0x34655...
121
+
Dest Network: 0 (L1)
122
+
Dest Address: 0x27564...
123
+
Amount: 92
124
+
Metadata: 0x116...
125
+
```
126
+
127
+
The newly added L2 exit leaf means the L2 exit tree has a new root. The new L2 exit tree Root is then appended to the global exit tree, and thus the root of the global exit tree is updated.
128
+
129
+
130
+
131
+
## Global Exit Root manager contract
132
+
133
+
The Global Exit Root Manager SC (PolygonZkEVMGlobalExitRoot.sol) manages the Global Exit Tree Root. It is in charge of updating the Global Exit Tree Root and acts as a repository for the Global Exit Tree's history.
134
+
135
+
The logic of the zkEVM Bridge SC has been separated from that of the Global Exit Root Manager SC in order to achieve improved interoperability.
136
+
137
+
This means that the zkEVM Bridge SC, in conjunction with the Global Exit Root Manager SC, can be installed in any network to achieve the same results.
138
+
139
+
!!!info
140
+
There are two Global Exit Root manager SCs: one deployed in L1, while the other is deployed in L2.
141
+
142
+
Their Solidity code files are; [PolygonZkEVMGlobalExitRoot.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/main/contracts/PolygonZkEVMGlobalExitRoot.sol), and [PolygonZkEVMGlobalExitRootL2.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/main/contracts/PolygonZkEVMGlobalExitRootL2.sol), respectively.
143
+
144
+
But the L2 Global Exit Root Manager SC is different, and it appears in code as `PolygonZkEVMGlobalExitRootL2.sol`. This is a special contract that allows synchronization of L2 Exit Tree Root and the Global Exit Root.
Copy file name to clipboardExpand all lines: docs/zkEVM/architecture/high-level/smart-contracts/overview.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
@@ -21,7 +21,7 @@ There are four key contract types built into the system design:
21
21
22
22
## Consensus contracts
23
23
24
-
In the Ethereum realm, the set of consensus contracts and the methods they expose fuel the sequencing and verification mechanisms triggered by stack components, such as the sequencer and aggregator, at the node level.
24
+
In the Ethereum realm, the set of consensus contracts and the functions they expose fuel the sequencing and verification mechanisms triggered by stack components, such as the sequencer and aggregator, at the node level.
0 commit comments