feat(go-api): analytics endpoint — events per contract

[Depo-dev]

Context

Phase 3 of the PRD adds analytics endpoints. The first and most valuable analytics query is: which contracts are generating the most events, and how much activity has each contract seen in a given ledger range?

This serves three distinct use cases:

1. Operators want to know which contracts are responsible for the most DB and Redis load, so they can plan capacity
2. Developers want to understand the relative activity of different contracts on the network
3. The dashboard (feat(infra): developer dashboard — event browser UI #76) uses this endpoint to populate a leaderboard view

Without this endpoint, operators have to run raw SQL queries to get this information.

What needs to be built

Endpoint

GET /v1/stats/contracts

Query parameters:

• from_ledger (optional, integer) — lower bound, inclusive. Default: 0 (all time)
• to_ledger (optional, integer) — upper bound, inclusive. Default: latest indexed ledger
• network (optional, string) — testnet or mainnet. Default: testnet
• limit (optional, integer 1-100) — number of contracts to return. Default: 50

Response:

{
  "contracts": [
    {
      "contract_id": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM",
      "event_count": 48219,
      "last_seen_ledger": 55001,
      "last_seen_at": "2026-06-22T10:00:00Z"
    }
  ],
  "from_ledger": 50000,
  "to_ledger": 55001,
  "network": "testnet",
  "generated_at": "2026-06-22T10:05:00Z"
}

Ordered by event_count DESC (highest volume contract first).

SQL query

SELECT
  contract_id,
  COUNT(*) AS event_count,
  MAX(ledger_sequence) AS last_seen_ledger,
  MAX(ledger_timestamp) AS last_seen_at
FROM soroban_events
WHERE
  network = 
  AND (::BIGINT IS NULL OR ledger_sequence >= )
  AND (::BIGINT IS NULL OR ledger_sequence <= )
GROUP BY contract_id
ORDER BY event_count DESC
LIMIT ;

This query requires the compound index from #61 (contract_id, ledger_sequence DESC) to avoid a seq scan. Without that index, this query will be extremely slow on large datasets. This issue depends on #61 being merged first.

Caching

The response should be cached in Redis for 60 seconds using the cache key stats:contracts:{network}:{from}:{to}:{limit}. This is important because:

• The query involves a GROUP BY on potentially millions of rows
• Dashboard polling intervals could hammer the DB if not cached
• 60-second staleness is completely acceptable for analytics data

Set Cache-Control: public, max-age=60 on the response.

If Redis is unavailable, fall through to the DB query (cache is best-effort, not required for correctness).

Performance requirement

The query must complete in under 200ms on a 10 million row table with the indexes from #61 in place. Verify this before merging with an EXPLAIN ANALYZE run on a seeded dataset.

Authentication

This endpoint requires a valid API key (same as all other /v1 endpoints). It is not a public endpoint — analytics data could reveal commercially sensitive information about network activity patterns.

Acceptance criteria

• GET /v1/stats/contracts returns a correctly sorted list with accurate counts
• Ledger range filter works correctly (events outside the range are excluded)
• Result is cached in Redis for 60 seconds
• Cache miss gracefully falls back to DB if Redis is unavailable
• Response time < 200ms on a 10M row dataset (with indexes from feat(db): compound indexes for high-cardinality query patterns #61)
• Cache-Control: public, max-age=60 header present on response
• Endpoint requires auth (returns 401 without API key)
• OpenAPI spec in feat(go-api): OpenAPI 3.1 spec and generated client types #72 updated to include this endpoint

Dependencies

• feat(db): compound indexes for high-cardinality query patterns #61 (compound indexes — required for acceptable query performance)
• feat(indexer): mainnet support with per-network cursor #65 (network column — the query filters by network)
• feat(go-api): OpenAPI 3.1 spec and generated client types #72 (OpenAPI spec should include this endpoint)

[Stellahub-64]

@Stellahub-64 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

i will love to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Stellahub-64 to this issue.

[drips-wave]

Congratulations, @Just-Bamford! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @Just-Bamford: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[Heazzy500]

@Heazzy500 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hello Maintainer, I’ve reviewed the issue description and I’m confident I can work on it effectively. Please assign it to me.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Heazzy500 to this issue.

[DaddyMord]

@DaddyMord has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi! I’d love to contribute to this issue. It looks interesting and I’d be happy to take it on if it’s still available.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @DaddyMord to this issue.

[Oluwasuyi-Oluwatimilehin-Daniel]

@Oluwasuyi-Timilehin has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hello maintainer, please assign me to this task. i would get started immediately
ETA 1 hour

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Oluwasuyi-Timilehin to this issue.

[graceshaba93]

@graceshaba93 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hello Maintainer, I can fix this issue.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @graceshaba93 to this issue.

[shadrach68]

@shadrach68 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I would like to work on this issue because I am a full-stack developer with 5+ years experience. I focus on identifying root causes and delivering clean, efficient, and maintainable solutions, with thorough testing to ensure reliable results.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @shadrach68 to this issue.

[obedojukwu50-stack]

@obedojukwu50-stack has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I will like to work on this issue, I know exactly what to do and will deliver efficiently.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @obedojukwu50-stack to this issue.