feat: add pagination to _getRailsForAddressAndToken (#237)

Author: DarkLord017

src/Payments.sol

@@ -1688,42 +1688,61 @@ contract Payments is ReentrancyGuard {
      * @notice Gets all rails where the given address is the payer for a specific token.
      * @param payer The address of the payer to get rails for.
      * @param token The token address to filter rails by.
-     * @return Array of RailInfo structs containing rail IDs and termination status.
+     * @param offset The offset to start from.
+     * @param limit Maximum number of entries to return
+     * @return results Array of RailInfo structs containing rail IDs and termination status.
+     * @return nextOffset The next offset to use for pagination.
+     * @return total The total number of rails.
      */
-    function getRailsForPayerAndToken(address payer, IERC20 token) external view returns (RailInfo[] memory) {
-        return _getRailsForAddressAndToken(payer, token, true);
+    function getRailsForPayerAndToken(address payer, IERC20 token, uint256 offset, uint256 limit)
+        external
+        view
+        returns (RailInfo[] memory results, uint256 nextOffset, uint256 total)
+    {
+        return _getRailsForAddressAndToken(payerRails[token][payer], offset, limit);
     }
 
     /**
      * @notice Gets all rails where the given address is the payee for a specific token.
      * @param payee The address of the payee to get rails for.
      * @param token The token address to filter rails by.
-     * @return Array of RailInfo structs containing rail IDs and termination status.
+     * @param offset The offset to start from.
+     * @param limit Maximum number of entries to return
+     * @return results Array of RailInfo structs containing rail IDs and termination status.
+     * @return nextOffset The next offset to use for pagination.
+     * @return total The total number of rails.
      */
-    function getRailsForPayeeAndToken(address payee, IERC20 token) external view returns (RailInfo[] memory) {
-        return _getRailsForAddressAndToken(payee, token, false);
+    function getRailsForPayeeAndToken(address payee, IERC20 token, uint256 offset, uint256 limit)
+        external
+        view
+        returns (RailInfo[] memory results, uint256 nextOffset, uint256 total)
+    {
+        return _getRailsForAddressAndToken(payeeRails[token][payee], offset, limit);
     }
 
     /**
      * @dev Internal function to get rails for either a payer or payee.
-     * @param addr The address to get rails for (either payer or payee).
-     * @param token The token address to filter rails by.
-     * @param isPayer If true, search for rails where addr is the payer, otherwise search for rails where addr is the payee.
-     * @return Array of RailInfo structs containing rail IDs and termination status.
+     * @param allRailIds The array of rail IDs to filter rails by.
+     * @param offset The offset to start from.
+     * @param limit Maximum number of entries to return
+     * @return results Array of RailInfo structs containing rail IDs and termination status.
+     * @return nextOffset The next offset to use for pagination.
+     * @return total The total number of rails.
      */
-    function _getRailsForAddressAndToken(address addr, IERC20 token, bool isPayer)
+    function _getRailsForAddressAndToken(uint256[] storage allRailIds, uint256 offset, uint256 limit)
         internal
         view
-        returns (RailInfo[] memory)
+        returns (RailInfo[] memory results, uint256 nextOffset, uint256 total)
     {
-        // Get the appropriate list of rails based on whether we're looking for payer or payee
-        uint256[] storage allRailIds = isPayer ? payerRails[token][addr] : payeeRails[token][addr];
         uint256 railsLength = allRailIds.length;
+        if (limit == 0) limit = railsLength;
+        if (offset >= railsLength) return (new RailInfo[](0), railsLength, railsLength);
+        uint256 end = offset + limit > railsLength ? railsLength : offset + limit;
 
-        RailInfo[] memory results = new RailInfo[](railsLength);
+        results = new RailInfo[](end - offset);
         uint256 resultCount = 0;
 
-        for (uint256 i = 0; i < railsLength; i++) {
+        for (uint256 i = offset; i < end; i++) {
             uint256 railId = allRailIds[i];
             Rail storage rail = rails[railId];
 
@@ -1740,7 +1759,7 @@ contract Payments is ReentrancyGuard {
             mstore(results, resultCount)
         }
 
-        return results;
+        return (results, end, railsLength);
     }
 
     /// @notice Number of pending rate-change entries for a rail

test/RailGetters.t.sol

@@ -149,7 +149,7 @@ contract PayeeRailsTest is Test, BaseTestHelper {
 
     function testGetRailsForPayeeAndToken() public view {
         // Test getting all rails for USER2 and token1 (should include terminated)
-        Payments.RailInfo[] memory rails = payments.getRailsForPayeeAndToken(USER2, token);
+        (Payments.RailInfo[] memory rails,,) = payments.getRailsForPayeeAndToken(USER2, token, 0, 3);
 
         // Should include 3 rails: rail1Id, rail2Id, and rail3Id (terminated)
         assertEq(rails.length, 3, "Should have 3 rails for USER2 with token1");
@@ -180,14 +180,14 @@ contract PayeeRailsTest is Test, BaseTestHelper {
         assertTrue(foundRail3, "Rail 3 not found");
 
         // Test different token (should only return rails for that token)
-        Payments.RailInfo[] memory token2Rails = payments.getRailsForPayeeAndToken(USER2, token2);
+        (Payments.RailInfo[] memory token2Rail,,) = payments.getRailsForPayeeAndToken(USER2, token2, 0, 0);
 
         // Should include only 1 rail with token2: rail4Id
-        assertEq(token2Rails.length, 1, "Should have 1 rail for USER2 with token2");
-        assertEq(token2Rails[0].railId, rail4Id, "Rail ID should match rail4Id");
+        assertEq(token2Rail.length, 1, "Should have 1 rail for USER2 with token2");
+        assertEq(token2Rail[0].railId, rail4Id, "Rail ID should match rail4Id");
 
         // Test different payee (should only return rails for that payee)
-        Payments.RailInfo[] memory user3Rails = payments.getRailsForPayeeAndToken(USER3, token);
+        (Payments.RailInfo[] memory user3Rails,,) = payments.getRailsForPayeeAndToken(USER3, token, 0, 0);
 
         // Should include only 1 rail for USER3: rail5Id
         assertEq(user3Rails.length, 1, "Should have 1 rail for USER3 with token1");
@@ -196,7 +196,7 @@ contract PayeeRailsTest is Test, BaseTestHelper {
 
     function testGetRailsForPayerAndToken() public view {
         // Test getting all rails for USER1 (payer) and token1 (should include terminated)
-        Payments.RailInfo[] memory rails = payments.getRailsForPayerAndToken(USER1, token);
+        (Payments.RailInfo[] memory rails,,) = payments.getRailsForPayerAndToken(USER1, token, 0, 4);
 
         // Should include 4 rails: rail1Id, rail2Id, rail3Id (terminated), and rail5Id
         assertEq(rails.length, 4, "Should have 4 rails for USER1 with token1");
@@ -233,7 +233,7 @@ contract PayeeRailsTest is Test, BaseTestHelper {
         assertTrue(foundRail5, "Rail 5 not found");
 
         // Test different token (should only return rails for that token)
-        Payments.RailInfo[] memory token2Rails = payments.getRailsForPayerAndToken(USER1, token2);
+        (Payments.RailInfo[] memory token2Rails,,) = payments.getRailsForPayerAndToken(USER1, token2, 0, 0);
 
         // Should include only 1 rail with token2: rail4Id
         assertEq(token2Rails.length, 1, "Should have 1 rail for USER1 with token2");
@@ -242,8 +242,8 @@ contract PayeeRailsTest is Test, BaseTestHelper {
 
     function testRailsBeyondEndEpoch() public {
         // Get the initial rails when Rail 3 is terminated but not beyond its end epoch
-        Payments.RailInfo[] memory initialPayeeRails = payments.getRailsForPayeeAndToken(USER2, token);
-        Payments.RailInfo[] memory initialPayerRails = payments.getRailsForPayerAndToken(USER1, token);
+        (Payments.RailInfo[] memory initialPayeeRails,,) = payments.getRailsForPayeeAndToken(USER2, token, 0, 3);
+        (Payments.RailInfo[] memory initialPayerRails,,) = payments.getRailsForPayerAndToken(USER1, token, 0, 4);
 
         // Should include all 3 rails for payee
         assertEq(initialPayeeRails.length, 3, "Should have 3 rails initially for payee");
@@ -269,8 +269,8 @@ contract PayeeRailsTest is Test, BaseTestHelper {
         payments.settleRail(rail3Id, endEpoch);
 
         // Get rails again for both payee and payer
-        Payments.RailInfo[] memory finalPayeeRails = payments.getRailsForPayeeAndToken(USER2, token);
-        Payments.RailInfo[] memory finalPayerRails = payments.getRailsForPayerAndToken(USER1, token);
+        (Payments.RailInfo[] memory finalPayeeRails,,) = payments.getRailsForPayeeAndToken(USER2, token, 0, 3);
+        (Payments.RailInfo[] memory finalPayerRails,,) = payments.getRailsForPayerAndToken(USER1, token, 0, 4);
 
         // Should include only 2 rails now for payee, as Rail 3 is beyond its end epoch
         assertEq(finalPayeeRails.length, 2, "Should have 2 rails for payee after advancing beyond end epoch");
@@ -303,21 +303,76 @@ contract PayeeRailsTest is Test, BaseTestHelper {
 
     function testEmptyResult() public view {
         // Test non-existent payee
-        Payments.RailInfo[] memory nonExistentPayee = payments.getRailsForPayeeAndToken(address(0x123), token);
+        (Payments.RailInfo[] memory nonExistentPayee,,) = payments.getRailsForPayeeAndToken(address(0x123), token, 0, 0);
         assertEq(nonExistentPayee.length, 0, "Should return empty array for non-existent payee");
 
         // Test non-existent payer
-        Payments.RailInfo[] memory nonExistentPayer = payments.getRailsForPayerAndToken(address(0x123), token);
+        (Payments.RailInfo[] memory nonExistentPayer,,) = payments.getRailsForPayerAndToken(address(0x123), token, 0, 0);
         assertEq(nonExistentPayer.length, 0, "Should return empty array for non-existent payer");
 
         // Test non-existent token for payee
-        Payments.RailInfo[] memory nonExistentTokenForPayee =
-            payments.getRailsForPayeeAndToken(USER2, IERC20(address(0x456)));
+        (Payments.RailInfo[] memory nonExistentTokenForPayee,,) =
+            payments.getRailsForPayeeAndToken(USER2, IERC20(address(0x456)), 0, 0);
         assertEq(nonExistentTokenForPayee.length, 0, "Should return empty array for non-existent token with payee");
 
         // Test non-existent token for payer
-        Payments.RailInfo[] memory nonExistentTokenForPayer =
-            payments.getRailsForPayerAndToken(USER1, IERC20(address(0x456)));
+        (Payments.RailInfo[] memory nonExistentTokenForPayer,,) =
+            payments.getRailsForPayerAndToken(USER1, IERC20(address(0x456)), 0, 0);
         assertEq(nonExistentTokenForPayer.length, 0, "Should return empty array for non-existent token with payer");
     }
+
+    function testPagination() public view {
+        // Test pagination for payee rails (USER2 has 3 rails with token1)
+
+        // Test getting first 2 rails
+        (Payments.RailInfo[] memory page1, uint256 nextOffset1, uint256 total1) =
+            payments.getRailsForPayeeAndToken(USER2, token, 0, 2);
+
+        assertEq(page1.length, 2, "First page should have 2 rails");
+        assertEq(nextOffset1, 2, "Next offset should be 2");
+        assertEq(total1, 3, "Total should be 3");
+
+        // Test getting remaining rail
+        (Payments.RailInfo[] memory page2, uint256 nextOffset2, uint256 total2) =
+            payments.getRailsForPayeeAndToken(USER2, token, nextOffset1, 2);
+
+        assertEq(page2.length, 1, "Second page should have 1 rail");
+        assertEq(nextOffset2, 3, "Next offset should be 3 (end of array)");
+        assertEq(total2, 3, "Total should still be 3");
+
+        // Verify no duplicate rails between pages
+        bool duplicateFound = false;
+        for (uint256 i = 0; i < page1.length; i++) {
+            for (uint256 j = 0; j < page2.length; j++) {
+                if (page1[i].railId == page2[j].railId) {
+                    duplicateFound = true;
+                    break;
+                }
+            }
+        }
+        assertFalse(duplicateFound, "No duplicate rails should exist between pages");
+
+        // Test offset beyond array length
+        (Payments.RailInfo[] memory emptyPage, uint256 nextOffset3, uint256 total3) =
+            payments.getRailsForPayeeAndToken(USER2, token, 10, 2);
+
+        assertEq(emptyPage.length, 0, "Should return empty array for offset beyond length");
+        assertEq(nextOffset3, 3, "Next offset should equal total length");
+        assertEq(total3, 3, "Total should still be 3");
+
+        // Test pagination for payer rails (USER1 has 4 rails with token1)
+        (Payments.RailInfo[] memory payerPage1, uint256 payerNext1, uint256 payerTotal1) =
+            payments.getRailsForPayerAndToken(USER1, token, 0, 3);
+
+        assertEq(payerPage1.length, 3, "Payer first page should have 3 rails");
+        assertEq(payerNext1, 3, "Payer next offset should be 3");
+        assertEq(payerTotal1, 4, "Payer total should be 4");
+
+        (Payments.RailInfo[] memory payerPage2, uint256 payerNext2, uint256 payerTotal2) =
+            payments.getRailsForPayerAndToken(USER1, token, payerNext1, 3);
+
+        assertEq(payerPage2.length, 1, "Payer second page should have 1 rail");
+        assertEq(payerNext2, 4, "Payer next offset should be 4 (end of array)");
+        assertEq(payerTotal2, 4, "Payer total should still be 4");
+    }
 }