feat: add paginated developer balance view with stable cursor

[Deyanju23]

Closes #512

Summary

Adds a read-only paginated developer balance view that returns up to N developer balances per request using a stable cursor. The implementation is designed for reconciliation jobs, provides deterministic pagination, and introduces no contract state mutations.

Changes

Pagination

Added:

• contracts/settlement/src/pagination.rs

Implemented a pagination helper that:

• returns up to N developer balances per request
• uses a stable cursor to fetch subsequent pages
• guarantees deterministic ordering across calls
• respects the configured page size from the environment/configuration
• performs read-only operations only

Contract Integration

Updated:

• contracts/settlement/src/lib.rs

Integrated the pagination helper into the existing developer balance view endpoint while preserving existing behavior where applicable.

Tests

Added comprehensive tests covering:

• fewer than N developers
• exactly N developers
• more than N developers
• cursor progression across multiple pages
• stable ordering across repeated calls
• empty developer list
• invalid/end-of-list cursor handling
• read-only behavior (no state mutation)

Documentation

Added Rust /// documentation describing:

• pagination semantics
• cursor format and stability guarantees
• page size configuration
• intended reconciliation workflow

Security

• Read-only implementation.
• No contract state mutation.
• No unwrap() introduced in production code.
• Overflow-safe arithmetic maintained.
• Existing authorization behavior remains unchanged.

Testing

Executed:

cargo test
cargo clippy --workspace --all-targets -- -D warnings

Notes

• No breaking API changes.
• Minimal, focused implementation.
• No unrelated refactoring.

[drips-wave]

@Deyanju23 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[GBOYEE]

@GBOYEE has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Implement following existing patterns and conventions. Add tests, ensure CI passes, and document any new API surface.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @GBOYEE to this issue.