Add vault invariants, risk limits, oracle failure tests, and nightly benches

[amanosiadnan-cmyk]

closes #1166
closes #1173
closes #1231
closes #1235

PR description

Summary

This PR hardens YieldVault accounting and exposure, then adds the oracle failure suite and nightly contract benchmarks. The repo is Stellar/Soroban (Rust), not EVM, so Foundry/Anvil acceptance criteria are implemented with Soroban Env tests, mock oracles, host CPU/memory metering, and GitHub Actions.

---

#1166 — Contract-level total-supply and share-price invariants

Vault accounting is now checked before VaultState is persisted, not only in off-chain tests.

Invariants (enforced in persist_accounting_state):

• total_shares >= 0 and total_assets >= 0
• No unbacked shares (total_shares > 0 ⇒ total_assets > 0)
• Empty vault ⇒ share price 0
• Non-empty vault ⇒ share_price == floor(total_assets * 10^18 / total_shares) and > 0

Broken snapshots return VaultError::MathOverflow (error enum is capped at 50 cases). Donated assets with zero shares remain allowed.

Hooks: deposit, gasless_deposit, batch_deposit, withdraw, queued withdraw, accrue_yield, report_benji_yield.

Tests: unit violation snapshots in invariants.rs; transition/regression coverage in invariant_tests.rs.
Docs: docs/VAULT_INVARIANTS.md

---

#1173 — Protocol-level risk limits for vault exposure

Hard caps on top of per-strategy StrategyCap / StrategyRiskThreshold. Defaults are unlimited so existing flows stay unchanged.

Cap	Default	Enforced on
Max vault TVL	0 (off)	deposit / gasless / batch
Max strategy concentration	100%	invest, rebalance
Max deployed capital	100%	invest, rebalance
Stress concentration / deployed	50% / 70%	same, when stress mode is on

Stress mode uses min(normal, stress) so it can only tighten. Overrun then recover: withdraw (TVL) or divest (concentration), then the same op is allowed again.

Overrides (documented, no force-invest backdoor):

1. Admin raises caps (set_max_vault_tvl, set_max_conc_bps, set_max_deployed_bps); TVL 0 = unlimited
2. Admin turns off stress mode after volatility
3. Reduce exposure first, then retry
4. Pause (LiquidityCrisis / OracleFailure) as a full halt

Storage is nested under DataKeyExt::Risk(RiskExtKey) to stay within Soroban key limits.

Tests: overrun + recovery for TVL, strategy cap, concentration, and stress-mode override.
Docs: docs/PROTOCOL_RISK_LIMITS.md

---

#1235 — Oracle failure test suite

Mock oracle failure modes: stale heartbeat, zero/negative price, invalid decimals, deviation spike (3×), future timestamp, network partition, timeout.

Vault wiring:

• Last validated price cached for the 50% deviation breaker
• Cache cleared on execute_price_oracle_change
• Fail-closed: bad/missing feed aborts total_assets (and thus invest)

Tests: validator edge cases + mock oracle wired into the vault (cargo test -p vault oracle); mock crate tests all pass (cargo test -p mock-strategy → 6/6).
Docs: docs/ORACLE_FAILURE_HANDLING.md (classify → halt → rotate/resume; no stale-price fallback)

---

#1235 — Nightly contract benchmarks

Soroban equivalent of forge test --gas-report:

• contracts/vault/tests/benchmarks.rs measures host CPU/memory for deposit, withdraw, invest, switch strategy on two Benji strategy instances (v1 vs v2)
• contracts/vault/scripts/benchmark.sh parses BENCH lines, writes the report, fails if any op exceeds baseline + 15%
• .github/workflows/nightly-benchmarks.yml runs at 02:00 UTC, uploads the summary, and posts/comments a GitHub Issue (nightly-benchmark)

Docs: docs/PERFORMANCE_REGRESSION.md
Baseline: contracts/vault/benches/baseline.json

---

How to verify

cargo test -p mock-strategy
cargo test -p vault invariant
cargo test -p vault risk_limits
cargo test -p vault oracle
bash contracts/vault/scripts/benchmark.sh

[drips-wave]

@amanosiadnan-cmyk 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

[Junirezz]

Resolved merge conflicts and merged via local rebase. Content is now on main.