Keep searchAfter cursors on their positions when sorting locally

[stefangutica]

Reasoning

• Some results are sorted locally after they come from elastic: sortElasticTransfers and sortElasticTransfersByTxsOrder for transfers, and reorderAccountSentTransactionsByNonce for account transactions and transfers.
• Each item's searchAfter holds the elastic sort values of that item. After a local sort, the last item is not always the last elastic hit, so continuing with its searchAfter starts the next page from an earlier position, and items already returned come back again.
• To avoid this, the local sorts were skipped when searchAfter was set, and withTxsOrder + miniBlockHash with searchAfter was rejected with a 400. As a result, the first page and the next ones were ordered differently.
• The local sorts were always descending, so with order=asc the first page came back descending while elastic returned the next ones ascending.

Proposed Changes

• Added SearchAfterUtils.sortKeepingSearchAfterPositions: it sorts the items and then puts each searchAfter back on its original position. When two items swap places, they also swap their searchAfter, so the last item always carries the cursor of the last elastic hit.
• Used it for all three local sorts.
• Local sorting now also applies to pages requested with searchAfter, and withTxsOrder + miniBlockHash + searchAfter is accepted instead of returning 400.
• The transfers sort and the sent transactions nonce sort follow filter.order: ascending for order=asc, descending otherwise (same default as before). The withTxsOrder execution order is left as it is.
• Note: a cursor now belongs to a position, not to the item shown there. Continuing from the last item's searchAfter (the normal flow) is exact; continuing from an item in the middle of a page resumes from that position in elastic order.
• Added a disclaimer to the pagination section in docs/swagger.md: on endpoints that reorder the results, only the searchAfter of the last item is guaranteed to be consistent.

How to test

• npx jest --config ./src/test/jest-unit-config.json src/test/unit/utils/search.after.utils.spec.ts src/test/unit/services/transfers.spec.ts src/test/unit/services/transactions.spec.ts
• GET /accounts/:address/transfers?size=50, then request the next pages with the searchAfter of the last item. There should be no duplicated txHash across pages, and each page should be ordered the same way as the first one.
• Same for GET /accounts/:address/transactions: sent transactions should be ordered by nonce on every page.
• Repeat both with order=asc: every page should be ascending, including the first one.
• GET /transfers?miniBlockHash=<hash>&withTxsOrder=true&searchAfter=<cursor> should return 200 instead of 400.
• Open /docs and check the new disclaimer in the Pagination section.

[github-actions]

k6 load testing comparison.
Base Commit Hash: 3d783b2
Target Commit Hash: f4d2b8c

Metric	Base				Target				Diff
	Avg	Max	90	95	Avg	Max	90	95	Avg	Max	90	95
Transactions	197.93	32250.56	131.98	161.41	87.24	1802.76	188.61	281.03	-55.92% ✅	-94.41% ✅	+42.91% 🔴	+74.11% 🔴
Tokens	64.83	389.48	125.80	223.98	63.55	486.11	142.88	166.12	-1.97% ✅	+24.81% 🔴	+13.58% 🔴	-25.83% ✅
Blocks	89.23	1204.67	204.59	297.52	82.76	1070.77	156.93	185.98	-7.25% ✅	-11.11% ✅	-23.29% ✅	-37.49% ✅
Accounts	68.27	713.89	150.06	226.24	72.11	663.79	155.71	180.78	+5.62% 🔴	-7.02% ✅	+3.77% 🔴	-20.10% ✅
Nodes	1118.03	34546.60	171.25	256.12	64.14	486.30	143.06	168.10	-94.26% ✅	-98.59% ✅	-16.46% ✅	-34.36% ✅
Mex	64.72	392.76	124.72	223.54	64.48	601.35	143.25	167.76	-0.37% ✅	+53.11% 🔴	+14.85% 🔴	-24.95% ✅
Pool	64.44	392.76	123.65	222.61	63.29	486.23	142.45	166.06	-1.78% ✅	+23.80% 🔴	+15.21% 🔴	-25.40% ✅
Test Run Duration	60003.60				60001.78

Legend: Avg - Average Response Time, Max - Maximum Response Time, 90 - 90th Percentile, 95 - 95th Percentile
All times are in milliseconds.