feat(contracts): add read-only view functions to all contract modules

[SaintSammi]

Closes #433

PR Description

feat(giveaway): add read-only view functions

Summary

Adds read-only view functions to all contract modules (giveaway, admin, mutual_aid) to enable off-chain clients to query contract state without manually decoding raw storage keys.

Changes

Giveaway Module (contracts/geev-core/src/giveaway.rs)

• ✅ get_giveaway(giveaway_id: u64) -> Option<Giveaway> - Retrieve complete giveaway data
• ✅ get_winners(giveaway_id: u64) -> Vec<Address> - Get list of winners for a giveaway
• ✅ get_participants(giveaway_id: u64) -> Vec<Address> - Get all participants in a giveaway
• ✅ has_claimed(giveaway_id: u64, winner: Address) -> bool - Check if winner has claimed their prize

Admin Module (contracts/geev-core/src/admin.rs)

• ✅ get_collected_fees() -> i128 - View total collected platform fees

Mutual Aid Module (contracts/geev-core/src/mutual_aid.rs)

• ✅ get_all_requests() -> Vec<(u64, Request)> - Retrieve all mutual aid requests
• ✅ is_open(request_id: u64) -> bool - Check if request is open
• ✅ is_completed(request_id: u64) -> bool - Check if request is completed

Testing

• Added 7 comprehensive tests for giveaway view functions covering:
  • Populated giveaways
  • Empty/missing giveaway IDs
  • Winner and participant lists
  • Claim status checks
• All tests passing (171 tests total)
• Fixed unused variable warnings in test suite

Documentation

• Updated contracts/README.md with full API documentation for all new view functions
• Added usage examples and return type specifications

Benefits

• No more storage layout duplication: Frontend and indexer can use contract views instead of reimplementing storage decoding
• Future-proof: Changes to DataKey or storage structs won't break off-chain clients
• Consistent API: Mirrors existing patterns from other modules (e.g., get_profile, get_request)
• Safe: All getters are read-only, never panic, and return Option/empty Vec for missing data

Breaking Changes

None - this is purely additive functionality

Branch

feat/giveaway-view-functions