feat: implemented Executable Global TVL Background Snapshot Cron

[Ugasutun]

Closes #415

PR Description - Issue #415: Executable Global TVL Background Snapshot Cron

Summary

Implements a daily cron job that snapshots the global Total Value Locked (TVL) at 12:00 UTC and stores it in the ProtocolMetrics table for historical tracking and charting.

Background & Context

• Issue: [Backend] Executable Global TVL Background Snapshot Cron #415 - [Backend] Executable Global TVL Background Snapshot Cron
• Purpose: Drawing full protocol charts spanning the lifetime of Nestera requires daily global snapshoting stored structurally in the DB.
• Acceptance Criteria:
  • Create @Cron('0 0 12 * * *') inside admin-analytics.service.ts
  • Iterate every SavingsProduct, fetching absolute smart contract total_assets
  • Multiply those assets cleanly against the oracle.service.ts prices to determine absolute Net USD value locked in the protocol today
  • DB insertion into ProtocolMetrics table

Changes Made

Files Modified:

1. backend/src/modules/admin-analytics/admin-analytics.service.ts
   • Added snapshotGlobalTvl() cron method (lines 70-172)
   • Scheduled to run daily at 12:00 UTC
   • Fetches all active SavingsProducts
   • Gets total assets from each smart contract via savingsService
   • Converts to USD using oracle prices
   • Stores snapshot in ProtocolMetrics table

Implementation Details

Cron Schedule

@Cron('0 0 12 * * *')  // Runs at 12:00 UTC every day

Process Flow:

1. Fetch Active Savings Products: Retrieves all active savings products from DB
2. Get XLM Price: Fetches current XLM price from oracle service
3. Iterate Products: For each product with a contractId:
   • Calls savingsService.getVaultTotalAssets(contractId)
   • Converts stroops to XLM
   • Multiplies by XLM price to get USD value
4. Calculate Total: Sums up all product values for global TVL
5. Store Snapshot: Inserts record into ProtocolMetrics table

Data Stored in ProtocolMetrics:

{
  snapshotDate: Date,
  totalValueLockedUsd: number,
  totalValueLockedXlm: number,
  savingsProductCount: number,
  productBreakdown: Record<string, {
    name: string,
    type: string,
    contractId: string,
    totalAssetsStroops: number,
    totalAssetsXlm: number,
    totalAssetsUsd: number
  }>
}

Example Output

Global TVL snapshot completed: 50000 XLM ($35000.00)

Testing

• Cron method handles edge cases:
  • No active savings products (logs warning)
  • Failed oracle price fetch (aborts snapshot)
  • Individual product failures (logs error, continues)
• Each product's assets are converted: stroops → XLM → USD

Checklist

• @Cron('0 0 12 * * *') scheduled inside admin-analytics.service.ts
• Iterates every SavingsProduct with contractId
• Fetches total_assets from smart contracts
• Multiplies assets against oracle prices (XLM → USD)
• Inserts snapshot into ProtocolMetrics table
• Handles errors gracefully and continues on individual failures
• Logs progress for monitoring

Target Branch

• Branch: feature/global-tvl-snapshot-cron
• Target: main

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nestera	Ready	Preview, Comment	Mar 27, 2026 10:01pm

[drips-wave]

@Ugasutun Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits