f: more natSpec

Author: matiasedgeandnode

packages/horizon/contracts/interfaces/IRecurringCollector.sol

@@ -13,13 +13,15 @@ import { IAuthorizable } from "./IAuthorizable.sol";
  * recurrent payments.
  */
 interface IRecurringCollector is IAuthorizable, IPaymentsCollector {
+    // @notice The state of an agreement
     enum AgreementState {
         NotAccepted,
         Accepted,
         CanceledByServiceProvider,
         CanceledByPayer
     }
 
+    // @notice The party that can cancel an agreement
     enum CancelAgreementBy {
         ServiceProvider,
         Payer
@@ -69,6 +71,7 @@ interface IRecurringCollector is IAuthorizable, IPaymentsCollector {
         bytes signature;
     }
 
+    /// @notice The Recurring Collection Agreement Update (RCAU)
     struct RecurringCollectionAgreementUpdate {
         // The agreement ID
         bytes16 agreementId;
@@ -206,6 +209,10 @@ interface IRecurringCollector is IAuthorizable, IPaymentsCollector {
      * @param dataService The address of the data service
      * @param payer The address of the payer
      * @param serviceProvider The address of the service provider
+     * @param agreementId The agreement ID
+     * @param collectionId The collection ID
+     * @param tokens The amount of tokens collected
+     * @param dataServiceCut The tokens cut for the data service
      */
     event RCACollected(
         address indexed dataService,
@@ -276,6 +283,7 @@ interface IRecurringCollector is IAuthorizable, IPaymentsCollector {
 
     /**
      * Thrown when accepting or upgrading an agreement with invalid parameters
+     * @param message A descriptive error message
      */
     error RecurringCollectorAgreementInvalidParameters(string message);
 
@@ -317,6 +325,7 @@ interface IRecurringCollector is IAuthorizable, IPaymentsCollector {
 
     /**
      * @dev Update an indexing agreement.
+     * @param signedRCAU The signed Recurring Collection Agreement Update which is to be applied.
      */
     function update(SignedRCAU calldata signedRCAU) external;
 
@@ -350,6 +359,8 @@ interface IRecurringCollector is IAuthorizable, IPaymentsCollector {
 
     /**
      * @notice Gets an agreement.
+     * @param agreementId The ID of the agreement to retrieve.
+     * @return The AgreementData struct containing the agreement's data.
      */
     function getAgreement(bytes16 agreementId) external view returns (AgreementData memory);
 }

packages/subgraph-service/contracts/SubgraphService.sol

@@ -420,7 +420,7 @@ contract SubgraphService is
 
     /**
      * @notice Accept an indexing agreement.
-     * See {ISubgraphService.acceptIndexingAgreement}.
+     * See {ISubgraphServiceExtended.acceptIndexingAgreement}.
      *
      * Requirements:
      * - The agreement's indexer must be registered

packages/subgraph-service/contracts/SubgraphServiceExtension.sol

@@ -13,6 +13,16 @@ import { ISubgraphServiceExtension } from "./interfaces/ISubgraphServiceExtensio
 contract SubgraphServiceExtension is PausableUpgradeable, ISubgraphServiceExtension {
     using IndexingAgreement for IndexingAgreement.Manager;
 
+    /**
+     * @notice Checks that an indexer is valid
+     * @param indexer The address of the indexer
+     *
+     * Requirements:
+     * - The caller must be authorized by the indexer
+     * - The provision must be valid according to the subgraph service rules
+     * - The indexer must be registered
+     *
+     */
     modifier onlyValid(address indexer) {
         ProvisionManagerLib.requireAuthorizedForProvision(
             IHorizonStaking(_getBase().getGraphStaking()),
@@ -25,6 +35,17 @@ contract SubgraphServiceExtension is PausableUpgradeable, ISubgraphServiceExtens
         _;
     }
 
+    /**
+     * @notice Update an indexing agreement.
+     * See {IndexingAgreement.update}.
+     *
+     * Requirements:
+     * - The contract must not be paused
+     * - The indexer must be valid
+     *
+     * @param indexer The indexer address
+     * @param signedRCAU The signed Recurring Collection Agreement Update
+     */
     function updateIndexingAgreement(
         address indexer,
         IRecurringCollector.SignedRCAU calldata signedRCAU
@@ -34,18 +55,15 @@ contract SubgraphServiceExtension is PausableUpgradeable, ISubgraphServiceExtens
 
     /**
      * @notice Cancel an indexing agreement by indexer / operator.
-     * See {ISubgraphService.cancelIndexingAgreement}.
+     * See {IndexingAgreement.cancel}.
      *
      * @dev Can only be canceled on behalf of a valid indexer.
      *
      * Requirements:
-     * - The indexer must be registered
-     * - The caller must be authorized by the indexer
-     * - The provision must be valid according to the subgraph service rules
-     * - The agreement must be active
-     *
-     * Emits {IndexingAgreementCanceled} event
+     * - The contract must not be paused
+     * - The indexer must be valid
      *
+     * @param indexer The indexer address
      * @param agreementId The id of the agreement
      */
     function cancelIndexingAgreement(address indexer, bytes16 agreementId) external whenNotPaused onlyValid(indexer) {

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

@@ -261,7 +261,6 @@ interface ISubgraphService is IDataServiceFees {
 
     /**
      * @notice Accept an indexing agreement.
-     * @dev Emits a {IndexingAgreement.IndexingAgreementAccepted} event
      * @param allocationId The id of the allocation
      * @param signedRCA The signed recurring collector agreement (RCA) that the indexer accepts
      */

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

@@ -6,11 +6,6 @@ import { IRecurringCollector } from "@graphprotocol/horizon/contracts/interfaces
 import { IndexingAgreement } from "../libraries/IndexingAgreement.sol";
 
 interface ISubgraphServiceExtension {
-    /**
-     * @notice Accept an indexing agreement.
-     */
-    // function acceptIndexingAgreement(address allocationId, IRecurringCollector.SignedRCA calldata signedRCA) external;
-
     /**
      * @notice Update an indexing agreement.
      */
@@ -26,6 +21,9 @@ interface ISubgraphServiceExtension {
      */
     function cancelIndexingAgreementByPayer(bytes16 agreementId) external;
 
+    /**
+     * @notice Get the indexing agreement for a given agreement ID.
+     */
     function getIndexingAgreement(
         bytes16 agreementId
     ) external view returns (IndexingAgreement.AgreementWrapper memory);

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

@@ -273,6 +273,21 @@ library IndexingAgreement {
         _directory().recurringCollector().accept(signedRCA);
     }
 
+    /**
+     * @notice Update an indexing agreement.
+     *
+     * Requirements:
+     * - Agreement must be active
+     * - The indexer must be the service provider of the agreement
+     *
+     * @dev signedRCA.rcau.metadata is an encoding of {IndexingAgreement.UpdateIndexingAgreementMetadata}
+     *
+     * Emits {IndexingAgreementUpdated} event
+     *
+     * @param self The indexing agreement manager storage
+     * @param indexer The indexer address
+     * @param signedRCAU The signed Recurring Collection Agreement Update
+     */
     function update(
         Manager storage self,
         address indexer,
@@ -304,6 +319,19 @@ library IndexingAgreement {
         _directory().recurringCollector().update(signedRCAU);
     }
 
+    /**
+     * @notice Cancel an indexing agreement.
+     *
+     * Requirements:
+     * - Agreement must be active
+     * - The indexer must be the service provider of the agreement
+     *
+     * Emits {IndexingAgreementCanceled} event
+     *
+     * @param self The indexing agreement manager storage
+     * @param indexer The indexer address
+     * @param agreementId The id of the agreement to cancel
+     */
     function cancel(Manager storage self, address indexer, bytes16 agreementId) external {
         AgreementWrapper memory wrapper = _get(self, agreementId);
         require(_isActive(wrapper), IndexingAgreementNotActive(agreementId));