feat: per-token vault reserve cap

[Fury03]

Closes #524

---

Summary

• Adds a per-token reserve cap to the Callora Vault so deposits are rejected when they would push the vault's tracked balance past an owner-configured ceiling.
• Introduces contracts/vault/src/limits.rs (new module per the issue spec) with set, get, and check helpers.
• New public entrypoints: set_reserve_cap(caller, token, cap) (owner-only) and get_reserve_cap(token) (view).
• New error code 37 (ExceedsReserveCap) and event topic reserve_cap_set.

Changes

File	Type	Notes
contracts/vault/src/limits.rs	New	Per-token cap storage, retrieval, and deposit guard
contracts/vault/src/lib.rs	Modified	StorageKey::ReserveCap, VaultError::ExceedsReserveCap, set_reserve_cap, get_reserve_cap, deposit guard call
contracts/vault/src/events.rs	Modified	event_reserve_cap_set topic
contracts/vault/src/test_reserve_cap.rs	New	17 focused tests
contracts/vault/src/test_error_codes.rs	Modified	Stability snapshot extended to codes 35–37
docs/ERROR_CODES.md	Modified	Codes 35–37 documented

Security & Design

• set_reserve_cap calls caller.require_auth() and require_owner before any state write.
• The cap check sits in the Checks phase of deposit(), before the Effects block, consistent with CEI ordering.
• All arithmetic uses checked_add — no unwrap() on production paths.
• Default cap is i128::MAX (fast-path skip), so existing vaults behave identically until a cap is explicitly set.
• Withdrawals and deductions are unaffected by the cap.

Test plan

• get_reserve_cap_returns_max_when_not_set — default is unlimited
• set_reserve_cap_stores_value / set_reserve_cap_can_be_updated — happy path
• set_reserve_cap_to_max_restores_unlimited — removing cap
• set_reserve_cap_rejects_zero / set_reserve_cap_rejects_negative — validation
• set_reserve_cap_requires_owner — auth guard
• set_reserve_cap_is_per_token — caps isolated per token address
• set_reserve_cap_emits_event / set_reserve_cap_event_includes_previous_value — event correctness
• deposit_succeeds_when_no_cap_set — no regression when uncapped
• deposit_succeeds_when_below_cap / deposit_succeeds_at_exact_cap — boundary pass
• deposit_fails_when_exceeds_cap — boundary reject
• deposit_fails_when_cumulative_total_exceeds_cap — cumulative enforcement
• deposit_succeeds_again_after_cap_raised — cap increase unblocks deposits
• deposit_at_one_above_cap_fails — off-by-one boundary
• reserve_cap_does_not_affect_withdrawal — cap is deposit-only

[drips-wave]

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