Skip to content

Bridge guide #485

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TheDZhon merged 4 commits into from
Dec 9, 2024
Merged

Bridge guide #485

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fffb51d
feat: minor polishing
Dec 7, 2024
11d252c
feat: NEW -> NEC
Dec 7, 2024
f0ae990
Update wsteth-bridging-guide.md
iamnp Dec 9, 2024
bac7969
Update wsteth-bridging-guide.md
iamnp Dec 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 26 additions & 26 deletions docs/token-guides/wsteth-bridging-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# wstETH rollup bridging guide

:::warning Disclaimer
This guide provides recommendations provided by the NEW workgroup. NEW is not a representative of the Lido DAO and by giving the feedback NEW makes no warranties, express or implied, and disclaims all implied warranties, including any warranty of the likelihood of the recognition or rejection by the Lido DAO and representation.
This guide provides recommendations provided by the [Network Expansion Committee (NEC)](https://snapshot.org/#/lido-snapshot.eth/proposal/0x7cdf1af7cfeb472ae202c45fb6d7e952bb34bfcbc82113549986b2bc2d5f54c5). Following these recommendations increases the likelihood of recognition by the Committee, but does not guarantee it. Moreover, the Lido DAO vote, with a quorum established, can override any NEC decision at any time, even if it has already been implemented and released. Therefore, NEC makes no warranties, express or implied, and disclaims all implied warranties, including any warranty of the likelihood of the recognition or rejection by the Lido DAO.
:::

## Intro
Expand All @@ -19,10 +19,10 @@ See the [lido-l2-with-steth](https://github.com/lidofinance/lido-l2-with-steth/)

While technically, it is feasible to bridge the wstETH token on an L2 network as any other standard plain ERC-20 compatible token, it might not be aligned with the long-term vision of the Lido DAO for stETH future-proof adoption and general community sentiment.

This guide covers the recommendations as well as provides general guidelines, and reveals the logic behind to smooth the process. **It's essential to understand that conforming to or diverging from these guidelines won't ensure the recognition or rejection of a specific proposal by the Lido DAO.** Nonetheless, adhering to these guidelines substantially increases the likelihood of gaining support from the Network Expansion Workgroup (NEW) and community. Ultimately, the final decision is determined by the outcome of the voting process.
This guide covers the recommendations as well as provides general guidelines, and reveals the logic behind to smooth the process. **It's essential to understand that conforming to or diverging from these guidelines won't ensure the recognition or rejection of a specific proposal by the Lido DAO, which can override any NEC decision at any time, even if it has already been implemented and released.** Nonetheless, adhering to these guidelines substantially increases the likelihood of gaining support from the Network Expansion Committee (NEC) and community.

:::info
Please send any of your feedback on the guide to the NEW — the doc gets iterative updates.
Please send any of your feedback on the guide to the NEC — the doc gets iterative updates.
:::

## Why is this guide needed
Expand Down Expand Up @@ -57,21 +57,21 @@ If Lido DAO recognizes the bridged wstETH endpoints, in general, it means:

Usually, the Lido DAO recognizes the bridged wstETH endpoints if the specific set of security and design recommendations are followed. These recommendations are set out in the [Recommendations](#recommendations) section in paragraphs **R-1..R-8**. The rest of the recommendations (**R-9...**) are also important and foster the recognition's likelihood.

If the recommendations **R-1...R-4** are followed, the token may have a chance of being acknowledged by NEW as following the security and future-proofing baseline.
If the recommendations **R-1...R-4** are followed, the token may have a chance of being formally recognized by NEC as following the security and future-proofing baseline.

If any of **R-1...R-4** isn’t followed, there can be less likelihood of the Lido DAO’s recognition or the NEW's acknowledgment.
If any of **R-1...R-4** isn’t followed, there can be less likelihood of the NEC recognition.

## General scenario towards the Lido DAO recognition

This section describes an approximate path to bridging wstETH to an L2 network. The order of the steps is not strict but follows the general flow.

🐾 Study the bridging guide and fill in [the questionnaire](#questionnaire) about your solution and send it to the NEW.
🐾 Study the bridging guide and fill in [the questionnaire](#questionnaire) about your solution and send it to the NEC.

🐾 Coordinate on priority lane, timings, and reviews with the NEW.
🐾 Coordinate on priority lane, timings, and reviews with the NEC.

🐾 Get the architecture and the deploy configuration verified by the NEW.
🐾 Get the architecture and the deploy configuration verified by the NEC.

🐾 Deploy the contracts to testnet. Get the testnet deployment verified by coordinating through the NEW.
🐾 Deploy the contracts to testnet. Get the testnet deployment verified by coordinating through the NEC.

🐾 Express intention to bridge wstETH on the forum, outlining the details and technical plan. Consider:

Expand All @@ -87,7 +87,7 @@ This section describes an approximate path to bridging wstETH to an L2 network.
- [wstETH to Scroll](https://research.lido.fi/t/wsteth-deployment-on-scroll/6603)
- [wstETH to Mode](https://research.lido.fi/t/wsteth-deployment-on-mode/7365)

🐾 Deploy the contracts to mainnet. Get the mainnet deployment verified by the external security group (getting in touch with NEW).
🐾 Deploy the contracts to mainnet. Get the mainnet deployment verified by the external security group (getting in touch with NEC).

🐾 Pass snapshot voting on https://snapshot.org/#/lido-snapshot.eth/. It should contain the final mainnet addresses and audits according to **R-1**. Otherwise, one more snapshot voting with the addresses would have been required.

Expand All @@ -99,7 +99,7 @@ graph TD;
B("Is the bridged token deployed behind a proxy (follows R-4)?")
C("Follow the general scenario <br> towards DAO recognition")
D("Consider migrating liquidity and redeploying, <br> following the general scenario towards <br> DAO recognition")
F["Consider delivering and/or committing <br> to deliver the missing parts.<br>Contact NEW for the best way forward"]
F["Consider delivering and/or committing <br> to deliver the missing parts.<br>Contact NEC for the best way forward"]

A-- Yes -->B
B-- Yes -->F
Expand All @@ -117,11 +117,11 @@ This section enumerates design and security recommendations for a wstETH bridgin

### Security and future-proof baseline

The baseline recommendations: the following of the recommendations are highly encouraged to increase the chance of the Lido DAO recognition or NEW acknowledgment.
The baseline recommendations: following these recommendations is highly encouraged to increase the chance of NEC recognition.

#### R-1: Audited code and verifiable deployment

The entire on-chain codebase (rollup, bridge, token) must be audited by a third party. Please, contact the NEW to check the temperature if the audit provider isn't familiar with the Lido protocol codebase (see the providers here: https://github.com/lidofinance/audits/)
The entire on-chain codebase (rollup, bridge, token) must be audited by a third party. Please, contact the NEC to check the temperature if the audit provider isn't familiar with the Lido protocol codebase (see the providers here: https://github.com/lidofinance/audits/)

The deployment must be verifiable:

Expand Down Expand Up @@ -151,31 +151,31 @@ The general security approach here is to isolate L2/cross-chain risks, ensuring

#### R-3: Usage of canonical bridge

Usage of the bridge, canonical for the L2 network, is highly encouraged. If the native bridge does not exist, is not a public good, or is closed-sourced. Most "canonical like " options may be suitable.
Usage of the bridge, canonical for the L2 network, is highly encouraged. If the native bridge does not exist, is not a public good, or is closed-sourced. Most "canonical like" options may be suitable.

#### R-4: L2 wstETH token upgradable

The bridged token contract should be deployed behind a proxy with the ability to set the proxy admin on a case-by-case basis (or even eventually ossify). This allows the token to be future-proof (support of new standards, passing additional data, etc.) and provides a foundation for potential stETH bridging without incurring liquidity fragmentation.

If a dedicated bridge endpoint contract is not deployed behind a proxy (**R-5**), it must provide the capability to set/change the bridge contract instance used.

### The Lido DAO recognition recommendations by the NEW
### Lido DAO support recommendations by the NEC

The recommendations **R-5...R-8** are highly encouraged to follow for the recognition of the bridged wstETH endpoints by the Lido DAO.
The recommendations **R-5...R-8** are highly encouraged to follow so that the recognition of the bridged wstETH endpoints is supported by the Lido DAO.

The recommendations starting from **R-9** are also encouraged and may significantly contribute to the likelihood of the Lido DAO recognition.
The recommendations starting from **R-9** are also encouraged and may significantly contribute to the likelihood of the Lido DAO support.

#### R-5: Bridging L1 Lido DAO decisions

A dedicated governance executor contract should be set as an admin the of the L2 endpoint contracts.
A dedicated governance executor contract should be set as an admin of the L2 endpoint contracts.

Examples:

- [`OptimismBridgeExecutor`](https://optimistic.etherscan.io/address/0xefa0db536d2c8089685630fafe88cf7805966fc3);
- [Bridge executor on Base](https://basescan.org/address/0x0E37599436974a25dDeEdF795C848d30Af46eaCF) - reused `OptimismBridgeExecutor` contract;
- [`OptimismBridgeExecutor`](https://optimistic.etherscan.io/address/0xefa0db536d2c8089685630fafe88cf7805966fc3)
- [Bridge executor on Base](https://basescan.org/address/0x0E37599436974a25dDeEdF795C848d30Af46eaCF) - reused `OptimismBridgeExecutor` contract
- [`ZkSyncBridgeExecutor`](https://explorer.zksync.io/address/0x13f46b59067f064c634fb17e207ed203916dccc8#contract)
- [`LineaBridgeExecutor`](https://lineascan.build/address/0x74Be82F00CC867614803ffd7f36A2a4aF0405670)
- [`ScrollBridgeExecutor`]https://scrollscan.com/address/0x0c67D8D067E349669dfEAB132A7c03A90594eE09)
- [`ScrollBridgeExecutor`](https://scrollscan.com/address/0x0c67D8D067E349669dfEAB132A7c03A90594eE09)

For more examples, see Governance Bridge Executors at https://docs.lido.fi/deployed-contracts/#lido-multichain. The contracts originate from [Aave Governance Cross-Chain Bridges](https://github.com/aave/governance-crosschain-bridges) and can be found at https://github.com/lidofinance/governance-crosschain-bridges and [PRs](https://github.com/lidofinance/governance-crosschain-bridges/pulls).

Expand Down Expand Up @@ -227,7 +227,7 @@ For access control, please prefer the standard OpenZeppelin ACL contract and its

It's advised to have the answered statements of the [questionnaire](#questionnaire) included in the token bridge contracts GitHub repo README. As an example one might see https://github.com/txfusion/lido-l2/tree/main/zksync#statements for wstETH on zkSync Era (but note that the questions are outdated there).

Please share with the NEW: deploy scripts, acceptance tests, deploy plans, rollup-specific documentation on bridging approaches, etc. A PR to the diffyscan repo with [configs like this](https://github.com/lidofinance/diffyscan/tree/main/config_samples/zksync). This would allow the NEW to simplify the deployment verification and make the feedback more specific.
Please share with the NEC: deploy scripts, acceptance tests, deploy plans, rollup-specific documentation on bridging approaches, etc. A PR to the diffyscan repo with [configs like this](https://github.com/lidofinance/diffyscan/tree/main/config_samples/zksync). This would allow the NEC to simplify the deployment verification and make the feedback more specific.

:::note
To prepare the deployment actions plan, you might want to refer to the following [wstETH on Optimism deployment log](https://hackmd.io/@lido/By-ANUXT3?type=view) as a reference.
Expand Down Expand Up @@ -288,8 +288,8 @@ Notation used:
- Optionally applicable (if `L2 Custom Bridge` doesn't support these)
- Admin is `L2 Governance Executor`
- Withdrawals pausable by
- `Emergency Brakes Multisig`
- `L2 Governance Executor`
- `Emergency Brakes Multisig`
- Withdrawals resumable by
- `L2 Governance Executor`
- Deposits pausable by
Expand All @@ -309,7 +309,7 @@ Notation used:
- `Emergency Brakes L1 Multisig`
- `0x73b047fe6337183A454c5217241D780a932777bD`
- `Emergency Brakes L2 Multisig`
- ask the NEW for the address (the deployed Safe instance would be needed)
- ask the NEC for the address (the deployed Safe instance would be needed)

### Testnets

Expand Down Expand Up @@ -351,11 +351,11 @@ Follow the case of [`wstETH on Mode`](https://research.lido.fi/t/wsteth-deployme

### What if wstETH is already bridged and has ample liquidity?

Please consider getting in touch with the NEW if (**R-1...R-4**) are followed.
Please consider getting in touch with the NEC if (**R-1...R-4**) are followed.

## Questionnaire

To get fast feedback on the likelihood of the wstETH recognized by the Lido DAO, please fill in the questionnaire and send it to the NEW. **Please note: NEW is not a representative of the Lido DAO and by giving the feedback NEW makes no warranties, express or implied, and disclaims all implied warranties, including any warranty of the likelihood of the recognition or rejection by the Lido DAO and representation.**
To get quick feedback on the likelihood of the wstETH being recognized by the NEC, please fill in the questionnaire and send it to the NEC. **Please note: by giving the feedback NEC makes no warranties, express or implied, and disclaims all implied warranties, including any warranty of the likelihood of the recognition or rejection by the Lido DAO.**

In the comments section, please provide the relevant details: the artifacts, if present, and/or a description why the recommendation is not followed or followed partially, etc.

Expand Down
Loading