[Joshua13-stack]

Closes #1768

Issues

#1768 Fix: record_snapshot overwrites the oldest entry silently with no event

Category: Escrow Contract - Bug
Priority: Low
Estimated Time: 30 minutes

Description:
When the snapshot ring buffer is full, record_snapshot wraps around and overwrites the oldest entry without emitting any event or incrementing a lost-entry counter. Off-chain indexers cannot detect the data loss.

Tasks:

• Emit a match/snapshot_overwritten event when a slot is recycled
• Document the wrap-around behaviour in docs/architecture.md

Summary

The overwrite condition can be detected by checking index >= MAX_SNAPSHOTS_PER_MATCH before writing, since the slot is only reused after the first wrap. Read the existing snapshot at DataKey::Snapshot(m.id, slot) to obtain the overwritten index for the event payload. Ensure the event topic uses Symbol::new(env, "match") and symbol_short!("snapshot_overwritten") (or a suitable short symbol) consistent with existing event conventions.

Changes

• In record_snapshot, before writing the new snapshot, check whether the target slot already holds a snapshot (i.e., index >= MAX_SNAPSHOTS_PER_MATCH or the slot key exists). If so, read the existing snapshot to capture its index, then publish a match/snapshot_overwritten event with (match_id, overwritten_index, new_index) before overwriting the slot. Keep the existing match/snapshot event. Update the doc comment on record_snapshot to state that overwrites now emit an event. (contracts/escrow/src/lib.rs)
• Add a test test_snapshot_ring_buffer_emits_overwrite_event that creates a match, drives record_snapshot past MAX_SNAPSHOTS_PER_MATCH via env.as_contract, and asserts that a match/snapshot_overwritten event is emitted on the first wrap-around write with the correct match id, overwritten index, and new index. Use env.events().all() to inspect emitted events. (contracts/escrow/src/tests/snapshots.rs)
• Update the 'Balance Snapshots' section to document the ring buffer capacity (MAX_SNAPSHOTS_PER_MATCH = 8), wrap-around semantics, and the new match/snapshot_overwritten event (payload: match id, overwritten snapshot index, new snapshot index) so off-chain indexers can detect data loss. (docs/architecture.md)

[drips-wave]

@Joshua13-stack 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