feat(contracts): fix FIFO withdrawal queue persistence on-chain by returning Ok(0) instead of reverting Err

[Amas-01]

Pull Request Description

Overview

This PR implements Cross-Strategy Exposure Cap Validation (#741) and the Emergency Guardian Role (#739) for the YieldVault-RWA contract suite. It also resolves critical regressions in the FIFO withdrawal queue integration tests, ensuring all state transitions and storage modifications are safely persisted on-chain.

Closes

• Closes Contracts: Add cross-strategy exposure cap validation before rebalance commit #741
• Closes Contracts: Add emergency guardian role with narrowly scoped pause permissions #739

Changes Made

1. Core Contract Changes (contracts/vault/src/lib.rs)

• Aggregate Exposure Cap Validation: Validates that any rebalance or investment operation across all strategies does not exceed the aggregate exposure cap configured for the vault.
• Emergency Guardian Role: Integrates a designated guardian role with restricted pause/unpause permissions to quickly halt key vault operations (deposits, withdrawals, rebalances) in case of emergencies without needing full admin keys.
• Withdrawal Queue Persistence Fix: Modified enqueue_withdrawal_for_liquidity to return Ok(0) instead of Err(VaultError::WithdrawalQueued). Returning an Err in Soroban causes a full transaction rollback, which was discarding the enqueued queue state. Returning Ok(0) successfully persists the queue entry to storage.
• no_std Compliance: Cleaned up internal debug std::println! statements from the contract to ensure successful compilation under #![no_std].

2. Test Suite Enhancements (contracts/vault/src/test.rs)

• Queue Test Stabilization: Updated test_withdrawal_queue_processes_fifo_when_liquidity_returns and test_withdrawal_queue_stops_when_liquidity_insufficient_for_head to expect Ok(Ok(0)) on queueing.
• Corrected Test Liquidity: Adjusted the mock divestment amount in the queue-stop test to 450 USDC to ensure exactly enough liquidity (500 USDC) is available to process the first queued withdrawal while blocking the second, successfully verifying the strict FIFO queue termination behavior.

Verification & Testing

All integration and unit tests built and ran successfully.

cargo test

Output summary:

running 221 tests
...
test test::test_withdrawal_queue_processes_fifo_when_liquidity_returns ... ok
test test::test_withdrawal_queue_stops_when_liquidity_insufficient_for_head ... ok
test result: ok. 221 passed; 0 failed; 0 ignored;

[drips-wave]

@Amas-01 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