feat: withdrawal credentials

contracts/0.8.9/WithdrawalVault.sol

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2023 Lido <[email protected]>
+// SPDX-FileCopyrightText: 2025 Lido <[email protected]>
 // SPDX-License-Identifier: GPL-3.0
 
 /* See contracts/COMPILERS.md */
@@ -9,6 +9,9 @@
 import "@openzeppelin/contracts-v4.4/token/ERC20/utils/SafeERC20.sol";
 
 import {Versioned} from "./utils/Versioned.sol";
+import {AccessControlEnumerable} from "./utils/access/AccessControlEnumerable.sol";
+import {TriggerableWithdrawals} from "../common/lib/TriggerableWithdrawals.sol";
+import {ILidoLocator} from "../common/interfaces/ILidoLocator.sol";
 
 interface ILido {
     /**
@@ -22,12 +25,14 @@
 /**
  * @title A vault for temporary storage of withdrawals
  */
-contract WithdrawalVault is Versioned {
+contract WithdrawalVault is AccessControlEnumerable, Versioned {
     using SafeERC20 for IERC20;
 
     ILido public immutable LIDO;
     address public immutable TREASURY;
 
+    bytes32 public constant ADD_FULL_WITHDRAWAL_REQUEST_ROLE = keccak256("ADD_FULL_WITHDRAWAL_REQUEST_ROLE");
+
     // Events
     /**
      * Emitted when the ERC20 `token` recovered (i.e. transferred)
@@ -42,34 +47,48 @@
     event ERC721Recovered(address indexed requestedBy, address indexed token, uint256 tokenId);
 
     // Errors
-    error LidoZeroAddress();
-    error TreasuryZeroAddress();
+    error ZeroAddress();
     error NotLido();
     error NotEnoughEther(uint256 requested, uint256 balance);
     error ZeroAmount();
+    error InsufficientTriggerableWithdrawalFee(
+        uint256 providedTotalFee,
+        uint256 requiredTotalFee,
+        uint256 requestCount
+    );
+    error TriggerableWithdrawalRefundFailed();
 
     /**
      * @param _lido the Lido token (stETH) address
      * @param _treasury the Lido treasury address (see ERC20/ERC721-recovery interfaces)
      */
-    constructor(ILido _lido, address _treasury) {
-        if (address(_lido) == address(0)) {
-            revert LidoZeroAddress();
-        }
-        if (_treasury == address(0)) {
-            revert TreasuryZeroAddress();
-        }
+    constructor(address _lido, address _treasury) {
+        _onlyNonZeroAddress(_lido);
+        _onlyNonZeroAddress(_treasury);
 
-        LIDO = _lido;
+        LIDO = ILido(_lido);
         TREASURY = _treasury;
     }
 
-    /**
-     * @notice Initialize the contract explicitly.
-     * Sets the contract version to '1'.
-     */
-    function initialize() external {
-        _initializeContractVersionTo(1);
+    /// @notice Initializes the contract. Can be called only once.
+    /// @param _admin Lido DAO Aragon agent contract address.
+    /// @dev Proxy initialization method.
+    function initialize(address _admin) external {
+        // Initializations for v0 --> v2
+        _checkContractVersion(0);
+
+        _initialize_v2(_admin);
+        _initializeContractVersionTo(2);
+    }
+
+    /// @notice Finalizes upgrade to v2 (from v1). Can be called only once.
+    /// @param _admin Lido DAO Aragon agent contract address.
+    function finalizeUpgrade_v2(address _admin) external {
+        // Finalization for v1 --> v2
+        _checkContractVersion(1);
+
+        _initialize_v2(_admin);
+        _updateContractVersion(2);
     }
 
     /**
@@ -122,4 +141,66 @@
 
         _token.transferFrom(address(this), TREASURY, _tokenId);
     }
+
+    /**
+     * @dev Submits EIP-7002 full withdrawal requests for the specified public keys.
+     *      Each request instructs a validator to fully withdraw its stake and exit its duties as a validator.
+     *      Refunds any excess fee to the caller after deducting the total fees,
+     *      which are calculated based on the number of public keys and the current minimum fee per withdrawal request.
+     *
+     * @param pubkeys A tightly packed array of 48-byte public keys corresponding to validators requesting full withdrawals.
+     *                | ----- public key (48 bytes) ----- || ----- public key (48 bytes) ----- | ...
+     *
+     * @notice Reverts if:
+     *         - The caller does not have the `ADD_FULL_WITHDRAWAL_REQUEST_ROLE`.
+     *         - Validation of any of the provided public keys fails.
+     *         - The provided total withdrawal fee is insufficient to cover all requests.
+     *         - Refund of the excess fee fails.
+     */
+    function addFullWithdrawalRequests(
+        bytes calldata pubkeys
+    ) external payable onlyRole(ADD_FULL_WITHDRAWAL_REQUEST_ROLE) {
+        uint256 prevBalance = address(this).balance - msg.value;
+
+        uint256 minFeePerRequest = TriggerableWithdrawals.getWithdrawalRequestFee();
+        uint256 totalFee = (pubkeys.length / TriggerableWithdrawals.PUBLIC_KEY_LENGTH) * minFeePerRequest;
+
+        if (totalFee > msg.value) {
+            revert InsufficientTriggerableWithdrawalFee(
+                msg.value,
+                totalFee,
+                pubkeys.length / TriggerableWithdrawals.PUBLIC_KEY_LENGTH
+            );
+        }
+
+        TriggerableWithdrawals.addFullWithdrawalRequests(pubkeys, minFeePerRequest);
+
+        uint256 refund = msg.value - totalFee;
+        if (refund > 0) {
+            (bool success, ) = msg.sender.call{value: refund}("");
+
+            if (!success) {
+                revert TriggerableWithdrawalRefundFailed();
+            }
+        }
+
+        assert(address(this).balance == prevBalance);
+    }
+
+    /**
+     * @dev Retrieves the current EIP-7002 withdrawal fee.
+     * @return The minimum fee required per withdrawal request.
+     */
+    function getWithdrawalRequestFee() external view returns (uint256) {
+        return TriggerableWithdrawals.getWithdrawalRequestFee();
+    }
+
+    function _onlyNonZeroAddress(address _address) internal pure {
+        if (_address == address(0)) revert ZeroAddress();
+    }
+
+    function _initialize_v2(address _admin) internal {
+        _onlyNonZeroAddress(_admin);
+        _setupRole(DEFAULT_ADMIN_ROLE, _admin);
+    }
 }

contracts/common/lib/TriggerableWithdrawals.sol

@@ -0,0 +1,209 @@
+// SPDX-FileCopyrightText: 2025 Lido <[email protected]>
+// SPDX-License-Identifier: GPL-3.0
+
+/* See contracts/COMPILERS.md */
+// solhint-disable-next-line lido/fixed-compiler-version
+pragma solidity >=0.8.9 <0.9.0;
+
+/**
+ * @title A lib for EIP-7002: Execution layer triggerable withdrawals.
+ * Allow validators to trigger withdrawals and exits from their execution layer (0x01) withdrawal credentials.
+ */
+library TriggerableWithdrawals {
+    address constant WITHDRAWAL_REQUEST = 0x00000961Ef480Eb55e80D19ad83579A64c007002;
+
+    uint256 internal constant PUBLIC_KEY_LENGTH = 48;
+    uint256 internal constant WITHDRAWAL_AMOUNT_LENGTH = 8;
+    uint256 internal constant WITHDRAWAL_REQUEST_CALLDATA_LENGTH = 56;
+
+    error WithdrawalFeeReadFailed();
+    error WithdrawalFeeInvalidData();
+    error WithdrawalRequestAdditionFailed(bytes callData);
+
+    error InsufficientWithdrawalFee(uint256 feePerRequest, uint256 minFeePerRequest);
+    error TotalWithdrawalFeeExceededBalance(uint256 balance, uint256 totalWithdrawalFee);
+
+    error NoWithdrawalRequests();
+    error MalformedPubkeysArray();
+    error PartialWithdrawalRequired(uint256 index);
+    error MismatchedArrayLengths(uint256 keysCount, uint256 amountsCount);
+
+    /**
+     * @dev Send EIP-7002 full withdrawal requests for the specified public keys.
+     *      Each request instructs a validator to fully withdraw its stake and exit its duties as a validator.
+     *
+     * @param pubkeys A tightly packed array of 48-byte public keys corresponding to validators requesting full withdrawals.
+     *      | ----- public key (48 bytes) ----- || ----- public key (48 bytes) ----- | ...
+     *
+     * @param feePerRequest The withdrawal fee for each withdrawal request.
+     *        - Must be greater than or equal to the current minimal withdrawal fee.
+     *        - If set to zero, the current minimal withdrawal fee will be used automatically.
+     *
+     * @notice Reverts if:
+     *         - Validation of the public keys fails.
+     *         - The provided fee per request is insufficient.
+     *         - The contract has an insufficient balance to cover the total fees.
+     */
+    function addFullWithdrawalRequests(bytes calldata pubkeys, uint256 feePerRequest) internal {
+        uint256 keysCount = _validateAndCountPubkeys(pubkeys);
+        feePerRequest = _validateAndAdjustFee(feePerRequest, keysCount);
+
+        bytes memory callData = new bytes(56);
+
+        for (uint256 i = 0; i < keysCount; i++) {
+            _copyPubkeyToMemory(pubkeys, callData, i);
+
+            (bool success, ) = WITHDRAWAL_REQUEST.call{value: feePerRequest}(callData);
+
+            if (!success) {
+                revert WithdrawalRequestAdditionFailed(callData);
+            }
+        }
+    }
+
+    /**
+     * @dev Send EIP-7002 partial withdrawal requests for the specified public keys with corresponding amounts.
+     *      Each request instructs a validator to partially withdraw its stake.
+     *      A partial withdrawal is any withdrawal where the amount is greater than zero,
+     *      allows withdrawal of any balance exceeding 32 ETH (e.g., if a validator has 35 ETH, up to 3 ETH can be withdrawn),
+     *      the protocol enforces a minimum balance of 32 ETH per validator, even if a higher amount is requested.
+     *
+     * @param pubkeys A tightly packed array of 48-byte public keys corresponding to validators requesting full withdrawals.
+     *      | ----- public key (48 bytes) ----- || ----- public key (48 bytes) ----- | ...
+     *
+     * @param amounts An array of corresponding partial withdrawal amounts for each public key.
+     *
+     * @param feePerRequest The withdrawal fee for each withdrawal request.
+     *        - Must be greater than or equal to the current minimal withdrawal fee.
+     *        - If set to zero, the current minimal withdrawal fee will be used automatically.
+     *
+     * @notice Reverts if:
+     *         - Validation of the public keys fails.
+     *         - The pubkeys and amounts length mismatch.
+     *         - Full withdrawal requested for any pubkeys (withdrawal amount = 0).
+     *         - The provided fee per request is insufficient.
+     *         - The contract has an insufficient balance to cover the total fees.
+     */
+    function addPartialWithdrawalRequests(
+        bytes calldata pubkeys,
+        uint64[] calldata amounts,
+        uint256 feePerRequest
+    ) internal {
+        for (uint256 i = 0; i < amounts.length; i++) {
+            if (amounts[i] == 0) {
+                revert PartialWithdrawalRequired(i);
+            }
+        }
+
+        addWithdrawalRequests(pubkeys, amounts, feePerRequest);
+    }
+
+    /**
+     * @dev Send EIP-7002 partial or full withdrawal requests for the specified public keys with corresponding amounts.
+     *      Each request instructs a validator to partially or fully withdraw its stake.
+
+     *      1. A partial withdrawal is any withdrawal where the amount is greater than zero,
+     *      allows withdrawal of any balance exceeding 32 ETH (e.g., if a validator has 35 ETH, up to 3 ETH can be withdrawn),
+     *      the protocol enforces a minimum balance of 32 ETH per validator, even if a higher amount is requested.
+     *
+     *      2. A full withdrawal is a withdrawal where the amount is equal to zero,
+     *      allows to fully withdraw validator stake and exit its duties as a validator.
+     *
+     * @param pubkeys A tightly packed array of 48-byte public keys corresponding to validators requesting full withdrawals.
+     *      | ----- public key (48 bytes) ----- || ----- public key (48 bytes) ----- | ...
+     *
+     * @param amounts An array of corresponding partial withdrawal amounts for each public key.
+     *
+     * @param feePerRequest The withdrawal fee for each withdrawal request.
+     *        - Must be greater than or equal to the current minimal withdrawal fee.
+     *        - If set to zero, the current minimal withdrawal fee will be used automatically.
+     *
+     * @notice Reverts if:
+     *         - Validation of the public keys fails.
+     *         - The pubkeys and amounts length mismatch.
+     *         - The provided fee per request is insufficient.
+     *         - The contract has an insufficient balance to cover the total fees.
+     */
+    function addWithdrawalRequests(bytes calldata pubkeys, uint64[] calldata amounts, uint256 feePerRequest) internal {
+        uint256 keysCount = _validateAndCountPubkeys(pubkeys);
+
+        if (keysCount != amounts.length) {
+            revert MismatchedArrayLengths(keysCount, amounts.length);
+        }
+
+        feePerRequest = _validateAndAdjustFee(feePerRequest, keysCount);
+
+        bytes memory callData = new bytes(56);
+        for (uint256 i = 0; i < keysCount; i++) {
+            _copyPubkeyToMemory(pubkeys, callData, i);
+            _copyAmountToMemory(callData, amounts[i]);
+
+            (bool success, ) = WITHDRAWAL_REQUEST.call{value: feePerRequest}(callData);
+
+            if (!success) {
+                revert WithdrawalRequestAdditionFailed(callData);
+            }
+        }
+    }
+
+    /**
+     * @dev Retrieves the current EIP-7002 withdrawal fee.
+     * @return The minimum fee required per withdrawal request.
+     */
+    function getWithdrawalRequestFee() internal view returns (uint256) {
+        (bool success, bytes memory feeData) = WITHDRAWAL_REQUEST.staticcall("");
+
+        if (!success) {
+            revert WithdrawalFeeReadFailed();
+        }
+
+        if (feeData.length != 32) {
+            revert WithdrawalFeeInvalidData();
+        }
+
+        return abi.decode(feeData, (uint256));
+    }
+
+    function _copyPubkeyToMemory(bytes calldata pubkeys, bytes memory target, uint256 keyIndex) private pure {
+        assembly {
+            calldatacopy(add(target, 32), add(pubkeys.offset, mul(keyIndex, PUBLIC_KEY_LENGTH)), PUBLIC_KEY_LENGTH)
+        }
+    }
+
+    function _copyAmountToMemory(bytes memory target, uint64 amount) private pure {
+        assembly {
+            mstore(add(target, 80), shl(192, amount))
+        }
+    }
+
+    function _validateAndCountPubkeys(bytes calldata pubkeys) private pure returns (uint256) {
+        if (pubkeys.length % PUBLIC_KEY_LENGTH != 0) {
+            revert MalformedPubkeysArray();
+        }
+
+        uint256 keysCount = pubkeys.length / PUBLIC_KEY_LENGTH;
+        if (keysCount == 0) {
+            revert NoWithdrawalRequests();
+        }
+
+        return keysCount;
+    }
+
+    function _validateAndAdjustFee(uint256 feePerRequest, uint256 keysCount) private view returns (uint256) {
+        uint256 minFeePerRequest = getWithdrawalRequestFee();
+
+        if (feePerRequest == 0) {
+            feePerRequest = minFeePerRequest;
+        }
+
+        if (feePerRequest < minFeePerRequest) {
+            revert InsufficientWithdrawalFee(feePerRequest, minFeePerRequest);
+        }
+
+        if (address(this).balance < feePerRequest * keysCount) {
+            revert TotalWithdrawalFeeExceededBalance(address(this).balance, feePerRequest * keysCount);
+        }
+
+        return feePerRequest;
+    }
+}

scripts/scratch/steps/0120-initialize-non-aragon-contracts.ts

@@ -35,6 +35,7 @@ export async function main() {
   const exitBusOracleAdmin = testnetAdmin;
   const stakingRouterAdmin = testnetAdmin;
   const withdrawalQueueAdmin = testnetAdmin;
+  const withdrawalVaultAdmin = testnetAdmin;
 
   // Initialize NodeOperatorsRegistry
 
@@ -108,6 +109,10 @@ export async function main() {
     { from: deployer },
   );
 
+  // Initialize WithdrawalVault
+  const withdrawalVault = await loadContract("WithdrawalVault", withdrawalVaultAddress);
+  await makeTx(withdrawalVault, "initialize", [withdrawalVaultAdmin], { from: deployer });
+
   // Initialize WithdrawalQueue
   const withdrawalQueue = await loadContract("WithdrawalQueueERC721", withdrawalQueueAddress);
   await makeTx(withdrawalQueue, "initialize", [withdrawalQueueAdmin], { from: deployer });