Pull Request: Implement Automatic Tier Migration Logic (#58, #13)

[JerryIdoko]

📝 Description
This PR introduces the migrate_tier function to the SubStream core contracts. This feature allows users to upgrade or downgrade their subscription tiers in a single atomic transaction, solving the "double-start" bug where multiple streams could overlap.

The core of this update is the Pro-Rated Settlement Engine, which calculates exactly how much a creator has earned from the old tier since the last checkpoint, settles that amount, and then instantly pivots the stream to the new tier's flow rate.

🎯 Key Changes
Atomic Migration: Combined the stop_stream(old_tier) and start_stream(new_tier) logic into a single internal function to ensure no funds are lost or double-charged.

Real-time Pro-rating: Implemented a calculation based on env.ledger().timestamp() to settle the "unclaimed" portion of the current tier before moving the user to the new one.

Vault Integration: Automated the transfer of the final old-tier settlement to the creator's vault during the migration call.

Validation Guards: Added checks to ensure the user has sufficient balance for the first "pulse" of the new, higher-tier stream.

💻 Implementation
Detail: Pro-Rated SettlementThe transition logic follows this strict sequence to maintain ledger integrity:Capture Timestamp: Get current ledger time $T_{now}$.Calculate Accrued: $Earnings = (T_{now} - T_{last_checkpoint}) \times \text{Old_Flow_Rate}$.Settle Old Tier: Transfer $Earnings$ to Creator and close Old Stream.Initiate New Tier: Open New Stream starting at $T_{now}$ with $\text{New_Flow_Rate}$.

✅ Acceptance Criteria Checklist
[x] Single Transaction: Users can migrate tiers with one click/call.

[x] No Overlap: Verified that the old stream is invalidated before the new one is registered.

[x] Exact Settlement: Pro-rated earnings are calculated to the second and sent to the creator's vault.

[x] Test Coverage: Added edge-case tests for migrating exactly at the start of a ledger or during high network congestion.

🚀 How to Verify
Integration Test:

Bash
cargo test test_tier_migration_pro_rating
Manual Verification:
Start a "Bronze" stream, wait 60 seconds, call migrate_tier to "Gold", and verify that the creator received exactly 60 seconds worth of "Bronze" pay before the "Gold" rate kicked in.

🔗 Linked Issues
Closes #58
Closes #13

[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