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
The LxLy bridge is the native bridging infrastructure for all CDK chains. The way it works is each individual CDK chain deploys an instance of the LxLy bridge that connects to an L1 (Ethereum by default) by deploying contracts that carry out deposit and withdrawal of assets, along with escrow management. These contracts are managed by node operators corresponding to the respective CDK chains.
2
+
3
+
This changes as the AggLayer v1 goes online, and introduces an upgrade to the existing LxLy architecture in the form of a _unified instance_ of the LxLy bridge that multiple chains can connect to.
4
+
5
+
## What's the "unified" bridge?
6
+
7
+
AggLayer envisions a scalability solution that leverages shared state and unified liquidity across multiple ZK-powered chains within the Polygon ecosystem, all powered by the CDK infrastructure.
8
+
9
+
!!! tip "What's AggLayer?"
10
+
11
+
Want to learn more about what AggLayer is and what it looks to achieve? Check out [the AggLayer documentation in the Learn space](../../learn/agglayer.md).
12
+
13
+
All of this cool infrastructure needs a unified channel for easy transmission of assets and messages between the multiple chains connected via the AggLayer. And this is where the unified bridge comes into play. It allows all chains to take advantage of the AggLayer's unified liquidity, lower transaction costs, and more.
14
+
15
+
!!! tip "Lxly vs unified bridging TL;DR"
16
+
17
+
- **LxLy bridge:** A ZK bridge that supports asset and message transfers between a zkEVM system and the L1, typically Ethereum.
18
+
- **Unified bridge:** A specific instance of an LxLy bridge that allows several chains to connect to it. This instance is specific to the AggLayer v1.
19
+
20
+
The new unified model of the LxLy bridge introduced as a part of the AggLayer v1 infrastructure has one significant difference from the existing LxLy bridge: any asset bridged onto a CDK chain using the unified bridge is held by the **Unified Escrow** (also referred to as the **Master Escrow**) contract instead of a dedicated bridge contract.
21
+
22
+
Due to the shared nature of the bridge, chain operators will not have admin access to the funds locked in the master escrow contract, including the funds that belong to their own network.
23
+
24
+
The ability to manage bridge reserves is crucial to implement staking/restaking and other similar use cases, and is managed by the respective chain operators. How does the unified bridge address this?
25
+
26
+
## Introducing "Stake the Bridge"
27
+
28
+
Stake the Bridge, or **STB**, is a feature that lets CDK chain operators maintain control over the assets that are deposited to their respective networks.
29
+
30
+
### Design and implementation
31
+
32
+
On L1, CDK chains enable STB for an asset by deploying STB contracts on L1 to create an alternative [`L1Escrow`](https://github.com/pyk/zkevm-stb/blob/main/src/L1Escrow.sol) account that holds the asset, and allows the CDK chain operator to manage this token reserve.
33
+
34
+
On L2 (the CDK chain), there are three components needed to make this work:
35
+
36
+
-[`L2Token`](https://github.com/pyk/zkevm-stb/blob/main/src/L2Token.sol), which is a natively deployed ERC20 contract.
37
+
-[`L2Escrow`](https://github.com/pyk/zkevm-stb/blob/main/src/L2Escrow.sol), a contract that manages the L2Token's supply.
38
+
-[`L2TokenConverter`](https://github.com/pyk/zkevm-stb/blob/main/src/L2TokenConverter.sol), the contract that enables converting bridge-wrapped tokens to natively-minted tokens on L2.
39
+
40
+
!!! info
41
+
42
+
Each token needs to have its own set of STB contracts that perform the functions described above.
43
+
44
+
Let's briefly go over the specific actions and characteristics of each STB contract on L1 and L2.
45
+
46
+
#### `L1Escrow`
47
+
48
+
- Defines staking strategies to contribute to network security, or achieve other goals.
49
+
- Sending token issuance messages to `L2Escrow`.
50
+
- Fulfilling redemption messages from `L2Escrow`.
51
+
52
+
#### `L2Escrow`
53
+
54
+
- Receives minting instructions from `L1Escrow` via the unified bridge upon token deposit, and prompts `L2Token` contract to mint assets to a given address on L2.
55
+
- Burns the native asset on L2 and sends minting instructions to `L1Escrow` to release assets on L1.
56
+
57
+
#### `L2Token`
58
+
59
+
- Natively mints L2 tokens and sends them to a designated address.
60
+
- Interfaces with the `L2TokenConverter` contract.
61
+
62
+
#### `L2TokenConverter`
63
+
64
+
- Supports 1:1 conversion between the STB minted native tokens, and the bridged tokens minted by depositing tokens to LxLy bridge directly on L1.
65
+
- Doesn't have a default cap on the token volume that can be converted, but it can be added by chain operators as necessary.
66
+
- An asset can have multiple token converters that can have different properties.
67
+
68
+
## Roles and responsibilities
69
+
70
+
There are three roles, each of which performs specific actions to manage the STB system:
71
+
72
+
- Admin: Can upgrade and pause the system.
73
+
- Escrow manager: Can withdraw token backing from the respective escrow contract to stake using the `managerWithdraw()` function and contribute to network security, or achieve other goals.
74
+
- Risk manager: Can invoke `setIssuanceCap()` multiple times to increase or reduce the issuance cap.
75
+
76
+
## STB transaction flow vs. existing LxLy flow
77
+
78
+
With the STB contracts set up on L1 and L2 for a particular CDK chain, the bridging UX for a user doesn't differ from what it would be if they were carrying it out using the existing LxLy bridge. Let's consider an example using the following tokens:
79
+
80
+
- USDC - L1
81
+
- USDC.e - L2
82
+
- LxLy USDC
83
+
84
+
85
+
86
+
The diagram above illustrates the following flow:
87
+
88
+
1. A user initiates a USDC deposit from L1 to L2.
89
+
2. Instead of being deposited directly to the unified bridge, the USDC is deposited into the STB `L1Escrow` contract.
90
+
3. The STB `L1Escrow` locks the USDC and passes a message to the unified messenger containing the user’s address and amount of USDC being bridged.
91
+
4. The `Messenger` contract validates the message and then sends it to the STB `L2Escrow`.
92
+
5. The STB `L2Escrow` receives the message and mints USDC.e from the `L2Token` contract.
93
+
6. The USDC.e is sent to the user's address on L2.
94
+
95
+
### Native token conversion
96
+
97
+
With the introduction of STB, there are now two ways to deposit tokens to an L2 CDK chain, and two distinct resultant tokens:
98
+
99
+
- The STB flow involves locking tokens in the L1Escrow contract, which is followed by the minting of USDC.e on L2.
100
+
- On the other hand, if the tokens are deposited directly into the LxLy bridge contract, it results in the minting of LxLy USDC on L2.
101
+
102
+
The `L2TokenConverter` facilitates conversion between USDC.e and LxLy USDC. The way it works is by locking (`Deposit` function) either of the tokens in the converter contract, and then sending (`Withdraw` function) the equivalent amount of the other token to the user's wallet.
103
+
104
+
## Using the STB contracts
105
+
106
+
The STB contracts grant chain operators control over the token backing in the escrow contracts for all the chains that connect to the Polygon ecosystem via the AggLayer.
107
+
108
+
!!! warning
109
+
110
+
Polygon Labs **does not** manage or facilitate the staking of the assets locked in the escrow contracts. Any decision to implement any staking strategies and contribute to network security, or otherwise, is completely at the discretion of the chain operators.
111
+
112
+
Bridging tokens to L2 CDK chains using the STB contracts is ideal for the following use cases:
113
+
114
+
- Tokens that need to implement staking/restaking or other mechanisms, or strategies.
115
+
- Tokens that need to implement custom L2 functionality.
116
+
- Tokens that possess native issuance capabilities.
117
+
118
+
Want to start testing with STB? The contracts are still being audited, but are ready to use on testnets, and can be found here: https://github.com/pyk/zkevm-stb.
zkevm-data-availability /bin/sh -c /app/cdk-data-a ... Up 0.0.0.0:8444->8444/tcp,:::8444->8444/tcp
78
+
zkevm-data-node-db docker-entrypoint.sh postg ... Up (healthy) 0.0.0.0:5444->5432/tcp,:::5444->5432/tcp
79
+
zkevm-eth-tx-manager /bin/sh -c /app/cdk-validi ... Up 8123/tcp, 0.0.0.0:9094->9091/tcp,:::9094->9091/tcp
80
+
zkevm-event-db docker-entrypoint.sh postg ... Up 0.0.0.0:5435->5432/tcp,:::5435->5432/tcp
81
+
zkevm-explorer-json-rpc /bin/sh -c /app/cdk-validi ... Up 8123/tcp, 0.0.0.0:8124->8124/tcp,:::8124->8124/tcp,
88
82
0.0.0.0:8134->8134/tcp,:::8134->8134/tcp
89
83
explorer-sig-provider ./sig-provider-serv ... Up 0.0.0.0:8151->8050/tcp
90
84
visualizer-proxy /docker-entrypoint ... Up 80/tcp, 0.0.0.0:8083->8081/tcp
@@ -101,23 +95,22 @@ explorer-stats-db-l2 docker-entrypoint.s ... Up
101
95
explorer-frontend-l2 sh -c 'bin/blocksco ... Up 0.0.0.0:3001->3000/tcp
102
96
explorer-backend-l2 sh -c 'bin/blocksco ... Up 0.0.0.0:4001->4000/tcp
103
97
explorer-backend-l2-db docker-entrypoint.sh postg ... Up 0.0.0.0:5437->5432/tcp
104
-
cdk-validium-json-rpc /bin/sh -c /app/cdk-validi ... Up 0.0.0.0:8123->8123/tcp,:::8123->8123/tcp,
98
+
zkevm-json-rpc /bin/sh -c /app/cdk-validi ... Up 0.0.0.0:8123->8123/tcp,:::8123->8123/tcp,
105
99
0.0.0.0:8133->8133/tcp,:::8133->8133/tcp,
106
100
0.0.0.0:9091->9091/tcp,:::9091->9091/tcp
107
-
cdk-validium-l2gaspricer /bin/sh -c /app/cdk-validi ... Up 8123/tcp
108
-
cdk-validium-mock-l1-network geth --http --http.api adm ... Up 30303/tcp, 30303/udp,
101
+
zkevm-l2gaspricer /bin/sh -c /app/cdk-validi ... Up 8123/tcp
102
+
zkevm-mock-l1-network geth --http --http.api adm ... Up 30303/tcp, 30303/udp,
109
103
0.0.0.0:8545->8545/tcp,:::8545->8545/tcp,
110
104
0.0.0.0:8546->8546/tcp,:::8546->8546/tcp
111
-
cdk-validium-pool-db docker-entrypoint.sh postg ... Up 0.0.0.0:5433->5432/tcp,:::5433->5432/tcp
112
-
cdk-validium-prover zkProver -c /usr/src/app/c ... Up 0.0.0.0:50052->50052/tcp,:::50052->50052/tcp,
105
+
zkevm-pool-db docker-entrypoint.sh postg ... Up 0.0.0.0:5433->5432/tcp,:::5433->5432/tcp
106
+
zkevm-prover zkProver -c /usr/src/app/c ... Up 0.0.0.0:50052->50052/tcp,:::50052->50052/tcp,
113
107
0.0.0.0:50061->50061/tcp,:::50061->50061/tcp,
114
108
0.0.0.0:50071->50071/tcp,:::50071->50071/tcp
115
-
cdk-validium-sequence-sender /bin/sh -c /app/cdk-validi ... Up 8123/tcp
116
-
cdk-validium-sequencer /bin/sh -c /app/cdk-validi ... Up 0.0.0.0:6060->6060/tcp,:::6060->6060/tcp, 8123/tcp,
109
+
zkevm-sequence-sender /bin/sh -c /app/cdk-validi ... Up 8123/tcp
110
+
zkevm-sequencer /bin/sh -c /app/cdk-validi ... Up 0.0.0.0:6060->6060/tcp,:::6060->6060/tcp, 8123/tcp,
117
111
0.0.0.0:9092->9091/tcp,:::9092->9091/tcp
118
-
cdk-validium-state-db docker-entrypoint.sh postg ... Up 0.0.0.0:5432->5432/tcp,:::5432->5432/tcp
119
-
cdk-validium-sync /bin/sh -c /app/cdk-validi ... Up 8123/tcp
120
-
dac-setup-committee docker-entrypoint.sh npm r ... Exit 0
112
+
zkevm-state-db docker-entrypoint.sh postg ... Up 0.0.0.0:5432->5432/tcp,:::5432->5432/tcp
113
+
zkevm-sync /bin/sh -c /app/cdk-validi ... Up 8123/tcp
121
114
zkevm-bridge-db docker-entrypoint.sh postg ... Up 0.0.0.0:5438->5432/tcp,:::5438->5432/tcp
122
115
zkevm-bridge-service /bin/sh -c /app/zkevm-brid ... Up 0.0.0.0:8080->8080/tcp,:::8080->8080/tcp,
123
116
0.0.0.0:9090->9090/tcp,:::9090->9090/tcp
@@ -126,16 +119,16 @@ zkevm-bridge-ui /bin/sh /app/scripts/deploy.sh Up
126
119
127
120
</details>
128
121
129
-
2.3.1 If a service isn't running (i.e. it is in `Exit 1` state), investigate further using the logs:
122
+
2.2.1 If a service isn't running (i.e. it is in `Exit 1` state), investigate further using the logs:
130
123
131
124
```bash
132
-
sudo docker-compose logs <container_name>
125
+
sudo dockercompose logs <container_name>
133
126
```
134
127
135
128
!!! info
136
129
Find the `<container_name>` in the log output.
137
130
138
-
2.4 Useful commands
131
+
2.3 Useful commands
139
132
140
133
To stop CDK validium, use:
141
134
@@ -146,9 +139,18 @@ sudo make stop
146
139
To restart all services:
147
140
148
141
```bash
149
-
sudo make restart
142
+
sudo make run-resume
150
143
```
151
144
145
+
To check all running or exited services, use:
146
+
147
+
```bash
148
+
sudo make ps
149
+
sudo make ps-exited
150
+
```
151
+
152
+
In this guide, the L2 is launched that allows gasless transactions. To enable transaction gas, you need to first bridge fund from the L1 to the L2 under gasless mode, then run `sudo make gasless off`, stop and restart the services.
153
+
152
154
!!! note
153
155
This local deployment runs on an L1 Geth instance.
0 commit comments