From 2a131ca23da6f8b731c2d260b1e3e931cadc9f12 Mon Sep 17 00:00:00 2001
From: Miguel de Elias <miguel.deelias@gmail.com>
Date: Fri, 23 Aug 2024 14:03:47 -0300
Subject: [PATCH] fix: missing or incorrect documentation (OZ L-08)

---
 .../contracts/interfaces/internal/IHorizonStakingMain.sol | 8 ++++----
 .../interfaces/internal/IHorizonStakingTypes.sol          | 4 ++--
 packages/horizon/contracts/libraries/PPMMath.sol          | 4 +++-
 .../subgraph-service/contracts/libraries/Allocation.sol   | 2 +-
 .../subgraph-service/contracts/libraries/Attestation.sol  | 3 +++
 5 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/packages/horizon/contracts/interfaces/internal/IHorizonStakingMain.sol b/packages/horizon/contracts/interfaces/internal/IHorizonStakingMain.sol
index 52dc62339..bbbfa07b6 100644
--- a/packages/horizon/contracts/interfaces/internal/IHorizonStakingMain.sol
+++ b/packages/horizon/contracts/interfaces/internal/IHorizonStakingMain.sol
@@ -514,9 +514,10 @@ interface IHorizonStakingMain {
      * This function can be called by the service provider or by an operator authorized by the provider
      * for this specific verifier.
      * @dev Requirements:
-     * - `tokens` cannot be zero and must be over the data service minimum required.
-     * - Provision parameters must be within the range allowed by the verifier (`maxVerifierCut` and `thawingPeriod`)
+     * - `tokens` cannot be zero.
      * - The `serviceProvider` must have enough idle stake to cover the tokens to provision.
+     * - `maxVerifierCut` must be less than or equal to `MAX_MAX_VERIFIER_CUT`.
+     * - `thawingPeriod` must be less than or equal to `_maxThawingPeriod`.
      *
      * Emits a {ProvisionCreated} event.
      *
@@ -688,7 +689,6 @@ interface IHorizonStakingMain {
      * - Then after the thawing period, the tokens are removed from the provision using {withdrawDelegated}.
      *
      * Requirements:
-     * - Must have previously initiated a thaw request using {undelegate}.
      * - `shares` cannot be zero.
      *
      * Emits a {TokensUndelegated} and {ThawRequestCreated} event.
@@ -822,7 +822,7 @@ interface IHorizonStakingMain {
     ) external;
 
     /**
-     * @notice Authorize or unauthorize an address to be an operator for the caller on a data service.
+     * @notice Authorize or unauthorize an address to be an operator for the caller on a verifier.
      *
      * @dev See {setOperator}.
      * Additional requirements:
diff --git a/packages/horizon/contracts/interfaces/internal/IHorizonStakingTypes.sol b/packages/horizon/contracts/interfaces/internal/IHorizonStakingTypes.sol
index c0d6892b3..5c2f3f5e7 100644
--- a/packages/horizon/contracts/interfaces/internal/IHorizonStakingTypes.sol
+++ b/packages/horizon/contracts/interfaces/internal/IHorizonStakingTypes.sol
@@ -85,9 +85,9 @@ interface IHorizonStakingTypes {
     struct DelegationPoolInternal {
         // (Deprecated) Time, in blocks, an indexer must wait before updating delegation parameters
         uint32 __DEPRECATED_cooldownBlocks;
-        // (Deprecated) Percentage of indexing rewards for the delegation pool, in PPM
+        // (Deprecated) Percentage of indexing rewards for the service provider, in PPM
         uint32 __DEPRECATED_indexingRewardCut;
-        // (Deprecated) Percentage of query fees for the delegation pool, in PPM
+        // (Deprecated) Percentage of query fees for the service provider, in PPM
         uint32 __DEPRECATED_queryFeeCut;
         // (Deprecated) Block when the delegation parameters were last updated
         uint256 __DEPRECATED_updatedAtBlock;
diff --git a/packages/horizon/contracts/libraries/PPMMath.sol b/packages/horizon/contracts/libraries/PPMMath.sol
index 1496be4d8..e992e8831 100644
--- a/packages/horizon/contracts/libraries/PPMMath.sol
+++ b/packages/horizon/contracts/libraries/PPMMath.sol
@@ -34,7 +34,9 @@ library PPMMath {
     }
 
     /**
-     * @notice Multiplies two values, one of which must be in PPM, and rounds up the result.
+     * @notice Multiplies two values, the second one must be in PPM, and rounds up the result.
+     * @dev requirements:
+     * - The second value must be in PPM.
      * @param a The first value.
      * @param b The second value.
      */
diff --git a/packages/subgraph-service/contracts/libraries/Allocation.sol b/packages/subgraph-service/contracts/libraries/Allocation.sol
index d8f08d6d6..e039b75bd 100644
--- a/packages/subgraph-service/contracts/libraries/Allocation.sol
+++ b/packages/subgraph-service/contracts/libraries/Allocation.sol
@@ -193,7 +193,7 @@ library Allocation {
     }
 
     /**
-     * @notice Checks if an allocation is closed
+     * @notice Checks if an allocation is alturistic
      * @param self The allocation
      */
     function isAltruistic(State memory self) internal pure returns (bool) {
diff --git a/packages/subgraph-service/contracts/libraries/Attestation.sol b/packages/subgraph-service/contracts/libraries/Attestation.sol
index efb76388f..587fadca7 100644
--- a/packages/subgraph-service/contracts/libraries/Attestation.sol
+++ b/packages/subgraph-service/contracts/libraries/Attestation.sol
@@ -96,6 +96,9 @@ library Attestation {
 
         // solhint-disable-next-line no-inline-assembly
         assembly {
+            // Load the 32-byte word from memory starting at `_bytes + _start + 1`
+            // The `0x1` accounts for the fact that we want only the first byte (uint8)
+            // of the loaded 32 bytes.
             tempUint := mload(add(add(_bytes, 0x1), _start))
         }