docs: add NatSpec-style rustdoc to betting public entrypoints

[Phantomcall]

Adds comprehensive NatSpec-style rustdoc to every public function in the betting module (contracts/predictify-hybrid/src/bets.rs) and introduces 28 focused unit tests covering the documented behavior.

Closes #921

---

Motivation

The betting module is a critical surface area of the Predictify smart contract. Public entrypoints lacked consistent # Parameters, # Returns, and # Errors sections, making it harder for auditors, integrators, and future contributors to understand the API contract at a glance.

This PR brings the betting module in line with the NatSpec-style rustdoc standard already established in lib.rs.

---

Changes

Rustdoc enhancements (530 lines added, 103 removed)

All public functions, structs, and module-level items in bets.rs now include:

Section	Coverage
# Parameters	Every public function
# Returns	Every function with a return value
# Errors	Every fallible function
# Security	Security-relevant entrypoints (place_bet, cancel_bet)

Functions updated:

• Standalone: get_effective_bet_limits, set_global_bet_limits, set_event_bet_limits, set_market_max_bet_cap, remove_market_max_bet_cap, get_market_max_bet_cap
• BetManager: get_live_fee_percentage, place_bet, place_bets, has_user_bet, get_bet, get_market_bet_stats, resolve_market_bets, refund_market_bets, calculate_bet_payout, cancel_bet
• BetStorage: store_bet, get_bet, remove_bet, get_market_bet_stats, store_market_bet_stats, get_all_bets_for_market
• BetValidator: validate_market_for_betting, effective_bet_deadline, validate_bet_parameters, validate_bet_amount_against_limits, validate_bet_amount, validate_fee_slippage, get_max_bet_cap, set_max_bet_cap, get_user_stake, update_user_stake, validate_user_stake_under_cap
• BetUtils: lock_funds, unlock_funds, get_contract_balance, has_sufficient_balance
• BetAnalytics: calculate_implied_probability, calculate_payout_multiplier, get_market_summary

Struct-level docs also updated for BetManager, BetStorage, BetValidator, BetUtils, and BetAnalytics.

Focused tests (28 new tests)

Test	What it covers
test_get_effective_bet_limits_returns_defaults_when_empty	Default limits when no config stored
test_get_effective_bet_limits_prefers_per_event_over_global	Per-event > global priority
test_get_effective_bet_limits_falls_back_to_global	Global fallback when no per-event
test_set_global_bet_limits_rejects_min_gt_max	Invalid bounds rejection
test_set_global_bet_limits_rejects_below_absolute_min	Absolute min enforcement
test_set_global_bet_limits_rejects_above_absolute_max	Absolute max enforcement
test_set_event_bet_limits_persists_and_retrieves	Round-trip persistence
test_set_market_max_bet_cap_and_get	Set/get lifecycle
test_set_market_max_bet_cap_rejects_zero	Zero cap rejection
test_set_market_max_bet_cap_rejects_negative	Negative cap rejection
test_set_market_max_bet_cap_rejects_exceeding_max	Over-max cap rejection
test_remove_market_max_bet_cap	Remove lifecycle
test_bet_analytics_implied_probability_empty_market	Empty market returns 0
test_bet_analytics_implied_probability_with_data	75/25 split = 75% implied
test_bet_analytics_payout_multiplier_empty_outcome	No bets = 0 multiplier
test_bet_analytics_payout_multiplier_with_data	Pool/outcome = correct multiplier
test_bet_analytics_get_market_summary_delegates	Summary matches stored stats
test_bet_storage_store_and_get_roundtrip	Store -> get consistency
test_bet_storage_remove_bet	Remove = None
test_bet_storage_get_all_bets_for_market_empty	Empty registry returns 0
test_bet_storage_get_all_bets_for_market_multiple	Multiple bettors registered
test_effective_bet_deadline_zero_falls_back_to_end_time	0 = end_time
test_effective_bet_deadline_uses_explicit_value	Explicit deadline honored
test_effective_bet_deadline_rejects_after_end_time	Deadline > end_time rejected
test_validate_bet_amount_against_limits_uses_per_event	Per-event min/max enforcement
test_validate_bet_amount_against_limits_enforces_market_cap	Per-market cap enforcement

---

Testing

Note: The repository has pre-existing compilation errors on the master branch that are unrelated to this PR. These errors exist in lib.rs, err.rs, oracle_health.rs, and other files. The full test build cannot complete due to these pre-existing issues.

All changes are confined to contracts/predictify-hybrid/src/bets.rs and are pure documentation + test additions with no runtime code changes.

---

Acceptance Criteria

• NatSpec-style /// rustdoc on every public fn in bets.rs
• # Parameters, # Returns, # Errors sections where applicable
• 28 focused unit tests added
• No runtime code changes (docs-only + tests)
• No unwrap() in production paths
• Overflow-safe math preserved
• require_auth() documented on every state-changing entrypoint

---

Files Changed

File	Lines
contracts/predictify-hybrid/src/bets.rs	+530 / -103

[drips-wave]

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

[greatest0fallt1me]

Merged via direct push to master (admin)