Skip to content

Conversation

@Marvy247
Copy link

@Marvy247 Marvy247 commented Jan 8, 2026

Overview

 Extends the cursor pagination pattern (introduced in #2422) to high-traffic transaction endpoints to improve performance and eliminate pagination
 drift issues.

 ## Motivation

 Transaction list endpoints can return large result sets and are frequently accessed. Traditional offset-based pagination has two main issues:
 1. **Performance degradation** for large offsets (O(n) complexity)
 2. **Pagination drift** when new transactions are added while paginating

 Cursor-based pagination solves both by using row-value comparisons (O(1) for any page) and maintaining stable references to specific transactions.

 ## Changes

 ### 1. `/extended/v1/tx` - Main Transaction List

 - **Cursor format**: `indexBlockHash:microblockSequence:txIndex`
 - Supports all existing filters (type, from_address, to_address, start_time, end_time, etc.)
 - Returns `cursor`, `next_cursor`, and `prev_cursor` in response
 - Backward compatible (cursor parameter is optional, offset/limit still work)

 **Example:**
 ```bash
 GET /extended/v1/tx?limit=20
 GET /extended/v1/tx?cursor=0xabc123...def:2147483647:5&limit=20
  1. /extended/v2/blocks/:block/transactions - Block Transactions

• Cursor format: microblockSequence:txIndex (simpler since all txs share same block)
• Maintains ASC ordering within block
• Returns cursor fields in response

Example:

bash
GET /extended/v2/blocks/12345/transactions?limit=10
GET /extended/v2/blocks/12345/transactions?cursor=2147483647:3&limit=10

Implementation Details

• Uses PostgreSQL row-value comparison: (block_height, microblock_sequence, tx_index) <= (values)
• Fetches limit + 1 records to detect if next page exists
• Generates next_cursor by looking up the start of the previous page
• Handles both ASC and DESC ordering for transaction list
• Proper error handling for invalid cursor formats

Testing

Added comprehensive test coverage for transaction list cursor pagination:
• Forward pagination (prev_cursor navigation)
• Backward pagination (next_cursor navigation)
• Cursor with filters applied
• Invalid cursor format handling
• Edge cases (first page, last page, empty results)

Performance Benefits

• Constant-time pagination: O(1) for any page vs O(n) for large offsets
• Consistency: No pagination drift when data changes
• Scalability: Efficient for endpoints with millions of transactions

Backward Compatibility

Fully backward compatible

• Cursor parameter is optional
• Existing offset/limit pagination still works
• Response includes both offset/limit and cursor fields

Related

• Follows pattern from #2422 (cursor pagination for address transactions)
• Addresses issue #2349 (block-based filtering for pagination)

     - Add cursor pagination to /extended/v1/tx endpoint
       * Cursor format: indexBlockHash:microblockSequence:txIndex
       * Supports all existing filters (type, from_address, to_address, etc.)
       * Uses row-value comparison for O(1) performance on any page
       * Backward compatible (cursor parameter is optional)

     - Add cursor pagination to /extended/v2/blocks/:block/transactions endpoint
       * Cursor format: microblockSequence:txIndex (simpler since all txs in same block)
       * Maintains ASC ordering by microblock_sequence and tx_index

     - Comprehensive test coverage for main transaction list
       * Forward/backward navigation
       * Cursor with filters
       * Invalid cursor handling
       * Edge cases (first page, last page)

     Benefits:
     - Eliminates pagination drift during data changes
     - Faster pagination for large offsets (O(1) vs O(n))
     - Consistent cursor-based navigation pattern across API

     Files modified:
     - src/api/routes/tx.ts: Add cursor support to transaction list
     - src/api/routes/v2/blocks.ts: Add cursor support to block transactions
     - src/datastore/pg-store.ts: Implement getTxList cursor logic
     - src/datastore/pg-store-v2.ts: Implement getBlockTransactions cursor logic
     - tests/api/tx.test.ts: Add comprehensive cursor pagination tests
@Marvy247
Copy link
Author

Marvy247 commented Jan 8, 2026

@rafaelcr @rmottley-hiro @pradel
Awaiting your review ;)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant