feat(yield-vault): implement guards and tests (#732–#735)

[damilareojetunde]

feat(yield-vault): Implement guard layers and tests (#732–#735)

Epic: Yield-Bearing Fee Vaults

Closes #732
Closes #733
Closes #734
Closes #735

This PR implements three guard functions and comprehensive tests for the yield_vault contract, closing issues #732, #733, #734, and #735.

---

Changes

#732 — rate_limit_deposits integration

• Added a rate_limit_deposits guard that hooks into the existing bc_forge_rate_limit module.
• Enforces a configurable per-address and global deposit rate limit using the "deposit" operation type.
• Prevents whale manipulation by rejecting deposits that exceed the configured threshold.
• Returns VaultError::RateLimited when the limit is hit.
• If no rate limit is configured, deposits pass unchecked (backward compatible).

#733 — pause_vault_deposits function

• Added ensure_not_paused guard to the deposit function that checks bc_forge_lifecycle::is_paused.
• Deposits revert with VaultError::ContractPaused when the vault is paused.
• Withdrawals are NOT affected — users can always exit, even during a pause.
• Pauser-role addresses can pause/unpause via the existing bc_forge_lifecycle module.

#734 — rescue_stuck_funds function

• Added rescue_tokens(admin, token, to, amount) — admin-only.
• Transfers any non-underlying SEP-41 token balance held by the vault to the specified recipient.
• Reverts with VaultError::CannotRescueUnderlying if the requested token matches the vault's core underlying asset (those tokens belong to depositors).
• Validates amount > 0.
• Emits a rescue event for auditability.

#735 — Deposit to mint ratio tests

Comprehensive test coverage verifying the share calculation formula:

Test	Scenario
test_deposit_to_mint_ratio_initial_deposit_1_to_1	First deposit bootstraps 1:1
test_deposit_to_mint_ratio_secondary_deposit_matches_formula	shares = assets × total_shares / total_assets
test_deposit_to_mint_ratio_after_reward_distribution	Post-reward: secondary deposit yields fewer shares per token
test_deposit_to_mint_ratio_inexact_division_floors	Floor division rounds down in protocol's favour
test_deposit_to_mint_ratio_three_users_pro_rata	Multi-user pro-rata share allocation

---

Additional Changes

• Removed yield_vault from workspace exclude in root Cargo.toml so it compiles as a workspace member.
• Updated yield_vault/Cargo.toml with dependencies: bc-forge-admin, bc-forge-lifecycle, bc-forge-rate-limit, bc-forge-ttl.
• Added cdylib crate type for WASM deployment.
• Added events.rs module with structured event emission for init, deposit, withdraw, and rescue.

---

Test Coverage

Guard	Happy Path	Error Path
Rate limit (#732)	Deposits within limit succeed	Deposit exceeding limit reverts RateLimited
Pause (#733)	Withdraw works while paused; deposit resumes after unpause	Deposit reverts ContractPaused when paused
Rescue (#734)	Non-underlying tokens rescued to recipient	Reverts CannotRescueUnderlying for underlying token; reverts for zero/negative amount; non-admin rejected
Deposit ratio (#735)	All formula scenarios pass exactly	—
Slippage	min_shares_out / min_tokens_out respected	Reverts when slippage exceeded
Edge cases	Zero supply, uninitialized, unknown addresses	InvalidAmount, InsufficientBalance, NotInitialized

---

Files Changed

File	Description
Cargo.toml	Removed yield_vault from workspace exclude
contracts/yield_vault/Cargo.toml	Added admin, lifecycle, rate-limit, ttl deps
contracts/yield_vault/src/lib.rs	Full vault implementation with 3 guards + rescue_tokens
contracts/yield_vault/src/events.rs	Structured event emission (new)
contracts/yield_vault/src/test.rs	30+ unit tests covering all issues

[drips-wave]

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