fix: handle cross-contract asset transfer failures with explicit checks (#104)

[Nanle-code]

Problem Summary

Issue #104 identified that cross-contract asset transfer failures were not properly handled, potentially leaving vault states inconsistent. Token transfer failures resulted in opaque error messages, and the code relied on implicit atomicity guarantees without documentation.

Solution Overview

This PR implements comprehensive error handling for asset transfer failures with explicit balance checks, clear error diagnostics, and documented atomicity assumptions.

Key Changes

1. Enhanced Error Handling

• New Error Variant: Error::InsufficientVaultBalance for vault-specific failures
• User Balance Checks: Pre-transfer validation in transfer_asset_to_vault
• Vault Balance Checks: Pre-transfer validation in transfer_asset_from_vault

2. Atomicity Documentation

Added explicit atomicity documentation to all functions combining state changes with external calls:

• deposit(), mint(), withdraw(), redeem()
• distribute_yield(), claim_yield(), claim_yield_for_epoch()
• refund(), redeem_at_maturity(), process_early_redemption()
• emergency_withdraw(), emergency_claim()

3. Frontend Integration

• New Public Function: vault_asset_balance() for solvency verification
• Enables off-chain validation before transaction submission

4. Comprehensive Testing

Added 8 new test functions covering all insufficient balance scenarios:

• Vault balance failures in withdraw/redeem/claim operations
• User balance failures in deposit/mint operations
• Emergency claim scenarios
• Public view function validation

Security Benefits

• No Inconsistent States: Explicit balance checks prevent vault corruption
• Clear Failure Modes: Distinguish expected vs unexpected failures
• Documented Guarantees: Atomicity assumptions explicitly documented
• Frontend Protection: Pre-transaction solvency verification

Definition of Done

• ✅ Every external call has documented atomicity behavior
• ✅ Vault balance is pre-checked before outgoing transfers
• ✅ Typed error for insufficient vault balance
• ✅ Public view function exposes raw vault balance
• ✅ Tests simulate insufficient vault balance scenario

Testing

All new tests pass and verify proper error handling without state corruption. The implementation maintains backward compatibility while providing enhanced safety and clarity.

Files Modified

• src/lib.rs - Core implementation changes
• src/errors.rs - New error variant
• src/test_insufficient_balance.rs - New comprehensive test suite

This implementation fully addresses the core issue of cross-contract asset transfer failures and ensures vault state consistency under all failure scenarios.

Closes #104

[drips-wave]

@Nanle-code 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