feat(contracts): unstaking period choice

Author: mattstam

contracts/src/SuccinctStaking.sol

@@ -3,7 +3,7 @@ pragma solidity ^0.8.28;
 
 import {ProverRegistry} from "./libraries/ProverRegistry.sol";
 import {StakedSuccinct} from "./tokens/StakedSuccinct.sol";
-import {ISuccinctStaking} from "./interfaces/ISuccinctStaking.sol";
+import {UnstakePeriod, ISuccinctStaking} from "./interfaces/ISuccinctStaking.sol";
 import {IIntermediateSuccinct} from "./interfaces/IIntermediateSuccinct.sol";
 import {IProver} from "./interfaces/IProver.sol";
 import {SuccinctGovernor} from "./SuccinctGovernor.sol";
@@ -48,8 +48,8 @@ contract SuccinctStaking is
     /// @inheritdoc ISuccinctStaking
     uint256 public override maxUnstakeRequests;
 
-    /// @inheritdoc ISuccinctStaking
-    uint256 public override unstakePeriod;
+    /// @dev The old global unstake period.
+    uint256 private deprecatedUnstakePeriod;
 
     /// @inheritdoc ISuccinctStaking
     uint256 public override slashCancellationPeriod;
@@ -81,6 +81,9 @@ contract SuccinctStaking is
     /// @dev A mapping from prover to their unstaking escrow pool.
     mapping(address => EscrowPool) internal escrowPools;
 
+    /// @inheritdoc ISuccinctStaking
+    mapping(address => UnstakePeriod) public override unstakePeriodChoice;
+
     /*//////////////////////////////////////////////////////////////
                                 MODIFIER
     //////////////////////////////////////////////////////////////*/
@@ -110,7 +113,6 @@ contract SuccinctStaking is
         address _dispenser,
         uint256 _minStakeAmount,
         uint256 _maxUnstakeRequests,
-        uint256 _unstakePeriod,
         uint256 _slashCancellationPeriod
     ) external initializer {
         // Ensure that parameters critical for functionality are non-zero.
@@ -121,7 +123,6 @@ contract SuccinctStaking is
         _requireNonZeroAddress(_intermediateProve);
         _requireNonZeroAddress(_dispenser);
         _requireNonZeroNumber(_maxUnstakeRequests);
-        _requireNonZeroNumber(_unstakePeriod);
         _requireNonZeroNumber(_slashCancellationPeriod);
 
         // Setup the initial state.
@@ -132,7 +133,6 @@ contract SuccinctStaking is
         dispenser = _dispenser;
         minStakeAmount = _minStakeAmount;
         maxUnstakeRequests = _maxUnstakeRequests;
-        unstakePeriod = _unstakePeriod;
         slashCancellationPeriod = _slashCancellationPeriod;
 
         // Approve the $iPROVE contract to transfer $PROVE from this contract during stake().
@@ -241,7 +241,7 @@ contract SuccinctStaking is
     //////////////////////////////////////////////////////////////*/
 
     /// @inheritdoc ISuccinctStaking
-    function stake(address _prover, uint256 _PROVE)
+    function stake(address _prover, uint256 _PROVE, UnstakePeriod _unstakePeriod)
         external
         override
         onlyForProver(_prover)
@@ -250,7 +250,7 @@ contract SuccinctStaking is
         // Transfer $PROVE from the staker to this contract.
         IERC20(prove).safeTransferFrom(msg.sender, address(this), _PROVE);
 
-        return _stake(msg.sender, _prover, _PROVE);
+        return _stake(msg.sender, _prover, _PROVE, _unstakePeriod);
     }
 
     /// @inheritdoc ISuccinctStaking
@@ -261,7 +261,8 @@ contract SuccinctStaking is
         uint256 _deadline,
         uint8 _v,
         bytes32 _r,
-        bytes32 _s
+        bytes32 _s,
+        UnstakePeriod _unstakePeriod
     ) external override onlyForProver(_prover) returns (uint256) {
         // If the $PROVE allowance is not equal to the amount being staked, permit the prover to
         // spend the $PROVE from the staker.
@@ -273,7 +274,7 @@ contract SuccinctStaking is
         // spender.
         IProver(_prover).transferProveToStaking(_from, _PROVE);
 
-        return _stake(_from, _prover, _PROVE);
+        return _stake(_from, _prover, _PROVE, _unstakePeriod);
     }
 
     /// @inheritdoc ISuccinctStaking
@@ -335,8 +336,11 @@ contract SuccinctStaking is
         // Check that this prover is not in the process of being slashed.
         _requireProverWithoutSlashRequests(prover);
 
+        // Get the staker's unstake period choice.
+        UnstakePeriod unstakePeriod = unstakePeriodChoice[_staker];
+
         // Process the available unstake claims.
-        PROVE += _finishUnstake(_staker, prover, claims);
+        PROVE += _finishUnstake(_staker, prover, claims, unstakePeriod);
 
         // Reset the slash factor if all $iPROVE has been removed.
         EscrowPool storage pool = escrowPools[prover];
@@ -345,11 +349,15 @@ contract SuccinctStaking is
         }
 
         // If the staker has no remaining balance and no pending unstakes, remove the staker's
-        // delegate. This allows them to choose a different prover if they stake again.
+        // delegate and reset their unstake period choice. This allows them to choose a different
+        // prover if they stake again.
         if (balanceOf(_staker) == 0 && claims.length == 0) {
             // Remove the staker's prover delegation.
             stakerToProver[_staker] = address(0);
 
+            // Remove the staker's unstake period choice.
+            unstakePeriodChoice[_staker] = UnstakePeriod.UNSPECIFIED;
+
             emit ProverUnbound(_staker, prover);
         }
     }
@@ -526,7 +534,7 @@ contract SuccinctStaking is
 
     /// @dev Deposit a staker's $PROVE to mint $iPROVE, then deposit $iPROVE to mint $PROVER-N, and
     ///      then directly mint $stPROVE to the staker, which acts as the receipt token for staking.
-    function _stake(address _staker, address _prover, uint256 _PROVE)
+    function _stake(address _staker, address _prover, uint256 _PROVE, UnstakePeriod _unstakePeriod)
         internal
         stakingOperation
         returns (uint256 stPROVE)
@@ -543,6 +551,15 @@ contract SuccinctStaking is
         // Check that this prover is not in the process of being slashed.
         _requireProverWithoutSlashRequests(_prover);
 
+        // If the staker has not set a unstake period choice, set it to their choice. If they have
+        // already set a choice, ensure it matches their choice.
+        UnstakePeriod existingUnstakePeriod = unstakePeriodChoice[_staker];
+        if (existingUnstakePeriod == UnstakePeriod.UNSPECIFIED) {
+            unstakePeriodChoice[_staker] = _unstakePeriod;
+        } else if (existingUnstakePeriod != _unstakePeriod) {
+            revert AlreadySetUnstakePeriod(existingUnstakePeriod);
+        }
+
         // Ensure the staker is not already staked with a different prover.
         address existingProver = stakerToProver[_staker];
         if (existingProver != address(0) && existingProver != _prover) {
@@ -553,7 +570,7 @@ contract SuccinctStaking is
         if (existingProver == address(0)) {
             stakerToProver[_staker] = _prover;
 
-            emit ProverBound(_staker, _prover);
+            emit ProverBound(_staker, _prover, _unstakePeriod);
         }
 
         // Deposit $PROVE to mint $iPROVE, sending it to this contract.
@@ -620,13 +637,15 @@ contract SuccinctStaking is
 
     /// @dev Iterate over the unstake claims, processing each one that has passed the unstake
     ///      period.
-    function _finishUnstake(address _staker, address _prover, UnstakeClaim[] storage _claims)
-        internal
-        returns (uint256 PROVE)
-    {
+    function _finishUnstake(
+        address _staker,
+        address _prover,
+        UnstakeClaim[] storage _claims,
+        UnstakePeriod _unstakePeriod
+    ) internal returns (uint256 PROVE) {
         uint256 i = 0;
         while (i < _claims.length) {
-            if (block.timestamp >= _claims[i].timestamp + unstakePeriod) {
+            if (block.timestamp >= _claims[i].timestamp + _unstakePeriodToSeconds(_unstakePeriod)) {
                 // Store claim before modifying the array.
                 UnstakeClaim memory claim = _claims[i];
 
@@ -678,6 +697,20 @@ contract SuccinctStaking is
         if (slashClaimCount[_prover] > 0) revert ProverHasSlashRequest();
     }
 
+    /// @dev Converts a UnstakePeriod enum to a number of seconds. Defaults to 14 days if the
+    ///      unstake period is unspecified, which is relevant for backward compatibility.
+    function _unstakePeriodToSeconds(UnstakePeriod _unstakePeriod)
+        internal
+        pure
+        returns (uint256)
+    {
+        if (_unstakePeriod == UnstakePeriod.TWENTY_FOUR_MONTHS) return 730 days;
+        if (_unstakePeriod == UnstakePeriod.TWELVE_MONTHS) return 365 days;
+        if (_unstakePeriod == UnstakePeriod.SIX_MONTHS) return 183 days;
+        if (_unstakePeriod == UnstakePeriod.FOURTEEN_DAYS) return 14 days;
+        return 14 days;
+    }
+
     /// @dev Authorizes an ERC1967 proxy upgrade to a new implementation contract.
     function _authorizeUpgrade(address _newImplementation) internal override onlyOwner {}
 }

contracts/src/interfaces/ISuccinctStaking.sol

@@ -3,6 +3,16 @@ pragma solidity ^0.8.28;
 
 import {IProverRegistry} from "./IProverRegistry.sol";
 
+/// @dev Represents the period that a staker must wait before finishing unstaking from their
+///      prover.
+enum UnstakePeriod {
+    UNSPECIFIED,
+    FOURTEEN_DAYS,
+    SIX_MONTHS,
+    TWELVE_MONTHS,
+    TWENTY_FOUR_MONTHS
+}
+
 interface ISuccinctStaking is IProverRegistry {
     /// @dev Represents a claim for unstaking.
     /// @param iPROVEEscrow The escrowed amount of $iPROVE at request time.
@@ -38,7 +48,7 @@ interface ISuccinctStaking is IProverRegistry {
 
     /// @dev Emitted when a staker first stakes to their delegated prover. This indicates that any
     ///      additional stake from the staker can only be added to this prover, unless unbound.
-    event ProverBound(address indexed staker, address indexed prover);
+    event ProverBound(address indexed staker, address indexed prover, UnstakePeriod unstakePeriod);
 
     /// @dev Emitted when a staker fully unstakes from their delegated prover. This indicates that
     ///      the staker can now stake to a different prover.
@@ -105,6 +115,10 @@ interface ISuccinctStaking is IProverRegistry {
     /// @dev Thrown if the staker tries to deposit while already staked with a different prover.
     error AlreadyStakedWithDifferentProver(address existingProver);
 
+    /// @dev Thrown if the staker tries to stake with a different unstake period choice than they
+    ///      have already set.
+    error AlreadySetUnstakePeriod(UnstakePeriod existingUnstakePeriod);
+
     /// @dev Thrown if staking or unstaking while the prover has one or more pending slash requests.
     error ProverHasSlashRequest();
 
@@ -138,12 +152,6 @@ interface ISuccinctStaking is IProverRegistry {
     ///      Immutable after deployment.
     function maxUnstakeRequests() external view returns (uint256);
 
-    /// @notice The minimum delay (in seconds) for an unstake request be finished.
-    /// @dev Ensures that a staker cannot frontrun an upcoming prover slash by unstaking early.
-    ///      Should be greater than the longest length that a VApp `step` can be delayed by.
-    ///      Immutable after deployment.
-    function unstakePeriod() external view returns (uint256);
-
     /// @notice The minimum delay (in seconds), plus governance parameters, for a slash request
     ///         to be cancelled.
     /// @dev Cancelling a slash requires `slashCancellationPeriod` + `votingDelay` +
@@ -217,14 +225,22 @@ interface ISuccinctStaking is IProverRegistry {
     /// @return The maximum amount of $PROVE available to dispense.
     function maxDispense() external view returns (uint256);
 
+    /// @notice The unstake period choice for a staker.
+    /// @param staker The address of the staker.
+    /// @return The unstake period choice.
+    function unstakePeriodChoice(address staker) external view returns (UnstakePeriod);
+
     /// @notice Stake $PROVE to a prover. Must have approved $PROVE with this contract as the
     ///         spender. You may only stake to one prover at a time.
     /// @dev Deposits $PROVE into the iPROVE vault to mint $iPROVE, then deposits $iPROVE into the
     ///      chosen prover to mint $PROVER-N/$stPROVE.
     /// @param prover The address of the prover to delegate $iPROVE to.
     /// @param PROVE The amount of $PROVE to deposit.
+    /// @param unstakePeriod The period that the staker must wait before finishing unstaking.
     /// @return The amount of $stPROVE received.
-    function stake(address prover, uint256 PROVE) external returns (uint256);
+    function stake(address prover, uint256 PROVE, UnstakePeriod unstakePeriod)
+        external
+        returns (uint256);
 
     /// @notice Stake $PROVE to a prover. You may only stake to one prover at a time.
     /// @dev Deposits $PROVE to mint $iPROVE, then deposits $iPROVE into the chosen
@@ -239,6 +255,7 @@ interface ISuccinctStaking is IProverRegistry {
     /// @param v The v component of the permit signature.
     /// @param r The r component of the permit signature.
     /// @param s The s component of the permit signature.
+    /// @param unstakePeriod The period that the staker must wait before finishing unstaking.
     /// @return The amount of $stPROVE the staker received.
     function permitAndStake(
         address prover,
@@ -247,7 +264,8 @@ interface ISuccinctStaking is IProverRegistry {
         uint256 deadline,
         uint8 v,
         bytes32 r,
-        bytes32 s
+        bytes32 s,
+        UnstakePeriod unstakePeriod
     ) external returns (uint256);
 
     /// @notice Creates a request to unstake $stPROVE from the prover for the specified amount. Only