feat: add candidate-key pagination for selective transactions

[flemzord]

Summary

Adds an experimental candidate-key pagination path for selective transaction list queries.

The new path is disabled by default and can be enabled with:

--experimental-transaction-candidate-pagination

When enabled, it only applies to transaction pagination when all of these are true:

• pagination column is id
• order is descending
• the request is not a reverse page
• the query has a positive selective transaction filter (account, source, destination, or metadata[...])

The generated shape materializes candidate transaction keys first, pages those keys, then joins back to fetch full transaction rows. Non-matching queries keep the existing pagination path.

Validation

• go test ./...
• go test ./internal/storage/common ./internal/storage/ledger ./internal/storage/driver ./internal/storage ./cmd
• go test -tags it ./internal/storage/ledger -run 'TestTransactionsCandidateKeyPagination|TestTransactions' -count=1
• go test -race -tags it ./internal/storage/ledger -run 'TestTransactionsCandidateKeyPagination|TestHasPositiveSelectiveTransactionFilter' -count=1
• go test -tags it ./internal/api/v1 ./internal/api/v2 ./internal/controller/ledger -run 'Transactions|ListTransactions' -count=1
• go test -tags it ./internal/storage/common ./internal/storage/driver ./internal/storage -count=1
• git diff --check

Notes

go test -tags it ./internal/storage/ledger -count=1 currently fails on TestVolumesAggregate/filter_using_metadata_and_PIT. I reproduced the same failure on a clean detached worktree at the original HEAD, so it is pre-existing and unrelated to this PR.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 005e512f-90e5-4d68-9b61-004d7dcc348f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/transaction-candidate-pagination

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}