f: more NatSpec

Author: matiasedgeandnode

packages/subgraph-service/contracts/DisputeManager.sol

@@ -525,6 +525,7 @@ contract DisputeManager is
      * @param _agreementId The agreement id being disputed
      * @param _poi The POI being disputed
      * @param _entities The number of entities disputed
+     * @param _blockNumber The block number of the disputed POI
      * @return The dispute id
      */
     function _createIndexingFeeDisputeV1(

packages/subgraph-service/contracts/SubgraphService.sol

@@ -67,6 +67,7 @@ contract SubgraphService is
      * @param disputeManager The address of the DisputeManager contract
      * @param graphTallyCollector The address of the GraphTallyCollector contract
      * @param curation The address of the Curation contract
+     * @param recurringCollector The address of the RecurringCollector contract
      */
     constructor(
         address graphController,
@@ -394,7 +395,9 @@ contract SubgraphService is
     }
 
     /**
+     * @inheritdoc ISubgraphService
      * @notice Accept an indexing agreement.
+     *
      * See {ISubgraphService.acceptIndexingAgreement}.
      *
      * Requirements:
@@ -428,7 +431,9 @@ contract SubgraphService is
     }
 
     /**
+     * @inheritdoc ISubgraphService
      * @notice Update an indexing agreement.
+     *
      * See {IndexingAgreement.update}.
      *
      * Requirements:
@@ -452,7 +457,9 @@ contract SubgraphService is
     }
 
     /**
+     * @inheritdoc ISubgraphService
      * @notice Cancel an indexing agreement by indexer / operator.
+     *
      * See {IndexingAgreement.cancel}.
      *
      * @dev Can only be canceled on behalf of a valid indexer.
@@ -478,7 +485,9 @@ contract SubgraphService is
     }
 
     /**
+     * @inheritdoc ISubgraphService
      * @notice Cancel an indexing agreement by payer / signer.
+     *
      * See {ISubgraphService.cancelIndexingAgreementByPayer}.
      *
      * Requirements:
@@ -493,6 +502,7 @@ contract SubgraphService is
         IndexingAgreement._getStorageManager().cancelByPayer(agreementId);
     }
 
+    /// @inheritdoc ISubgraphService
     function getIndexingAgreement(
         bytes16 agreementId
     ) external view returns (IndexingAgreement.AgreementWrapper memory) {
@@ -554,6 +564,12 @@ contract SubgraphService is
         return _isOverAllocated(indexer, _delegationRatio);
     }
 
+    /**
+     * @notice Internal function to handle closing an allocation
+     * @dev This function is called when an allocation is closed, either by the indexer or by a third party
+     * @param _allocationId The id of the allocation being closed
+     * @param _stale Whether the allocation is stale or not
+     */
     function _onCloseAllocation(address _allocationId, bool _stale) internal {
         IndexingAgreement._getStorageManager().onCloseAllocation(_allocationId, _stale);
     }
@@ -569,6 +585,10 @@ contract SubgraphService is
         emit PaymentsDestinationSet(_indexer, _paymentsDestination);
     }
 
+    /**
+     * @notice Requires that the indexer is registered
+     * @param _indexer The address of the indexer
+     */
     function _requireRegisteredIndexer(address _indexer) internal view {
         require(indexers[_indexer].registeredAt != 0, SubgraphServiceIndexerNotRegistered(_indexer));
     }
@@ -764,6 +784,13 @@ contract SubgraphService is
         emit StakeToFeesRatioSet(_stakeToFeesRatio);
     }
 
+    /**
+     * @notice Release stake claims and lock new stake as economic security for fees
+     * @dev This function releases all expired stake claims and locks new stake as economic security for fees.
+     * It is called after collecting query fees or indexing fees.
+     * @param _indexer The address of the indexer
+     * @param _tokensCollected The amount of tokens collected from fees
+     */
     function _releaseAndLockStake(address _indexer, uint256 _tokensCollected) private {
         _releaseStake(_indexer, 0);
         if (_tokensCollected > 0) {

packages/subgraph-service/contracts/interfaces/IDisputeManager.sol

@@ -123,6 +123,7 @@ interface IDisputeManager {
      * @param indexer The indexer address
      * @param fisherman The fisherman address
      * @param tokens The amount of tokens deposited by the fisherman
+     * @param payer The address of the payer of the indexing fee
      * @param agreementId The agreement id
      * @param poi The POI disputed
      * @param entities The entities disputed

packages/subgraph-service/contracts/interfaces/ISubgraphService.sol

@@ -290,6 +290,7 @@ interface ISubgraphService is IDataServiceFees {
     /**
      * @notice Get the indexing agreement for a given agreement ID.
      * @param agreementId The id of the indexing agreement
+     * @return The indexing agreement details
      */
     function getIndexingAgreement(
         bytes16 agreementId

packages/subgraph-service/contracts/libraries/AllocationManagerLib.sol

@@ -60,6 +60,10 @@ library AllocationManagerLib {
      * Emits a {AllocationCreated} event
      *
      * @param _allocations The mapping of allocation ids to allocation states
+     * @param _legacyAllocations The mapping of legacy allocation ids to legacy allocation states
+     * @param allocationProvisionTracker The mapping of indexers to their locked tokens
+     * @param _subgraphAllocatedTokens The mapping of subgraph deployment ids to their allocated tokens
+     * @param params The parameters for the allocation
      */
     function allocate(
         mapping(address allocationId => Allocation.State allocation) storage _allocations,
@@ -103,6 +107,32 @@ library AllocationManagerLib {
         );
     }
 
+    /**
+     * @notice Present a POI to collect indexing rewards for an allocation
+     * This function will mint indexing rewards using the {RewardsManager} and distribute them to the indexer and delegators.
+     *
+     * Conditions to qualify for indexing rewards:
+     * - POI must be non-zero
+     * - POI must not be stale, i.e: older than `maxPOIStaleness`
+     * - allocation must not be altruistic (allocated tokens = 0)
+     * - allocation must be open for at least one epoch
+     *
+     * Note that indexers are required to periodically (at most every `maxPOIStaleness`) present POIs to collect rewards.
+     * Rewards will not be issued to stale POIs, which means that indexers are advised to present a zero POI if they are
+     * unable to present a valid one to prevent being locked out of future rewards.
+     *
+     * Note on allocation duration restriction: this is required to ensure that non protocol chains have a valid block number for
+     * which to calculate POIs. EBO posts once per epoch typically at each epoch change, so we restrict rewards to allocations
+     * that have gone through at least one epoch change.
+     *
+     * Emits a {IndexingRewardsCollected} event.
+     *
+     * @param _allocations The mapping of allocation ids to allocation states
+     * @param allocationProvisionTracker The mapping of indexers to their locked tokens
+     * @param _subgraphAllocatedTokens The mapping of subgraph deployment ids to their allocated tokens
+     * @param params The parameters for the POI presentation
+     * @return The amount of tokens collected
+     */
     function presentPOI(
         mapping(address allocationId => Allocation.State allocation) storage _allocations,
         mapping(address indexer => uint256 tokens) storage allocationProvisionTracker,
@@ -195,6 +225,22 @@ library AllocationManagerLib {
         return tokensRewards;
     }
 
+    /**
+     * @notice Close an allocation
+     * Does not require presenting a POI, use {_collectIndexingRewards} to present a POI and collect rewards
+     * @dev Note that allocations are nowlong lived. All service payments, including indexing rewards, should be collected periodically
+     * without the need of closing the allocation. Allocations should only be closed when indexers want to reclaim the allocated
+     * tokens for other purposes.
+     *
+     * Emits a {AllocationClosed} event
+     *
+     * @param _allocations The mapping of allocation ids to allocation states
+     * @param allocationProvisionTracker The mapping of indexers to their locked tokens
+     * @param _subgraphAllocatedTokens The mapping of subgraph deployment ids to their allocated tokens
+     * @param graphRewardsManager The rewards manager to handle rewards distribution
+     * @param _allocationId The id of the allocation to be closed
+     * @param _forceClosed Whether the allocation was force closed
+     */
     function closeAllocation(
         mapping(address allocationId => Allocation.State allocation) storage _allocations,
         mapping(address indexer => uint256 tokens) storage allocationProvisionTracker,
@@ -302,6 +348,22 @@ library AllocationManagerLib {
         return _isOverAllocated(allocationProvisionTracker, graphStaking, _indexer, _delegationRatio);
     }
 
+    /**
+     * @notice Close an allocation
+     * Does not require presenting a POI, use {_collectIndexingRewards} to present a POI and collect rewards
+     * @dev Note that allocations are nowlong lived. All service payments, including indexing rewards, should be collected periodically
+     * without the need of closing the allocation. Allocations should only be closed when indexers want to reclaim the allocated
+     * tokens for other purposes.
+     *
+     * Emits a {AllocationClosed} event
+     *
+     * @param _allocations The mapping of allocation ids to allocation states
+     * @param allocationProvisionTracker The mapping of indexers to their locked tokens
+     * @param _subgraphAllocatedTokens The mapping of subgraph deployment ids to their allocated tokens
+     * @param graphRewardsManager The rewards manager to handle rewards distribution
+     * @param _allocationId The id of the allocation to be closed
+     * @param _forceClosed Whether the allocation was force closed
+     */
     function _closeAllocation(
         mapping(address allocationId => Allocation.State allocation) storage _allocations,
         mapping(address indexer => uint256 tokens) storage allocationProvisionTracker,
@@ -335,6 +397,14 @@ library AllocationManagerLib {
         );
     }
 
+    /**
+     * @notice Checks if an allocation is over-allocated
+     * @param allocationProvisionTracker The mapping of indexers to their locked tokens
+     * @param graphStaking The Horizon staking contract to check delegation ratios
+     * @param _indexer The address of the indexer
+     * @param _delegationRatio The delegation ratio to consider when locking tokens
+     * @return True if the allocation is over-allocated, false otherwise
+     */
     function _isOverAllocated(
         mapping(address indexer => uint256 tokens) storage allocationProvisionTracker,
         IHorizonStaking graphStaking,