feat: sort v2 fps by active TVL

[necipsagiro]

Resolves: #212

Implements database-level sorting by active_tvl (descending) for the /v2/finality-providers endpoint using cursor-based pagination.

---

• added IndexerFinalityProviderStatsPagination model and GetFinalityProviderStatsPaginated using a compound key (active_tvl + fp_btc_pk_hex)
• added GetFinalityProvidersByPks for bulk-fetching finality provider details with case-insensitive matching
• refactored GetFinalityProvidersWithStats to a stats-first approach, fetching sorted stats before merging with bulk-fetched provider details
• updated Swagger documentation
• added integration tests for sorting, pagination, and bulk fetch operations

---

• uses compound index (active_tvl DESC, _id DESC) for deterministic sorting and stable pagination
• implements compound cursor logic: (active_tvl < cursor.tvl) OR (active_tvl = cursor.tvl AND _id < cursor.id)
• normalizes public keys to lowercase for case-insensitive matching across stats and details collections

[Copilot]

Pull request overview

This PR implements database-level sorting by active_tvl (descending) for the /v2/finality-providers endpoint using cursor-based pagination. The implementation shifts from a "details-first" to a "stats-first" approach: it queries finality provider stats sorted by TVL, then fetches corresponding provider details in bulk.

• Added IndexerFinalityProviderStatsPagination model and GetFinalityProviderStatsPaginated method with compound cursor logic (active_tvl + fp_btc_pk_hex)
• Implemented GetFinalityProvidersByPks to bulk-fetch provider details for FPs already sorted by stats
• Refactored GetFinalityProvidersWithStats service method to follow the stats-first approach

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
internal/indexer/db/model/stats.go	Added pagination model and token builder for finality provider stats sorted by active TVL
internal/indexer/db/client/stats.go	Implemented paginated stats query with sorting by active_tvl DESC and compound cursor filtering
internal/indexer/db/client/finality_provider.go	Added bulk fetch method for finality provider details by public keys
internal/indexer/db/client/interface.go	Extended interface with new pagination and bulk fetch methods
internal/v2/service/finality_provider.go	Refactored to stats-first approach: fetch sorted stats, then merge with bulk-fetched details
internal/v2/api/handlers/finality_provider.go	Updated documentation to reflect sorting by active TVL
docs/swagger.yaml, docs/swagger.json, docs/docs.go	Updated API documentation for the sorted endpoint
tests/mocks/mock_indexer_db_client.go	Added mock implementations for new methods

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

When some finality providers have stats but are missing from the details collection, they will be silently skipped (lines 102-106). This means the returned page will have fewer results than the configured page limit, potentially confusing pagination logic. Consider logging at a higher severity level (warn or error) since this represents a data inconsistency issue that should be investigated, or consider returning an error if critical details are missing.

Suggested change

	log.Ctx(ctx).Debug().
	log.Ctx(ctx).Warn().

[necipsagiro]

i dont agree