docs: add natspec to payments protocol contracts and libraries

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

packages/horizon/contracts/interfaces/IGraphPayments.sol

@@ -1,30 +1,64 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 pragma solidity 0.8.26;
 
+/**
+ * @title Interface for the {GraphPayments} contract
+ * @notice This contract is part of the Graph Horizon payments protocol. It's designed
+ * to pull funds (GRT) from the {PaymentsEscrow} and distribute them according to a
+ * set of pre established rules.
+ */
 interface IGraphPayments {
-    // Payment types
+    /**
+     * @notice Types of payments that are supported by the payments protocol
+     * @dev
+     */
     enum PaymentTypes {
         QueryFee,
         IndexingFee,
         IndexingRewards
     }
 
-    event GraphPaymentsCollected(
-        address indexed sender,
+    /**
+     * @notice Emitted when a payment is collected
+     * @param payer The address of the payer
+     * @param receiver The address of the receiver
+     * @param dataService The address of the data service
+     * @param tokensReceiver Amount of tokens for the receiver
+     * @param tokensDelegationPool Amount of tokens for delegators
+     * @param tokensDataService Amount of tokens for the data service
+     * @param tokensProtocol Amount of tokens charged as protocol tax
+     */
+    event PaymentCollected(
+        address indexed payer,
         address indexed receiver,
         address indexed dataService,
         uint256 tokensReceiver,
         uint256 tokensDelegationPool,
         uint256 tokensDataService,
         uint256 tokensProtocol
     );
-    // -- Errors --
 
-    error GraphPaymentsInsufficientTokens(uint256 available, uint256 required);
+    /**
+     * @notice Emitted when there are insufficient tokens to pay the required amount
+     * @param tokens The amount of tokens available
+     * @param minTokens The amount of tokens being collected
+     */
+    error GraphPaymentsInsufficientTokens(uint256 tokens, uint256 minTokens);
 
+    /**
+     * @notice Initialize the contract
+     */
     function initialize() external;
 
-    // collect funds from a sender, pay cuts and forward the rest to the receiver
+    /**
+     * @notice Collects funds from a payer.
+     * It will pay cuts to all relevant parties and forward the rest to the receiver.
+     * @param paymentType The type of payment as defined in {IGraphPayments}
+     * @param receiver The address of the receiver
+     * @param tokens The amount of tokens being collected
+     * @param dataService The address of the data service
+     * @param tokensDataService The amount of tokens that should be sent to the data service
+     */
     function collect(
         PaymentTypes paymentType,
         address receiver,

packages/horizon/contracts/interfaces/IPaymentsCollector.sol

@@ -4,6 +4,44 @@ pragma solidity 0.8.26;
 
 import { IGraphPayments } from "./IGraphPayments.sol";
 
+/**
+ * @title Interface for a payments collector contract as defined by Graph Horizon payments protocol
+ * @notice Contracts implementing this interface can be used with the payments protocol. First, a payer must
+ * approve the collector to collect payments on their behalf. Only then can payment collection be initiated
+ * using the collector contract.
+ *
+ * @dev It's important to note that it's the collector contract's responsibility to validate the payment
+ * request is legitimate.
+ */
 interface IPaymentsCollector {
+    /**
+     * @notice Emitted when a payment is collected
+     * @param paymentType The payment type collected as defined by {IGraphPayments}
+     * @param payer The address of the payer
+     * @param receiver The address of the receiver
+     * @param tokensReceiver The amount of tokens received by the receiver
+     * @param dataService The address of the data service
+     * @param tokensDataService The amount of tokens received by the data service
+     */
+    event PaymentCollected(
+        IGraphPayments.PaymentTypes indexed paymentType,
+        address indexed payer,
+        address receiver,
+        uint256 tokensReceiver,
+        address indexed dataService,
+        uint256 tokensDataService
+    );
+
+    /**
+     * @notice Initiate a payment collection through the payments protocol
+     * @dev This function should require the caller to present some form of evidence of the payer's debt to
+     * the receiver. The collector should validate this evidence and, if valid, collect the payment.
+     *
+     * Emits a {PaymentCollected} event
+     *
+     * @param paymentType The payment type to collect, as defined by {IGraphPayments}
+     * @param data Additional data required for the payment collection. Will vary depending on the collector
+     * implementation.
+     */
     function collect(IGraphPayments.PaymentTypes paymentType, bytes memory data) external returns (uint256);
 }