PR fixes: fix comments, readme, rename bridges, notifier refactoring

.env.example

@@ -25,23 +25,20 @@ ETHERSCAN_API_KEY_OPT=
 # Bridge/Gateway Deployment
 # ############################
 
-# Address of the token to deploy the bridge/gateway for
+# Address of the token on L1 to deploy the bridge/gateway for
 TOKEN=
 
-# Address of the rebasable token to deploy the bridge/gateway for
+# Address of the rebasable token on L1 to deploy the bridge/gateway for
 REBASABLE_TOKEN=
 
-# Address of token rate notifier. Connects Lido core protocol.
-TOKEN_RATE_NOTIFIER=
-
-# Address of token rate pusher
+# Address of token rate pusher. Required to config TokenRateOracle.
 L1_OP_STACK_TOKEN_RATE_PUSHER=
 
 # Gas limit required to complete pushing token rate on L2.
 L2_GAS_LIMIT_FOR_PUSHING_TOKEN_RATE=
 
 # A time period when token rate can be considered outdated.
-RATE_OUTDATED_DELAY=
+RATE_OUTDATED_DELAY=86400 # default is 24 hours
 
 # Address of L1 token bridge proxy.
 L1_TOKEN_BRIDGE=
@@ -59,7 +56,7 @@ L2_TOKEN_RATE_ORACLE=
 GOV_BRIDGE_EXECUTOR=
 
 # Name of the network environments used by deployment scripts.
-# Might be one of: "mainnet", "goerli".
+# Might be one of: "mainnet", "sepolia".
 NETWORK=mainnet
 
 # Run deployment in the forking network instead of public ones

README.md

@@ -6,6 +6,7 @@ To retrieve more detailed info about the bridging process, see the specification
 
 - [Lido's Arbitrum Gateway](https://github.com/lidofinance/lido-l2/blob/main/contracts/arbitrum/README.md).
 - [Lido's Optimism Bridge](https://github.com/lidofinance/lido-l2/blob/main/contracts/optimism/README.md).
+- [wstETH Bridging Guide](https://docs.lido.fi/token-guides/wsteth-bridging-guide/#r-5-bridging-l1-lido-dao-decisions)
 
 ## Project setup
 
@@ -44,7 +45,15 @@ The configuration of the deployment scripts happens via the ENV variables. The f
 
 - [`TOKEN`](#TOKEN) - address of the non-rebasable token to deploy a new bridge on the Ethereum chain.
 - [`REBASABLE_TOKEN`] (#REBASABLE_TOKEN) - address of the rebasable token to deploy new bridge on the Ethereum chain.
-- [`NETWORK`](#NETWORK) - name of the network environments used by deployment scripts. Allowed values: `mainnet`, `goerli`.
+- [`L1_OP_STACK_TOKEN_RATE_PUSHER`](#L1_OP_STACK_TOKEN_RATE_PUSHER) - address of token rate pusher. Required to config TokenRateOracle.
+- [`L2_GAS_LIMIT_FOR_PUSHING_TOKEN_RATE`](#L2_GAS_LIMIT_FOR_PUSHING_TOKEN_RATE) - gas limit required to complete pushing token rate on L2.
+- [`RATE_OUTDATED_DELAY`](#RATE_OUTDATED_DELAY) - a time period when token rate can be considered outdated. Default is 24 hours.
+- [`L1_TOKEN_BRIDGE`](#L1_TOKEN_BRIDGE) - address of L1 token bridge.
+- [`L2_TOKEN_BRIDGE`](#L2_TOKEN_BRIDGE) - address of L2 token bridge.
+- [`L2_TOKEN`](#L2_TOKEN) - address of the non-rebasable token on L2.
+- [`L2_TOKEN_RATE_ORACLE`](#L2_TOKEN_RATE_ORACLE) - address of token rate oracle on L2.
+- [`GOV_BRIDGE_EXECUTOR`](#GOV_BRIDGE_EXECUTOR) - address of bridge executor.
+- [`NETWORK`](#NETWORK) - name of the network environments used by deployment scripts. Allowed values: `mainnet`, `sepolia`.
 - [`FORKING`](#FORKING) - run deployment in the forking network instead of real ones
 - [`ETH_DEPLOYER_PRIVATE_KEY`](#ETH_DEPLOYER_PRIVATE_KEY) - The private key of the deployer account in the Ethereum network is used during the deployment process.
 - [`ARB_DEPLOYER_PRIVATE_KEY`](#ARB_DEPLOYER_PRIVATE_KEY) - The private key of the deployer account in the Arbitrum network is used during the deployment process.
@@ -315,17 +324,17 @@ Below variables used in the Arbitrum/Optimism bridge deployment process.
 
 #### `TOKEN`
 
-Address of the non-rebasable token to deploy a new bridge on the Ethereum chain.
+Address of the existing non-rebasable token to deploy a new bridge for on the Ethereum chain.
 
 #### `REBASABLE_TOKEN`
 
-Address of the rebasable token to deploy new bridge on the Ethereum chain.
+Address of the existing rebasable token to deploy new bridge for on the Ethereum chain.
 
 #### `NETWORK`
 
 > Default value: `mainnet`
 
-Name of the network environments used by deployment scripts. Might be one of: `mainnet`, `goerli`.
+Name of the network environments used by deployment scripts. Might be one of: `mainnet`, `sepolia`.
 
 #### `FORKING`
 
@@ -447,7 +456,7 @@ The following variables are used in the process of the Integration & E2E testing
 
 #### `TESTING_ARB_NETWORK`
 
-Name of the network environments used for Arbitrum Integration & E2E testing. Might be one of: `mainnet`, `goerli`.
+Name of the network environments used for Arbitrum Integration & E2E testing. Might be one of: `mainnet`, `sepolia`.
 
 #### `TESTING_ARB_L1_TOKEN`
 
@@ -487,7 +496,7 @@ Address of the L2 gateway router used in the Acceptance Integration & E2E (when
 
 #### `TESTING_OPT_NETWORK`
 
-Name of the network environments used for Optimism Integration & E2E testing. Might be one of: `mainnet`, `goerli`.
+Name of the network environments used for Optimism Integration & E2E testing. Might be one of: `mainnet`, `sepolia`.
 
 #### `TESTING_OPT_L1_TOKEN`
 

contracts/lib/SignatureChecker.sol

@@ -1,6 +1,6 @@
 // SPDX-FileCopyrightText: 2024 OpenZeppelin, Lido <info@lido.fi>
 // SPDX-License-Identifier: GPL-3.0
-// Writen based on (utils/cryptography/SignatureChecker.sol from d398d68
+// Written based on (utils/cryptography/SignatureChecker.sol from d398d68
 
 pragma solidity 0.8.10;
 
@@ -24,7 +24,6 @@ library SignatureChecker {
  */
  function isValidSignatureNow(address signer, bytes32 hash, bytes memory signature) internal view returns (bool) {
  if (signer.code.length == 0) {
- // return true;
  (address recovered, ECDSA.RecoverError err) = ECDSA.tryRecover(hash, signature);
  return err == ECDSA.RecoverError.NoError && recovered == signer;
  } else {

contracts/lido/TokenRateNotifier.sol

@@ -3,21 +3,32 @@
 
 pragma solidity 0.8.10;
 
-import {IPostTokenRebaseReceiver} from "./interfaces/IPostTokenRebaseReceiver.sol";
 import {ITokenRatePusher} from "./interfaces/ITokenRatePusher.sol";
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {ERC165Checker} from "@openzeppelin/contracts/utils/introspection/ERC165Checker.sol";
 
+/// @notice An interface to subscribe on the `stETH` token rebases (defined in the `Lido` core contract)
+interface IPostTokenRebaseReceiver {
+
+ /// @notice Is called in the context of `Lido.handleOracleReport` to notify the subscribers about each token rebase
+ function handlePostTokenRebase(
+ uint256 _reportTimestamp,
+ uint256 _timeElapsed,
+ uint256 _preTotalShares,
+ uint256 _preTotalEther,
+ uint256 _postTotalShares,
+ uint256 _postTotalEther,
+ uint256 _sharesMintedAsFees
+ ) external;
+}
+
 /// @author kovalgek
 /// @notice Notifies all observers when rebase event occures.
 contract TokenRateNotifier is Ownable, IPostTokenRebaseReceiver {
  using ERC165Checker for address;
 
  /// @notice Maximum amount of observers to be supported.
- uint256 public constant MAX_OBSERVERS_COUNT = 16;
-
- /// @notice Invalid interface id.
- bytes4 public constant INVALID_INTERFACE_ID = 0xffffffff;
+ uint256 public constant MAX_OBSERVERS_COUNT = 32;
 
  /// @notice A value that indicates that value was not found.
  uint256 public constant INDEX_NOT_FOUND = type(uint256).max;
@@ -28,6 +39,11 @@ contract TokenRateNotifier is Ownable, IPostTokenRebaseReceiver {
  /// @notice All observers.
  address[] public observers;
 
+ /// @param initialOwner_ initial owner
+ constructor(address initialOwner_) {
+ _transferOwnership(initialOwner_);
+ }
+
  /// @notice Add a `observer_` to the back of array
  /// @param observer_ observer address
  function addObserver(address observer_) external onlyOwner {
@@ -55,24 +71,22 @@ contract TokenRateNotifier is Ownable, IPostTokenRebaseReceiver {
  revert ErrorNoObserverToRemove();
  }
 
- for (uint256 obIndex = observerIndexToRemove; obIndex < observers.length - 1; obIndex++) {
- observers[obIndex] = observers[obIndex + 1];
- }
-
+ observers[observerIndexToRemove] = observers[observers.length - 1];
  observers.pop();
 
  emit ObserverRemoved(observer_);
  }
 
  /// @inheritdoc IPostTokenRebaseReceiver
+ /// @dev Parameters aren't used because all required data further components fetch by themselves.
  function handlePostTokenRebase(
- uint256,
- uint256,
- uint256,
- uint256,
- uint256,
- uint256,
- uint256
+ uint256, /* reportTimestamp */
+ uint256, /* timeElapsed */
+ uint256, /* preTotalShares */
+ uint256, /* preTotalEther */
+ uint256, /* postTotalShares */
+ uint256, /* postTotalEther */
+ uint256 /* sharesMintedAsFees */
  ) external {
  for (uint256 obIndex = 0; obIndex < observers.length; obIndex++) {
  try ITokenRatePusher(observers[obIndex]).pushTokenRate() {}
@@ -93,7 +107,7 @@ contract TokenRateNotifier is Ownable, IPostTokenRebaseReceiver {
 
  /// @notice Observer length
  /// @return Added observers count
- function observersLength() public view returns (uint256) {
+ function observersLength() external view returns (uint256) {
  return observers.length;
  }
 

contracts/lido/interfaces/ITokenRatePusher.sol

@@ -4,8 +4,8 @@
 pragma solidity 0.8.10;
 
 /// @author kovalgek
-/// @notice An interface for entity that pushes rate.
+/// @notice An interface for entity that pushes token rate.
 interface ITokenRatePusher {
- /// @notice Pushes token rate to L2 by depositing zero tokens.
+ /// @notice Pushes token rate to L2 by depositing zero token amount.
  function pushTokenRate() external;
 }

contracts/lido/stubs/OpStackTokenRatePusherWithOutOfGasErrorStub.sol

@@ -8,10 +8,12 @@ import {ERC165} from "@openzeppelin/contracts/utils/introspection/ERC165.sol";
 
 contract OpStackTokenRatePusherWithOutOfGasErrorStub is ERC165, ITokenRatePusher {
 
- mapping (uint256 => uint256) data;
+ uint256 public constant OUT_OF_GAS_INCURRING_MAX = 1000000000000;
+
+ mapping (uint256 => uint256) public data;
 
  function pushTokenRate() external {
- for (uint256 i = 0; i < 1000000000000; ++i) {
+ for (uint256 i = 0; i < OUT_OF_GAS_INCURRING_MAX; ++i) {
  data[i] = i;
  }
  }

contracts/optimism/DepositDataCodec.sol

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2023 Lido <info@lido.fi>
+// SPDX-FileCopyrightText: 2024 Lido <info@lido.fi>
 // SPDX-License-Identifier: GPL-3.0
 
 pragma solidity 0.8.10;
@@ -9,7 +9,7 @@ contract DepositDataCodec {
 
  uint8 internal constant RATE_FIELD_SIZE = 12;
  uint8 internal constant TIMESTAMP_FIELD_SIZE = 5;
- 
+
  struct DepositData {
  uint96 rate;
  uint40 timestamp;
@@ -26,11 +26,11 @@ contract DepositDataCodec {
  }
 
  function decodeDepositData(bytes calldata buffer) internal pure returns (DepositData memory) {
- 
+
  if (buffer.length < RATE_FIELD_SIZE + TIMESTAMP_FIELD_SIZE) {
  revert ErrorDepositDataLength();
  }
- 
+
  DepositData memory depositData = DepositData({
  rate: uint96(bytes12(buffer[0:RATE_FIELD_SIZE])),
  timestamp: uint40(bytes5(buffer[RATE_FIELD_SIZE:RATE_FIELD_SIZE + TIMESTAMP_FIELD_SIZE])),

contracts/optimism/L1ERC20TokenBridge.sol → contracts/optimism/L1ERC20ExtendedTokensBridge.sol

@@ -20,7 +20,7 @@ import {IERC20WstETH} from "../token/interfaces/IERC20WstETH.sol";
 /// @notice The L1 ERC20 token bridge locks bridged tokens on the L1 side, sends deposit messages
 /// on the L2 side, and finalizes token withdrawals from L2. Additionally, adds the methods for
 /// bridging management: enabling and disabling withdrawals/deposits
-abstract contract L1ERC20TokenBridge is
+abstract contract L1ERC20ExtendedTokensBridge is
  IL1ERC20Bridge,
  BridgingManager,
  RebasableAndNonRebasableTokens,
@@ -44,7 +44,12 @@ abstract contract L1ERC20TokenBridge is
  address l1TokenRebasable_,
  address l2TokenNonRebasable_,
  address l2TokenRebasable_
- ) CrossDomainEnabled(messenger_) RebasableAndNonRebasableTokens(l1TokenNonRebasable_, l1TokenRebasable_, l2TokenNonRebasable_, l2TokenRebasable_) {
+ ) CrossDomainEnabled(messenger_) RebasableAndNonRebasableTokens(
+ l1TokenNonRebasable_,
+ l1TokenRebasable_,
+ l2TokenNonRebasable_,
+ l2TokenRebasable_
+ ) {
  L2_TOKEN_BRIDGE = l2TokenBridge_;
  }
 

contracts/optimism/L1LidoTokensBridge.sol

@@ -3,12 +3,12 @@
 
 pragma solidity 0.8.10;
 
-import {L1ERC20TokenBridge} from "./L1ERC20TokenBridge.sol";
+import {L1ERC20ExtendedTokensBridge} from "./L1ERC20ExtendedTokensBridge.sol";
 import {IERC20WstETH} from "../token/interfaces/IERC20WstETH.sol";
 
 /// @author kovalgek
-/// @notice Hides wstETH concept from other contracts to keep `L1ERC20TokenBridge` reusable.
-contract L1LidoTokensBridge is L1ERC20TokenBridge {
+/// @notice Hides wstETH concept from other contracts to keep `L1ERC20ExtendedTokensBridge` reusable.
+contract L1LidoTokensBridge is L1ERC20ExtendedTokensBridge {
 
  constructor(
  address messenger_,
@@ -17,7 +17,7 @@ contract L1LidoTokensBridge is L1ERC20TokenBridge {
  address l1TokenRebasable_,
  address l2TokenNonRebasable_,
  address l2TokenRebasable_
- ) L1ERC20TokenBridge(
+ ) L1ERC20ExtendedTokensBridge(
  messenger_,
  l2TokenBridge_,
  l1TokenNonRebasable_,

contracts/optimism/L2ERC20TokenBridge.sol → contracts/optimism/L2ERC20ExtendedTokensBridge.sol

@@ -24,7 +24,7 @@ import {DepositDataCodec} from "./DepositDataCodec.sol";
 /// deposits into the L1 token bridge. It also acts as a burner of the tokens
 /// intended for withdrawal, informing the L1 bridge to release L1 funds. Additionally, adds
 /// the methods for bridging management: enabling and disabling withdrawals/deposits
-contract L2ERC20TokenBridge is
+contract L2ERC20ExtendedTokensBridge is
  IL2ERC20Bridge,
  BridgingManager,
  RebasableAndNonRebasableTokens,
@@ -48,7 +48,12 @@ contract L2ERC20TokenBridge is
  address l1TokenRebasable_,
  address l2TokenNonRebasable_,
  address l2TokenRebasable_
- ) CrossDomainEnabled(messenger_) RebasableAndNonRebasableTokens(l1TokenNonRebasable_, l1TokenRebasable_, l2TokenNonRebasable_, l2TokenRebasable_) {
+ ) CrossDomainEnabled(messenger_) RebasableAndNonRebasableTokens(
+ l1TokenNonRebasable_,
+ l1TokenRebasable_,
+ l2TokenNonRebasable_,
+ l2TokenRebasable_
+ ) {
  L1_TOKEN_BRIDGE = l1TokenBridge_;
  }
 
@@ -95,6 +100,7 @@ contract L2ERC20TokenBridge is
  {
  if (_isRebasableTokenFlow(l1Token_, l2Token_)) {
  DepositData memory depositData = decodeDepositData(data_);
+
  ITokenRateOracle tokenRateOracle = ERC20Rebasable(L2_TOKEN_REBASABLE).TOKEN_RATE_ORACLE();
  tokenRateOracle.updateRate(depositData.rate, depositData.timestamp);