StakeFor upgrade to staking system (#280)

This upgrade to the staking system adds the function stakeFor, that allows value to be staked on behalf of accounts.

The contract deployed by deploySimple and deployComplex scripts is now the version 2 contract.

Author: drinkcoffee

,,.x.txt

@@ -0,0 +1,3 @@
+Compiling 118 files with Solc 0.8.17
+Compiling 55 files with Solc 0.8.20
+Compiling 305 files with Solc 0.8.28

audits/staking/202506-threat-model-stake-holder.md

@@ -5,8 +5,7 @@ pragma solidity >=0.8.19 <0.8.29;
 import {IAccessControlEnumerableUpgradeable} from "openzeppelin-contracts-upgradeable-4.9.3/access/IAccessControlEnumerableUpgradeable.sol";
 
 /**
- * @title StakeHolderBase: allows anyone to stake any amount of an ERC20 token and to then remove all or part of that stake.
- * @dev The StakeHolderERC20 contract is designed to be upgradeable.
+ * @title IStakeHolder: Interface for staking system.
  */
 interface IStakeHolder is IAccessControlEnumerableUpgradeable {
     /// @notice implementation does not accept native tokens.
@@ -33,13 +32,18 @@ interface IStakeHolder is IAccessControlEnumerableUpgradeable {
     /// @notice Error: Call to stake for implementations that accept value require value and parameter to match.
     error MismatchMsgValueAmount(uint256 _msgValue, uint256 _amount);
 
+    /// @notice Error: Unstake native value transfer failed with revert with no revert information.
+    /// @dev An error was detected by the EVM. For example a function call to an address with no contract associated with it.
+    error UnstakeTransferFailed();
+
     /// @notice Event when an amount has been staked or when an amount is distributed to an account.
     event StakeAdded(address _staker, uint256 _amountAdded, uint256 _newBalance);
 
     /// @notice Event when an amount has been unstaked.
     event StakeRemoved(address _staker, uint256 _amountRemoved, uint256 _newBalance);
 
-    /// @notice Event summarising a distribution. There will also be one StakeAdded event for each recipient.
+    /// @notice Event summarising a distribution.
+    /// @dev There will also be one StakeAdded event for each recipient.
     event Distributed(address _distributor, uint256 _totalDistribution, uint256 _numRecipients);
 
     /// @notice Struct to combine an account and an amount.
@@ -61,7 +65,9 @@ interface IStakeHolder is IAccessControlEnumerableUpgradeable {
     function unstake(uint256 _amountToUnstake) external;
 
     /**
-     * @notice Accounts with DISTRIBUTE_ROLE can distribute tokens to any set of accounts.
+     * @notice Distribute rewards to stakers.
+     * @dev Only callable by accounts with DISTRIBUTE_ROLE.
+     * @dev Recipients must have staked value prior to this function call.
      * @param _recipientsAndAmounts An array of recipients to distribute value to and
      *          amounts to be distributed to each recipient.
      */

contracts/staking/IStakeHolder.sol

@@ -0,0 +1,26 @@
+// Copyright (c) Immutable Pty Ltd 2018 - 2025
+// SPDX-License-Identifier: Apache 2
+pragma solidity >=0.8.19 <0.8.29;
+
+import {IStakeHolder} from "./IStakeHolder.sol";
+
+/**
+ * @title IStakeHolderV2: Interface for V2 staking system.
+ */
+interface IStakeHolderV2 is IStakeHolder {
+    /// @notice Native IMX was received from an account other than the WIMX contract.
+    error ImxNotFromWimxContract(address _from);
+
+    /// @notice Event summarising a distribution via the stakeFor function.
+    /// @dev There will be one StakeAdded event for each recipient.
+    event StakedFor(address _distributor, uint256 _totalDistribution, uint256 _numRecipients);
+
+    /**
+     * @notice Stake on behalf of others.
+     * @dev Only callable by accounts with DISTRIBUTE_ROLE.
+     * @dev Unlike the distributeRewards function, there is no requirement that recipients are existing stakers.
+     * @param _recipientsAndAmounts An array of recipients to distribute value to and
+     *          amounts to be distributed to each recipient.
+     */
+    function stakeFor(AccountAmount[] calldata _recipientsAndAmounts) external payable;
+}

contracts/staking/IStakeHolderV2.sol

@@ -1,6 +1,6 @@
 # Staking
 
-The Immutable zkEVM staking system allows any account (EOA or contract) to stake any amount of a token at any time. An account can remove all or some of their stake at any time. The contract has the facility to distribute rewards to stakers.
+The Immutable zkEVM staking system allows any account (EOA or contract) to stake any amount of a token at any time. An account can remove all or some of their stake at any time. The contracts have the facility to distribute rewards to stakers and to stake on behalf of accounts
 
 The staking contracts are upgradeable and operate via a proxy contract. They use the [Universal Upgradeable Proxy Standard (UUPS)](https://eips.ethereum.org/EIPS/eip-1822) upgrade pattern, where the access control for upgrade resides within the application contract (the staking contract). 
 
@@ -24,6 +24,10 @@ The system consists of a set of contracts show in the diagram below.
 
 `OwnableCreate3Deployer.sol` ensures contracts are deployed to the same addresses across chains. The use of this contract is optional. See [deployment scripts](../../script/staking/README.md) for more information.
 
+## Staking System V2
+
+Files, contracts, and interfaced suffixed with `V2` form a part of the version two staking system. Version two introduces the ability for an admin account to stake on behalf of other accounts using the `stakeFor` function.
+
 ## Immutable Contract Addresses
 
 TimelockController.sol:

contracts/staking/README.md

@@ -8,8 +8,8 @@ import {ReentrancyGuardUpgradeable} from "openzeppelin-contracts-upgradeable-4.9
 import {IStakeHolder} from "./IStakeHolder.sol";
 
 /**
- * @title StakeHolderBase: allows anyone to stake any amount of an ERC20 token and to then remove all or part of that stake.
- * @dev The StakeHolderERC20 contract is designed to be upgradeable.
+ * @title StakeHolderBase: allows anyone to stake and unstake value.
+ * @dev This contract is designed to be upgradeable.
  */
 abstract contract StakeHolderBase is
     IStakeHolder,
@@ -58,7 +58,7 @@ abstract contract StakeHolderBase is
         address _roleAdmin,
         address _upgradeAdmin,
         address _distributeAdmin
-    ) internal onlyInitializing {
+    ) internal virtual onlyInitializing {
         __UUPSUpgradeable_init();
         __AccessControl_init();
         __ReentrancyGuard_init();
@@ -117,7 +117,7 @@ abstract contract StakeHolderBase is
      */
     function distributeRewards(
         AccountAmount[] calldata _recipientsAndAmounts
-    ) external payable nonReentrant onlyRole(DISTRIBUTE_ROLE) {
+    ) external payable virtual nonReentrant onlyRole(DISTRIBUTE_ROLE) {
         // Distribute the value.
         uint256 total = 0;
         uint256 len = _recipientsAndAmounts.length;

contracts/staking/StakeHolderBase.sol

@@ -0,0 +1,101 @@
+// Copyright (c) Immutable Pty Ltd 2018 - 2025
+// SPDX-License-Identifier: Apache 2
+pragma solidity >=0.8.19 <0.8.29;
+
+import {StakeHolderBase} from "./StakeHolderBase.sol";
+import {IStakeHolderV2, IStakeHolder} from "./IStakeHolderV2.sol";
+
+/**
+ * @title StakeHolderBase: allows anyone to stake any amount of an ERC20 token and to then remove all or part of that stake.
+ * @dev This contract is designed to be upgradeable.
+ */
+abstract contract StakeHolderBaseV2 is IStakeHolderV2, StakeHolderBase {
+    /// @notice Version 2 version number
+    uint256 internal constant _VERSION2 = 2;
+
+    /**
+     * @notice Initialises the upgradeable contract, setting up admin accounts.
+     * @param _roleAdmin the address to grant `DEFAULT_ADMIN_ROLE` to
+     * @param _upgradeAdmin the address to grant `UPGRADE_ROLE` to
+     * @param _distributeAdmin the address to grant `DISTRIBUTE_ROLE` to
+     */
+    function __StakeHolderBase_init(
+        address _roleAdmin,
+        address _upgradeAdmin,
+        address _distributeAdmin
+    ) internal virtual override {
+        // NOTE: onlyInitializing is called in super.
+        super.__StakeHolderBase_init(_roleAdmin, _upgradeAdmin, _distributeAdmin);
+        version = _VERSION2;
+    }
+
+    /**
+     * @notice Function to be called when upgrading this contract.
+     * @dev Call this function as part of upgradeToAndCall().
+     *      This initial version of this function reverts. There is no situation
+     *      in which it makes sense to upgrade to the V0 storage layout.
+     *      Note that this function is permissionless. Future versions must
+     *      compare the code version and the storage version and upgrade
+     *      appropriately. As such, the code will revert if an attacker calls
+     *      this function attempting a malicious upgrade.
+     * @ param _data ABI encoded data to be used as part of the contract storage upgrade.
+     */
+    function upgradeStorage(bytes memory /* _data */) external virtual override {
+        if (version == _VERSION0) {
+            // Upgrading from version 0 to 2 involves only code changes and
+            // changing the storage version number.
+            version = _VERSION2;
+        } else {
+            // Don't allow downgrade or re-initialising.
+            revert CanNotUpgradeToLowerOrSameVersion(version);
+        }
+    }
+
+    /**
+     * @inheritdoc IStakeHolder
+     */
+    function distributeRewards(
+        AccountAmount[] calldata _recipientsAndAmounts
+    ) external payable override(IStakeHolder, StakeHolderBase) nonReentrant onlyRole(DISTRIBUTE_ROLE) {
+        uint256 total = _distributeRewards(_recipientsAndAmounts, true);
+        uint256 len = _recipientsAndAmounts.length;
+        emit Distributed(msg.sender, total, len);
+    }
+
+    /**
+     * @inheritdoc IStakeHolderV2
+     */
+    function stakeFor(
+        AccountAmount[] calldata _recipientsAndAmounts
+    ) external payable nonReentrant onlyRole(DISTRIBUTE_ROLE) {
+        uint256 total = _distributeRewards(_recipientsAndAmounts, false);
+        uint256 len = _recipientsAndAmounts.length;
+        emit StakedFor(msg.sender, total, len);
+    }
+
+    /**
+     * @notice Distribute tokens to a set of accounts.
+     * @param _recipientsAndAmounts An array of recipients to distribute value to and
+     *          amounts to be distributed to each recipient.
+     * @param _existingAccountsOnly If true, revert if the account has never been used.
+     * @return _total Value distributed.
+     */
+    function _distributeRewards(
+        AccountAmount[] calldata _recipientsAndAmounts,
+        bool _existingAccountsOnly
+    ) private returns (uint256 _total) {
+        // Distribute the value.
+        _total = 0;
+        uint256 len = _recipientsAndAmounts.length;
+        for (uint256 i = 0; i < len; i++) {
+            AccountAmount calldata accountAmount = _recipientsAndAmounts[i];
+            uint256 amount = accountAmount.amount;
+            _addStake(accountAmount.account, amount, _existingAccountsOnly);
+            _total += amount;
+        }
+        if (_total == 0) {
+            revert MustDistributeMoreThanZero();
+        }
+        _checksAndTransfer(_total);
+    }
+}

contracts/staking/StakeHolderBaseV2.sol

@@ -0,0 +1,75 @@
+// Copyright (c) Immutable Pty Ltd 2018 - 2025
+// SPDX-License-Identifier: Apache 2
+pragma solidity >=0.8.19 <0.8.29;
+
+import {IERC20Upgradeable} from "openzeppelin-contracts-upgradeable-4.9.3/token/ERC20/IERC20Upgradeable.sol";
+import {SafeERC20Upgradeable} from "openzeppelin-contracts-upgradeable-4.9.3/token/ERC20/utils/SafeERC20Upgradeable.sol";
+import {IStakeHolder, StakeHolderBase, StakeHolderBaseV2} from "./StakeHolderBaseV2.sol";
+
+/**
+ * @title StakeHolderERC20V2: allows anyone to stake any amount of an ERC20 token and to then remove all or part of that stake.
+ * @dev The StakeHolderERC20 contract is designed to be upgradeable.
+ * @dev This contract is the same as StakeHolderERC20, with the exception that it derives from StakeHolderBaseV2.
+ */
+contract StakeHolderERC20V2 is StakeHolderBaseV2 {
+    using SafeERC20Upgradeable for IERC20Upgradeable;
+
+    /// @notice The token used for staking.
+    IERC20Upgradeable internal token;
+
+    /**
+     * @notice Initialises the upgradeable contract, setting up admin accounts.
+     * @param _roleAdmin the address to grant `DEFAULT_ADMIN_ROLE` to
+     * @param _upgradeAdmin the address to grant `UPGRADE_ROLE` to
+     * @param _distributeAdmin the address to grant `DISTRIBUTE_ROLE` to.
+     * @param _token the token to use for staking.
+     */
+    function initialize(
+        address _roleAdmin,
+        address _upgradeAdmin,
+        address _distributeAdmin,
+        address _token
+    ) public initializer {
+        __StakeHolderERC20_init(_roleAdmin, _upgradeAdmin, _distributeAdmin, _token);
+    }
+
+    function __StakeHolderERC20_init(
+        address _roleAdmin,
+        address _upgradeAdmin,
+        address _distributeAdmin,
+        address _token
+    ) internal onlyInitializing {
+        __StakeHolderBase_init(_roleAdmin, _upgradeAdmin, _distributeAdmin);
+        token = IERC20Upgradeable(_token);
+    }
+
+    /**
+     * @inheritdoc IStakeHolder
+     */
+    function getToken() external view returns (address) {
+        return address(token);
+    }
+
+    /**
+     * @inheritdoc StakeHolderBase
+     */
+    function _sendValue(address _to, uint256 _amount) internal override {
+        token.safeTransfer(_to, _amount);
+    }
+
+    /**
+     * @inheritdoc StakeHolderBase
+     */
+    function _checksAndTransfer(uint256 _amount) internal override {
+        if (msg.value != 0) {
+            revert NonPayable();
+        }
+        token.safeTransferFrom(msg.sender, address(this), _amount);
+    }
+
+    /// @notice storage gap for additional variables for upgrades
+    // slither-disable-start unused-state
+    // solhint-disable-next-line var-name-mixedcase
+    uint256[50] private __StakeHolderERC20Gap;
+    // slither-disable-end unused-state
+}

contracts/staking/StakeHolderERC20V2.sol

@@ -9,9 +9,6 @@ import {IStakeHolder, StakeHolderBase} from "./StakeHolderBase.sol";
  * @dev The StakeHolder contract is designed to be upgradeable.
  */
 contract StakeHolderNative is StakeHolderBase {
-    /// @notice Error: Unstake transfer failed.
-    error UnstakeTransferFailed();
-
     /**
      * @notice Initialises the upgradeable contract, setting up admin accounts.
      * @param _roleAdmin the address to grant `DEFAULT_ADMIN_ROLE` to

contracts/staking/StakeHolderNative.sol

@@ -0,0 +1,66 @@
+// Copyright (c) Immutable Pty Ltd 2018 - 2025
+// SPDX-License-Identifier: Apache 2
+pragma solidity >=0.8.19 <0.8.29;
+
+import {IStakeHolder, StakeHolderBase, StakeHolderBaseV2} from "./StakeHolderBaseV2.sol";
+
+/**
+ * @title StakeHolderNativeV2: allows anyone to stake any amount of native IMX and to then remove all or part of that stake.
+ * @dev The StakeHolder contract is designed to be upgradeable.
+ * @dev This contract is the same as StakeHolderNative, with the exception that it derives from StakeHolderBaseV2.
+ */
+contract StakeHolderNativeV2 is StakeHolderBaseV2 {
+    /**
+     * @notice Initialises the upgradeable contract, setting up admin accounts.
+     * @param _roleAdmin the address to grant `DEFAULT_ADMIN_ROLE` to
+     * @param _upgradeAdmin the address to grant `UPGRADE_ROLE` to
+     * @param _distributeAdmin the address to grant `DISTRIBUTE_ROLE` to
+     */
+    function initialize(address _roleAdmin, address _upgradeAdmin, address _distributeAdmin) public initializer {
+        __StakeHolderBase_init(_roleAdmin, _upgradeAdmin, _distributeAdmin);
+    }
+
+    /**
+     * @inheritdoc IStakeHolder
+     */
+    function getToken() external view virtual returns (address) {
+        return address(0);
+    }
+
+    /**
+     * @inheritdoc StakeHolderBase
+     */
+    function _sendValue(address _to, uint256 _amount) internal virtual override {
+        // slither-disable-next-line low-level-calls,arbitrary-send-eth
+        (bool success, bytes memory returndata) = payable(_to).call{value: _amount}("");
+        if (!success) {
+            // Look for revert reason and bubble it up if present.
+            // Revert reasons should contain an error selector, which is four bytes long.
+            if (returndata.length >= 4) {
+                // solhint-disable-next-line no-inline-assembly
+                assembly {
+                    let returndata_size := mload(returndata)
+                    revert(add(32, returndata), returndata_size)
+                }
+            } else {
+                revert UnstakeTransferFailed();
+            }
+        }
+    }
+
+    /**
+     * @inheritdoc StakeHolderBase
+     */
+    function _checksAndTransfer(uint256 _amount) internal virtual override {
+        // Check that the amount matches the msg.value.
+        if (_amount != msg.value) {
+            revert MismatchMsgValueAmount(msg.value, _amount);
+        }
+    }
+
+    /// @notice storage gap for additional variables for upgrades
+    // slither-disable-start unused-state
+    // solhint-disable-next-line var-name-mixedcase
+    uint256[50] private __StakeHolderNativeGap;
+    // slither-disable-end unused-state
+}