Bill Payments: add index structure and get_bills_by_currency pagination at realistic scale

[Menjay7]

PR: Bill Payments: Add Index Structure and get_bills_by_currency Pagination at Realistic Scale
Summary

Improve bill retrieval performance and scalability by introducing a dedicated currency index structure and implementing paginated get_bills_by_currency queries optimized for large datasets.

This PR enables efficient lookup of bills by currency without full dataset scans and ensures consistent performance as the number of bill payment records grows.

Problem

The current bill retrieval implementation does not scale efficiently:

Retrieving bills by currency requires scanning all bill records.
Response times degrade as the dataset grows.
Large result sets may exceed execution or memory limits.
Clients cannot efficiently consume extensive bill histories.
There is limited confidence in behavior under production-scale workloads.
Solution

Introduce a currency-based indexing mechanism and add cursor-based pagination to get_bills_by_currency.

Core Changes
Add a dedicated index structure for currency-to-bill mappings.
Maintain index updates during bill creation and modification.
Implement paginated retrieval for get_bills_by_currency.
Return deterministic ordering across pages.
Optimize storage access patterns to avoid full-table scans.
Index Structure
Before
Bills
├── bill_1 (USD)
├── bill_2 (NGN)
├── bill_3 (USD)
└── bill_4 (EUR)

get_bills_by_currency("USD")
→ Scan all bills
After
Currency Index
USD → [bill_1, bill_3]
NGN → [bill_2]
EUR → [bill_4]

get_bills_by_currency("USD")
→ Direct index lookup
Pagination API
Request
get_bills_by_currency(
currency: String,
cursor: Option,
limit: u32
)
Response
{
"bills": [...],
"next_cursor": 250,
"has_more": true
}
Implementation Details
Introduce a persistent currency index data structure.
Store bill identifiers grouped by currency.
Implement cursor-based pagination over indexed entries.
Enforce configurable page-size limits.
Ensure deterministic ordering to avoid duplicate or skipped records between pages.
Keep indexes synchronized with bill lifecycle operations.
Realistic Scale Testing

Added tests simulating production-scale workloads:

Thousands of bills distributed across multiple currencies.
High-cardinality currencies with large bill volumes.
Pagination across multiple pages.
Boundary conditions at page limits.
Empty result sets.
Single-page and multi-page retrieval scenarios.
Index consistency after inserts and updates.
Example Test Scenario
10,000 Bills
├── USD: 4,500
├── NGN: 3,000
├── EUR: 1,500
└── GBP: 1,000

Query:
get_bills_by_currency("USD", cursor=0, limit=100)

Result:
100 bills returned
next_cursor = 100
has_more = true
Performance Benefits
Eliminates full dataset scans for currency lookups.
Provides near-constant-time access to currency-specific bill collections.
Reduces memory consumption through incremental retrieval.
Supports efficient browsing of large bill histories.
Improves responsiveness under high-volume workloads.
Testing

Added tests covering:

Currency index creation and maintenance.
Paginated retrieval correctness.
Cursor advancement and continuation.
Page boundary conditions.
Invalid cursor handling.
Empty and non-existent currency lookups.
Large-scale dataset performance and consistency.
Deterministic ordering across paginated requests.
Breaking Changes
get_bills_by_currency now supports paginated responses and may return partial result sets.
Consumers expecting all records in a single response should migrate to iterative page retrieval using next_cursor...closed #726

[Baskarayelu]

good - get_bills_by_currency with an index + pagination is exactly the realistic-scale query support bill_payments was missing. merging 👍