From 7496c1ab53991a472860a703d666a9c785af8699 Mon Sep 17 00:00:00 2001 From: Artyom Veremeenko Date: Tue, 17 Dec 2024 12:44:05 +0300 Subject: [PATCH 1/7] feat(bridging guide): WIP update wsteth bridging guide --- docs/token-guides/wsteth-bridging-guide.md | 343 +++++++++++---------- 1 file changed, 185 insertions(+), 158 deletions(-) diff --git a/docs/token-guides/wsteth-bridging-guide.md b/docs/token-guides/wsteth-bridging-guide.md index fd9f6411d..8aca9c871 100644 --- a/docs/token-guides/wsteth-bridging-guide.md +++ b/docs/token-guides/wsteth-bridging-guide.md @@ -1,4 +1,4 @@ -# wstETH rollup bridging guide +# Lido tokens adoption guide :::warning Disclaimer 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. @@ -6,106 +6,86 @@ This guide provides recommendations provided by the [Network Expansion Committee ## Intro -This document is intended for the developers representing network/rollup foundations and DAOs looking to bridge Lido's wstETH on Ethereum L2 (rollup) networks. - -:::info -This guide doesn't cover yet bridging of rebasable stETH token nor bridging to non-L2-rollup networks. However, please note that bridging rebasable stETH token in a regular way might cause a loss of user assets due to the rewards accrued being stuck on an L1 bridge. - -Effective 2024 October, stETH token has become available [on Optimism](/docs/deployed-contracts/index.md#optimism). -The wstETH and stETH tokens design follows the [LIP-22](https://github.com/lidofinance/lido-improvement-proposals/blob/develop/LIPS/lip-22.md) architecture approach. - -See the [lido-l2-with-steth](https://github.com/lidofinance/lido-l2-with-steth/) repository for more details. -::: - -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 document is intended for the developers representing network/rollup foundations and DAOs looking to bridge Lido tokens (wstETH, stETH). 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. +While technically, it is feasible to bridge the wstETH/stETH token as any other standard non-upgradable ERC-20 compatible token, +it might not be aligned with the long-term vision of the Lido DAO , nor support the stETH rebasable nature. + :::info -Please send any of your feedback on the guide to the NEC — the doc gets iterative updates. +Please note that bridging rebasable stETH token in a regular way might cause a loss of user assets due to the rewards accrued being stuck on an L1 bridge. ::: -## Why is this guide needed - -As said before, the default way to bridge an ERC-20 token is to deploy on L2 a non-upgradable token and use the general bridge contract, this guide proposes to implement a more complex solution. +To close the gaps this guide proposes to implement a more complex solution. -The solution involves deploying dedicated bridge endpoint contracts behind proxy on L1 and L2 and an upgradable token on L2, all governed by the Lido DAO on L1 ([Aragon Agent contract](https://etherscan.io/address/0x3e40D73EB977Dc6a537aF587D48316feE66E9C8c)) via a dedicated [governance executor](https://github.com/lidofinance/governance-crosschain-bridges/) contract on L2. This architecture is proposed to provide the following capabilities. +The solution involves deploying dedicated bridge endpoint contracts behind proxy on L1 and the target network and an upgradable token on the target network, +all governed by the Lido DAO on L1 ([Aragon Agent contract](https://etherscan.io/address/0x3e40D73EB977Dc6a537aF587D48316feE66E9C8c)) +via a dedicated governance executor contract on target network. This architecture is proposed to provide the following capabilities. -1. Passing arbitrary data. It allows laying the foundation for bridging rebasable stETH in the future (need to pass wstETH/stETH rate). +1. Passing arbitrary data. It allows delivering wstETH/stETH rate to the target network. 2. Revamping the token logic, as stETH is not a general-purpose token but an asset built on top of a living liquid-staking middleware. 3. Future-proofing the token, for example, to avoid high-cost liquidity migration as Ethereum continues evolving and new standards like [ERC-2612](https://eips.ethereum.org/EIPS/eip-2612)/[ERC-1271](https://eips.ethereum.org/EIPS/eip-1271) are adopted. 4. Pausing and resuming bridging in an emergency or during upgrades. -## The Lido DAO bridging endpoints recognition +The wstETH and stETH tokens design follows the [LIP-22](https://github.com/lidofinance/lido-improvement-proposals/blob/develop/LIPS/lip-22.md) architecture approach. -Lido DAO can recognize the bridged wstETH endpoints by means of a signalling snapshot. For example, it has happened for: -[Base](https://snapshot.org/#/lido-snapshot.eth/proposal/0x8b35f64fffe67f67d4aeb2de2f3351404c54cd75a08277c035fa77065b6792f4), -[ZKSync](https://snapshot.org/#/lido-snapshot.eth/proposal/0xe35f56a6117599eeb9dbef982613c0545710d91403a828d1fba00ab21d5188f3), -[Mantle](https://snapshot.org/#/lido-snapshot.eth/proposal/0x1d38c11b27590ab5c69ca21c5d2545d53b7f5150dada7e05f89d500ede5becad), -[Linea](https://snapshot.org/#/lido-snapshot.eth/proposal/0x9382624eeee68a175dd7d1438347dbad4899ba0d2bfcf7c3955f087cb9f5cfc4), -[Scroll](https://snapshot.org/#/lido-snapshot.eth/proposal/0xcdb7d84ea80d914a4abffd689ecf9bdc4bb05d47f1fdbdda8793d555381a0493), -[Mode](https://snapshot.org/#/lido-snapshot.eth/proposal/0x6bc51c2b07a9345a03a0bc0acb72ccc9f63879c981f3a6954164d110c5d330b2) +See the [lido-l2-with-steth](https://github.com/lidofinance/lido-l2-with-steth/) repository for more details. -If Lido DAO recognizes the bridged wstETH endpoints, in general, it means: +## TL;DR -- the integration is highlighted on the frontend pages: [landing](https://lido.fi/lido-multichain), [widget](https://stake.lido.fi/), and [ecosystem pages](https://lido.fi/lido-ecosystem); -- when/if the dedicated bridging Lido UI is implemented, the network will be included; -- the newly appeared integration announcement is published in the Lido's [blog](https://blog.lido.fi/category/l2/) and [twitter](https://twitter.com/LidoFinance); -- the endpoint contracts are under the Lido's [bug bounty program](https://immunefi.com/bug-bounty/lido/); -- the endpoint contracts get monitored by means of [Lido alerting system](https://github.com/lidofinance/alerting-forta/); -- the opportunity for obtaining extra support, potentially from [LEGO](https://lido.fi/lego) or [Liquidity observation Labs](https://lido.fi/governance#liquidity-observation-labs), becomes available. For the details one should [reach out to ProRel](https://tally.so/r/waeRLX). +In case you are looking for a typical copy-paste solution, refer to the suitable subsection below for a reference implementation. +Any of these setups satisfies the minimum [Recommendations](#recommendations) for the Lido tokens bridging solution. -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 none of the reference setups matches your case, follow though the [Recommendations](#recommendations) section and fill out the [Architecture checklist](#architecture-checklist) for further evaluation by NEC. -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. +In any case, follow the [General scenario towards the recognition](#general-scenario-towards-the-recognition). -If any of **R-1...R-4** aren’t followed, there can be less likelihood of the NEC recognition. +### Optimistic rollup, wstETH + stETH -## General scenario towards the Lido DAO recognition +Use [multichain-automaton](https://github.com/lidofinance/multichain-automaton) for automated deployment of wstETH + stETH setup. -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. +### Optimistic rollup, wstETH -🐾 Study the bridging guide and fill in [the questionnaire](#questionnaire) about your solution and send it to the NEC. +Deploy the setup from [lido-l2](https://github.com/lidofinance/lido-l2) repository. -🐾 Coordinate on priority lane, timings, and reviews with the NEC. +### Non-rollup network, wstETH + +Use [Wormhole x Axelar | Lido Bridge: Implementation for wstETH on BNB Chain](https://research.lido.fi/t/wormhole-x-axelar-lido-bridge-implementation-for-wsteth-on-bnb-chain/6012/3) +as a reference for bridging wstETH via aggregation and bridging governance decisions via [a.DI](https://github.com/lidofinance/aave-delivery-infrastructure). + +Adhere to TODO R-1...R-8. + +## General scenario towards the recognition + +This section describes an approximate path to bridging Lido tokens to a network. The order of the steps is not strict but follows the general flow. + +🐾 Study the bridging guide and fill in [Architecture checklist](#architecture-checklist) about your solution and send it to the NEC. 🐾 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 NEC. +🐾 Coordinate on priority lane, timings, and reviews with the NEC. + +🐾 Deploy the contracts to testnet. Get approval of the setup by the NEC. 🐾 Express intention to bridge wstETH on the forum, outlining the details and technical plan. Consider: - Target one network per proposal to make the discussion more focused. -- The post should be published in advance, ideally at least two weeks before any potential snapshot vote, to allow time for discussion and verification of the proposal. +- The post should be published in advance to allow time for discussion and verification of the proposal. - The deployment addresses are not required at once but must be proposed at least a week before the snapshot voting starts. -- If the proposed solution does not include some of the recommendations (**R-5...**), consider including the roadmap and committing to deliver it. +- If the proposed solution does not fulfill some of the recommendations consider including the roadmap and committing to deliver it. - Examples: - [wstETH to Base](https://research.lido.fi/t/wsteth-deployment-to-base-and-ownership-acceptance-by-lido-dao/5668) - [wstETH to ZKSync](https://research.lido.fi/t/wsteth-deployment-on-zksync/5701) - - [wstETH to Mantle](https://research.lido.fi/t/wsteth-deployment-on-mantle/5991) - - [wstETH to Linea](https://research.lido.fi/t/wsteth-on-linea-ownership-acceptance-by-lido-dao/5961) - [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) + - [wstETH and stETH to Soneium](https://research.lido.fi/t/steth-wsteth-deployment-on-soneium/9389/2) + - [wstETH to BSC by Wormhole x Axelar](https://research.lido.fi/t/wormhole-x-axelar-lido-bridge-implementation-for-wsteth-on-bnb-chain/6012) -🐾 Deploy the contracts to mainnet. Get the mainnet deployment verified by the external security group (getting in touch with NEC). +🐾 Deploy the contracts to mainnet. Get pre-endorsement approval of the setup by the 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. +🐾 Pass ownership of the bridging endpoints to the Lido DAO. The final setup goes through final verification by the external security group (organized by the NEC). -Here is also an approximate decision tree to guide on this scenario. - -```mermaid -graph TD; - A("Is wstETH already bridged and has got adoption?") - B("Is the bridged token deployed behind a proxy (follows R-4)?") - C("Follow the general scenario
towards DAO recognition") - D("Consider migrating liquidity and redeploying,
following the general scenario towards
DAO recognition") - F["Consider delivering and/or committing
to deliver the missing parts.
Contact NEC for the best way forward"] - - A-- Yes -->B - B-- Yes -->F - A-- No -->C - B-- No -->D -``` +🐾 Get the endorsement by NEC expressed in research.lido.fi forum post. :::warning Ensure that the official bridging UI utilizes the customized bridge endpoint contract. Using the default bridge contract in the past caused problems, leading to deposited funds becoming locked within the contract. @@ -113,13 +93,13 @@ Ensure that the official bridging UI utilizes the customized bridge endpoint con ## Recommendations -This section enumerates design and security recommendations for a wstETH bridging solution. - -### Security and future-proof baseline +This section enumerates design and security recommendations for a Lido tokens bridging solution. +Usually, the NEC recognizes the bridged endpoints only if at least recommendations **R-1..R-8** are followed. +The rest of the recommendations (**R-9...**) are also important and foster the recognition's likelihood. Some of them might be not applicable to non-rollup networks. -The baseline recommendations: following these recommendations is highly encouraged to increase the chance of NEC recognition. +TODO: ^ Rs numbers -#### R-1: Audited code and verifiable deployment +### 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 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/) @@ -143,33 +123,32 @@ To speed up the process and make it more robust, please provide the artifacts (i - [wstETH on Mantle](https://github.com/lidofinance/state-mate/tree/main/configs/mantle) - [a.DI on Binance Smart Chain (BSC)](https://github.com/lidofinance/state-mate/tree/main/configs/bsc) -#### R-2: "Lock and mint" bridge mechanics +### R-2: "Lock and mint" bridge mechanics Use the lock-and-mint bridging mechanism. The general security approach here is to isolate L2/cross-chain risks, ensuring no additional risks are imposed on Lido protocol on Ethereum or to other L2s and alt L1s with already bridged wstETH. This is almost unachievable with a ‘burn-and-mint’ architecture. -#### R-3: Usage of canonical bridge +### R-3: Robust token bridging provider -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. +Usage of the bridge, canonical for the L2 network, is highly encouraged. -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. +If the native bridge does not exist - what is typical for non-rollup networks - two options are possible. -### Lido DAO support recommendations by the NEC +1. 1 bridge provider with framework to add/change at least 2 bridge providers +2. 2/X aggregation (X bridge providers, where X >= 2) -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. +Aggregation is preferred, but (1) is suitable as a temporary solution. -The recommendations starting from **R-9** are also encouraged and may significantly contribute to the likelihood of the Lido DAO support. +As a reference implementation of (1) and/or (2) one might consider +[Wormhole x Axelar | Lido Bridge: Implementation for wstETH on BNB Chain](https://research.lido.fi/t/wormhole-x-axelar-lido-bridge-implementation-for-wsteth-on-bnb-chain/6012/3). +For the deployed addresses see [this](https://docs.lido.fi/deployed-contracts/#binance-smart-chain-bsc). -#### R-5: Bridging L1 Lido DAO decisions +### R-4: Bridging L1 Lido DAO decisions A dedicated governance executor contract should be set as an admin of the L2 endpoint contracts. -Examples: +Rollup examples: - [`OptimismBridgeExecutor`](https://optimistic.etherscan.io/address/0xefa0db536d2c8089685630fafe88cf7805966fc3) - [Bridge executor on Base](https://basescan.org/address/0x0E37599436974a25dDeEdF795C848d30Af46eaCF) - reused `OptimismBridgeExecutor` contract @@ -177,13 +156,27 @@ Examples: - [`LineaBridgeExecutor`](https://lineascan.build/address/0x74Be82F00CC867614803ffd7f36A2a4aF0405670) - [`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). +Non-rollup examples: + +- [CrossChainExecutor](https://bscscan.com/address/0x8E5175D17f74d1D512de59b2f5d5A5d8177A123d) from a.DI (see R-3) + +[a.DI (Aave Delivery Infrastructure)](https://github.com/lidofinance/aave-delivery-infrastructure). It was used to bridge wstETH to Binance Smart Chain (BSC). +See this forum post for more details: [Wormhole x Axelar | Lido Bridge: Implementation for wstETH on BNB Chain](https://research.lido.fi/t/wormhole-x-axelar-lido-bridge-implementation-for-wsteth-on-bnb-chain/6012/3) -#### R-6: Dedicated upgradable bridge instances + +For more rollup 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). + +### R-5: 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. + +### R-6: Dedicated upgradable bridge instances Deploy dedicated instances of bridge contracts on L1 and L2. The contract instances 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 to lay the foundation for the emergency capabilities (**R-7**) and for possible bridging of rebasable stETH. For more details on why, see for section [Why is this guide needed](#why-is-this-guide-needed). For the architecture outline, see section [Reference architecture and permissions setup](#reference-architecture-and-permissions-setup). -#### R-7: Pausable deposits and withdrawals +### R-7: Pausable deposits and withdrawals To provide the capability to react fast and reduce losses in case of a security contingency, depositing and withdrawing should be pausable. Namely: @@ -196,48 +189,42 @@ To curb the multisig's power, it is proposed to use the "Gate Seals" mechanic. T - one-time disposable pauser contact [Gate Seals](https://github.com/lidofinance/gate-seals); - [PausableUntil](https://github.com/lidofinance/lido-dao/blob/master/contracts/0.8.9/utils/PausableUntil.sol) contract (inherited by [WithdrawalQueue](https://github.com/lidofinance/lido-dao/blob/master/contracts/0.8.9/WithdrawalQueue.sol)). -#### R-8: Support of ERC-2612 permit enhanced with EIP-1271 +### R-8: The contracts state -The bridged wstETH should support [EIP-2612 permit ERC-20 token extension](https://eips.ethereum.org/EIPS/eip-2612) with [EIP-1271 standard signature validation method for contracts](https://eip1271.io/). The latter paves the way to Account Abstraction adoption, see https://eip1271.io/. - -Please take into account that the [OpenZeppelin ERC20 with permit (EIP-2612) implementation](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/extensions/ERC20Permit.sol) does not support smart contract signatures validation EIP-1271 and thus shouldn't be used as it is. Please consider extending ERC20Permit using [OpenZeppelin SignatureChecker util](https://docs.openzeppelin.com/contracts/4.x/api/utils#SignatureChecker) or [stETHPermit contract](https://github.com/lidofinance/lido-dao/blob/master/contracts/0.4.24/StETHPermit.sol) as a reference implementation. NB, that the wstETH token itself on Ethereum doesn't support this due to non-upgradability. +There are two states to consider: pre-endorsement and endorsement. -#### R-9: wstETH token/bridge state before snapshot vote +Endorsement state is the state ready for the final NEC assessment and subsequent recognition. +Pre-endorsement state is when the contracts are deployed and the setup is yet to be evaluated by NEC for correctness. -By the snapshot vote start, deposits and withdrawals should be unpaused unless there are any specific considerations to do otherwise. -Going with unpaused states provides the following: +In the endorsement state, the permissions must be set as per [Reference rollup architecture and permissions setup](#reference-rollup-architecture-and-permissions-setup). -- the bridge being in the final state during the snapshot vote — without any temporary permissions granted to the resumer or other actors; -- less operational load for contributors and token holders (to re-vote on additional changes). +In the pre-endorsement state, the admins of the contracts might be set to the representatives of the target network / bridging provider, to allow for amending the setup in case of any issues. -Nevertheless, consider risks of liquidity fragmentation in case the currently deployed setup is not supported by snapshot vote but some wstETH has already been deposited. +It is fine to have the contracts in the pre-endorsement state in unpaused state. +Nevertheless, consider risks of liquidity fragmentation in case the currently deployed setup is not got recognized but liquidity has already been deposited. -#### R-10: Upgradability mechanics +### R-9: No same contract addresses -- The regular (`ERC1967Proxy`) proxy pattern is good enough; the transparent proxy pattern might be an unnecessary complication. -- Use ossifiable proxies when possible. For example, consider [OssifiableProxy](https://github.com/lidofinance/lido-l2/blob/main/contracts/proxy/OssifiableProxy.sol), which is used in Lido protocol on Ethereum. - -Please have the implementations petrified with dummy values. It helps to reduce confusion, like taking the implementation address instead of the proxy address. For example, see [zkSync Era ERC20BridgedUpgradeable implementation](https://explorer.zksync.io/address/0xc7a0daa1b8fea68532b6425d0e156088b0d2ab2c#contract) (bridge, decimals, name, symbol views). +Please avoid deploying contracts to the same addresses on L1 and L2 and/or testnets, as this might occur when deploying from a single EOA to multiple networks. Following this recommendation helps to avoid potential confusion in the future. -#### R-11: Use AccessControlEnumerable for ACL +### R-10: Support of ERC-2612 permit enhanced with EIP-1271 -For access control, please prefer the standard OpenZeppelin ACL contract and its [enumerable version](https://docs.openzeppelin.com/contracts/4.x/api/access#AccessControlEnumerable) over non-enumerable versions. It allows full on-chain permissions verification — no need to analyze events or transactions as in non-enumerable implementations. For example, see [Lido ValidatorsExitBusOracle contract](https://etherscan.io/address/0xa89ea51fdde660f67d1850e03c9c9862d33bc42c#code). +The bridged wstETH should support [EIP-2612 permit ERC-20 token extension](https://eips.ethereum.org/EIPS/eip-2612) with [EIP-1271 standard signature validation method for contracts](https://eip1271.io/). The latter paves the way to Account Abstraction adoption, see https://eip1271.io/. -#### R-12: Prepare the solution statements and share the deploy artifacts +Please take into account that the [OpenZeppelin ERC20 with permit (EIP-2612) implementation](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/extensions/ERC20Permit.sol) does not support smart contract signatures validation EIP-1271 and thus shouldn't be used as it is. Please consider extending ERC20Permit using [OpenZeppelin SignatureChecker util](https://docs.openzeppelin.com/contracts/4.x/api/utils#SignatureChecker) or [stETHPermit contract](https://github.com/lidofinance/lido-dao/blob/master/contracts/0.4.24/StETHPermit.sol) as a reference implementation. NB, that the wstETH token itself on Ethereum doesn't support this due to non-upgradability. -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). +### R-11: Upgradability mechanics -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. +- The regular (`ERC1967Proxy`) proxy pattern is good enough; the transparent proxy pattern might be an unnecessary complication. +- Use ossifiable proxies when possible. For example, consider [OssifiableProxy](https://github.com/lidofinance/lido-l2/blob/main/contracts/proxy/OssifiableProxy.sol), which is used in Lido protocol on Ethereum. -:::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. -::: +Please have the implementations petrified with dummy values. It helps to reduce confusion, like taking the implementation address instead of the proxy address. For example, see [zkSync Era ERC20BridgedUpgradeable implementation](https://explorer.zksync.io/address/0xc7a0daa1b8fea68532b6425d0e156088b0d2ab2c#contract) (bridge, decimals, name, symbol views). -#### R-13: No same contract addresses +### R-12: Use AccessControlEnumerable for ACL -Please avoid deploying contracts to the same addresses on L1 and L2 and/or testnets, as this might occur when deploying from a single EOA to multiple networks. Following this recommendation helps to avoid potential confusion in the future. +For access control, please prefer the standard OpenZeppelin ACL contract and its [enumerable version](https://docs.openzeppelin.com/contracts/4.x/api/access#AccessControlEnumerable) over non-enumerable versions. It allows full on-chain permissions verification — no need to analyze events or transactions as in non-enumerable implementations. For example, see [Lido ValidatorsExitBusOracle contract](https://etherscan.io/address/0xa89ea51fdde660f67d1850e03c9c9862d33bc42c#code). -## Reference architecture and permissions setup +## Reference architecture and proposed configuration This section describes a kind of minimal bridging contracts setup and its configuration. This setup is a recommendation and might not be the best for a specific network — it serves as a suggestion for the main functional parts and their interconnections. @@ -264,7 +251,7 @@ Notation used: **L2 Governance Executor** -- The only allow-listed L1 execution sender is `Lido Agent` (retrieved via `getEthereumExecutor()`) +- The only allow-listed L1 execution sender is `Lido Agent` **L2 Custom Bridge Endpoint** - Upgradeable @@ -286,21 +273,19 @@ Notation used: - Proxy admin is `L2 Governance Executor` - Mint is allowed only by `L2 Custom Bridge` - Optionally applicable (if `L2 Custom Bridge` doesn't support these) - - Admin is `L2 Governance Executor` - - Withdrawals pausable by - - `L2 Governance Executor` - - `Emergency Brakes Multisig` - - Withdrawals resumable by - - `L2 Governance Executor` - - Deposits pausable by - - `L2 Governance Executor` - - `Emergency Brakes Multisig` - - Deposits resumable by - - `L2 Governance Executor` - -## The proposed configuration - -### Mainnet + - Admin is `L2 Governance Executor` + - Withdrawals pausable by + - `L2 Governance Executor` + - `Emergency Brakes Multisig` + - Withdrawals resumable by + - `L2 Governance Executor` + - Deposits pausable by + - `L2 Governance Executor` + - `Emergency Brakes Multisig` + - Deposits resumable by + - `L2 Governance Executor` + +### Mainnet proposed configuration - `wstETH` - the wstETH token on L1 - `0x7f39c581f595b53c5cb19bd0b3f8da6c935e2ca0` @@ -311,14 +296,12 @@ Notation used: - `Emergency Brakes L2 Multisig` - ask the NEC for the address (the deployed Safe instance would be needed) -### Testnets +### Testnet Holesky proposed configuration :::info Please, deploy to Holešky if possible because it has better long-term exposure and more robust Lido protocol deployment. ::: -#### Holesky - - `wstETH` - the wstETH token on L1 - `0x8d09a4502Cc8Cf1547aD300E066060D043f6982D` - `Lido Agent` - Lido DAO Aragon Agent @@ -328,7 +311,7 @@ Please, deploy to Holešky if possible because it has better long-term exposure - `Emergency Brakes L2 Multisig` - `0xa5F1d7D49F581136Cf6e58B32cBE9a2039C48bA1` (EOA) -#### Sepolia +### Testnet Sepolia proposed configuration - `wstETH` - the wstETH token on L1 - `0xB82381A3fBD3FaFA77B3a7bE693342618240067b` @@ -339,6 +322,45 @@ Please, deploy to Holešky if possible because it has better long-term exposure - `Emergency Brakes L2 Multisig` - `0xa5F1d7D49F581136Cf6e58B32cBE9a2039C48bA1` (EOA) +## Questionnaire + +### Deployment and verifiability checklist + +- [ ] Audited by a third party (see R1) +- [ ] Deployed code matches the commit in the audit report precisely (see R1) +- [ ] Sources verified on block explorers without flattening (see R1) +- [ ] PR with config for Diffyscan (see R1) +- [ ] PR with config for StateMate (see R1) +- [ ] Correct pre-endorsement state (see R9) +- [ ] Official bridging UI utilizes the customized bridge endpoint contract + +### Architecture checklist + +If a reference architecture is used, consider all checked. Otherwise, please fill out the list, providing the details if following not strictly. + +- [ ] Lock and mint bridge mechanics (see R2) +- [ ] Robust bridging provider (one of) (see R3) + - [ ] Canonical bridge + - [ ] Aggregation 2/X + - [ ] 1 bridge provider with framework to add/change at least 2 +- [ ] Dedicated governance contract on target network for bridging L1 Lido DAO decisions (see R4) +- [ ] Governance bridging (one of) (see R TODO) + - [ ] Canonical bridge + - [ ] Aggregation with a.DI with 2/2, 3/4, 3/5 (Wormhole x Chainlink x Hyperlane x Axelar x LayerZero) +- [ ] Dedicated upgradable L1 bridge instance (see R6) +- [ ] Dedicated upgradable target network bridge instance (see R6) +- [ ] L2 wstETH token upgradable (see R5) +- [ ] Pausable deposits (see R7) +- [ ] Pausable withdrawals (see R7) +- [ ] Support of ERC-2612 permit enhanced with EIP-1271 (see R8) +- [ ] Token/bridge state before endorsement (see R9) +- [ ] AccessControlEnumerable is used for ACL (see R11) +- [ ] No same contract addresses (see R13) + +### Other questions + +1. Bridges are complicated in that the transaction can succeed on one side and fail on the other. What's the handling mechanism for this issue + ## FAQ ### Our network is Y-compatible, how about reusing the solution present on Y? @@ -349,36 +371,40 @@ If so, please don't alter the contract's code and use the same names. It allows To speed up the process, you might perform a deployment verification against the bytecode already used for another network and configuration/storage state comparison to be 1:1 except only for the network specific configuration changes needed. Follow the case of [`wstETH on Mode`](https://research.lido.fi/t/wsteth-deployment-on-mode/7365) for the reference. -### What if wstETH is already bridged and has ample liquidity? +### What if wstETH is already bridged? -Please consider getting in touch with the NEC if (**R-1...R-4**) are followed. +Here is also an approximate decision tree to guide on this scenario. +Please consider getting in touch with the NEC but for -## Questionnaire +```mermaid +graph TD; + A("Is wstETH already bridged and has got adoption?") + B("Is the bridged token deployed behind a proxy (follows R-4)?") + C("Follow the general scenario
towards DAO recognition") + D("Consider migrating liquidity and redeploying,
following the general scenario towards
DAO recognition") + F["Consider delivering and/or committing
to deliver the missing parts.
Contact NEC for the best way forward"] + + A-- Yes -->B + B-- Yes -->F + A-- No -->C + B-- No -->D +``` + +### What is the bridging endpoints recognition? + +Previously, the Lido DAO recognized the bridging endpoints by means of a signalling snapshot. For example, it happened for +[Base](https://snapshot.org/#/lido-snapshot.eth/proposal/0x8b35f64fffe67f67d4aeb2de2f3351404c54cd75a08277c035fa77065b6792f4). +Now, after establishing the [NEC](https://snapshot.org/#/s:lido-snapshot.eth/proposal/0x7cdf1af7cfeb472ae202c45fb6d7e952bb34bfcbc82113549986b2bc2d5f54c5), the bridged endpoints get recognized by NEC decision (yet Lido DAO has the overruling power). + +If the bridged token endpoints are recognized, in general, it means: + +- the integration is highlighted on the frontend pages: [landing](https://lido.fi/lido-multichain), [widget](https://stake.lido.fi/), and [ecosystem pages](https://lido.fi/lido-ecosystem); +- the newly appeared integration announcement is published in the Lido's [blog](https://blog.lido.fi/category/l2/) and [twitter](https://twitter.com/LidoFinance); +- the endpoint contracts get monitored by means of [Lido alerting system](https://github.com/lidofinance/alerting-forta/); +- the opportunity for obtaining extra support, potentially from [LEGO](https://lido.fi/lego) or [Liquidity observation Labs](https://lido.fi/governance#liquidity-observation-labs), becomes available. For the details one should [reach out to ProRel](https://tally.so/r/waeRLX). +- the endpoint contracts are under the Lido's [bug bounty program](https://immunefi.com/bug-bounty/lido/); +- when/if the dedicated bridging Lido UI is implemented, the network will be included; -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. - -| Question | Is followed and/or comment | -| -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | -| Has wstETH been bridged? | yes/no | -| If bridged, how much adoption token has got? | yes/no | -| R-1: Audited code and verifiable deployment | yes/no/partially | -| R-2: Lock-and-mint bridge mechanics | yes/no | -| R-3: Usage of canonical bridge | yes/no | -| R-4: L2 wstETH token upgradable | yes/no/partially | -| R-5: Bridging L1 Lido DAO decisions | yes/no/partially | -| R-6: Dedicated upgradable bridge instances | yes/no/partially | -| R-7: Pausable deposits and withdrawals | yes/no/partially | -| R-8: ERC-2612 permit enhanced with EIP-1271 | yes/no/partially | -| R-9: Token/bridge state before snapshot vote | yes/no/partially | -| R-10: Upgradability mechanics | yes/no/partially | -| R-11: Use AccessControlEnumerable for ACL | yes/no/partially | -| R-12: Share the deploy artifacts | yes/no/partially | -| R-13: No same contract addresses | yes/no | -| Bridges are complicated in that the transaction can succeed on one side and fail on the other. What's the handling mechanism for this issue? | | -| Is there a deployment script that sets all the parameters and authorities correctly? | | -| Is there a post-deploy check script that, given a deployment, checks that all parameters and authorities are set correctly? | | ## References @@ -393,3 +419,4 @@ In the comments section, please provide the relevant details: the artifacts, if - Lido DAO recognition proposal for wstETH on Linea https://research.lido.fi/t/wsteth-on-linea-ownership-acceptance-by-lido-dao/5961 - Lido DAO recognition proposal for wstETH on Scroll https://research.lido.fi/t/wsteth-deployment-on-scroll/6603 - Lido DAO recognition proposal for wstETH on Mode https://research.lido.fi/t/wsteth-deployment-on-mode/7365 +- Wormhole x Axelar | Lido Bridge: Implementation for wstETH on BNB Chain https://research.lido.fi/t/wormhole-x-axelar-lido-bridge-implementation-for-wsteth-on-bnb-chain/6012/3 From 02557e1e84ae7700083a8436d7f1d0c3b9e63431 Mon Sep 17 00:00:00 2001 From: Veremeenko Artyom Date: Thu, 30 Jan 2025 21:26:05 +0400 Subject: [PATCH 2/7] Update docs/token-guides/wsteth-bridging-guide.md Co-authored-by: Eugene Mamin --- docs/token-guides/wsteth-bridging-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/token-guides/wsteth-bridging-guide.md b/docs/token-guides/wsteth-bridging-guide.md index 8aca9c871..5d35065ed 100644 --- a/docs/token-guides/wsteth-bridging-guide.md +++ b/docs/token-guides/wsteth-bridging-guide.md @@ -1,4 +1,4 @@ -# Lido tokens adoption guide +# Lido cross-chain tokens adoption guide :::warning Disclaimer 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. From 3c83a7b2b3a47dc1f2855d43582afa7798fc001d Mon Sep 17 00:00:00 2001 From: Veremeenko Artyom Date: Thu, 30 Jan 2025 21:29:14 +0400 Subject: [PATCH 3/7] Apply suggestions from code review Co-authored-by: Eugene Mamin --- docs/token-guides/wsteth-bridging-guide.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/token-guides/wsteth-bridging-guide.md b/docs/token-guides/wsteth-bridging-guide.md index 5d35065ed..9c8c5e005 100644 --- a/docs/token-guides/wsteth-bridging-guide.md +++ b/docs/token-guides/wsteth-bridging-guide.md @@ -6,12 +6,12 @@ This guide provides recommendations provided by the [Network Expansion Committee ## Intro -This document is intended for the developers representing network/rollup foundations and DAOs looking to bridge Lido tokens (wstETH, stETH). +This document is intended for the developers representing network/rollup foundations/bridge infra providers and DAOs looking to establish Lido tokens (wstETH, stETH) bridged representations outside Ethereum Mainnet. 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. While technically, it is feasible to bridge the wstETH/stETH token as any other standard non-upgradable ERC-20 compatible token, -it might not be aligned with the long-term vision of the Lido DAO , nor support the stETH rebasable nature. +it might not be aligned with the long-term vision of the Lido DAO, nor support the stETH rebasable nature, nor lay out the foundation for cross-chain interoperability considerations in future. :::info Please note that bridging rebasable stETH token in a regular way might cause a loss of user assets due to the rewards accrued being stuck on an L1 bridge. @@ -23,7 +23,7 @@ The solution involves deploying dedicated bridge endpoint contracts behind proxy all governed by the Lido DAO on L1 ([Aragon Agent contract](https://etherscan.io/address/0x3e40D73EB977Dc6a537aF587D48316feE66E9C8c)) via a dedicated governance executor contract on target network. This architecture is proposed to provide the following capabilities. -1. Passing arbitrary data. It allows delivering wstETH/stETH rate to the target network. +1. Passing arbitrary data. E.g., it allows delivering wstETH/stETH rate to the target network or implementing any potential sophisticated interoperability-enabled messaging. 2. Revamping the token logic, as stETH is not a general-purpose token but an asset built on top of a living liquid-staking middleware. 3. Future-proofing the token, for example, to avoid high-cost liquidity migration as Ethereum continues evolving and new standards like [ERC-2612](https://eips.ethereum.org/EIPS/eip-2612)/[ERC-1271](https://eips.ethereum.org/EIPS/eip-1271) are adopted. 4. Pausing and resuming bridging in an emergency or during upgrades. @@ -41,15 +41,15 @@ If none of the reference setups matches your case, follow though the [Recommenda In any case, follow the [General scenario towards the recognition](#general-scenario-towards-the-recognition). -### Optimistic rollup, wstETH + stETH +### Ethereum L2 built on OP-Stack, wstETH + stETH Use [multichain-automaton](https://github.com/lidofinance/multichain-automaton) for automated deployment of wstETH + stETH setup. -### Optimistic rollup, wstETH +### Ethereum L2, wstETH Deploy the setup from [lido-l2](https://github.com/lidofinance/lido-l2) repository. -### Non-rollup network, wstETH +### alt-L1 network or L2 with non-native canonical ecosystem-wide bridges, wstETH Use [Wormhole x Axelar | Lido Bridge: Implementation for wstETH on BNB Chain](https://research.lido.fi/t/wormhole-x-axelar-lido-bridge-implementation-for-wsteth-on-bnb-chain/6012/3) as a reference for bridging wstETH via aggregation and bridging governance decisions via [a.DI](https://github.com/lidofinance/aave-delivery-infrastructure). From 8c1eaf75ee381c543a036d6116c48624a04607d6 Mon Sep 17 00:00:00 2001 From: Artyom Veremeenko Date: Wed, 5 Feb 2025 16:03:58 +0300 Subject: [PATCH 4/7] feat(bridging-guide): bunch of work on the former wsteth bridging guide --- docs/guides/lido-tokens-integration-guide.md | 4 +- ...verify-steth-on-optimism-upgrade-manual.md | 2 +- ...g-guide.md => cross-chain-tokens-guide.md} | 314 ++++++++++-------- docusaurus.config.js | 5 + sidebars.js | 2 +- 5 files changed, 186 insertions(+), 141 deletions(-) rename docs/token-guides/{wsteth-bridging-guide.md => cross-chain-tokens-guide.md} (61%) diff --git a/docs/guides/lido-tokens-integration-guide.md b/docs/guides/lido-tokens-integration-guide.md index 77022520e..0557283a6 100644 --- a/docs/guides/lido-tokens-integration-guide.md +++ b/docs/guides/lido-tokens-integration-guide.md @@ -278,7 +278,7 @@ Currently, wstETH token is [present on](/docs/deployed-contracts/index.md#lido-m - [Mode](https://explorer.mode.network/address/0x98f96A4B34D03a2E6f225B28b8f8Cb1279562d81) - [Binance Smart Chain (BSC)](https://bscscan.com/address/0x26c5e01524d2E6280A48F2c50fF6De7e52E9611C) -with bridging implemented via [the canonical bridges recommended approach](/docs/token-guides/wsteth-bridging-guide.md). +with bridging implemented via [the canonical bridges recommended approach](/docs/token-guides/cross-chain-tokens-guide.md). :::note Unlike on the Ethereum mainnet, wstETH for Lido Multichain is a plain ERC-20 token and cannot be unwrapped to unlock stETH on the corresponding L2 network unless handled via [LIP-22](https://github.com/lidofinance/lido-improvement-proposals/blob/develop/LIPS/lip-22.md) @@ -493,7 +493,7 @@ The integration might be implemented leveraging the [Lido on Ethereum SDK](/docs ### Cross chain bridging The Lido's wstETH gets bridged to various L2's and sidechains. -The process of a new network adoption in a future-proof way is outlined as a part of the separate [bridging guide](/docs/token-guides/wsteth-bridging-guide.md). +The process of a new network adoption in a future-proof way is outlined as a part of the separate [bridging guide](/docs/token-guides/cross-chain-tokens-guide.md). Most cross-chain token bridges have no mechanics to handle rebases. This means bridging stETH to other chains will prevent stakers from collecting their staking rewards. diff --git a/docs/guides/verify-steth-on-optimism-upgrade-manual.md b/docs/guides/verify-steth-on-optimism-upgrade-manual.md index 37618d67a..64247344e 100644 --- a/docs/guides/verify-steth-on-optimism-upgrade-manual.md +++ b/docs/guides/verify-steth-on-optimism-upgrade-manual.md @@ -5,7 +5,7 @@ The full list of the contracts in scope is provided in the Lido Multichain section for [Optimism](https://docs.lido.fi/deployed-contracts/#optimism). :::note -Levers and access control lists for L1 and L2 bridge endpoints stay the same and correspond to the [reference architecture and permissions setup](/token-guides/wsteth-bridging-guide.md#reference-architecture-and-permissions-setup). +Levers and access control lists for L1 and L2 bridge endpoints stay the same and correspond to the [reference architecture and permissions setup](/token-guides/cross-chain-tokens-guide.md#reference-architecture-and-permissions-setup). This document covers incremental changes proposed with the stETH on Optimism deployment. ::: diff --git a/docs/token-guides/wsteth-bridging-guide.md b/docs/token-guides/cross-chain-tokens-guide.md similarity index 61% rename from docs/token-guides/wsteth-bridging-guide.md rename to docs/token-guides/cross-chain-tokens-guide.md index 9c8c5e005..3f612e0e9 100644 --- a/docs/token-guides/wsteth-bridging-guide.md +++ b/docs/token-guides/cross-chain-tokens-guide.md @@ -4,76 +4,51 @@ 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 - -This document is intended for the developers representing network/rollup foundations/bridge infra providers and DAOs looking to establish Lido tokens (wstETH, stETH) bridged representations outside Ethereum Mainnet. - -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. - -While technically, it is feasible to bridge the wstETH/stETH token as any other standard non-upgradable ERC-20 compatible token, -it might not be aligned with the long-term vision of the Lido DAO, nor support the stETH rebasable nature, nor lay out the foundation for cross-chain interoperability considerations in future. - -:::info -Please note that bridging rebasable stETH token in a regular way might cause a loss of user assets due to the rewards accrued being stuck on an L1 bridge. -::: - -To close the gaps this guide proposes to implement a more complex solution. - -The solution involves deploying dedicated bridge endpoint contracts behind proxy on L1 and the target network and an upgradable token on the target network, -all governed by the Lido DAO on L1 ([Aragon Agent contract](https://etherscan.io/address/0x3e40D73EB977Dc6a537aF587D48316feE66E9C8c)) -via a dedicated governance executor contract on target network. This architecture is proposed to provide the following capabilities. - -1. Passing arbitrary data. E.g., it allows delivering wstETH/stETH rate to the target network or implementing any potential sophisticated interoperability-enabled messaging. -2. Revamping the token logic, as stETH is not a general-purpose token but an asset built on top of a living liquid-staking middleware. -3. Future-proofing the token, for example, to avoid high-cost liquidity migration as Ethereum continues evolving and new standards like [ERC-2612](https://eips.ethereum.org/EIPS/eip-2612)/[ERC-1271](https://eips.ethereum.org/EIPS/eip-1271) are adopted. -4. Pausing and resuming bridging in an emergency or during upgrades. +## TL;DR -The wstETH and stETH tokens design follows the [LIP-22](https://github.com/lidofinance/lido-improvement-proposals/blob/develop/LIPS/lip-22.md) architecture approach. +If you are looking for a typical copy-paste solution, refer to the suitable subsection below if any fits your case. +Follow the [General Scenario Towards Recognition](#general-scenario-towards-the-recognition). -See the [lido-l2-with-steth](https://github.com/lidofinance/lido-l2-with-steth/) repository for more details. +### Ethereum L2 built on OP-Stack, wstETH + stETH -## TL;DR +Use [multichain-automaton](https://github.com/lidofinance/multichain-automaton) for automated deployment of the wstETH + stETH setup. This tool will automatically deploy the default wstETH + stETH setup, which satisfies the required [Recommendations](#recommendations). -In case you are looking for a typical copy-paste solution, refer to the suitable subsection below for a reference implementation. -Any of these setups satisfies the minimum [Recommendations](#recommendations) for the Lido tokens bridging solution. +Please follow recommendation R-9, which is specific to stETH bridging. -If none of the reference setups matches your case, follow though the [Recommendations](#recommendations) section and fill out the [Architecture checklist](#architecture-checklist) for further evaluation by NEC. +### Ethereum L2, wstETH -In any case, follow the [General scenario towards the recognition](#general-scenario-towards-the-recognition). +Deploy the setup from the [lido-l2](https://github.com/lidofinance/lido-l2) repository. This repository allows you to deploy the default wstETH setup, which satisfies the required [Recommendations](#recommendations). -### Ethereum L2 built on OP-Stack, wstETH + stETH +### alt-L1 network or L2 with non-native canonical ecosystem-wide bridges, wstETH -Use [multichain-automaton](https://github.com/lidofinance/multichain-automaton) for automated deployment of wstETH + stETH setup. +#### Bridge early without NEC endorsement -### Ethereum L2, wstETH +It is acceptable to start with a simpler opening transient bridging implementation while obtaining liquidity. In this case, recommendations R-1 to R-4 and "transient" recommendations R-5-transient and R-6-transient are **required** for the possibility of future endorsement. -Deploy the setup from [lido-l2](https://github.com/lidofinance/lido-l2) repository. +#### Bridge with NEC endorsement from the start or getting endorsement when high liquidity -### alt-L1 network or L2 with non-native canonical ecosystem-wide bridges, wstETH +In this case, the required recommendations are R-1 to R-6. -Use [Wormhole x Axelar | Lido Bridge: Implementation for wstETH on BNB Chain](https://research.lido.fi/t/wormhole-x-axelar-lido-bridge-implementation-for-wsteth-on-bnb-chain/6012/3) +Consider [Wormhole x Axelar | Lido Bridge: Implementation for wstETH on BNB Chain](https://research.lido.fi/t/wormhole-x-axelar-lido-bridge-implementation-for-wsteth-on-bnb-chain/6012/3) as a reference for bridging wstETH via aggregation and bridging governance decisions via [a.DI](https://github.com/lidofinance/aave-delivery-infrastructure). -Adhere to TODO R-1...R-8. +Adhere to recommendations R-1 to R-8. ## General scenario towards the recognition This section describes an approximate path to bridging Lido tokens to a network. The order of the steps is not strict but follows the general flow. -🐾 Study the bridging guide and fill in [Architecture checklist](#architecture-checklist) about your solution and send it to the NEC. - -🐾 Get the architecture and the deploy configuration verified by the NEC. +🐾 Study the bridging guide, starting from the TL;DR section. -🐾 Coordinate on priority lane, timings, and reviews with the NEC. +🐾 Fill in the [Architecture Checklist](#architecture-checklist) about your setup. Send it to the NEC. Get the deployment green light. -🐾 Deploy the contracts to testnet. Get approval of the setup by the NEC. +🐾 Deploy the contracts to testnet and/or mainnet. Follow the [Deployment and Verification Checklist](#deployment-and-verification-checklist). -🐾 Express intention to bridge wstETH on the forum, outlining the details and technical plan. Consider: +🐾 Make a proposal on the forum, outlining the details and technical plan. Consider: - Target one network per proposal to make the discussion more focused. - The post should be published in advance to allow time for discussion and verification of the proposal. -- The deployment addresses are not required at once but must be proposed at least a week before the snapshot voting starts. -- If the proposed solution does not fulfill some of the recommendations consider including the roadmap and committing to deliver it. +- If the proposed solution does not fulfill some of the recommendations, consider including the roadmap and committing to deliver it. - Examples: - [wstETH to Base](https://research.lido.fi/t/wsteth-deployment-to-base-and-ownership-acceptance-by-lido-dao/5668) - [wstETH to ZKSync](https://research.lido.fi/t/wsteth-deployment-on-zksync/5701) @@ -81,27 +56,56 @@ This section describes an approximate path to bridging Lido tokens to a network. - [wstETH and stETH to Soneium](https://research.lido.fi/t/steth-wsteth-deployment-on-soneium/9389/2) - [wstETH to BSC by Wormhole x Axelar](https://research.lido.fi/t/wormhole-x-axelar-lido-bridge-implementation-for-wsteth-on-bnb-chain/6012) -🐾 Deploy the contracts to mainnet. Get pre-endorsement approval of the setup by the NEC. +🐾 Get transient/pre-endorsement approval of the setup from the NEC. + +:::info +It is fine to have the contracts in a pre-NEC-approved state in an unpaused state. Nevertheless, consider the risks of liquidity fragmentation in case the currently deployed setup is not approved or recognized, but liquidity has already been deposited. +::: + +🐾 [Optional, if going from the transient state] Transition the setup to the pre-endorsement state according to the [Recommendations](#recommendations). Express this in the forum post and get NEC approval. + +🐾 [If not done yet] Pass ownership of the bridging endpoints to the Lido DAO. -🐾 Pass ownership of the bridging endpoints to the Lido DAO. The final setup goes through final verification by the external security group (organized by the NEC). +🐾 Get the setup final verification by an external security group (possibly with the help of the NEC). -🐾 Get the endorsement by NEC expressed in research.lido.fi forum post. +🐾 Get the endorsement by the NEC expressed in the forum post. :::warning Ensure that the official bridging UI utilizes the customized bridge endpoint contract. Using the default bridge contract in the past caused problems, leading to deposited funds becoming locked within the contract. ::: +## Motivation of this guide + +This document is intended for developers representing network/rollup foundations, bridge infrastructure providers, and DAOs looking to establish Lido tokens (wstETH, stETH) bridged representations outside the Ethereum Mainnet. + +This guide covers the recommendations, provides general guidelines, and reveals the logic behind them 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 the community. + +While technically feasible, bridging the wstETH/stETH token as any other standard non-upgradable ERC-20 compatible token might not align with the long-term vision of the Lido DAO, nor support the stETH rebasable nature, nor lay out the foundation for future cross-chain interoperability considerations. + +:::info +Please note that bridging the rebasable stETH token in a regular way might cause a loss of user assets due to the rewards accrued being stuck on an L1 bridge. For non-OP Stack networks, consider wstETH to be the default way to go. +::: + +To close the gaps, this guide proposes implementing a more complex solution. + +The solution involves deploying dedicated bridge endpoint contracts behind a proxy on L1 and the target network, and an upgradable token on the target network, all governed by the Lido DAO on L1 ([Aragon Agent contract](https://etherscan.io/address/0x3e40D73EB977Dc6a537aF587D48316feE66E9C8c)) via a dedicated governance executor contract on the target network. This architecture is proposed to provide the following capabilities: + +1. Passing arbitrary data. For example, it allows delivering the wstETH/stETH rate to the target network or implementing any potential sophisticated interoperability-enabled messaging. +2. Revamping the token logic, as stETH is not a general-purpose token but an asset built on top of a living liquid-staking middleware. +3. Future-proofing the token, for example, to avoid high-cost liquidity migration as Ethereum continues evolving and new standards like [ERC-2612](https://eips.ethereum.org/EIPS/eip-2612)/[ERC-1271](https://eips.ethereum.org/EIPS/eip-1271) are adopted. +4. Pausing and resuming bridging in an emergency or during upgrades. + +The wstETH and stETH tokens design follows the [LIP-22](https://github.com/lidofinance/lido-improvement-proposals/blob/develop/LIPS/lip-22.md) architecture approach. + +See the [lido-l2-with-steth](https://github.com/lidofinance/lido-l2-with-steth/) repository for more details. + ## Recommendations This section enumerates design and security recommendations for a Lido tokens bridging solution. -Usually, the NEC recognizes the bridged endpoints only if at least recommendations **R-1..R-8** are followed. -The rest of the recommendations (**R-9...**) are also important and foster the recognition's likelihood. Some of them might be not applicable to non-rollup networks. - -TODO: ^ Rs numbers ### 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 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 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: @@ -127,26 +131,37 @@ To speed up the process and make it more robust, please provide the artifacts (i Use the lock-and-mint bridging mechanism. -The general security approach here is to isolate L2/cross-chain risks, ensuring no additional risks are imposed on Lido protocol on Ethereum or to other L2s and alt L1s with already bridged wstETH. This is almost unachievable with a ‘burn-and-mint’ architecture. +The general security approach here is to isolate L2/cross-chain risks, ensuring no additional risks are imposed on the Lido protocol on Ethereum or to other L2s and alt L1s with already bridged wstETH. This is almost unachievable with a 'burn-and-mint' architecture. + +### R-3: 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-4), it must provide the capability to set/change the bridge contract instance used. -### R-3: Robust token bridging provider +### R-4: Dedicated upgradable bridge instances -Usage of the bridge, canonical for the L2 network, is highly encouraged. +Deploy dedicated instances of bridge contracts on L1 and L2. The contract instances 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 laying the foundation for the emergency capabilities (R-7) and for possible bridging of rebasable stETH. For more details on why, see the section [Motivation of this guide](#motivation-of-this-guide). For the architecture outline, see the section [Reference wstETH architecture and permissions setup](#reference-wsteth-rollup-architecture-and-permissions-setup). -If the native bridge does not exist - what is typical for non-rollup networks - two options are possible. +### R-5: Robust token bridging provider -1. 1 bridge provider with framework to add/change at least 2 bridge providers -2. 2/X aggregation (X bridge providers, where X >= 2) +There are two main options: -Aggregation is preferred, but (1) is suitable as a temporary solution. +1. Usage of the native bridge as a token bridging provider +2. 2/X aggregation of X bridge providers, where X >= 2, in case the native bridge is not available -As a reference implementation of (1) and/or (2) one might consider +As a reference implementation of aggregations consider [Wormhole x Axelar | Lido Bridge: Implementation for wstETH on BNB Chain](https://research.lido.fi/t/wormhole-x-axelar-lido-bridge-implementation-for-wsteth-on-bnb-chain/6012/3). For the deployed addresses see [this](https://docs.lido.fi/deployed-contracts/#binance-smart-chain-bsc). -### R-4: Bridging L1 Lido DAO decisions +### R-5-transient: Pre robust token bridging provider + +If the native bridge does not exist or a fast bridging implementation is required, +as a transient state it is possible to use 1 arbitrary bridge provider with a framework to add/change to a solution following R-5. -A dedicated governance executor contract should be set as an admin of the L2 endpoint contracts. +### R-6: Bridging L1 Lido DAO decisions + +A dedicated governance executor contract should be set as an admin of the target network endpoint contracts. Rollup examples: @@ -158,73 +173,132 @@ Rollup examples: Non-rollup examples: -- [CrossChainExecutor](https://bscscan.com/address/0x8E5175D17f74d1D512de59b2f5d5A5d8177A123d) from a.DI (see R-3) - -[a.DI (Aave Delivery Infrastructure)](https://github.com/lidofinance/aave-delivery-infrastructure). It was used to bridge wstETH to Binance Smart Chain (BSC). -See this forum post for more details: [Wormhole x Axelar | Lido Bridge: Implementation for wstETH on BNB Chain](https://research.lido.fi/t/wormhole-x-axelar-lido-bridge-implementation-for-wsteth-on-bnb-chain/6012/3) +- [CrossChainExecutor](https://bscscan.com/address/0x8E5175D17f74d1D512de59b2f5d5A5d8177A123d) from a.DI (see R-6) +[a.DI (Aave Delivery Infrastructure)](https://github.com/lidofinance/aave-delivery-infrastructure). It was used to bridge governance to Binance Smart Chain (BSC). +See forum post [Wormhole x Axelar | Lido Bridge: Implementation for wstETH on BNB Chain](https://research.lido.fi/t/wormhole-x-axelar-lido-bridge-implementation-for-wsteth-on-bnb-chain/6012/3) for more details. For more rollup 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). -### R-5: L2 wstETH token upgradable +### R-6-transient: Pre bridging L1 Lido DAO decisions -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. +For the transient state, one of the following options is applicable: -### R-6: Dedicated upgradable bridge instances +- the bridging provider used can upgrade the bridge endpoint contract and wstETH token +- the target network onchain representative can upgrade the bridge endpoint contract and wstETH token -Deploy dedicated instances of bridge contracts on L1 and L2. The contract instances 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 to lay the foundation for the emergency capabilities (**R-7**) and for possible bridging of rebasable stETH. For more details on why, see for section [Why is this guide needed](#why-is-this-guide-needed). For the architecture outline, see section [Reference architecture and permissions setup](#reference-architecture-and-permissions-setup). +There must be a capability to transition to the R-6 state. ### R-7: Pausable deposits and withdrawals To provide the capability to react fast and reduce losses in case of a security contingency, depositing and withdrawing should be pausable. Namely: - L1 bridge endpoint has pausable and resumable deposits; -- L2 bridge endpoint and has pausable and resumable withdrawals. +- L2 bridge endpoint has pausable and resumable withdrawals. -The bridge endpoint contracts should have an ability to set the resume and pause roles holders on a case-by-case basis. For the pause role there should be at least two holders possible to be able to assign the dedicated Emergency Multisig which is [ratified by the Lido DAO](https://snapshot.org/#/lido-snapshot.eth/proposal/0xfe2a6a6506a642b616118363bc29aa83dd9ef2ec80447bb607a8f52c0a96aed0) as the second role holder. +The bridge endpoint contracts should have the ability to set the resume and pause roles holders on a case-by-case basis. For the pause role, there should be at least two holders possible to be able to assign the dedicated Emergency Multisig which is [ratified by the Lido DAO](https://snapshot.org/#/lido-snapshot.eth/proposal/0xfe2a6a6506a642b616118363bc29aa83dd9ef2ec80447bb607a8f52c0a96aed0) as the second role holder. -To curb the multisig's power, it is proposed to use the "Gate Seals" mechanic. The mechanic limits the pause duration and restricts the capability to pause to a single use. To grant the capability repeatedly, the Lido DAO vote is required. The mechanic has been implemented, e.g., for withdrawals in Lido protocol on Ethereum in two parts: +To curb the multisig's power, it is proposed to use the "Gate Seals" mechanic. The mechanic limits the pause duration and restricts the capability to pause to a single use. To grant the capability repeatedly, the Lido DAO vote is required. The mechanic has been implemented, e.g., for withdrawals in the Lido protocol on Ethereum in two parts: - one-time disposable pauser contact [Gate Seals](https://github.com/lidofinance/gate-seals); - [PausableUntil](https://github.com/lidofinance/lido-dao/blob/master/contracts/0.8.9/utils/PausableUntil.sol) contract (inherited by [WithdrawalQueue](https://github.com/lidofinance/lido-dao/blob/master/contracts/0.8.9/WithdrawalQueue.sol)). ### R-8: The contracts state -There are two states to consider: pre-endorsement and endorsement. +There are three contract states to consider: transient, pre-endorsement, and endorsement. + +The transient state is applicable for the transient setup when not all the minimal recommendations are followed yet. +This state is mostly referred to [alt-L1 network or L2 with non-native canonical ecosystem-wide bridges, wstETH](alt-l1-network-or-l2-with-non-native-canonical-ecosystem-wide-bridges-wsteth). -Endorsement state is the state ready for the final NEC assessment and subsequent recognition. -Pre-endorsement state is when the contracts are deployed and the setup is yet to be evaluated by NEC for correctness. +The pre-endorsement state is applicable for the setup when all the minimal recommendations are followed +possibly except for the bridging endpoint ownership passed to the Lido DAO. +This state is aimed for the pre-endorsement evaluation of the setup by the NEC. -In the endorsement state, the permissions must be set as per [Reference rollup architecture and permissions setup](#reference-rollup-architecture-and-permissions-setup). +The endorsement state is the state ready for the final NEC and external security assessment and subsequent recognition. -In the pre-endorsement state, the admins of the contracts might be set to the representatives of the target network / bridging provider, to allow for amending the setup in case of any issues. +For example, in the endorsement state of the reference wstETH setup from +[lido-l2](https://github.com/lidofinance/lido-l2) repository, the permissions must be set as per +[Reference wstETH rollup architecture and permissions setup](#reference-wsteth-rollup-architecture-and-permissions-setup). -It is fine to have the contracts in the pre-endorsement state in unpaused state. -Nevertheless, consider risks of liquidity fragmentation in case the currently deployed setup is not got recognized but liquidity has already been deposited. +In the transient or pre-endorsement state, the owners of the endpoint contracts might be set to the representatives of the target network / bridging provider, to allow for amending the setup in case of any issues. -### R-9: No same contract addresses +### R-9: stETH rate pushing + +_Applicable only for the setup with stETH token._ + +The correct rate of the rebasable stETH token on the target network depends +on the timely rate update provided for the contract TokenRateOracle (see [example of it on Optimism](https://optimistic.etherscan.io/address/0x294ED1f214F4e0ecAE31C3Eae4F04EBB3b36C9d0)). + +Token rate update happens when: + +1. wstETH or stETH is bridged in a regular way; +2. `pushTokenRate` of L1 contract `OpStackTokenRatePusher` is called (see [example on Optimism](https://etherscan.io/address/0xd54c1c6413caac3477AC14b2a80D5398E3c32FfE#writeContract#F1)). + +The tokens might not get bridged by users for periods of time, that is why a mechanism to call `pushTokenRate` timely is required. +It should be called either periodically or occasionally when the rate is not updated for some time. +Which option to choose is up to the user of this guide. +The goal is not to let the rate get outdated for longer than 5 days. +The last updated timestamp is retrievable from the `TokenRateOracle` contract by call of `latestRoundData` function (see field `updatedAt_`). + +### R-10: No same contract addresses Please avoid deploying contracts to the same addresses on L1 and L2 and/or testnets, as this might occur when deploying from a single EOA to multiple networks. Following this recommendation helps to avoid potential confusion in the future. -### R-10: Support of ERC-2612 permit enhanced with EIP-1271 +### R-11: Support of ERC-2612 permit enhanced with EIP-1271 The bridged wstETH should support [EIP-2612 permit ERC-20 token extension](https://eips.ethereum.org/EIPS/eip-2612) with [EIP-1271 standard signature validation method for contracts](https://eip1271.io/). The latter paves the way to Account Abstraction adoption, see https://eip1271.io/. Please take into account that the [OpenZeppelin ERC20 with permit (EIP-2612) implementation](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/extensions/ERC20Permit.sol) does not support smart contract signatures validation EIP-1271 and thus shouldn't be used as it is. Please consider extending ERC20Permit using [OpenZeppelin SignatureChecker util](https://docs.openzeppelin.com/contracts/4.x/api/utils#SignatureChecker) or [stETHPermit contract](https://github.com/lidofinance/lido-dao/blob/master/contracts/0.4.24/StETHPermit.sol) as a reference implementation. NB, that the wstETH token itself on Ethereum doesn't support this due to non-upgradability. -### R-11: Upgradability mechanics +### R-12: Upgradability mechanics - The regular (`ERC1967Proxy`) proxy pattern is good enough; the transparent proxy pattern might be an unnecessary complication. -- Use ossifiable proxies when possible. For example, consider [OssifiableProxy](https://github.com/lidofinance/lido-l2/blob/main/contracts/proxy/OssifiableProxy.sol), which is used in Lido protocol on Ethereum. +- Use ossifiable proxies when possible. For example, consider [OssifiableProxy](https://github.com/lidofinance/lido-l2/blob/main/contracts/proxy/OssifiableProxy.sol), which is used in the Lido protocol on Ethereum. Please have the implementations petrified with dummy values. It helps to reduce confusion, like taking the implementation address instead of the proxy address. For example, see [zkSync Era ERC20BridgedUpgradeable implementation](https://explorer.zksync.io/address/0xc7a0daa1b8fea68532b6425d0e156088b0d2ab2c#contract) (bridge, decimals, name, symbol views). -### R-12: Use AccessControlEnumerable for ACL +### R-13: Use AccessControlEnumerable for ACL For access control, please prefer the standard OpenZeppelin ACL contract and its [enumerable version](https://docs.openzeppelin.com/contracts/4.x/api/access#AccessControlEnumerable) over non-enumerable versions. It allows full on-chain permissions verification — no need to analyze events or transactions as in non-enumerable implementations. For example, see [Lido ValidatorsExitBusOracle contract](https://etherscan.io/address/0xa89ea51fdde660f67d1850e03c9c9862d33bc42c#code). -## Reference architecture and proposed configuration +## Questionnaire + +### Deployment and verification checklist + +- [ ] Audited by a third party (see R-1) +- [ ] Deployed code matches the commit in the audit report precisely (see R-1) +- [ ] Sources verified on block explorers without flattening (see R-1) +- [ ] PR with config for Diffyscan (see R-1) +- [ ] PR with config for StateMate (see R-1) +- [ ] Correct contracts state before endorsement (see R-8) +- [ ] Official bridging UI utilizes the customized bridge endpoint contract (see warning in [General scenario](#general-scenario-towards-the-recognition)) + +### Architecture checklist + +If non-reference architecture is used +(nor [Ethereum L2 built on OP-Stack, wstETH + stETH](#ethereum-l2-built-on-op-stack-wsteth-steth), +nor [Ethereum L2, wstETH](#ethereum-l2-wsteth)) +please fill out the list, providing the details if needed. + +- [ ] Lock and mint bridge mechanics (see R-2) +- [ ] Robust bridging provider (one of) (see R-5) + - [ ] Canonical bridge + - [ ] Aggregation 2/X + - [ ] 1 bridge provider with framework to add/change at least 2 +- [ ] Dedicated governance contract on target network for bridging L1 Lido DAO decisions (see R-6) +- [ ] Governance bridging (one of) (see R-6) + - [ ] Canonical bridge + - [ ] Aggregation with a.DI with 2/2, 3/4 or 3/5 +- [ ] Dedicated upgradable L1 bridge instance (see R-4) +- [ ] Dedicated upgradable target network bridge instance (see R-4) +- [ ] L2 wstETH token upgradable (see R-3) +- [ ] Pausable deposits (see R-7) +- [ ] Pausable withdrawals (see R-7) +- [ ] Support of ERC-2612 permit enhanced with EIP-1271 (see R-11) +- [ ] (if applicable) stETH rate is pushed timely (see R-9). Please provide the implementation details. +- [ ] No same contract addresses (see R-10) +- [ ] AccessControlEnumerable is used for ACL (see R-13) + +## Reference wstETH rollup architecture and permissions setup This section describes a kind of minimal bridging contracts setup and its configuration. This setup is a recommendation and might not be the best for a specific network — it serves as a suggestion for the main functional parts and their interconnections. @@ -322,46 +396,26 @@ Please, deploy to Holešky if possible because it has better long-term exposure - `Emergency Brakes L2 Multisig` - `0xa5F1d7D49F581136Cf6e58B32cBE9a2039C48bA1` (EOA) -## Questionnaire - -### Deployment and verifiability checklist - -- [ ] Audited by a third party (see R1) -- [ ] Deployed code matches the commit in the audit report precisely (see R1) -- [ ] Sources verified on block explorers without flattening (see R1) -- [ ] PR with config for Diffyscan (see R1) -- [ ] PR with config for StateMate (see R1) -- [ ] Correct pre-endorsement state (see R9) -- [ ] Official bridging UI utilizes the customized bridge endpoint contract +### Other questions -### Architecture checklist +1. Bridges are complicated in that the transaction can succeed on one side and fail on the other. What's the handling mechanism for this issue -If a reference architecture is used, consider all checked. Otherwise, please fill out the list, providing the details if following not strictly. +## FAQ -- [ ] Lock and mint bridge mechanics (see R2) -- [ ] Robust bridging provider (one of) (see R3) - - [ ] Canonical bridge - - [ ] Aggregation 2/X - - [ ] 1 bridge provider with framework to add/change at least 2 -- [ ] Dedicated governance contract on target network for bridging L1 Lido DAO decisions (see R4) -- [ ] Governance bridging (one of) (see R TODO) - - [ ] Canonical bridge - - [ ] Aggregation with a.DI with 2/2, 3/4, 3/5 (Wormhole x Chainlink x Hyperlane x Axelar x LayerZero) -- [ ] Dedicated upgradable L1 bridge instance (see R6) -- [ ] Dedicated upgradable target network bridge instance (see R6) -- [ ] L2 wstETH token upgradable (see R5) -- [ ] Pausable deposits (see R7) -- [ ] Pausable withdrawals (see R7) -- [ ] Support of ERC-2612 permit enhanced with EIP-1271 (see R8) -- [ ] Token/bridge state before endorsement (see R9) -- [ ] AccessControlEnumerable is used for ACL (see R11) -- [ ] No same contract addresses (see R13) +### What is the bridging endpoints recognition? -### Other questions +Previously, the Lido DAO recognized the bridging endpoints by means of a signalling snapshot. For example, it happened for +[Base](https://snapshot.org/#/lido-snapshot.eth/proposal/0x8b35f64fffe67f67d4aeb2de2f3351404c54cd75a08277c035fa77065b6792f4). +Now, after establishing the [NEC](https://snapshot.org/#/s:lido-snapshot.eth/proposal/0x7cdf1af7cfeb472ae202c45fb6d7e952bb34bfcbc82113549986b2bc2d5f54c5), the bridged endpoints get recognized by NEC decision (yet Lido DAO has the overruling power). -1. Bridges are complicated in that the transaction can succeed on one side and fail on the other. What's the handling mechanism for this issue +If the bridged token endpoints are recognized, in general, it means: -## FAQ +- the integration is highlighted on the frontend pages: [landing](https://lido.fi/lido-multichain), [widget](https://stake.lido.fi/), and [ecosystem pages](https://lido.fi/lido-ecosystem); +- the newly appeared integration announcement is published in the Lido's [blog](https://blog.lido.fi/category/l2/) and [twitter](https://twitter.com/LidoFinance); +- the endpoint contracts get monitored by means of [Lido alerting system](https://github.com/lidofinance/alerting-forta/); +- the opportunity for obtaining extra support, potentially from [LEGO](https://lido.fi/lego) or [Liquidity observation Labs](https://lido.fi/governance#liquidity-observation-labs), becomes available. For the details one should [reach out to ProRel](https://tally.so/r/waeRLX). +- the endpoint contracts are under the Lido's [bug bounty program](https://immunefi.com/bug-bounty/lido/); +- when/if the dedicated bridging Lido UI is implemented, the network will be included; ### Our network is Y-compatible, how about reusing the solution present on Y? @@ -390,20 +444,6 @@ graph TD; B-- No -->D ``` -### What is the bridging endpoints recognition? - -Previously, the Lido DAO recognized the bridging endpoints by means of a signalling snapshot. For example, it happened for -[Base](https://snapshot.org/#/lido-snapshot.eth/proposal/0x8b35f64fffe67f67d4aeb2de2f3351404c54cd75a08277c035fa77065b6792f4). -Now, after establishing the [NEC](https://snapshot.org/#/s:lido-snapshot.eth/proposal/0x7cdf1af7cfeb472ae202c45fb6d7e952bb34bfcbc82113549986b2bc2d5f54c5), the bridged endpoints get recognized by NEC decision (yet Lido DAO has the overruling power). - -If the bridged token endpoints are recognized, in general, it means: - -- the integration is highlighted on the frontend pages: [landing](https://lido.fi/lido-multichain), [widget](https://stake.lido.fi/), and [ecosystem pages](https://lido.fi/lido-ecosystem); -- the newly appeared integration announcement is published in the Lido's [blog](https://blog.lido.fi/category/l2/) and [twitter](https://twitter.com/LidoFinance); -- the endpoint contracts get monitored by means of [Lido alerting system](https://github.com/lidofinance/alerting-forta/); -- the opportunity for obtaining extra support, potentially from [LEGO](https://lido.fi/lego) or [Liquidity observation Labs](https://lido.fi/governance#liquidity-observation-labs), becomes available. For the details one should [reach out to ProRel](https://tally.so/r/waeRLX). -- the endpoint contracts are under the Lido's [bug bounty program](https://immunefi.com/bug-bounty/lido/); -- when/if the dedicated bridging Lido UI is implemented, the network will be included; ## References diff --git a/docusaurus.config.js b/docusaurus.config.js index 298f0dc5b..e1e518387 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -61,6 +61,11 @@ module.exports = { { to: '/guides/lido-tokens-integration-guide', from: '/guides/steth-integration-guide', + }, + // /token-guides/wsteth-bridging-guide -> /token-guides/cross-chain-tokens-guide + { + to: '/token-guides/cross-chain-tokens-guide', + from: '/token-guides/wsteth-bridging-guide', } ], }, diff --git a/sidebars.js b/sidebars.js index 676ba8e64..085d51916 100644 --- a/sidebars.js +++ b/sidebars.js @@ -87,7 +87,7 @@ module.exports = { items: [ 'token-guides/steth-superuser-functions', 'token-guides/steth-on-aave-caveats', - 'token-guides/wsteth-bridging-guide', + 'token-guides/cross-chain-tokens-guide', ], }, { From ceda46f4391c126207a9f11359f7bb4c4111ff47 Mon Sep 17 00:00:00 2001 From: Veremeenko Artyom Date: Thu, 6 Feb 2025 13:54:00 +0400 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Eugene Mamin --- docs/token-guides/cross-chain-tokens-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/token-guides/cross-chain-tokens-guide.md b/docs/token-guides/cross-chain-tokens-guide.md index 3f612e0e9..6819600fc 100644 --- a/docs/token-guides/cross-chain-tokens-guide.md +++ b/docs/token-guides/cross-chain-tokens-guide.md @@ -1,7 +1,7 @@ # Lido cross-chain tokens adoption guide :::warning Disclaimer -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. +This guide provides recommendations supplied 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. ::: ## TL;DR @@ -236,7 +236,7 @@ Token rate update happens when: The tokens might not get bridged by users for periods of time, that is why a mechanism to call `pushTokenRate` timely is required. It should be called either periodically or occasionally when the rate is not updated for some time. Which option to choose is up to the user of this guide. -The goal is not to let the rate get outdated for longer than 5 days. +The goal is not to let the rate get outdated for longer than 2 days. The last updated timestamp is retrievable from the `TokenRateOracle` contract by call of `latestRoundData` function (see field `updatedAt_`). ### R-10: No same contract addresses From bc77ffc7ed191f2a9824b13e0de0809597e9618f Mon Sep 17 00:00:00 2001 From: Artyom Veremeenko Date: Thu, 6 Feb 2025 14:06:20 +0300 Subject: [PATCH 6/7] feat(bridging-guide): mentions setup types on lido-l2 repo --- docs/token-guides/cross-chain-tokens-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/token-guides/cross-chain-tokens-guide.md b/docs/token-guides/cross-chain-tokens-guide.md index 6819600fc..a7b94d87c 100644 --- a/docs/token-guides/cross-chain-tokens-guide.md +++ b/docs/token-guides/cross-chain-tokens-guide.md @@ -17,7 +17,7 @@ Please follow recommendation R-9, which is specific to stETH bridging. ### Ethereum L2, wstETH -Deploy the setup from the [lido-l2](https://github.com/lidofinance/lido-l2) repository. This repository allows you to deploy the default wstETH setup, which satisfies the required [Recommendations](#recommendations). +Deploy the setup from the [lido-l2](https://github.com/lidofinance/lido-l2) repository. This repository allows you to deploy the default wstETH setup on OP-Stack and Arbitrum networks. The setup satisfies the required [Recommendations](#recommendations). ### alt-L1 network or L2 with non-native canonical ecosystem-wide bridges, wstETH From b4730763a667d93a16167041b9bd8277d5325b92 Mon Sep 17 00:00:00 2001 From: Artyom Veremeenko Date: Thu, 6 Feb 2025 14:31:20 +0300 Subject: [PATCH 7/7] feat(bridging-guide): mention examples of modified setup of lido-l2 repo --- docs/token-guides/cross-chain-tokens-guide.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/token-guides/cross-chain-tokens-guide.md b/docs/token-guides/cross-chain-tokens-guide.md index a7b94d87c..6efabbb3a 100644 --- a/docs/token-guides/cross-chain-tokens-guide.md +++ b/docs/token-guides/cross-chain-tokens-guide.md @@ -17,7 +17,15 @@ Please follow recommendation R-9, which is specific to stETH bridging. ### Ethereum L2, wstETH -Deploy the setup from the [lido-l2](https://github.com/lidofinance/lido-l2) repository. This repository allows you to deploy the default wstETH setup on OP-Stack and Arbitrum networks. The setup satisfies the required [Recommendations](#recommendations). +Deploy the wstETH setup from the [lido-l2](https://github.com/lidofinance/lido-l2) repository. This repository allows you to deploy the default wstETH setup on OP-Stack and Arbitrum networks. The setup satisfies the required [Recommendations](#recommendations). + +If your stack requires a modification of the default setup, please consider examples of how it is done for: + +- [zkSync Era](https://github.com/lidofinance/lido-l2/pull/62) +- [Scroll](https://github.com/scroll-tech/scroll/pull/988) +- [Mantle](https://github.com/lidofinance/lido-l2/pull/63) + +For the governance forwarding setup, use the [Governance Bridge Executor](https://github.com/lidofinance/governance-crosschain-bridges) repository. ### alt-L1 network or L2 with non-native canonical ecosystem-wide bridges, wstETH