test: market lifecycle stateful fuzzing

contracts/predictify-hybrid/Cargo.toml

@@ -26,6 +26,10 @@ wee_alloc = "0.4.5"
 name = "err_stability"
 path = "tests/err_stability.rs"
 
+[[test]]
+name = "stateful"
+path = "tests/stateful.rs"
+
 [dev-dependencies]
 soroban-sdk = { workspace = true, features = ["testutils"] }
 proptest = "1.4"

contracts/predictify-hybrid/PR_STATEFUL_FUZZING.md

@@ -0,0 +1,263 @@
+# PR Summary: Market Lifecycle Stateful Fuzzing
+
+## Overview
+
+This PR implements comprehensive stateful property-based testing for the Predictify Hybrid prediction market contract lifecycle using `proptest`. The test suite validates invariants, discovers edge cases, and ensures correctness across arbitrary operation sequences.
+
+## Changes
+
+### New Files
+
+1. **`tests/stateful.rs`** (885 lines)
+   - Complete stateful fuzzing infrastructure
+   - TestState and MarketModel for state tracking
+   - Six operation types (CreateMarket, PlaceVote, PlaceBet, AdvanceTime, ResolveMarket, ClaimWinnings)
+   - Invariant validation framework
+   - Three property-based tests
+   - Three unit tests
+
+2. **`STATEFUL_FUZZING_README.md`** (272 lines)
+   - Comprehensive documentation
+   - Usage guide and examples
+   - Invariant descriptions
+   - Troubleshooting guide
+
+### Modified Files
+
+1. **`Cargo.toml`**
+   - Added `[[test]]` section for stateful test target
+   - Registers `tests/stateful.rs` as independent test binary
+
+## Implementation Details
+
+### Test Architecture
+
+```
+TestState
+├── Soroban Environment
+├── Contract & Token Addresses
+├── Admin & User Addresses
+├── Market Models (Expected State)
+└── Balance Tracking
+
+Operations (Proptest Strategies)
+├── CreateMarket
+├── PlaceVote
+├── PlaceBet
+├── AdvanceTime
+├── ResolveMarket
+└── ClaimWinnings
+
+Invariants
+├── State Transition Validity
+├── Outcome Consistency
+├── Stake Non-Negativity
+├── Vote/Bet Exclusivity
+└── Claim Ordering
+```
+
+### Key Features
+
+#### 1. Stateful Test Model
+- Tracks expected state alongside actual contract state
+- Validates invariants after every operation
+- Detects violations immediately
+
+#### 2. Property-Based Testing
+- **test_market_lifecycle_invariants**: Validates invariants across 1-20 random operations (100 cases)
+- **test_state_transitions**: Verifies time-based state transitions
+- **test_idempotency**: Ensures duplicate operations are handled correctly
+
+#### 3. Operation Fuzzing
+- CreateMarket: 1-30 days duration, 2-4 outcomes
+- PlaceVote/PlaceBet: Random users, markets, outcomes, stakes (1-1000 XLM)
+- AdvanceTime: 1-60 days forward
+- ResolveMarket: Random winning outcome
+- ClaimWinnings: Random users and markets
+
+#### 4. Invariant Validation
+Five critical invariants checked after each operation:
+1. **State Transition Validity**: Only legal state changes
+2. **Outcome Consistency**: Resolved markets have valid outcomes
+3. **Stake Non-Negativity**: No negative stakes
+4. **Vote/Bet Exclusivity**: Mutual exclusion (if enforced)
+5. **Claim Ordering**: Claims only after resolution
+
+### Coverage
+
+- ✅ Market creation with varying parameters
+- ✅ Voting and betting on active markets
+- ✅ Time-based state transitions (Active → Ended)
+- ✅ Market resolution
+- ✅ Winnings claims
+- ✅ Authorization checks
+- ✅ Idempotency guarantees
+- ✅ Balance consistency
+- ✅ State machine correctness
+
+## Testing
+
+### Run Stateful Tests
+
+```bash
+cargo test -p predictify-hybrid --test stateful
+```
+
+### Expected Output
+
+```
+running 6 tests
+test test_basic_market_creation ... ok
+test test_vote_on_active_market ... ok
+test test_no_vote_after_market_ends ... ok
+test test_market_lifecycle_invariants ... ok
+test test_state_transitions ... ok
+test test_idempotency ... ok
+
+test result: ok. 6 tests passed
+```
+
+### Integration with CI
+
+The tests are automatically included in:
+- `cargo test -p predictify-hybrid`
+- CI pipeline test runs
+- Pre-deployment validation
+
+## Security Considerations
+
+### Fuzzing Benefits
+
+1. **Edge Case Discovery**: Finds unexpected behaviors through randomized testing
+2. **Invariant Enforcement**: Catches violations of business rules
+3. **Authorization Testing**: Validates access control across scenarios
+4. **State Machine Validation**: Ensures legal state transitions
+5. **Balance Safety**: Detects arithmetic errors and negative balances
+
+### Invariants Enforced
+
+- No negative stakes or balances
+- State transitions follow defined lifecycle
+- Resolved markets have valid outcomes
+- No claims before resolution
+- No double claims
+- Idempotency of operations
+
+## Documentation
+
+### Added Documentation
+
+1. **STATEFUL_FUZZING_README.md**
+   - Complete guide to stateful fuzzing infrastructure
+   - Usage examples and configuration
+   - Invariant descriptions
+   - Troubleshooting guide
+   - Best practices
+
+2. **Inline Documentation**
+   - Comprehensive rustdoc comments
+   - Operation descriptions
+   - Invariant explanations
+   - Strategy documentation
+
+## Code Quality
+
+### Code Style
+- ✅ Follows Rust naming conventions
+- ✅ Comprehensive rustdoc comments
+- ✅ Clear structure and organization
+- ✅ Error handling best practices
+
+### Testing
+- ✅ 3 property-based tests
+- ✅ 3 unit tests
+- ✅ 100 test cases per property
+- ✅ Shrinking on failure
+
+### Security
+- ✅ Authorization checks included
+- ✅ Balance validation
+- ✅ State transition validation
+- ✅ Overflow protection (via SDK)
+
+## Commit Message
+
+```
+test: market lifecycle stateful fuzzing
+
+Implement comprehensive stateful property-based testing for the
+Predictify Hybrid prediction market lifecycle using proptest.
+
+Changes:
+- Add tests/stateful.rs with fuzzing infrastructure
+- Add STATEFUL_FUZZING_README.md documentation
+- Register stateful test target in Cargo.toml
+
+The test suite validates:
+- Market state transitions (Active → Ended → Resolved → Closed)
+- Invariants (stake non-negativity, outcome consistency, etc.)
+- Authorization requirements
+- Idempotency guarantees
+- Balance consistency
+
+Coverage includes:
+- Market creation (varying parameters)
+- Voting and betting on active markets
+- Time-based state transitions
+- Market resolution
+- Winnings claims
+- Edge cases and error conditions
+
+Test configuration:
+- 100 test cases per property
+- 1-20 random operations per case
+- Shrinking on failure for minimal reproduction
+
+Ref: GrantFox FWC26 campaign
+```
+
+## Acceptance Criteria
+
+- ✅ **Implementation matches description**: Stateful fuzzing for market lifecycle
+- ✅ **Tests added and passing**: 3 property tests + 3 unit tests
+- ✅ **Code review ready**: Well-documented, follows conventions
+- ✅ **Docs updated**: STATEFUL_FUZZING_README.md added
+
+## Additional Notes
+
+### Proptest Configuration
+
+```rust
+ProptestConfig {
+    cases: 100,                    // 100 test cases per property
+    max_shrink_iters: 1000,       // Shrink failures up to 1000 iterations
+    ..ProptestConfig::default()
+}
+```
+
+### Test Constants
+
+```rust
+const MAX_OPERATIONS: usize = 20;       // Max operations per test
+const MAX_USERS: usize = 5;             // Max users to simulate
+const MAX_STAKE: i128 = 1_000_000_000;  // 1,000 XLM max stake
+const INITIAL_BALANCE: i128 = 10_000_000_000; // 10,000 XLM per user
+```
+
+### Future Enhancements
+
+Potential extensions:
+1. Add dispute lifecycle operations
+2. Multi-market interaction testing
+3. Fee calculation validation
+4. Oracle callback fuzzing
+5. Extended lifecycle (cancellation, closure)
+6. Gas usage tracking
+7. Adversarial operation sequences
+
+## References
+
+- [Proptest Book](https://altsysrq.github.io/proptest-book/intro.html)
+- [Soroban Testing Guide](https://developers.stellar.org/docs/build/guides/testing)
+- [Stellar Fuzzing Guide](https://developers.stellar.org/docs/build/guides/testing/fuzzing)
+- [Property-Based Testing Patterns](https://fsharpforfunandprofit.com/posts/property-based-testing/)