feat: add get_position read-only view function

[minorkime-design]

Closes #317
Adds a public read-only get_position() function to query user positions in markets without modifying contract state.

Function Signature

pub fn get_position(
env: Env,
market_id: u32,
user: Address,
) -> Result<Optioncrate::types::Position, ContractError>

Purpose

Provides off-chain and on-chain clients with a clean, read-only view of:

• User's current share balances (YES/NO)
• Locked collateral backing current position
• Historical deposit data
• Settlement status

Returns

• Ok(Some(Position)): User has a position in the market with:

  • yes_shares: Number of YES shares held
  • no_shares: Number of NO shares held
  • locked_collateral: Collateral locked to back shares
  • total_deposited: Total collateral ever deposited
  • is_settled: Whether position has been settled

• Ok(None): User has no position in this market

• Err(ContractError::UpgradeRequired): Storage version mismatch

Documentation

Comprehensive docstring includes:
✓ Function description and purpose
✓ Full argument documentation
✓ Return value documentation
✓ Error cases
✓ Usage example with pattern matching

Use Cases

✓ Query position for UI display
✓ Check shares and collateral for trading calculations ✓ Verify settlement status
✓ Off-chain position tracking and analytics

Features

✓ Read-only: No state modification (safe for querying)
✓ Optional Result: Gracefully handles non-existent positions
✓ Version-checked: Ensures storage compatibility
✓ Well-documented: Clear docstring with examples
✓ Consistent API: Matches pattern of other get_* functions

Implementation

✓ Delegates to storage::get_position()
✓ Properly qualified return type with crate::types::Position ✓ Positioned logically after get_outcome_count()
✓ Follows existing code style and patterns
✓ No breaking changes (additive only)

Files Modified

• contracts/market/src/lib.rs: Added get_position() function (33 lines)

Summary

Clean, read-only accessor for querying user positions in markets. Enables client applications to safely inspect position data without state modification. Follows existing patterns and includes comprehensive documentation.

Total: 33 lines added