fix: document possible temporary thaw requests blockage when thawing period is shortened (OZ L-02)

Signed-off-by: Tomás Migone <[email protected]>

Author: tmigone

packages/horizon/contracts/data-service/extensions/DataServiceFees.sol

@@ -63,6 +63,9 @@ abstract contract DataServiceFees is DataService, DataServiceFeesV1Storage, IDat
     /**
      * @notice Releases expired stake claims for a service provider.
      * @dev This function can be overriden and/or disabled.
+     * @dev Note that the list is traversed by creation date not by releasableAt date. Traversing will stop
+     * when the first stake claim that is not yet expired is found even if later stake claims have expired. This
+     * could happen if stake claims are genereted with different unlock periods.
      * @dev Emits a {StakeClaimsReleased} event, and a {StakeClaimReleased} event for each claim released.
      * @param _serviceProvider The address of the service provider
      * @param _numClaimsToRelease Amount of stake claims to process. If 0, all stake claims are processed.

packages/horizon/contracts/interfaces/internal/IHorizonStakingBase.sol

@@ -169,7 +169,11 @@ interface IHorizonStakingBase {
     ) external view returns (LinkedList.List memory);
 
     /**
-     * @notice Gets the amount of thawed tokens for a given provision.
+     * @notice Gets the amount of thawed tokens that can be releasedfor a given provision.
+     * @dev Note that the value returned by this function does not return the total amount of thawed tokens
+     * but only those that can be released. If thaw requests are created with different thawing periods it's 
+     * possible that an unexpired thaw request temporarily blocks the release of other ones that have already 
+     * expired. This function will stop counting when it encounters the first thaw request that is not yet expired.
      * @param thawRequestType The type of thaw request.
      * @param serviceProvider The address of the service provider.
      * @param verifier The address of the verifier.

packages/horizon/contracts/interfaces/internal/IHorizonStakingMain.sol

@@ -659,7 +659,8 @@ interface IHorizonStakingMain {
     /**
      * @notice Remove tokens from a provision and move them back to the service provider's idle stake.
      * @dev The parameter `nThawRequests` can be set to a non zero value to fulfill a specific number of thaw
-     * requests in the event that fulfilling all of them results in a gas limit error.
+     * requests in the event that fulfilling all of them results in a gas limit error. Otherwise, the function
+     * will attempt to fulfill all thaw requests until the first one that is not yet expired is found.
      *
      * Requirements:
      * - Must have previously initiated a thaw request using {thaw}.
@@ -783,7 +784,8 @@ interface IHorizonStakingMain {
     /**
      * @notice Withdraw undelegated tokens from a provision after thawing.
      * @dev The parameter `nThawRequests` can be set to a non zero value to fulfill a specific number of thaw
-     * requests in the event that fulfilling all of them results in a gas limit error.
+     * requests in the event that fulfilling all of them results in a gas limit error. Otherwise, the function
+     * will attempt to fulfill all thaw requests until the first one that is not yet expired is found.
      * @dev If the delegation pool was completely slashed before withdrawing, calling this function will fulfill
      * the thaw requests with an amount equal to zero.
      *

packages/horizon/contracts/staking/HorizonStaking.sol

@@ -800,7 +800,8 @@ contract HorizonStaking is HorizonStakingBase, IHorizonStakingMain {
     /**
      * @notice Remove tokens from a provision and move them back to the service provider's idle stake.
      * @dev The parameter `nThawRequests` can be set to a non zero value to fulfill a specific number of thaw
-     * requests in the event that fulfilling all of them results in a gas limit error.
+     * requests in the event that fulfilling all of them results in a gas limit error. Otherwise, the function
+     * will attempt to fulfill all thaw requests until the first one that is not yet expired is found.
      * @param _serviceProvider The service provider address
      * @param _verifier The verifier address
      * @param _nThawRequests The number of thaw requests to fulfill. Set to 0 to fulfill all thaw requests.
@@ -956,7 +957,8 @@ contract HorizonStaking is HorizonStakingBase, IHorizonStakingMain {
     /**
      * @notice Withdraw undelegated tokens from a provision after thawing.
      * @dev The parameter `nThawRequests` can be set to a non zero value to fulfill a specific number of thaw
-     * requests in the event that fulfilling all of them results in a gas limit error.
+     * requests in the event that fulfilling all of them results in a gas limit error. Otherwise, the function
+     * will attempt to fulfill all thaw requests until the first one that is not yet expired is found.
      * @dev If the delegation pool was completely slashed before withdrawing, calling this function will fulfill
      * the thaw requests with an amount equal to zero.
      * @param _requestType The type of thaw request (Provision or Delegation).
@@ -1073,6 +1075,9 @@ contract HorizonStaking is HorizonStakingBase, IHorizonStakingMain {
 
     /**
      * @notice Traverses a thaw request list and fulfills expired thaw requests.
+     * @dev Note that the list is traversed by creation date not by thawing until date. Traversing will stop
+     * when the first thaw request that is not yet expired is found even if later thaw requests have expired. This
+     * could happen for example when the thawing period is shortened.
      * @param _params The parameters for fulfilling thaw requests
      * @return The amount of thawed tokens
      * @return The amount of tokens still thawing