Normalize pagination interface

[hugomrdias]

We have at least 5 different interfaces across the contracts for paginated methods
Filecoin pay

 * @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.

https://github.com/FilOzone/filecoin-pay/blob/2f4c9a3486f8c61d04fff127e6479f7b0483e2e0/src/FilecoinPayV1.sol#L1676-L1692

FWSS

* @param offset Starting index (0-based). Use 0 to start from beginning
* @param limit Maximum number of data set IDs to return. Use 0 to get all remaining
* @return dataSetIds Array of data set IDs
* @dev For large lists, use pagination to avoid gas limit issues. If limit=0,
* returns all remaining data sets starting from offset. Example:
* clientDataSets(service, payer, 0, 100) gets first 100 data set IDs.

https://github.com/FilOzone/filecoin-services/blob/3adbb283928eb13c5caa1e007444ee22178d47e1/service_contracts/src/lib/FilecoinWarmStorageServiceStateLibrary.sol#L157-L190

PDP Verifier

/**
 * @notice Returns active pieces (non-zero leaf count) for a data set with pagination
 * @dev WARNING: This function has O(offset) gas complexity because it always iterates from
 * piece ID 0. For large data sets with high offsets, consider using getActivePiecesByCursor()
 * @param setId The data set ID
 * @param offset Starting index for pagination (0-based)
 * @param limit Maximum number of pieces to return
 * @return pieces Array of active piece CIDs
 * @return pieceIds Array of corresponding piece IDs
 * @return hasMore True if there are more pieces beyond this page
 */

This one, the limit can NOT be 0 to get all
https://github.com/FilOzone/pdp/blob/main/src/PDPVerifier.sol#L383-L400

/**
 * @notice Returns active pieces using cursor-based pagination for O(limit) gas complexity
 * @dev This function is more gas-efficient than getActivePieces() for large data sets because
 * it starts iteration from startPieceId instead of always from 0. Use this for paginating
 * through large data sets.
 * @param setId The data set ID
 * @param startPieceId The piece ID to start from (use 0 for first page, then last returned pieceId + 1)
 * @param limit Maximum number of pieces to return
 * @return pieces Array of active piece CIDs
 * @return pieceIds Array of corresponding piece IDs
 * @return hasMore True if there are more pieces beyond this page
 */

Uses startPieceId not offset
https://github.com/FilOzone/pdp/blob/22df1d510002a9ff5dfa812155e84ab993840e72/src/PDPVerifier.sol#L446-L512

/**
 * @notice Finds piece IDs matching a given piece CID, with cursor-based pagination
 * @param setId The data set ID
 * @param pieceCid The piece CID to search for
 * @param startPieceId Piece ID to start scanning from (0 for first call)
 * @param limit Maximum number of matching piece IDs to return
 * @return pieceIds Array of matching piece IDs (up to limit)
 */

Same as the previous example but without hasMore in the output
https://github.com/FilOzone/pdp/blob/22df1d510002a9ff5dfa812155e84ab993840e72/src/PDPVerifier.sol#L514-L546

Maybe we could pick one and go with it?

[BigLep]

This is a good callout. I don't see us doing a contract upgrade for this before GA though. At most I could see presenting a standard client-facing interface at the Synapse SDK layer (maybe we already are) before Synaspe v1 (#592)? As a result I'm putting to M4.5. Let me know if you disagree @rvagg and @hugomrdias .

[hugomrdias]

Im doing a bit of research to see which interface is better on the synapse side, will post here the findings for discussion.

[hugomrdias]

We should include fix for this filecoin-project/filecoin-pin#362 (comment) here too