Pull Request: Add calculate_total_earned_by_creator Helper (#59, #12)

[JerryIdoko]

📝 Description
This PR implements a much-needed read-only helper function to aggregate real-time earnings for creators. Previously, the frontend had to perform multiple RPC calls to iterate through individual fan streams, which was non-scalable and prone to "stale data" lag.

The new calculate_total_earned_by_creator function performs this aggregation on-chain, utilizing the current ledger timestamp to provide an up-to-the-second "Unclaimed Balance" for any given creator address.

🎯 Key Changes
Aggregation Logic: Iterates through the CreatorSubscriptionMap to sum all "streamed but not yet withdrawn" funds.

Timestamp-Aware Calculation: Uses env.ledger().timestamp() to calculate flow rates dynamically, ensuring the value displayed to the creator is exactly what they would receive if they clicked "Withdraw" at that moment.

Gas-Efficient Read: Optimized as a getter to minimize resource consumption during RPC calls.

Precision: Maintained 7-decimal precision (stroops) to ensure no fractional XLM is lost during the calculation.

💻 Logic Highlight: Real-Time Accrual
The core math follows a linear flow model:

Rust
pub fn calculate_total_earned_by_creator(e: Env, creator: Address) -> i128 {
let current_time = e.ledger().timestamp();
let mut total_unclaimed: i128 = 0;

// Iterate through active streams linked to this creator
for stream in e.storage().instance().get::<Address, Vec<Stream>>(&creator).unwrap_or(vec![&e]) {
    let elapsed = current_time.saturating_sub(stream.last_withdrawal_time);
    let earned = (elapsed as i128) * stream.tokens_per_second;
    total_unclaimed += earned;
}

total_unclaimed

}
✅ Acceptance Criteria Checklist
[x] Real-Time Accuracy: Verified that the value updates correctly as the ledger timestamp progresses in tests.

[x] Unclaimed Only: The function correctly ignores funds that have already been moved to the creator's wallet.

[x] Frontend Ready: Tested via Soroban-CLI to ensure the return format is easily consumable by the dashboard.

[x] Scalability: Verified that the loop performs efficiently even when a creator has a high volume of active subscribers.

🚀 How to Verify
Run the Test Suite:

Bash
cargo test test_unclaimed_balance_aggregation
Simulate via CLI:

Bash
soroban contract invoke --id [CONTRACT_ID] --source [CREATOR_KEY] --fn calculate_total_earned_by_creator -- --creator [CREATOR_ADDRESS]
🔗 Linked Issues
Closes #59
Closes #12

[drips-wave]

@JerryIdoko 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