feat: implement treasury stream cancellation and recovery

[web3nova]

🔄 Treasury Stream Cancellation & Recovery Rules

Closes #859

📋 Description

Implements safe cancellation and recovery mechanisms for active treasury streams on testnet. This addresses the need for stream administrators to cancel allocations with deterministic refund calculations and emergency stop capabilities.

✨ Features

cancel_stream(admin, beneficiary)

• Cancels an active stream while honoring partial claims
• Calculates unlocked (claimable) amount based on elapsed time
• Refunds remaining balance to beneficiary
• Returns tuple: (claimed_amount, refunded_amount)
• Deterministic: claimed + refunded = original_allocation
• Emits StreamCancelled event with full context
• Removes stream from storage after cancellation

emergency_stop(admin, beneficiary, reason)

• Immediately halts stream and returns full allocated amount
• Does NOT honor partial vesting - full refund regardless of progress
• Useful for security incidents or contract anomalies
• Returns full refunded amount
• Emits EmergencyStop event with reason string
• Removes stream from storage

✅ Acceptance Criteria

• Treasury supports cancellation or emergency stop semantics for active streams
• Remaining claimable and refunded amounts are deterministic
• Events are emitted for cancellation and recovery actions
• Tests cover partial-claim and cancellation edge cases

🧪 Test Coverage

5 comprehensive test cases:

1. test_cancel_stream_partial_claim

   • Allocate stream, claim 50%, cancel and verify remaining refunded
   • Validates: claimed_total = 500, refunded = 500

2. test_cancel_stream_immediate

   • Cancel immediately with no vesting elapsed
   • Validates: claimed = 0, refunded = full_amount

3. test_cancel_stream_after_full_vesting

   • Cancel after vesting period complete
   • Validates: claimed = full_amount, refunded = 0

4. test_emergency_stop_full_refund

   • Emergency stop at 50% vesting
   • Validates: full_amount refunded (not partial)

5. test_cancel_nonexistent_stream

   • Attempt cancel on non-existent beneficiary stream
   • Validates: Proper error handling with StreamNotFound

🔒 Security Considerations

• Admin authorization required for both operations
• Stream data properly deleted after cancellation
• Refund amounts calculated deterministically (no rounding errors)
• No re-entrancy issues - single contract interaction per operation
• Events emitted before state modifications

📊 Determinism Guarantees

For any stream state at time T:

[drips-wave]

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