[Smart Contracts] Implement Permissionless Third-Party Top-Up & Automated Balance Refuel #1463

Overview & Background

In payroll, SaaS subscriptions, and continuous grant disbursement models, payment streams often risk premature exhaustion if the original stream creator runs low on capital, forgets to deposit additional collateral, or is temporarily unavailable. Currently, FlowFi's top_up entrypoint strictly requires the stream creator's authorization:

sender.require_auth();

This prevents external sponsors, automated treasury refuel bots (e.g., Gelato/Keepers), DAO multisigs, or affiliated parent entities from contributing funds to extend a vital stream's runway without transferring administrative ownership.

Detailed Problem Statement

1. Unintended Stream Halts in Payroll:
   • If a company's payroll wallet runs dry, team members or department leads cannot top up active employee streams from an emergency pool or subsidiary wallet.
2. Keeper / Bot Automation Incompatibility:
   • Automated keeper bots that monitor runway (e.g. "top up stream when remaining runway < 48 hours") cannot execute refuel transactions because they cannot sign on behalf of the stream's original sender.
3. Sponsorship & Grant Matching Blockers:
   • Web3 grant programs where community donors contribute matching funds directly into an active grantee stream cannot function under creator-only top-up constraints.

Technical Specification & Architecture

1. Permissionless Top-Up Entrypoint

Implement top_up_stream_from (or adjust top_up_stream) in contracts/stream_contract/src/lib.rs:

pub fn top_up_from(
    env: Env,
    funder: Address,
    stream_id: u64,
    amount: i128,
) -> Result<i128, StreamError>

2. Authorization & Accounting Invariants

• Enforce funder.require_auth().
• Validate that amount > 0.
• Load the stream via storage::load_stream(&env, stream_id).
• Enforce that the stream is active (stream.is_active == true) and not cancelled or completed.
• Transfer amount of stream.token_address from funder to the contract address via Soroban Token client.
• Update stream.deposited_amount += amount.
• Recalculate remaining runway: remaining_runway_seconds = (stream.deposited_amount - stream.withdrawn_amount) / stream.rate_per_second.
• Extend storage TTL for the stream entry.
• Save the updated stream back to persistent storage.

3. Event Emission

Emit an extended event or a dedicated StreamRefueled event in contracts/stream_contract/src/events.rs:

pub fn emit_stream_refueled(
    env: &Env,
    stream_id: u64,
    funder: &Address,
    amount: i128,
    new_total_deposited: i128,
)

4. Cancellation Refund Equity

• Ensure cancel_stream semantics maintain solvency: unvested balance refunds to the original sender (or document explicitly whether third-party funders waive claim to unvested amounts, treating top-ups as irrevocable donations to the stream principal).

Target Files

• contracts/stream_contract/src/lib.rs
• contracts/stream_contract/src/events.rs
• contracts/stream_contract/src/storage.rs
• contracts/stream_contract/src/test.rs

Acceptance Criteria

• Third-party funder can successfully top up an existing active stream using top_up_from.
• Unauthorized caller cannot spend funder tokens (enforces funder.require_auth()).
• Zero or negative amounts revert with StreamError::InvalidAmount.
• Cannot top up cancelled or completed streams (StreamError::StreamNotActive).
• Emits StreamRefueled with funder address, amount, and new total deposited balance.
• Comprehensive tests in test.rs verify multi-funder runway extension and post-refuel withdrawal consistency.