[VAULTS] PredepositGuarantee

contracts/0.8.25/vaults/PredepositDepositGuardian.sol

@@ -0,0 +1,127 @@
+// SPDX-FileCopyrightText: 2025 Lido <[email protected]>
+// SPDX-License-Identifier: GPL-3.0
+
+// See contracts/COMPILERS.md
+pragma solidity 0.8.25;
+
+import {StakingVault} from "./StakingVault.sol";
+
+contract PredepositDepositGuardian {
+    enum ValidatorStatus {
+        NO_RECORD,
+        AWAITING_PROOF,
+        RESOLVED,
+        WITHDRAWN
+    }
+
+    mapping(address nodeOperator => bytes32 validatorPubkeyHash) public nodeOperatorToValidators;
+    mapping(bytes32 validatorPubkeyHash => ValidatorStatus validatorStatus) public validatorStatuses;
+    mapping(bytes32 validatorPubkeyHash => bytes32 withdrawalCredentials) public wcRecords;
+
+    function predeposit(address stakingVault, StakingVault.Deposit[] calldata deposits) external payable {
+        if (msg.value % 1 ether != 0) revert PredepositMustBeMultipleOfOneEther();
+        if (msg.value / 1 ether != deposits.length) revert PredepositMustBeOneEtherPerDeposit();
+        if (msg.sender != StakingVault(payable(stakingVault)).nodeOperator()) revert MustBeNodeOperatorOfStakingVault();
+
+        for (uint256 i = 0; i < deposits.length; i++) {
+            StakingVault.Deposit calldata deposit = deposits[i];
+
+            if (validatorStatuses[keccak256(deposit.pubkey)] != ValidatorStatus.AWAITING_PROOF) {
+                revert MustBeNewValidatorPubkey();
+            }
+
+            nodeOperatorToValidators[msg.sender] = keccak256(deposit.pubkey);
+            validatorStatuses[keccak256(deposit.pubkey)] = ValidatorStatus.AWAITING_PROOF;
+
+            if (deposit.amount != 1 ether) revert PredepositMustBeOneEtherPerDeposit();
+        }
+
+        // we don't need to pass deposit root or signature because the msg.sender is deposit guardian itself
+        StakingVault(payable(stakingVault)).depositToBeaconChain(deposits, bytes32(0), bytes(""));
+    }
+
+    function proveWithdrawalCredentials(
+        bytes32[] calldata proof,
+        bytes calldata validatorPubkey,
+        bytes32 withdrawalCredentials
+    ) external {
+        // TODO: proof logic
+
+        bytes32 validatorPubkeyHash = keccak256(validatorPubkey);
+        wcRecords[validatorPubkeyHash] = withdrawalCredentials;
+        validatorStatuses[validatorPubkeyHash] = ValidatorStatus.RESOLVED;
+    }
+
+    function deposit(address _stakingVault, StakingVault.Deposit[] calldata deposits) external payable {
+        if (msg.sender != StakingVault(payable(_stakingVault)).nodeOperator())
+            revert MustBeNodeOperatorOfStakingVault();
+
+        for (uint256 i = 0; i < deposits.length; i++) {
+            StakingVault.Deposit calldata deposit = deposits[i];
+
+            if (validatorStatuses[keccak256(deposit.pubkey)] != ValidatorStatus.RESOLVED) {
+                revert MustBeResolvedValidatorPubkey();
+            }
+        }
+
+        // we don't need to pass deposit root or signature because the msg.sender is deposit guardian itself
+        StakingVault(payable(_stakingVault)).depositToBeaconChain(deposits, bytes32(0), bytes(""));
+    }
+
+    function withdrawAsVaultOwner(address stakingVault, bytes[] calldata validatorPubkeys) external {
+        if (msg.sender != StakingVault(payable(stakingVault)).owner()) revert MustBeVaultOwner();
+
+        for (uint256 i = 0; i < validatorPubkeys.length; i++) {
+            bytes32 validatorPubkeyHash = keccak256(validatorPubkeys[i]);
+
+            if (validatorStatuses[validatorPubkeyHash] != ValidatorStatus.RESOLVED) {
+                revert MustBeResolvedValidatorPubkey();
+            }
+
+            if (validatorStatuses[validatorPubkeyHash] == ValidatorStatus.WITHDRAWN) {
+                revert ValidatorAlreadyWithdrawn();
+            }
+
+            if (wcRecords[validatorPubkeyHash] == StakingVault(payable(stakingVault)).withdrawalCredentials()) {
+                revert ValidatorWithdrawalCredentialsMatchVaultWithdrawalCredentials();
+            }
+
+            msg.sender.call{value: 1 ether}("");
+
+            validatorStatuses[validatorPubkeyHash] = ValidatorStatus.WITHDRAWN;
+        }
+    }
+
+    function withdrawAsNodeOperator(bytes[] calldata validatorPubkeys) external {
+        for (uint256 i = 0; i < validatorPubkeys.length; i++) {
+            bytes32 validatorPubkeyHash = keccak256(validatorPubkeys[i]);
+
+            if (validatorStatuses[validatorPubkeyHash] != ValidatorStatus.RESOLVED) {
+                revert MustBeResolvedValidatorPubkey();
+            }
+
+            if (validatorStatuses[validatorPubkeyHash] == ValidatorStatus.WITHDRAWN) {
+                revert ValidatorAlreadyWithdrawn();
+            }
+
+            if (nodeOperatorToValidators[msg.sender] != validatorPubkeyHash) {
+                revert ValidatorMustBelongToSender();
+            }
+
+            msg.sender.call{value: 1 ether}("");
+
+            validatorStatuses[validatorPubkeyHash] = ValidatorStatus.WITHDRAWN;
+        }
+    }
+
+    error PredepositMustBeMultipleOfOneEther();
+    error PredepositMustBeOneEtherPerDeposit();
+    error MustBeNodeOperatorOfStakingVault();
+    error MustBeNewValidatorPubkey();
+    error WithdrawalFailed();
+    error MustBeResolvedValidatorPubkey();
+    error ValidatorMustBelongToSender();
+    error MustBeVaultOwner();
+    error ValidatorWithdrawalCredentialsMatchVaultWithdrawalCredentials();
+    error ValidatorAlreadyWithdrawn();
+}

contracts/0.8.25/vaults/StakingVault.sol

@@ -5,6 +5,7 @@
 pragma solidity 0.8.25;
 
 import {OwnableUpgradeable} from "contracts/openzeppelin/5.2/upgradeable/access/OwnableUpgradeable.sol";
+import {SignatureChecker} from "@openzeppelin/contracts-v5.2/utils/cryptography/SignatureChecker.sol";
 
 import {VaultHub} from "./VaultHub.sol";
 
@@ -67,6 +68,7 @@ contract StakingVault is IStakingVault, OwnableUpgradeable {
         uint128 locked;
         int128 inOutDelta;
         address nodeOperator;
+        address depositGuardian;
         bool beaconChainDepositsPaused;
     }
 
@@ -76,6 +78,8 @@ contract StakingVault is IStakingVault, OwnableUpgradeable {
      */
     uint64 private constant _VERSION = 1;
 
+    bytes32 public constant DEPOSIT_GUARDIAN_MESSAGE_PREFIX = keccak256("StakingVault.DepositGuardianMessagePrefix");
+
     /**
      * @notice Address of `VaultHub`
      *         Set immutably in the constructor to avoid storage costs
@@ -122,6 +126,7 @@ contract StakingVault is IStakingVault, OwnableUpgradeable {
     function initialize(address _owner, address _nodeOperator, bytes calldata /* _params */) external initializer {
         __Ownable_init(_owner);
         _getStorage().nodeOperator = _nodeOperator;
+        _getStorage().depositGuardian = _owner;
     }
 
     /**
@@ -313,24 +318,59 @@ contract StakingVault is IStakingVault, OwnableUpgradeable {
      * @param _deposits Array of deposit structs
      * @dev Includes a check to ensure StakingVault is balanced before making deposits
      */
-    function depositToBeaconChain(Deposit[] calldata _deposits) external {
+    function depositToBeaconChain(
+        Deposit[] calldata _deposits,
+        bytes32 _expectedGlobalDepositRoot,
+        bytes calldata _signature
+    ) external {
         if (_deposits.length == 0) revert ZeroArgument("_deposits");
-        ERC7201Storage storage $ = _getStorage();
+        if (!isBalanced()) revert Unbalanced();
 
-        if (msg.sender != $.nodeOperator) revert NotAuthorized("depositToBeaconChain", msg.sender);
+        ERC7201Storage storage $ = _getStorage();
         if ($.beaconChainDepositsPaused) revert BeaconChainDepositsArePaused();
-        if (!isBalanced()) revert Unbalanced();
 
-        uint256 totalAmount = 0;
         uint256 numberOfDeposits = _deposits.length;
+
+        if (msg.sender != $.depositGuardian) {
+            bytes32 currentGlobalDepositRoot = BEACON_CHAIN_DEPOSIT_CONTRACT.get_deposit_root();
+            if (_expectedGlobalDepositRoot != currentGlobalDepositRoot)
+                revert GlobalDepositRootMismatch(_expectedGlobalDepositRoot, currentGlobalDepositRoot);
+
+            bytes32 depositDataBatchXorRoot;
+
+            for (uint256 i = 0; i < numberOfDeposits; i++) {
+                Deposit calldata deposit = _deposits[i];
+
+                depositDataBatchXorRoot ^= keccak256(abi.encodePacked(deposit.depositDataRoot));
+            }
+
+            if (
+                !SignatureChecker.isValidSignatureNow(
+                    $.depositGuardian,
+                    keccak256(
+                        abi.encodePacked(
+                            DEPOSIT_GUARDIAN_MESSAGE_PREFIX,
+                            _expectedGlobalDepositRoot,
+                            depositDataBatchXorRoot
+                        )
+                    ),
+                    _signature
+                )
+            ) revert DepositGuardianSignatureInvalid();
+        }
+
+        uint256 totalAmount = 0;
+
         for (uint256 i = 0; i < numberOfDeposits; i++) {
             Deposit calldata deposit = _deposits[i];
+
             BEACON_CHAIN_DEPOSIT_CONTRACT.deposit{value: deposit.amount}(
                 deposit.pubkey,
                 bytes.concat(withdrawalCredentials()),
                 deposit.signature,
                 deposit.depositDataRoot
             );
+
             totalAmount += deposit.amount;
         }
 
@@ -404,6 +444,26 @@ contract StakingVault is IStakingVault, OwnableUpgradeable {
         emit Reported(_valuation, _inOutDelta, _locked);
     }
 
+    /**
+     * @notice Sets the deposit guardian
+     * @param _depositGuardian The address of the deposit guardian
+     * @dev In case where the deposit guardian is a contract, it must implement EIP-1271.
+     *      The interface check for EIP-1271 is omitted because the only way to check for whether an account is a contract
+     *      is to call `extcodesize` on it. This method is not reliable, as it can be broken, for instance, by CREATE2-deployed contracts.
+     *      So to avoid false positives, the contract shifts this responsibility to the owner.
+     *      If a contract mistakenly assigned as a deposit guardian is not a valid EIP-1271 signer,
+     *      the owner can simply set it to a different address.
+     */
+    function setDepositGuardian(address _depositGuardian) external onlyOwner {
+        if (_depositGuardian == address(0)) revert ZeroArgument("_depositGuardian");
+
+        ERC7201Storage storage $ = _getStorage();
+        address oldDepositGuardian = $.depositGuardian;
+        $.depositGuardian = _depositGuardian;
+
+        emit DepositGuardianSet(oldDepositGuardian, _depositGuardian);
+    }
+
     /**
      * @notice Computes the deposit data root for a validator deposit
      * @param _pubkey Validator public key, 48 bytes
@@ -554,6 +614,13 @@ contract StakingVault is IStakingVault, OwnableUpgradeable {
      */
     event BeaconChainDepositsResumed();
 
+    /**
+     * @notice Emitted when the deposit guardian is set
+     * @param oldDepositGuardian The address of the old deposit guardian
+     * @param newDepositGuardian The address of the new deposit guardian
+     */
+    event DepositGuardianSet(address oldDepositGuardian, address newDepositGuardian);
+
     /**
      * @notice Thrown when an invalid zero value is passed
      * @param name Name of the argument that was zero
@@ -617,6 +684,21 @@ contract StakingVault is IStakingVault, OwnableUpgradeable {
      */
     error UnrecoverableError();
 
+    /**
+     * @notice Thrown when the global deposit root does not match the expected global deposit root
+     */
+    error GlobalDepositRootMismatch(bytes32 expected, bytes32 actual);
+
+    /**
+     * @notice Thrown when the guardian signature is invalid
+     */
+    error DepositGuardianSignatureInvalid();
+
+    /**
+     * @notice Thrown when the deposit guardian is not an EIP-1271 contract
+     */
+    error DepositGuardianContractDoesNotSupportEIP1271();
+
     /**
      * @notice Thrown when trying to pause deposits to beacon chain while deposits are already paused
      */

contracts/0.8.25/vaults/interfaces/IStakingVault.sol

@@ -28,26 +28,52 @@ interface IStakingVault {
     }
 
     function initialize(address _owner, address _operator, bytes calldata _params) external;
-    function version() external pure returns(uint64);
+
+    function version() external pure returns (uint64);
+
     function getInitializedVersion() external view returns (uint64);
+
     function vaultHub() external view returns (address);
+
     function depositContract() external view returns (address);
+
     function nodeOperator() external view returns (address);
+
     function locked() external view returns (uint256);
+
     function valuation() external view returns (uint256);
+
     function isBalanced() external view returns (bool);
+
     function unlocked() external view returns (uint256);
+
     function inOutDelta() external view returns (int256);
+
     function beaconChainDepositsPaused() external view returns (bool);
+
     function withdrawalCredentials() external view returns (bytes32);
+
     function fund() external payable;
+
     function withdraw(address _recipient, uint256 _ether) external;
-    function depositToBeaconChain(Deposit[] calldata _deposits) external;
+
+    function depositToBeaconChain(
+        Deposit[] calldata _deposits,
+        bytes32 _expectedGlobalDepositRoot,
+        bytes calldata _guardianSignature
+    ) external;
+
     function requestValidatorExit(bytes calldata _pubkeys) external;
+
     function lock(uint256 _locked) external;
+
     function rebalance(uint256 _ether) external;
+
     function pauseBeaconChainDeposits() external;
+
     function resumeBeaconChainDeposits() external;
+
     function latestReport() external view returns (Report memory);
+
     function report(uint256 _valuation, int256 _inOutDelta, uint256 _locked) external;
 }