chore: rename collectorId to collectionId

tmigone · tmigone · commit 2af2e681c653 · 2025-02-10T11:08:22.000-03:00
Signed-off-by: Tomás Migone &lt;tomas@edgeandnode.com&gt;
diff --git a/packages/horizon/contracts/interfaces/IPaymentsCollector.sol b/packages/horizon/contracts/interfaces/IPaymentsCollector.sol
@@ -17,14 +17,15 @@ interface IPaymentsCollector {
     /**
      * @notice Emitted when a payment is collected
      * @param paymentType The payment type collected as defined by {IGraphPayments}
+     * @param collectionId The id for the collection. Can be used at the discretion of the collector to group multiple payments.
      * @param payer The address of the payer
      * @param receiver The address of the receiver
      * @param dataService The address of the data service
      * @param tokens The amount of tokens being collected
      */
     event PaymentCollected(
         IGraphPayments.PaymentTypes paymentType,
-        bytes32 indexed collectorId,
+        bytes32 indexed collectionId,
         address indexed payer,
         address receiver,
         address indexed dataService,
diff --git a/packages/horizon/contracts/interfaces/ITAPCollector.sol b/packages/horizon/contracts/interfaces/ITAPCollector.sol
@@ -25,8 +25,8 @@ interface ITAPCollector is IPaymentsCollector {
 
     /// @notice The Receipt Aggregate Voucher (RAV) struct
     struct ReceiptAggregateVoucher {
-        // The ID of the payment
-        bytes32 collectorId;
+        // The ID of the collection "bucket" the RAV belongs to. Note that multiple RAVs can be collected for the same collection id.
+        bytes32 collectionId;
         // The address of the payer the RAV was issued by
         address payer;
         // The address of the data service the RAV was issued to
@@ -82,6 +82,7 @@ interface ITAPCollector is IPaymentsCollector {
 
     /**
      * @notice Emitted when a RAV is collected
+     * @param collectionId The ID of the collection "bucket" the RAV belongs to.
      * @param payer The address of the payer
      * @param dataService The address of the data service
      * @param serviceProvider The address of the service provider
@@ -91,9 +92,10 @@ interface ITAPCollector is IPaymentsCollector {
      * @param signature The signature of the RAV
      */
     event RAVCollected(
+        bytes32 indexed collectionId,
         address indexed payer,
+        address serviceProvider,
         address indexed dataService,
-        address indexed serviceProvider,
         uint64 timestampNs,
         uint128 valueAggregate,
         bytes metadata,
diff --git a/packages/horizon/contracts/payments/collectors/TAPCollector.sol b/packages/horizon/contracts/payments/collectors/TAPCollector.sol
@@ -35,8 +35,10 @@ contract TAPCollector is EIP712, GraphDirectory, ITAPCollector {
     /// @notice Authorization details for payer-signer pairs
     mapping(address signer => PayerAuthorization authorizedSigner) public authorizedSigners;
 
-    /// @notice Tracks the amount of tokens already collected by a data service from a payer to a receiver
-    mapping(address dataService => mapping(bytes32 collectorId => mapping(address receiver => mapping(address payer => uint256 tokens))))
+    /// @notice Tracks the amount of tokens already collected by a data service from a payer to a receiver.
+    /// @dev The collectionId provides a secondary key for grouping payment tracking if needed. Data services that do not require
+    /// grouping can use the same collectionId for all payments (0x00 or some other default value).
+    mapping(address dataService => mapping(bytes32 collectionId => mapping(address receiver => mapping(address payer => uint256 tokens))))
         public tokensCollected;
 
     /// @notice The duration (in seconds) in which a signer is thawing before they can be revoked
@@ -182,7 +184,7 @@ contract TAPCollector is EIP712, GraphDirectory, ITAPCollector {
         address payer = authorizedSigners[signer].payer;
         require(signedRAV.rav.payer == payer, TAPCollectorInvalidRAVPayer(payer, signedRAV.rav.payer));
 
-        bytes32 collectorId = signedRAV.rav.collectorId;
+        bytes32 collectionId = signedRAV.rav.collectionId;
         address dataService = signedRAV.rav.dataService;
         address receiver = signedRAV.rav.serviceProvider;
 
@@ -200,7 +202,7 @@ contract TAPCollector is EIP712, GraphDirectory, ITAPCollector {
         uint256 tokensToCollect = 0;
         {
             uint256 tokensRAV = signedRAV.rav.valueAggregate;
-            uint256 tokensAlreadyCollected = tokensCollected[dataService][collectorId][receiver][payer];
+            uint256 tokensAlreadyCollected = tokensCollected[dataService][collectionId][receiver][payer];
             require(
                 tokensRAV > tokensAlreadyCollected,
                 TAPCollectorInconsistentRAVTokens(tokensRAV, tokensAlreadyCollected)
@@ -218,20 +220,24 @@ contract TAPCollector is EIP712, GraphDirectory, ITAPCollector {
         }
 
         if (tokensToCollect > 0) {
-            tokensCollected[dataService][collectorId][receiver][payer] += tokensToCollect;
+            tokensCollected[dataService][collectionId][receiver][payer] += tokensToCollect;
             _graphPaymentsEscrow().collect(_paymentType, payer, receiver, tokensToCollect, dataService, dataServiceCut);
         }
 
-        emit PaymentCollected(_paymentType, collectorId, payer, receiver, dataService, tokensToCollect);
+        emit PaymentCollected(_paymentType, collectionId, payer, receiver, dataService, tokensToCollect);
+
+        // This event is emitted to allow reconstructing RAV history with onchain data.
         emit RAVCollected(
+            collectionId,
             payer,
-            dataService,
             receiver,
+            dataService,
             signedRAV.rav.timestampNs,
             signedRAV.rav.valueAggregate,
             signedRAV.rav.metadata,
             signedRAV.signature
         );
+
         return tokensToCollect;
     }
 
diff --git a/packages/horizon/test/payments/tap-collector/TAPCollector.t.sol b/packages/horizon/test/payments/tap-collector/TAPCollector.t.sol
@@ -142,7 +142,7 @@ contract TAPCollectorTest is HorizonStakingSharedTest, PaymentsEscrowSharedTest
         (address _payer, , ) = tapCollector.authorizedSigners(_signer);
         uint256 tokensAlreadyCollected = tapCollector.tokensCollected(
             signedRAV.rav.dataService,
-            signedRAV.rav.collectorId,
+            signedRAV.rav.collectionId,
             signedRAV.rav.serviceProvider,
             _payer
         );
@@ -153,17 +153,18 @@ contract TAPCollectorTest is HorizonStakingSharedTest, PaymentsEscrowSharedTest
         vm.expectEmit(address(tapCollector));
         emit IPaymentsCollector.PaymentCollected(
             _paymentType,
-            signedRAV.rav.collectorId,
+            signedRAV.rav.collectionId,
             _payer,
             signedRAV.rav.serviceProvider,
             signedRAV.rav.dataService,
             tokensToCollect
         );
         vm.expectEmit(address(tapCollector));
         emit ITAPCollector.RAVCollected(
+            signedRAV.rav.collectionId,
             _payer,
-            signedRAV.rav.dataService,
             signedRAV.rav.serviceProvider,
+            signedRAV.rav.dataService,
             signedRAV.rav.timestampNs,
             signedRAV.rav.valueAggregate,
             signedRAV.rav.metadata,
@@ -175,7 +176,7 @@ contract TAPCollectorTest is HorizonStakingSharedTest, PaymentsEscrowSharedTest
 
         uint256 tokensCollectedAfter = tapCollector.tokensCollected(
             signedRAV.rav.dataService,
-            signedRAV.rav.collectorId,
+            signedRAV.rav.collectionId,
             signedRAV.rav.serviceProvider,
             _payer
         );
diff --git a/packages/horizon/test/payments/tap-collector/collect/collect.t.sol b/packages/horizon/test/payments/tap-collector/collect/collect.t.sol
@@ -48,7 +48,7 @@ contract TAPCollectorCollectTest is TAPCollectorTest {
     ) private pure returns (ITAPCollector.ReceiptAggregateVoucher memory rav) {
         return
             ITAPCollector.ReceiptAggregateVoucher({
-                collectorId: bytes32(uint256(uint160(_allocationId))),
+                collectionId: bytes32(uint256(uint160(_allocationId))),
                 payer: _payer,
                 dataService: _collector,
                 serviceProvider: _indexer,
diff --git a/packages/subgraph-service/contracts/SubgraphService.sol b/packages/subgraph-service/contracts/SubgraphService.sol
@@ -537,12 +537,12 @@ contract SubgraphService is
     function _collectQueryFees(ITAPCollector.SignedRAV memory _signedRav) private returns (uint256 feesCollected) {
         address indexer = _signedRav.rav.serviceProvider;
 
-        // Check that the collectorId fits in an address (160 bits)
+        // Check that collectionId (256 bits) is a valid address (160 bits)
         require(
-            uint256(_signedRav.rav.collectorId) < (1 << 160),
-            SubgraphServiceInvalidCollectorId(_signedRav.rav.collectorId)
+            uint256(_signedRav.rav.collectionId) <= type(uint160).max,
+            SubgraphServiceInvalidCollectionId(_signedRav.rav.collectionId)
         );
-        address allocationId = address(uint160(uint256(_signedRav.rav.collectorId)));
+        address allocationId = address(uint160(uint256(_signedRav.rav.collectionId)));
         Allocation.State memory allocation = _allocations.get(allocationId);
 
         // Check RAV is consistent - RAV indexer must match the allocation's indexer
diff --git a/packages/subgraph-service/contracts/interfaces/ISubgraphService.sol b/packages/subgraph-service/contracts/interfaces/ISubgraphService.sol
@@ -125,10 +125,10 @@ interface ISubgraphService is IDataServiceFees {
     error SubgraphServiceInvalidZeroStakeToFeesRatio();
 
     /**
-     * @notice Thrown when collectorId is too large for an address
-     * @param collectorId The collectorId that is too large
+     * @notice Thrown when collectionId is not a valid address
+     * @param collectionId The collectionId
      */
-    error SubgraphServiceInvalidCollectorId(bytes32 collectorId);
+    error SubgraphServiceInvalidCollectionId(bytes32 collectionId);
 
     /**
      * @notice Force close a stale allocation
diff --git a/packages/subgraph-service/test/subgraphService/SubgraphService.t.sol b/packages/subgraph-service/test/subgraphService/SubgraphService.t.sol
@@ -264,12 +264,12 @@ contract SubgraphServiceTest is SubgraphServiceSharedTest {
 
     function _handleQueryFeeCollection(address _indexer, bytes memory _data) private returns (uint256 paymentCollected) {
         ITAPCollector.SignedRAV memory signedRav = abi.decode(_data, (ITAPCollector.SignedRAV));
-        Allocation.State memory allocation = subgraphService.getAllocation(address(uint160(uint256(signedRav.rav.collectorId))));
+        Allocation.State memory allocation = subgraphService.getAllocation(address(uint160(uint256(signedRav.rav.collectionId))));
         (address payer, , ) = tapCollector.authorizedSigners(_recoverRAVSigner(signedRav));
 
         uint256 tokensCollected = tapCollector.tokensCollected(
             address(subgraphService),
-            signedRav.rav.collectorId,
+            signedRav.rav.collectionId,
             _indexer,
             payer
         );
@@ -334,7 +334,7 @@ contract SubgraphServiceTest is SubgraphServiceSharedTest {
         CollectPaymentData memory collectPaymentDataAfter
     ) private view {
         ITAPCollector.SignedRAV memory signedRav = abi.decode(_data, (ITAPCollector.SignedRAV));
-        Allocation.State memory allocation = subgraphService.getAllocation(address(uint160(uint256(signedRav.rav.collectorId))));
+        Allocation.State memory allocation = subgraphService.getAllocation(address(uint160(uint256(signedRav.rav.collectionId))));
         QueryFeeData memory queryFeeData = _queryFeeData(allocation.subgraphDeploymentId);
         uint256 tokensProtocol = _paymentCollected.mulPPMRoundUp(queryFeeData.protocolPaymentCut);
         uint256 curationTokens = (_paymentCollected - tokensProtocol).mulPPMRoundUp(queryFeeData.curationCut);
diff --git a/packages/subgraph-service/test/subgraphService/collect/query/query.t.sol b/packages/subgraph-service/test/subgraphService/collect/query/query.t.sol
@@ -42,12 +42,12 @@ contract SubgraphServiceRegisterTest is SubgraphServiceTest {
 
     function _getRAV(
         address indexer,
-        bytes32 collectorId,
+        bytes32 collectionId,
         uint128 tokens
     ) private view returns (ITAPCollector.ReceiptAggregateVoucher memory rav) {
         return
             ITAPCollector.ReceiptAggregateVoucher({
-                collectorId: collectorId,
+                collectionId: collectionId,
                 payer: users.gateway,
                 dataService: address(subgraphService),
                 serviceProvider: indexer,
@@ -172,15 +172,15 @@ contract SubgraphServiceRegisterTest is SubgraphServiceTest {
         subgraphService.collect(newIndexer, paymentType, data);
     }
 
-    function testCollect_QueryFees_RevertWhen_CollectorIdTooLarge() public useIndexer useAllocation(1000 ether) {
-        bytes32 collectorId = keccak256(abi.encodePacked("Large collector id, longer than 160 bits"));
-        ITAPCollector.ReceiptAggregateVoucher memory rav = _getRAV(users.indexer, collectorId, 1000 ether);
+    function testCollect_QueryFees_RevertWhen_CollectionIdTooLarge() public useIndexer useAllocation(1000 ether) {
+        bytes32 collectionId = keccak256(abi.encodePacked("Large collection id, longer than 160 bits"));
+        ITAPCollector.ReceiptAggregateVoucher memory rav = _getRAV(users.indexer, collectionId, 1000 ether);
         bytes32 messageHash = tapCollector.encodeRAV(rav);
         (uint8 v, bytes32 r, bytes32 s) = vm.sign(signerPrivateKey, messageHash);
         bytes memory signature = abi.encodePacked(r, s, v);
         ITAPCollector.SignedRAV memory signedRAV = ITAPCollector.SignedRAV(rav, signature);
         bytes memory data = abi.encode(signedRAV);
-        vm.expectRevert(abi.encodeWithSelector(ISubgraphService.SubgraphServiceInvalidCollectorId.selector, collectorId));
+        vm.expectRevert(abi.encodeWithSelector(ISubgraphService.SubgraphServiceInvalidCollectionId.selector, collectionId));
         subgraphService.collect(users.indexer, IGraphPayments.PaymentTypes.QueryFee, data);
     }
 }
