feat(escrow): add player-level balance history with historical snapshot queries (#953)

[Osifowora]

Summary

Implements player-level historical balance queries for the escrow contract. Adds the ability to ask "what was player X's escrow balance at ledger N?" via get_balance_at_timestamp, and records a snapshot on every balance-changing event.

This closes issue #953:

There is no way to query historical escrow balances for a player. Analytics and reporting require snapshotting balance at key points.

Tasks from #953

• Added DataKey::PlayerBalanceSnapshot(player, u64) and DataKey::PlayerBalanceSnapshotCount(player) to store per-player balance history.
• Implemented get_balance_at_timestamp(env, player, timestamp) -> i128 which walks the per-player ring buffer newest-first and returns 0 when no snapshot is recorded at or before timestamp.
• Records a snapshot on every deposit, withdrawal, and payout.
  • deposit -> records for the depositing player
  • submit_result -> records for both players (balance -> 0)
  • cancel_match -> records for refunded depositors only (non-depositors had balance 0 and would not change)
  • expire_match -> records for refunded depositors only
  • "Withdrawal" maps to the existing cancel/expire refund paths since the contract has no explicit withdrawal function.
• Added tests for snapshot accuracy across multiple operations - 8 test cases in contracts/escrow/src/tests/player_balance_history.rs covering no-history zeros, deposit cumulation, payout-zero, cancel-zero, expire-zero, multi-match cross-match timelines, pre-history queries returning 0, and ring-buffer-overwrite behavior.

Implementation notes

• Storage: new entries go through DataKey::PlayerBalanceSnapshot(player, slot) where slot = index % MAX_PLAYER_SNAPSHOTS (32). DataKey::PlayerBalanceSnapshotCount(player) tracks the monotonic counter so get_balance_at_timestamp can detect pruned entries and return 0 for queries before the surviving window.
• Balance definition: aggregate i128 = sum of stake_amount over every non-terminal match the player has deposited in. Identifies the depositing side via player{1,2}_deposited flags.
• Snapshot ring: identical pattern to the existing per-match snapshots (MAX_SNAPSHOTS_PER_MATCH), so behavior is consistent across both operational and analytical read paths.
• Auth model: get_balance_at_timestamp is read-only and unauthenticated - only an aggregate escrow total is exposed, no per-match stake amounts.
• Event topic: emits (Symbol::new(env, "player"), symbol_short!("snapshot"), (player, index, balance)) on each new snapshot, so off-chain indexers can stream player history easily.

Files changed

• contracts/escrow/src/lib.rs - added helpers, query function, hooks (+177 lines)
• contracts/escrow/src/types.rs - added 2 DataKey variants + PlayerBalanceSnapshot struct (+37 lines)
• contracts/escrow/src/tests/player_balance_history.rs - new test module (8 tests)
• contracts/escrow/src/tests/mod.rs - registered the new module (+1)

Closes #953

[drips-wave]

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