[Enhancement] On-chain revenue analytics API: platform volume, top educators, and per-educator earnings from settled payments

[zeemscript]

Summary

Build a read-only on-chain revenue analytics API over the confirmed Stellar payments the platform already records: platform-wide volume over time, top-earning educators, per-educator revenue breakdowns, best-selling courses/books, and buyer spend — all computed with MongoDB aggregation over the Transaction collection (optionally cross-checked against Horizon). Today the only way to read transactions is one user's paginated history; there is no aggregate reporting for admins or for an educator's own earnings dashboard.

Current state

• getTransactionHistory (src/controllers/stellar/paymentController.js) is the only reporting endpoint: it filters { buyer } or { creator } for the calling user and paginates raw rows. There is no $group/$sum anywhere — no totals, no time-series, no leaderboards.
• The data to power analytics already exists on every confirmed row (src/models/Transaction.js): buyer, creator, itemType (book/course), itemId, itemTitle, amount (string, precise), currency, network, status (confirmed is the settled state), confirmedAt, and indexes on { creator, status }, { buyer, status }, { itemType, itemId }.
• amount is stored as a string to preserve precision, so any sum must convert carefully ($toDecimal) — a naive JS Number sum would lose precision on USDC's 7 decimals.
• There is no admin surface and no educator earnings dashboard endpoint. User.role is ["student", "tutor"] with no admin, so aggregate/platform-wide analytics need a privilege gate.
• Educator-facing earnings live only implicitly in transactions; the earnings-ledger issue ([Enhancement] Educator earnings ledger and atomic batch payouts from the platform wallet #28) is about balances and payouts, not reporting/aggregation, so this fills the reporting gap without overlapping.

What to build

1. Analytics service (src/services/analytics/paymentAnalytics.js) built on aggregation pipelines that only count status: "confirmed" and use $toDecimal for money math:
   • Platform overview: total settled volume, transaction count, unique buyers, split by itemType and by currency/network.
   • Time-series: volume and count bucketed by day/week/month over a date range ($dateTrunc on confirmedAt).
   • Top educators: group by creator, sum amount, count sales, join User for name/avatar; support limit and date filter.
   • Top items: group by itemId/itemTitle.
   • Per-educator detail: one educator's totals, time-series, and top items.
2. Endpoints (new src/routes/analytics/analyticsRoutes.js, mounted /api/analytics):
   • GET /api/analytics/me/earnings — the authenticated educator's own revenue (scoped to creator === req.user._id), no elevated role needed.
   • GET /api/analytics/platform, /platform/timeseries, /top-educators, /top-items — admin-gated (small requireRole middleware aligned with [Enhancement] Introduce role-based authorization and fix registration privilege escalation #20's RBAC; do not widen tutor).
   • Shared query params: from, to, interval, currency, network, limit.
3. Precision + correctness: all monetary outputs are decimal strings (never floats). Guard against unbounded scans with date-range defaults and the existing indexes; add a compound index on { status: 1, confirmedAt: 1 } if the explain plan needs it.
4. Optional on-chain cross-check: an admin ?verify=true mode that spot-checks a sample of top transactions against Horizon via the existing verifyTransaction helper and flags mismatches (recorded-but-not-on-chain), reusing the reconciliation ideas from [Enhancement] Horizon payment ingestion and reconciliation worker for unreported on-chain payments #26 without duplicating the ingestion worker.
5. Caching: these are expensive read aggregations that change slowly — cache with the existing src/utils/cache.js helpers keyed by query params, invalidated on new confirmed transactions.

Acceptance criteria

• Aggregations count only status: "confirmed" and compute sums via $toDecimal, returning money as precise decimal strings (a test with fractional-cent amounts proves no float drift).
• GET /api/analytics/me/earnings returns the caller's own totals/time-series/top-items and never leaks other educators' data.
• Platform/top-educator/top-item endpoints reject unauthenticated (401) and non-admin (403) callers.
• Time-series buckets correctly by interval over [from, to], including empty buckets, using confirmedAt.
• Each list/leaderboard endpoint supports limit and date filtering and is backed by an index (verified via explain), not a full-collection scan by default.
• Jest + supertest tests seed a known set of transactions and assert exact totals, top-educator ordering, and authorization behavior; CI's Mongo service runs them for real.

Pointers

• src/models/Transaction.js (fields + existing indexes; amount is a string, status enum, confirmedAt), src/controllers/stellar/paymentController.js (getTransactionHistory as the existing single-user pattern; verifyTransaction import for the optional on-chain check), src/services/stellar/stellarService.js (verifyTransaction, getExplorerUrl), src/utils/cache.js.
• Distinct from: [Enhancement] Horizon payment ingestion and reconciliation worker for unreported on-chain payments #26 (Horizon ingestion/reconciliation worker — writes rows), [Enhancement] Educator earnings ledger and atomic batch payouts from the platform wallet #28 (earnings ledger + payouts — balances/money movement), [Enhancement] Observability: structured pino logging with request IDs, Prometheus /metrics, and slow-query logging #33 (Prometheus ops metrics, not business analytics). This issue is read-only business reporting over already-stored rows.
• Gotchas: never parseFloat a USDC amount — use $toDecimal/$sum in the pipeline. User.role has no admin value yet, so coordinate the role gate with [Enhancement] Introduce role-based authorization and fix registration privilege escalation #20. CI (.github/workflows/ci.yml) provides a real Mongo 7 service for aggregation tests. PRs target dev.

Difficulty

Medium — no protocol work, but correct decimal money aggregation, multi-dimensional pipelines with $dateTrunc/$lookup, index-aware querying, and admin authorization make it a substantial backend feature.

---

🏆 GrantFox OSS — Official Campaign | FWC26. Apply for this issue through the GrantFox campaign page. The maintainer assigns one contributor before work starts; unassigned PRs may not be reviewed. PRs target the dev branch. Quality bar: CI must stay green.

💬 Questions or need help? Reach the maintainers and other contributors on the DeenBridge Telegram: https://t.me/+nst9lXNj1wc4ZDE0

[Myart352]

Hello DeenBridge team,

I'd like to apply for this issue.

After reviewing the requirements, I understand that the main challenge is building accurate, efficient, and secure revenue analytics on top of the existing confirmed Stellar transaction data while preserving monetary precision and ensuring the endpoints remain performant.

My implementation approach would be to create a dedicated analytics service using MongoDB aggregation pipelines that operate only on status: "confirmed" transactions. I'd use $toDecimal throughout the aggregation pipeline to avoid precision loss with USDC amounts stored as strings, returning all monetary values as precise decimal strings rather than floating-point numbers. The implementation would include platform-wide analytics, educator-specific earnings, time-series reporting using $dateTrunc, top educators, top-selling items, and buyer spend summaries with flexible filtering by date range, currency, network, and result limits.

I'll also ensure proper authorization by keeping educator earnings scoped to the authenticated creator while protecting platform analytics behind an admin-only middleware aligned with the project's RBAC direction. To improve performance, I'll leverage existing indexes, add a { status, confirmedAt } compound index if needed after analyzing query plans, and cache expensive aggregation results using the project's existing cache utilities with appropriate invalidation on newly confirmed transactions.

Finally, I'll provide comprehensive Jest and Supertest coverage for authorization, aggregation accuracy, decimal precision, leaderboard ordering, time-series generation, and filtering to ensure the implementation is reliable and CI remains green.

Thank you for considering my application.

[grantfox-oss]

🦊 GrantFox — @Myart352 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #61)
2. Your PR will be reviewed by the Deen-Bridge maintainers

Good luck! Track your progress on GrantFox.