feat: implement match pause and resume for extended games (#952)

[Killerjunior]

Implement Match Pause and Resume for Extended Games (#952)

Summary

This PR implements pause and resume functionality for chess matches to support extended games (simuls, blindfold matches) that may span multiple days. The escrow contract now allows either player to pause an active match without losing stake or state, and the timeout calculation excludes pause duration to prevent unfair expiration of long matches.

Related Issue

Closes #952 - Implement Match Pause and Resume for Extended Games

What Changed

Contracts

• Added Paused state to MatchState enum in contracts/escrow/src/types.rs
• Added paused_ledger: Option<u32> field to Match struct to track pause start time
• Added total_pause_duration: u32 field to Match struct to accumulate pause time across multiple cycles
• Implemented pause_match(env, match_id, caller) - allows either player to pause an active match
• Implemented resume_match(env, match_id, caller) - allows either player to resume a paused match
• Updated expire_match() to exclude pause duration from timeout calculation using total_pause_duration
• Added SnapshotReason::Paused and SnapshotReason::Resumed variants for balance snapshot tracking

Tests

• Added 11 comprehensive tests in contracts/escrow/src/tests/lifecycle.rs:
  • test_pause_active_match_sets_paused_state - verifies state transition and paused_ledger recording
  • test_resume_paused_match_sets_active_state - verifies state transition back to Active
  • test_pause_accumulates_total_pause_duration - verifies pause duration tracking across multiple cycles
  • test_pause_fails_on_non_active_match - validates state requirements
  • test_resume_fails_on_non_paused_match - validates state requirements
  • test_unauthorized_player_cannot_pause - authorization checks
  • test_unauthorized_player_cannot_resume - authorization checks
  • test_pause_resume_cycle_preserves_escrow_balance - fund conservation
  • test_submit_result_fails_on_paused_match - prevents result submission while paused
  • test_deposit_fails_on_paused_match - prevents deposits while paused
  • test_multiple_pause_resume_cycles - tests multiple pause/resume cycles
  • test_pause_resume_with_snapshots - verifies balance snapshot recording

Errors

• Added MatchNotPaused = 22 - error when attempting to resume a non-paused match
• Added MatchAlreadyPaused = 23 - error when attempting to pause an already paused match
• Added InvalidPauseState = 24 - error when attempting to pause a non-active match

Events / API / Storage

• New events published:
  • (match, paused) - emitted when a match is paused
  • (match, resumed) - emitted when a match is resumed
• Balance snapshots recorded for pause/resume transitions
• Storage changes are backward-compatible (new fields added to Match struct with default values)

Verification

Note: Tests could not be run locally due to missing Visual Studio C++ build tools (link.exe not found). However, the implementation follows the existing codebase patterns and includes comprehensive test coverage.

The following verification steps should be performed:

• cargo test -p escrow - runs all escrow contract tests including new pause/resume tests
• cargo test -p oracle - ensures oracle integration still works
• cargo fmt - code formatting
• cargo clippy - linting

Checklist

• I added or updated tests covering this change. (11 new tests added)
• I updated documentation or confirmed no docs update is needed. (No documentation changes required - this is a feature addition)
• I confirmed any event/API/storage changes are documented and backward-compatible. (New events added, storage changes are additive)
• I manually verified the contract or CLI behavior where applicable. (Unable to run due to missing build tools)
• I linked this PR to the related issue. (Closes Implement Match Pause and Resume for Extended Games #952)
• I included notes on any TTL or storage assumptions affecting contract state. (No TTL changes - pause duration is tracked in-match)

Notes

Design Decisions

1. Either player can pause/resume - No admin intervention required, giving players control over extended matches
2. Accumulated pause duration - Multiple pause/resume cycles are supported with total pause time tracked across the match lifecycle
3. Timeout exclusion - Only expire_match() excludes pause duration; active match operations (deposit, submit_result) remain blocked while paused
4. Balance snapshots - Pause and resume events are recorded in the balance snapshot history for audit trail

Storage Impact

• Each match now stores 2 additional u32 fields (8 bytes total)
• Pause duration tracking is bounded by match timeout limits (max 90 days)
• No changes to TTL assumptions

Risks & Considerations

• Players could potentially pause indefinitely, but timeout still applies to active time only
• Oracle cannot submit results on paused matches (by design - matches must be Active)
• Deposits are blocked while paused (by design - prevents funding changes during pause)

Follow-up Tasks

• Consider adding admin override to force-resume long-paused matches if needed
• Consider adding maximum pause duration limit per match
• Update API documentation to expose pause/resume functionality to frontend

[drips-wave]

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