feat: implemented Enhance GET /savings/my-subscriptions via Live RPC sync

[Ugasutun]

Closes #408

PR Description - Issue #408: Enhance GET /savings/my-subscriptions via Live RPC Sync

Summary

Enhances the savings subscriptions endpoint to synthesize indexed cache with live RPC evaluations for perfect accuracy, mitigating indexer lag issues.

Background & Context

• Issue: [Backend] Enhance GET /savings/my-subscriptions via Live RPC sync #408 - [Backend] Enhance GET /savings/my-subscriptions via Live RPC sync
• Purpose: When a user loads the dashboard, the balance needs to be correct to the absolute current block, mitigating any indexer lag (e.g. indexer is 5 seconds behind, but the user just deposited).
• Acceptance Criteria:
  • Fetch the user's UserSubscription instances from the DB
  • Loop subscriptions and query the RPC (invokeContractRead) asking for the user's balanceOf in those vault contracts
  • Return the live bounds, allowing the DB to strictly serve as a fast placeholder cache

Changes Made

Files Modified:

1. backend/src/modules/savings/savings.service.ts
   • Enhanced findMySubscriptions() method (lines 215-281)
   • Added UserSubscriptionWithLiveBalance interface (lines 29-35)
   • Added helper methods: mapSubscriptionWithLiveBalance(), resolveVaultContractId()

Implementation Details

Interface: UserSubscriptionWithLiveBalance

export interface UserSubscriptionWithLiveBalance extends UserSubscription {
  indexedAmount: number;       // DB cached amount
  liveBalance: number;         // Live RPC balance (XLM)
  liveBalanceStroops: number;  // Live RPC balance (stroops)
  balanceSource: 'rpc' | 'cache';  // Source of balance
  vaultContractId: string | null;  // Contract used for RPC call
}

Process Flow (findMySubscriptions):

1. Fetch Subscriptions: Get all UserSubscription instances from DB for user
2. Get User PublicKey: Retrieve user's Stellar public key
3. Loop Subscriptions: For each subscription:
   • Resolve vault contract ID (from subscription or product)
   • Call blockchainSavingsService.getUserVaultBalance(contractId, userPublicKey) via RPC
   • Map live balance with indexed amount as fallback
4. Return Live Data: Return subscriptions with live balances from RPC

RPC Integration

• Uses blockchainSavingsService.getUserVaultBalance() to query live vault balance
• Falls back to DB cache (subscription.amount) when:
  • User has no public key
  • No vault contract ID available
  • RPC call fails
• Indicates balance source via balanceSource: 'rpc' | 'cache'

Example Response

[
  {
    "id": "sub-123",
    "userId": "user-456",
    "productId": "prod-789",
    "amount": "1000",
    "status": "ACTIVE",
    "indexedAmount": 1000,
    "liveBalance": 1050.50,
    "liveBalanceStroops": 10505000000,
    "balanceSource": "rpc",
    "vaultContractId": "CA...",
    ...
  }
]

Key Features

• Perfect Accuracy: Live RPC balance overrides potentially stale indexer data
• Graceful Fallback: Falls back to DB cache if RPC fails or no public key
• Performance: Uses Promise.all for parallel RPC calls
• Transparency: Indicates whether balance came from 'rpc' or 'cache'

Checklist

• Fetch UserSubscription instances from DB
• Loop subscriptions and query RPC for balanceOf
• Return live balances, using DB as fallback cache
• Include indexedAmount for comparison
• Track balanceSource indicator
• Handle missing publicKey gracefully

Target Branch

• Branch: feature/live-rpc-savings-subscriptions
• 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 29, 2026 2:50pm