Staking contracts: ERC20 and Native IMX

Added code, tests, and scripts for Staking using ERC20s, native IMX, and native IMX where the IMX is held as WIMX. The contracts can be deployed simply, or via a time delay upgrade

Co-authored-by: w3njah <[email protected]>

Author: drinkcoffee

.env.example

@@ -1,4 +1,9 @@
-ETHERSCAN_API_KEY=<YOUR_ETHERSCAN_API_KEY>
-SEPOLIA_URL=https://eth-sepolia.g.alchemy.com/v2/<YOUR_ALCHEMY_API_KEY>
-MAINNET_URL=https://eth-mainnet.g.alchemy.com/v2/<YOUR_ALCHEMY_API_KEY>
+IMMUTABLE_NETWORK=0
+BLOCKSCOUT_APIKEY=<YOUR_BLOCKSCOUT_APIKEY>
 PRIVATE_KEY=<YOUR_PRIVATE_KEY>
+HD_PATH="m/44'/60'/0'/0/0"
+DEPLOYER_ADDRESS=<Account matching private key or HD_PATH>
+ROLE_ADMIN=<Account or 0x0000000000000000000000000000000000000000>
+UPGRADE_ADMIN=<Account or 0x0000000000000000000000000000000000000000>
+DISTRIBUTE_ADMIN=<Account or 0x0000000000000000000000000000000000000000>
+ERC20_STAKING_TOKEN=<Token address?

.github/workflows/test.yml

@@ -74,6 +74,8 @@ jobs:
     steps:
       - name: Checkout Code
         uses: actions/checkout@v3
+      - name: Uninstall Debian package that slither needs to uninstall
+        run: sudo apt remove python3-typing-extensions
       - name: Install Slither
         run: sudo pip3 install slither-analyzer
       - name: Show Slither Version

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

@@ -1,7 +1,5 @@
 # Contract Deployers
 
-At present, use of the Contract Deployers described below is limited to Immutable. 
-
 This directory provides two types of contract deployers: CREATE2 and CREATE3. Both deployer types facilitate contract deployment to predictable addresses, independent of the deployer account’s nonce. The deployers offer a more reliable alternative to using a Nonce Reserver Key (a key that is only used for deploying contracts, and has specific nonces reserved for deploying specific contracts), particularly across different chains. These factories can also be utilized for contracts that don't necessarily need predictable addresses. The advantage of this method, compared to using a deployer key in conjunction with a deployment factory contract, is that it can enable better standardisation and simplification of deployment processes and enables the rotation of the deployer key without impacting the consistency of the perceived deployer address for contracts.
 
 Deployments via these factories can only be performed by the owner of the factory. 

contracts/deployer/README.md

@@ -65,7 +65,7 @@ contract PaymentSplitter is AccessControlEnumerable, IPaymentSplitterErrors, Ree
     /**
      * @notice Payable fallback method to receive IMX. The IMX received will be logged with {PaymentReceived} events.
      * this contract has no other payable method, all IMX receives will be tracked by the events emitted by this event
-     * ERC20 receives will not be tracked by this contract but tranfers events will be emitted by the erc20 contracts themselves.
+     * ERC20 receives will not be tracked by this contract but transfers events will be emitted by the erc20 contracts themselves.
      */
     receive() external payable virtual {
         emit PaymentReceived(_msgSender(), msg.value);

contracts/payment-splitter/PaymentSplitter.sol

@@ -0,0 +1,129 @@
+// Copyright (c) Immutable Pty Ltd 2018 - 2025
+// SPDX-License-Identifier: Apache 2
+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.
+ */
+interface IStakeHolder is IAccessControlEnumerableUpgradeable {
+    /// @notice implementation does not accept native tokens.
+    error NonPayable();
+
+    /// @notice Error: Attempting to upgrade contract storage to version 0.
+    error CanNotUpgradeToLowerOrSameVersion(uint256 _storageVersion);
+
+    /// @notice Error: Attempting to renounce the last role admin / default admin.
+    error MustHaveOneRoleAdmin();
+
+    /// @notice Error: Attempting to stake with zero value.
+    error MustStakeMoreThanZero();
+
+    /// @notice Error: Attempting to distribute zero value.
+    error MustDistributeMoreThanZero();
+
+    /// @notice Error: Attempting to unstake amount greater than the balance.
+    error UnstakeAmountExceedsBalance(uint256 _amountToUnstake, uint256 _currentStake);
+
+    /// @notice Error: Distributions can only be made to accounts that have staked.
+    error AttemptToDistributeToNewAccount(address _account, uint256 _amount);
+
+    /// @notice Error: Call to stake for implementations that accept value require value and parameter to match.
+    error MismatchMsgValueAmount(uint256 _msgValue, uint256 _amount);
+
+    /// @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.
+    event Distributed(address _distributor, uint256 _totalDistribution, uint256 _numRecipients);
+
+    /// @notice Struct to combine an account and an amount.
+    struct AccountAmount {
+        address account;
+        uint256 amount;
+    }
+
+    /**
+     * @notice Allow any account to stake more value.
+     * @param _amount The amount of tokens to be staked.
+     */
+    function stake(uint256 _amount) external payable;
+
+    /**
+     * @notice Allow any account to remove some or all of their own stake.
+     * @param _amountToUnstake Amount of stake to remove.
+     */
+    function unstake(uint256 _amountToUnstake) external;
+
+    /**
+     * @notice Accounts with DISTRIBUTE_ROLE can distribute tokens to any set of accounts.
+     * @param _recipientsAndAmounts An array of recipients to distribute value to and
+     *          amounts to be distributed to each recipient.
+     */
+    function distributeRewards(AccountAmount[] calldata _recipientsAndAmounts) external payable;
+
+    /**
+     * @notice Get the balance of an account.
+     * @param _account The account to return the balance for.
+     * @return _balance The balance of the account.
+     */
+    function getBalance(address _account) external view returns (uint256 _balance);
+
+    /**
+     * @notice Determine if an account has ever staked.
+     * @param _account The account to determine if they have staked
+     * @return _everStaked True if the account has ever staked.
+     */
+    function hasStaked(address _account) external view returns (bool _everStaked);
+
+    /**
+     * @notice Get the length of the stakers array.
+     * @dev This will be equal to the number of staker accounts that have ever staked.
+     *  Some of the accounts might have a zero balance, having staked and then
+     *  unstaked.
+     * @return _len The length of the stakers array.
+     */
+    function getNumStakers() external view returns (uint256 _len);
+
+    /**
+     * @notice Get the staker accounts from the stakers array.
+     * @dev Given the stakers list could grow arbitrarily long. To prevent out of memory or out of
+     *  gas situations due to attempting to return a very large array, this function call specifies
+     *  the start offset and number of accounts to be return.
+     *  NOTE: This code will cause a panic if the start offset + number to return is greater than
+     *  the length of the array. Use getNumStakers before calling this function to determine the
+     *  length of the array.
+     * @param _startOffset First offset in the stakers array to return the account number for.
+     * @param _numberToReturn The number of accounts to return.
+     * @return _stakers A subset of the stakers array.
+     */
+    function getStakers(
+        uint256 _startOffset,
+        uint256 _numberToReturn
+    ) external view returns (address[] memory _stakers);
+
+    /**
+     * @return The address of the staking token.
+     */
+    function getToken() external view returns (address);
+
+    /**
+     * @notice version number of the storage variable layout.
+     */
+    function version() external view returns (uint256);
+
+    /**
+     * @notice Only UPGRADE_ROLE can upgrade the contract
+     */
+    function UPGRADE_ROLE() external pure returns (bytes32);
+
+    /**
+     * @notice Only DISTRIBUTE_ROLE can call the distribute function
+     */
+    function DISTRIBUTE_ROLE() external pure returns (bytes32);
+}

contracts/staking/IStakeHolder.sol

@@ -0,0 +1,36 @@
+// Copyright Immutable Pty Ltd 2018 - 2023
+// SPDX-License-Identifier: Apache 2.0
+pragma solidity >=0.8.19 <0.8.29;
+
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+
+/*
+ * @notice Interface for the Wrapped IMX (wIMX) contract.
+ * @dev Based on the interface for the [Wrapped IMX contract](https://etherscan.io/token/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2#code)
+ */
+interface IWIMX is IERC20 {
+    /**
+     * @notice Emitted when native IMX is deposited to the contract, and a corresponding amount of wIMX are minted
+     * @param account The address of the account that deposited the tokens.
+     * @param value The amount of tokens that were deposited.
+     */
+    event Deposit(address indexed account, uint256 value);
+
+    /**
+     * @notice Emitted when wIMX is withdrawn from the contract, and a corresponding amount of wIMX are burnt.
+     * @param account The address of the account that withdrew the tokens.
+     * @param value The amount of tokens that were withdrawn.
+     */
+    event Withdrawal(address indexed account, uint256 value);
+
+    /**
+     * @notice Deposit native IMX to the contract and mint an equal amount of wrapped IMX to msg.sender.
+     */
+    function deposit() external payable;
+
+    /**
+     * @notice Withdraw given amount of native IMX to msg.sender after burning an equal amount of wrapped IMX.
+     * @param value The amount to withdraw.
+     */
+    function withdraw(uint256 value) external;
+}

contracts/staking/IWIMX.sol

@@ -1,9 +1,33 @@
 # Staking
 
-The Immutable zkEVM staking system consists of the Staking Holder contract. This contract holds staked native IMX. Any account (EOA or contract) can stake any amount 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 contract has the facility to distribute rewards to stakers.
+
+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). 
+
+The system consists of a set of contracts show in the diagram below.
+
+![Staking Architecture](./staking-architecture.png)
+
+`IStakeHolder.sol` is the interface that all staking implementations comply with.
+
+`StakeHolderBase.sol` is the abstract base contract that all staking implementation use.
+
+`StakeHolderWIMX.sol` allows the native token, IMX, to be used as the staking currency. Stake is held as wrapped IMX, WIMX, an ERC20 token.
+
+`StakeHolderERC20.sol` allows an ERC20 token to be used as the staking currency.
+
+`StakeHolderNative.sol` uses the native token, IMX, to be used as the staking currency. Stake is held as native IMX.
+
+`ERC1967Proxy.sol` is a proxy contract. All calls to StakeHolder contracts go via the ERC1967Proxy contract.
+
+`TimelockController.sol` can be used with the staking contracts to provide a one week delay between when upgrade or other admin changes are proposed and when they are executed. See below for information on how to configure the time lock controller.
+
+`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.
 
 ## Immutable Contract Addresses
 
+StakeHolderERC20.sol configured with IMX as the staking token:
+
 | Environment/Network      | Deployment Address | Commit Hash |
 |--------------------------|--------------------|-------------|
 | Immutable zkEVM Testnet  | Not deployed yet   |   -|
@@ -16,31 +40,24 @@ Contract threat models and audits:
 | Description               | Date             |Version Audited  | Link to Report |
 |---------------------------|------------------|-----------------|----------------|
 | Threat model              | Oct 21, 2024     | [`fd982abc49884af41e05f18349b13edc9eefbc1e`](https://github.com/immutable/contracts/blob/fd982abc49884af41e05f18349b13edc9eefbc1e/contracts/staking/README.md) | [202410-threat-model-stake-holder.md](../../audits/staking/202410-threat-model-stake-holder.md)              |
+| Threat model              | April 24, 2025     | [`bf327c7abdadd48fd51ae632500510ac2b07b5f0`](https://github.com/immutable/contracts/blob/bf327c7abdadd48fd51ae632500510ac2b07b5f0/contracts/staking/README.md) | [202504-threat-model-stake-holder.md](../../audits/staking/202504-threat-model-stake-holder.md)              |
 
 
 
 # Deployment
 
-**Deploy and verify using CREATE3 factory contract:**
-
-This repo includes a script for deploying via a CREATE3 factory contract. The script is defined as a test contract as per the examples [here](https://book.getfoundry.sh/reference/forge/forge-script#examples) and can be found in `./script/staking/DeployStakeHolder.sol`.
-
-See the `.env.example` for required environment variables.
-
-```sh
-forge script script/staking/DeployStakeHolder.sol --tc DeployStakeHolder --sig "deploy()" -vvv --rpc-url {rpc-url} --broadcast --verifier-url https://explorer.immutable.com/api --verifier blockscout --verify --gas-price 10000000000
-```
-
-Optionally, you can also specify `--ledger` or `--trezor` for hardware deployments. See docs [here](https://book.getfoundry.sh/reference/forge/forge-script#wallet-options---hardware-wallet).
+See [deployment scripts](../../script/staking/README.md).
 
 
 # Usage
 
-To stake, any account should call `stake()`, passing in the amount to be staked as the msg.value.
+For StakeHolderERC20 and StakeHolderWIMX, the ERC20 staking token must be specified when the contract is being initialised. The token can not be changed.
+
+To stake, any account should call `stake(uint256 _amount)`. For the WIMX and the native IMX variants, the amount to be staked must be passed in as the msg.value.
 
 To unstake, the account that previously staked should call, `unstake(uint256 _amountToUnstake)`.
 
-Accounts that have DISTRIBUTE_ROLE that wish to distribute rewards should call, `distributeRewards(AccountAmount[] calldata _recipientsAndAmounts)`. The `AccountAmount` structure consists of recipient address and amount to distribute pairs. Distributions can only be made to accounts that have previously or are currently staking. The amount to be distributed must be passed in as msg.value and must equal to the sum of the amounts specified in the `_recipientsAndAmounts` array.
+Accounts that have DISTRIBUTE_ROLE that wish to distribute rewards should call, `distributeRewards(AccountAmount[] calldata _recipientsAndAmounts)`. The `AccountAmount` structure consists of recipient address and amount to distribute pairs. Distributions can only be made to accounts that have previously or are currently staking. For the WIMX and the native IMX variants, the amount to be distributed must be passed in as msg.value and must equal to the sum of the amounts specified in the `_recipientsAndAmounts` array.
 
 The `stakers` array needs to be analysed to determine which accounts have staked and how much. The following functions provide access to this data structure:
 
@@ -51,11 +68,7 @@ The `stakers` array needs to be analysed to determine which accounts have staked
 
 # Administration Notes
 
-The `StakeHolder` contract is `AccessControlEnumerableUpgradeable`, with the following minor modification:
-
-* `_revokeRole(bytes32 _role, address _account)` has been overridden to prevent the last DEFAULT_ADMIN_ROLE (the last role admin) from either being revoked or renounced.
-
-The `StakeHolder` contract is `UUPSUpgradeable`. Only accounts with `UPGRADE_ROLE` are authorised to upgrade the contract.
+The `StakeHolderBase` contract is `AccessControlEnumerableUpgradeable`. The `StakeHolderERC20` and `StakeHolderNative` contracts are `UUPSUpgradeable`. Only accounts with `UPGRADE_ROLE` are authorised to upgrade the contract.
 
 ## Upgrade Concept
 
@@ -67,3 +80,11 @@ The `upgradeStorage` function should be updated each new contract version. It sh
   * The value is the same as the newt version: Someone (an attacker) has called the `upgradeStorage` function after the code has been upgraded. The function should revert.
 * Based on the old code version and storage format indicated by the `version`, update the storage variables. Typically, upgrades only involve code changes, and require no storage variable changes. However, in some circumstances storage variables should also be updated.
 * Update the `version` storage variable to indicate the new code version.
+
+## Time Delay Upgrade and Admin
+
+A staking systems may wish to delay upgrade actions and the granting of additional administrative access. To do this, the only account with UPGRADE_ROLE and DEFAULT_ADMIN_ROLE roles should be an instance of Open Zeppelin's [TimelockController](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/governance/TimelockController.sol). This ensures any upgrade proposals or proposals to add more accounts with `DEFAULT_ADMIN_ROLE`, `UPGRADE_ROLE` or `DISTRIBUTE_ROLE` must go through a time delay before being actioned. The account with `DEFAULT_ADMIN_ROLE` could choose to renounce this role to ensure the `TimelockController` can not be bypassed at a later date by having a compromised account with  `DEFAULT_ADMIN_ROLE` adding addtional accounts with `UPGRADE_ROLE`.
+
+## Preventing Upgrade
+
+A staking system could choose to have no account with DEFAULT_ADMIN_ROLE to to prevent additional accounts being granted UPGRADE_ROLE role. The system could have no acccounts with UPGRADE_ROLE, thus preventing upgrade. The system could configure this from start-up by passing in `address(0)` as the `roleAdmin` and `upgradeAdmin` to the constructor. Alternative, the `revokeRole` function can be used to revoke the roles from accounts.