feat: implement market comment API with pagination, thumbs-up, and ad…

[Grace-CODE-D]

…min moderation

Automated Market Settlement Logic (#11)

Description

Implements the automated market settlement logic that processes an Oracle's "Result" and calculates winning shares with precise fixed-point arithmetic.

Changes

New Files

• contracts/prediction_market/src/settlement_math.rs - Settlement math module with fixed-point arithmetic
• docs/math_spec.md - Mathematical specification and payout formula documentation

Modified Files

• contracts/prediction_market/src/lib.rs - Added distribute_rewards() and get_settlement_info() functions

Key Features

Fixed-Point Arithmetic

• Uses 7 decimal places of precision (10^7) for calculations
• No floating-point operations to avoid precision loss
• All monetary values stored as integers

Payout Formula

payout_pool = floor(total_pool × 97 / 100)  // 3% platform fee
individual_payout = floor(bet_amount × payout_pool / winning_stake)

Dust Handling

The implementation ensures 100% conservation by redistributing dust (remainder from integer division):

1. Calculate ideal payouts using integer division
2. Track dust: dust = payout_pool - sum(payouts)
3. Redistribute dust in 1-unit increments to first N winners

Market State Transition

• resolve_market() transitions market from Locked → Resolved
• distribute_rewards() executes payout calculation and transfers

Testing

All 15 tests passing:

• test_platform_fee - 3% fee calculation
• test_payout_pool - 97% payout pool calculation
• test_basic_payout - Single and multiple bettor scenarios
• test_exact_division - Cases with no dust
• test_dust_redistribution - Dust handling verification
• test_zero_winning_stake - Edge case handling
• test_large_amounts - Real XLM amount simulation
• test_conservation_property - All payouts sum to payout_pool

Documentation

See docs/math_spec.md for:

• Payout formula derivation
• Dust handling algorithm explanation
• Conservation property proof
• Edge case handling
• Security considerations

Related Issues

Closes #635

[drips-wave]

@Grace-CODE-D 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