@evvm/testnet-contracts 2.2.2 → 2.3.0

package/contracts/staking/Staking.sol

@@ -41,10 +41,14 @@ pragma solidity ^0.8.0;
  * - Estimator integration for yield calculations
  */
 
-import {IEvvm} from "@evvm/testnet-contracts/interfaces/IEvvm.sol";
+import {Evvm} from "@evvm/testnet-contracts/contracts/evvm/Evvm.sol";
 import {IEstimator} from "@evvm/testnet-contracts/interfaces/IEstimator.sol";
-import {AsyncNonce} from "@evvm/testnet-contracts/library/utils/nonces/AsyncNonce.sol";
-import {StakingStructs} from "@evvm/testnet-contracts/contracts/staking/lib/StakingStructs.sol";
+import {
+    AsyncNonce
+} from "@evvm/testnet-contracts/library/utils/nonces/AsyncNonce.sol";
+import {
+    StakingStructs
+} from "@evvm/testnet-contracts/contracts/staking/lib/StakingStructs.sol";
 import {ErrorsLib} from "./lib/ErrorsLib.sol";
 import {SignatureUtils} from "./lib/SignatureUtils.sol";
 
@@ -61,10 +65,6 @@ contract Staking is AsyncNonce, StakingStructs {
     /// @dev Price of one staking main token (5083 main token = 1 staking)
     uint256 private constant PRICE_OF_STAKING = 5083 * (10 ** 18);
 
-    /// @dev Address representing the principal Principal Token
-    address private constant PRINCIPAL_TOKEN_ADDRESS =
-        0x0000000000000000000000000000000000000001;
-
     /// @dev Admin address management with proposal system
     AddressTypeProposal private admin;
     /// @dev Golden Fisher address management with proposal system
@@ -91,7 +91,7 @@ contract Staking is AsyncNonce, StakingStructs {
     /// @dev Mapping to store complete staking history for each user
     mapping(address => HistoryMetadata[]) private userHistory;
 
-    IEvvm private evvm;
+    Evvm private evvm;
     IEstimator private estimator;
 
     /// @dev Modifier to verify access to admin functions
@@ -127,8 +127,22 @@ contract Staking is AsyncNonce, StakingStructs {
 
         goldenFisher.actual = initialGoldenFisher;
 
-        allowPublicStaking.flag = false;
-        allowPresaleStaking.flag = true;
+        /**
+         * @dev Because presale staking is disabled by default
+         *      if you want to enable it, you need to do it via
+         *      this admin functions
+         *
+         *      prepareChangeAllowPresaleStaking()
+         *      prepareChangeAllowPublicStaking()
+         *
+         *      wait TIME_TO_ACCEPT_PROPOSAL
+         *
+         *      confirmChangeAllowPresaleStaking()
+         *      confirmChangeAllowPublicStaking()
+         */
+
+        allowPublicStaking.flag = true;
+        allowPresaleStaking.flag = false;
 
         secondsToUnlockStaking.actual = 0;
 
@@ -152,7 +166,7 @@ contract Staking is AsyncNonce, StakingStructs {
         estimatorAddress.actual = _estimator;
         EVVM_ADDRESS = _evvm;
         breakerSetupEstimatorAndEvvm = 0x00;
-        evvm = IEvvm(_evvm);
+        evvm = Evvm(_evvm);
         estimator = IEstimator(_estimator);
     }
 
@@ -204,11 +218,13 @@ contract Staking is AsyncNonce, StakingStructs {
         bool priorityFlag_EVVM,
         bytes memory signature_EVVM
     ) external {
+        if (!allowPresaleStaking.flag || allowPublicStaking.flag)
+            revert ErrorsLib.PresaleStakingDisabled();
+
         if (
-            !SignatureUtils.verifyMessageSignedForStake(
+            !SignatureUtils.verifyMessageSignedForPresaleStake(
                 evvm.getEvvmID(),
                 user,
-                false,
                 isStaking,
                 1,
                 nonce,
@@ -216,12 +232,19 @@ contract Staking is AsyncNonce, StakingStructs {
             )
         ) revert ErrorsLib.InvalidSignatureOnStaking();
 
+        if (!userPresaleStaker[user].isAllow)
+            revert ErrorsLib.UserIsNotPresaleStaker();
+
         verifyAsyncNonce(user, nonce);
 
-        presaleClaims(isStaking, user);
+        uint256 current = userPresaleStaker[user].stakingAmount;
 
-        if (!allowPresaleStaking.flag)
-            revert ErrorsLib.PresaleStakingDisabled();
+        if (isStaking ? current >= 2 : current == 0)
+            revert ErrorsLib.UserPresaleStakerLimitExceeded();
+
+        userPresaleStaker[user].stakingAmount = isStaking
+            ? current + 1
+            : current - 1;
 
         stakingBaseProcess(
             AccountMetadata({Address: user, IsAService: false}),
@@ -236,38 +259,6 @@ contract Staking is AsyncNonce, StakingStructs {
         markAsyncNonceAsUsed(user, nonce);
     }
 
-    /**
-     * @notice Internal function to manage presale staking limits and permissions
-     * @dev Enforces the 2 staking token limit for presale users and tracks staking amounts
-     * @param _isStaking True for staking (increments count), false for unstaking (decrements count)
-     * @param _user Address of the presale user
-     */
-    function presaleClaims(bool _isStaking, address _user) internal {
-        if (allowPublicStaking.flag) {
-            revert ErrorsLib.PresaleStakingDisabled();
-        } else {
-            if (userPresaleStaker[_user].isAllow) {
-                if (_isStaking) {
-                    // staking
-
-                    if (userPresaleStaker[_user].stakingAmount >= 2)
-                        revert ErrorsLib.UserPresaleStakerLimitExceeded();
-
-                    userPresaleStaker[_user].stakingAmount++;
-                } else {
-                    // unstaking
-
-                    if (userPresaleStaker[_user].stakingAmount == 0)
-                        revert ErrorsLib.UserPresaleStakerLimitExceeded();
-
-                    userPresaleStaker[_user].stakingAmount--;
-                }
-            } else {
-                revert ErrorsLib.UserIsNotPresaleStaker();
-            }
-        }
-    }
-
     /**
      * @notice Allows any user to stake/unstake when public staking is enabled
      * @dev Requires signature verification and handles nonce management
@@ -292,15 +283,12 @@ contract Staking is AsyncNonce, StakingStructs {
         bool priorityFlag_EVVM,
         bytes memory signature_EVVM
     ) external {
-        if (!allowPublicStaking.flag) {
-            revert();
-        }
+        if (!allowPublicStaking.flag) revert ErrorsLib.PublicStakingDisabled();
 
         if (
-            !SignatureUtils.verifyMessageSignedForStake(
+            !SignatureUtils.verifyMessageSignedForPublicStake(
                 evvm.getEvvmID(),
                 user,
-                true,
                 isStaking,
                 amountOfStaking,
                 nonce,
@@ -346,11 +334,11 @@ contract Staking is AsyncNonce, StakingStructs {
             amountOfStaking: amountOfStaking,
             amountServiceBeforeStaking: evvm.getBalance(
                 msg.sender,
-                PRINCIPAL_TOKEN_ADDRESS
+                evvm.getPrincipalTokenAddress()
             ),
             amountStakingBeforeStaking: evvm.getBalance(
                 address(this),
-                PRINCIPAL_TOKEN_ADDRESS
+                evvm.getPrincipalTokenAddress()
             )
         });
     }
@@ -372,23 +360,13 @@ contract Staking is AsyncNonce, StakingStructs {
         uint256 totalStakingRequired = PRICE_OF_STAKING *
             serviceStakingData.amountOfStaking;
 
-        uint256 actualServiceBalance = evvm.getBalance(
-            msg.sender,
-            PRINCIPAL_TOKEN_ADDRESS
-        );
-
-        uint256 actualStakingBalance = evvm.getBalance(
-            address(this),
-            PRINCIPAL_TOKEN_ADDRESS
-        );
-
         if (
             serviceStakingData.amountServiceBeforeStaking -
                 totalStakingRequired !=
-            actualServiceBalance &&
+            evvm.getBalance(msg.sender, evvm.getPrincipalTokenAddress()) &&
             serviceStakingData.amountStakingBeforeStaking +
                 totalStakingRequired !=
-            actualStakingBalance
+            evvm.getBalance(address(this), evvm.getPrincipalTokenAddress())
         )
             revert ErrorsLib.ServiceDoesNotFulfillCorrectStakingAmount(
                 totalStakingRequired
@@ -492,8 +470,8 @@ contract Staking is AsyncNonce, StakingStructs {
             if (priorityFee_EVVM != 0 && !account.IsAService)
                 makePay(
                     account.Address,
-                    priorityFee_EVVM,
                     0,
+                    priorityFee_EVVM,
                     priorityFlag_EVVM,
                     nonce_EVVM,
                     signature_EVVM
@@ -506,7 +484,7 @@ contract Staking is AsyncNonce, StakingStructs {
                 amountOfStaking;
 
             makeCaPay(
-                PRINCIPAL_TOKEN_ADDRESS,
+                evvm.getPrincipalTokenAddress(),
                 account.Address,
                 (PRICE_OF_STAKING * amountOfStaking)
             );
@@ -523,12 +501,9 @@ contract Staking is AsyncNonce, StakingStructs {
             })
         );
 
-        if (
-            evvm.isAddressStaker(msg.sender) &&
-            !account.IsAService
-        ) {
+        if (evvm.isAddressStaker(msg.sender) && !account.IsAService) {
             makeCaPay(
-                PRINCIPAL_TOKEN_ADDRESS,
+                evvm.getPrincipalTokenAddress(),
                 msg.sender,
                 (evvm.getRewardAmount() * 2) + priorityFee_EVVM
             );
@@ -578,7 +553,7 @@ contract Staking is AsyncNonce, StakingStructs {
 
                 if (evvm.isAddressStaker(msg.sender)) {
                     makeCaPay(
-                        PRINCIPAL_TOKEN_ADDRESS,
+                        evvm.getPrincipalTokenAddress(),
                         msg.sender,
                         (evvm.getRewardAmount() * 1)
                     );
@@ -613,7 +588,7 @@ contract Staking is AsyncNonce, StakingStructs {
             user,
             address(this),
             "",
-            PRINCIPAL_TOKEN_ADDRESS,
+            evvm.getPrincipalTokenAddress(),
             amount,
             priorityFee,
             nonce,
@@ -648,9 +623,9 @@ contract Staking is AsyncNonce, StakingStructs {
      * @param _staker Address to be added to the presale staker list
      */
     function addPresaleStaker(address _staker) external onlyOwner {
-        if (presaleStakerCount > LIMIT_PRESALE_STAKER) {
-            revert();
-        }
+        if (presaleStakerCount > LIMIT_PRESALE_STAKER)
+            revert ErrorsLib.LimitPresaleStakersExceeded();
+
         userPresaleStaker[_staker].isAllow = true;
         presaleStakerCount++;
     }
@@ -662,9 +637,9 @@ contract Staking is AsyncNonce, StakingStructs {
      */
     function addPresaleStakers(address[] calldata _stakers) external onlyOwner {
         for (uint256 i = 0; i < _stakers.length; i++) {
-            if (presaleStakerCount > LIMIT_PRESALE_STAKER) {
-                revert();
-            }
+            if (presaleStakerCount > LIMIT_PRESALE_STAKER)
+                revert ErrorsLib.LimitPresaleStakersExceeded();
+
             userPresaleStaker[_stakers[i]].isAllow = true;
             presaleStakerCount++;
         }
@@ -694,11 +669,12 @@ contract Staking is AsyncNonce, StakingStructs {
      * @dev Can only be called by the proposed admin after the time delay has passed
      */
     function acceptNewAdmin() external {
-        if (
-            msg.sender != admin.proposal || admin.timeToAccept > block.timestamp
-        ) {
-            revert();
-        }
+        if (msg.sender != admin.proposal)
+            revert ErrorsLib.SenderIsNotProposedAdmin();
+
+        if (admin.timeToAccept > block.timestamp)
+            revert ErrorsLib.TimeToAcceptProposalNotReached();
+
         admin.actual = admin.proposal;
         admin.proposal = address(0);
         admin.timeToAccept = 0;
@@ -728,9 +704,9 @@ contract Staking is AsyncNonce, StakingStructs {
      * @dev Can only be called by the current admin after the 1-day time delay
      */
     function acceptNewGoldenFisher() external onlyOwner {
-        if (goldenFisher.timeToAccept > block.timestamp) {
-            revert();
-        }
+        if (goldenFisher.timeToAccept > block.timestamp)
+            revert ErrorsLib.TimeToAcceptProposalNotReached();
+
         goldenFisher.actual = goldenFisher.proposal;
         goldenFisher.proposal = address(0);
         goldenFisher.timeToAccept = 0;
@@ -764,9 +740,9 @@ contract Staking is AsyncNonce, StakingStructs {
      * @dev Can only be called by the current admin after the 1-day time delay
      */
     function acceptSetSecondsToUnlockStaking() external onlyOwner {
-        if (secondsToUnlockStaking.timeToAccept > block.timestamp) {
-            revert();
-        }
+        if (secondsToUnlockStaking.timeToAccept > block.timestamp)
+            revert ErrorsLib.TimeToAcceptProposalNotReached();
+
         secondsToUnlockStaking.actual = secondsToUnlockStaking.proposal;
         secondsToUnlockStaking.proposal = 0;
         secondsToUnlockStaking.timeToAccept = 0;
@@ -800,9 +776,9 @@ contract Staking is AsyncNonce, StakingStructs {
      * @dev Can only be called by the current admin after the 1-day time delay
      */
     function confirmSetSecondsToUnllockFullUnstaking() external onlyOwner {
-        if (secondsToUnllockFullUnstaking.timeToAccept > block.timestamp) {
-            revert();
-        }
+        if (secondsToUnllockFullUnstaking.timeToAccept > block.timestamp)
+            revert ErrorsLib.TimeToAcceptProposalNotReached();
+
         secondsToUnllockFullUnstaking.actual = secondsToUnllockFullUnstaking
             .proposal;
         secondsToUnllockFullUnstaking.proposal = 0;
@@ -832,9 +808,9 @@ contract Staking is AsyncNonce, StakingStructs {
      * @dev Toggles between enabled/disabled state for public staking after 1-day delay
      */
     function confirmChangeAllowPublicStaking() external onlyOwner {
-        if (allowPublicStaking.timeToAccept > block.timestamp) {
-            revert();
-        }
+        if (allowPublicStaking.timeToAccept > block.timestamp)
+            revert ErrorsLib.TimeToAcceptProposalNotReached();
+
         allowPublicStaking = BoolTypeProposal({
             flag: !allowPublicStaking.flag,
             timeToAccept: 0
@@ -864,13 +840,11 @@ contract Staking is AsyncNonce, StakingStructs {
      * @dev Toggles between enabled/disabled state for presale staking after 1-day delay
      */
     function confirmChangeAllowPresaleStaking() external onlyOwner {
-        if (allowPresaleStaking.timeToAccept > block.timestamp) {
-            revert();
-        }
-        allowPresaleStaking = BoolTypeProposal({
-            flag: !allowPresaleStaking.flag,
-            timeToAccept: 0
-        });
+        if (allowPresaleStaking.timeToAccept > block.timestamp)
+            revert ErrorsLib.TimeToAcceptProposalNotReached();
+
+        allowPresaleStaking.flag = !allowPresaleStaking.flag;
+        allowPresaleStaking.timeToAccept = 0;
     }
 
     /**
@@ -880,7 +854,9 @@ contract Staking is AsyncNonce, StakingStructs {
      */
     function proposeEstimator(address _estimator) external onlyOwner {
         estimatorAddress.proposal = _estimator;
-        estimatorAddress.timeToAccept = block.timestamp + TIME_TO_ACCEPT_PROPOSAL;
+        estimatorAddress.timeToAccept =
+            block.timestamp +
+            TIME_TO_ACCEPT_PROPOSAL;
     }
 
     /**
@@ -897,9 +873,9 @@ contract Staking is AsyncNonce, StakingStructs {
      * @dev Can only be called by the current admin after the 1-day time delay
      */
     function acceptNewEstimator() external onlyOwner {
-        if (estimatorAddress.timeToAccept > block.timestamp) {
-            revert();
-        }
+        if (estimatorAddress.timeToAccept > block.timestamp)
+            revert ErrorsLib.TimeToAcceptProposalNotReached();
+
         estimatorAddress.actual = estimatorAddress.proposal;
         estimatorAddress.proposal = address(0);
         estimatorAddress.timeToAccept = 0;
@@ -1104,7 +1080,7 @@ contract Staking is AsyncNonce, StakingStructs {
      * @dev Includes current flag state and any pending changes with timestamps
      * @return BoolTypeProposal struct containing flag and timeToAccept
      */
-    function getAllDataOfAllowPublicStaking()
+    function getAllowPublicStaking()
         external
         view
         returns (BoolTypeProposal memory)
@@ -1125,6 +1101,15 @@ contract Staking is AsyncNonce, StakingStructs {
         return allowPresaleStaking;
     }
 
+    /**
+     * @notice Gets the unique identifier string for this EVVM instance
+     * @dev Returns the EvvmID used for distinguishing different EVVM deployments
+     * @return Unique EvvmID string
+     */
+    function getEvvmID() external view returns (uint256) {
+        return evvm.getEvvmID();
+    }
+
     /**
      * @notice Returns the address of the EVVM core contract
      * @dev The EVVM contract handles payments and staker registration
@@ -1139,8 +1124,8 @@ contract Staking is AsyncNonce, StakingStructs {
      * @dev This is a constant address used to represent the principal token
      * @return Address representing the Principal Token (0x...0001)
      */
-    function getMateAddress() external pure returns (address) {
-        return PRINCIPAL_TOKEN_ADDRESS;
+    function getMateAddress() external view returns (address) {
+        return evvm.getPrincipalTokenAddress();
     }
 
     /**

package/contracts/staking/lib/ErrorsLib.sol

@@ -2,21 +2,97 @@
 // Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
 
 pragma solidity ^0.8.0;
+/**
+ * @title ErrorsLib
+ * @author Mate Labs
+ * @notice Library containing all custom error definitions for the Staking contract
+ * @dev This library is exclusive to the Staking.sol contract and provides descriptive
+ * error types for better gas efficiency and debugging compared to revert strings.
+ *
+ * Error Categories:
+ * - Access Control: Permission and authorization errors
+ * - Signature Verification: EIP-191 signature validation errors
+ * - Presale Staking: Presale-specific staking limitations
+ * - Public Staking: General staking state errors
+ * - Service Staking: Smart contract (service) staking errors
+ * - Time Lock: Time-delayed governance and cooldown errors
+ */
 
 library ErrorsLib {
+    ///▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+    /// Access Control Errors
+    /// ▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+
+    /// @dev Thrown when a non-admin address attempts to call an admin-only function
     error SenderIsNotAdmin();
+
+    /// @dev Thrown when a non-golden-fisher address attempts to call a golden fisher function
     error SenderIsNotGoldenFisher();
+
+    /// @dev Thrown when a non-proposed-admin address attempts to accept an admin proposal
+    error SenderIsNotProposedAdmin();
+
+    ///▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+    /// Signature Verification Errors
+    ///▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+
+    /// @dev Thrown when EIP-191 signature verification fails for a staking operation
     error InvalidSignatureOnStaking();
+
+    /// @dev Thrown when attempting to use a nonce that has already been consumed
     error StakingNonceAlreadyUsed();
+
+    ///▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+    /// Presale Staking Errors
+    ///▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+
+    /// @dev Thrown when presale staking is attempted while disabled or when public staking is active
     error PresaleStakingDisabled();
+
+    /// @dev Thrown when a presale user tries to stake more than the 2-staking limit
     error UserPresaleStakerLimitExceeded();
+
+    /// @dev Thrown when a non-presale-registered address attempts presale staking
     error UserIsNotPresaleStaker();
+
+    /// @dev Thrown when attempting to add more presale stakers beyond the 800 limit
+    error LimitPresaleStakersExceeded();
+
+    ///▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+    /// Public Staking Errors
+    ///▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+
+    /// @dev Thrown when public staking is attempted while the feature is disabled
     error PublicStakingDisabled();
+
+    ///Service Staking Errors
+
+    /// @dev Thrown when a non-contract address attempts to call a service-only function
     error AddressIsNotAService();
+
+    /// @dev Thrown when the user address doesn't match the service address in staking metadata
     error UserAndServiceMismatch();
-    error AddressMustWaitToStakeAgain();
-    error AddressMustWaitToFullUnstake();
+
+    /// @dev Thrown when confirmServiceStaking is called by a different address than prepareServiceStaking
+    error AddressMismatch();
+
+    /// @dev Thrown when the payment amount doesn't match the required staking cost
+    /// @param requiredAmount The exact amount of Principal Tokens that should have been transferred
     error ServiceDoesNotFulfillCorrectStakingAmount(uint256 requiredAmount);
+
+    /// @dev Thrown when confirmServiceStaking is not called in the same transaction as prepareServiceStaking
     error ServiceDoesNotStakeInSameTx();
-    error AddressMismatch();
+
+    ///▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+    /// Time Lock Errors
+    ///▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀▄▀
+
+    /// @dev Thrown when a user attempts to stake before their cooldown period expires
+    error AddressMustWaitToStakeAgain();
+
+    /// @dev Thrown when a user attempts full unstaking before the 21-day lock period expires
+    error AddressMustWaitToFullUnstake();
+
+    /// @dev Thrown when attempting to accept a proposal before the time delay has passed
+    error TimeToAcceptProposalNotReached();
 }

package/contracts/staking/lib/SignatureUtils.sol

@@ -1,39 +1,105 @@
 // SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
 // Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
 pragma solidity ^0.8.0;
+/**
+ * @title SignatureUtils
+ * @author Mate Labs
+ * @notice Library for EIP-191 signature verification in the Staking contract
+ * @dev This library is exclusive to the Staking.sol contract and provides
+ * functions to verify signatures for staking operations.
+ *
+ * Signature Format:
+ * All signatures follow the EIP-191 standard with message format:
+ * "[evvmID],[functionName],[isStaking],[amountOfStaking],[nonce]"
+ *
+ * Supported Operations:
+ * - Presale staking: Limited staking for pre-approved addresses
+ * - Public staking: Open staking for all users when enabled
+ */
 
-import {SignatureUtil} from "@evvm/testnet-contracts/library/utils/SignatureUtil.sol";
-import {AdvancedStrings} from "@evvm/testnet-contracts/library/utils/AdvancedStrings.sol";
+import {
+    SignatureUtil
+} from "@evvm/testnet-contracts/library/utils/SignatureUtil.sol";
+import {
+    AdvancedStrings
+} from "@evvm/testnet-contracts/library/utils/AdvancedStrings.sol";
 
 library SignatureUtils {
     /**
-     *  @dev using EIP-191 (https://eips.ethereum.org/EIPS/eip-191) can be used to sign and
-     *       verify messages, the next functions are used to verify the messages signed
-     *       by the users
+     * @dev Uses EIP-191 (https://eips.ethereum.org/EIPS/eip-191) for message signing
+     *      and verification. The following functions verify messages signed by users
+     *      for staking operations.
      */
 
-    function verifyMessageSignedForStake(
+    /**
+     * @notice Verifies an EIP-191 signature for presale staking operations
+     * @dev Message format: "[evvmID],presaleStaking,[isStaking],[amountOfStaking],[nonce]"
+     *      Presale staking has a limit of 2 staking tokens per user
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param signer Address that should have signed the message
+     * @param isStaking True for staking operation, false for unstaking
+     * @param amountOfStaking Amount of staking tokens (always 1 for presale)
+     * @param nonce Unique nonce to prevent replay attacks
+     * @param signature 65-byte EIP-191 signature to verify
+     * @return True if the signature is valid and matches the expected signer
+     */
+    function verifyMessageSignedForPresaleStake(
+        uint256 evvmID,
+        address signer,
+        bool isStaking,
+        uint256 amountOfStaking,
+        uint256 nonce,
+        bytes memory signature
+    ) internal pure returns (bool) {
+        return
+            SignatureUtil.verifySignature(
+                evvmID,
+                "presaleStaking",
+                string.concat(
+                    AdvancedStrings.boolToString(isStaking),
+                    ",",
+                    AdvancedStrings.uintToString(amountOfStaking),
+                    ",",
+                    AdvancedStrings.uintToString(nonce)
+                ),
+                signature,
+                signer
+            );
+    }
+
+    /**
+     * @notice Verifies an EIP-191 signature for public staking operations
+     * @dev Message format: "[evvmID],publicStaking,[isStaking],[amountOfStaking],[nonce]"
+     *      Public staking is available to all users when the feature is enabled
+     * @param evvmID Unique identifier of the EVVM instance
+     * @param signer Address that should have signed the message
+     * @param isStaking True for staking operation, false for unstaking
+     * @param amountOfStaking Amount of staking tokens to stake/unstake
+     * @param nonce Unique nonce to prevent replay attacks
+     * @param signature 65-byte EIP-191 signature to verify
+     * @return True if the signature is valid and matches the expected signer
+     */
+    function verifyMessageSignedForPublicStake(
         uint256 evvmID,
-        address user,
-        bool isExternalStaking,
-        bool _isStaking,
-        uint256 _amountOfStaking,
-        uint256 _nonce,
+        address signer,
+        bool isStaking,
+        uint256 amountOfStaking,
+        uint256 nonce,
         bytes memory signature
     ) internal pure returns (bool) {
         return
             SignatureUtil.verifySignature(
                 evvmID,
-                isExternalStaking ? "publicStaking" : "presaleStaking",
+                "publicStaking",
                 string.concat(
-                    _isStaking ? "true" : "false",
+                    AdvancedStrings.boolToString(isStaking),
                     ",",
-                    AdvancedStrings.uintToString(_amountOfStaking),
+                    AdvancedStrings.uintToString(amountOfStaking),
                     ",",
-                    AdvancedStrings.uintToString(_nonce)
+                    AdvancedStrings.uintToString(nonce)
                 ),
                 signature,
-                user
+                signer
             );
     }
 }

package/contracts/staking/lib/StakingStructs.sol

@@ -2,6 +2,18 @@
 // Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
 
 pragma solidity ^0.8.0;
+/**
+ * @title StakingStructs
+ * @author Mate Labs
+ * @notice Abstract contract containing all data structures used by the Staking contract
+ * @dev This contract is exclusive to the Staking.sol contract and defines the data
+ * structures for managing staking operations, governance proposals, and user history.
+ *
+ * Structure Categories:
+ * - Staker Metadata: presaleStakerMetadata, HistoryMetadata
+ * - Governance Proposals: AddressTypeProposal, UintTypeProposal, BoolTypeProposal
+ * - Service Staking: ServiceStakingMetadata, AccountMetadata
+ */
 
 abstract contract StakingStructs {
     /**