fix: Winner backward compat + O(1) claim_prize lookup

Two findings from Almanax review:

1. Winner deserialization on upgrade (High): reputation_bump was
   added as a non-optional u32, which would brick reads of old on-chain
   Winner entries after upgrade. Changed to Option<u32> — old entries
   deserialize as None (treated as 0), new entries store Some(x).

2. Linear winner scan in claim_prize (Medium): claim_prize scanned all
   winners to find the anchor row, approaching budget limits at higher
   winner counts. Added DataKey::WinnerIndex stored at selection time
   for O(1) lookup in claim_prize.

- Winner.reputation_bump: u32 → Option<u32>
- DataKey::WinnerIndex variant + storage get/set helpers
- select_winners stores index + Some() reputation_bump
- claim_prize uses index lookup, falls back to PrizeAlreadyClaimed
  if paid_at.is_some() (canonical guard)
- claim_milestone uses .unwrap_or(0) on read, Some() on write

Author: Shadow-MMN

contracts/events/src/event_ops.rs

@@ -152,7 +152,7 @@ pub fn create_event(env: &Env, params: CreateEventParams, op_id: BytesN<32>) ->
                 amount: 0,
                 milestone: None,
                 paid_at: None,
-                reputation_bump: 0,
+                reputation_bump: None,
             },
         );
     }
@@ -632,13 +632,14 @@ pub fn select_winners(
                 return Err(Error::InsufficientEscrow);
             }
 
-            for spec in winners.iter() {
+            for (i, spec) in winners.iter().enumerate() {
                 let percent = event
                     .winner_distribution
                     .get(spec.position)
                     .ok_or(Error::InvalidDistribution)? as i128;
                 let amount = escrow_at_select.saturating_mul(percent) / 100_i128;
 
+                let anchor_idx = existing_count + (i as u32);
                 storage::append_winner(
                     env,
                     event_id,
@@ -648,9 +649,16 @@ pub fn select_winners(
                         amount,
                         milestone: None,
                         paid_at: None,
-                        reputation_bump: spec.reputation_bump,
+                        reputation_bump: Some(spec.reputation_bump),
                     },
                 );
+                storage::set_winner_index(
+                    env,
+                    event_id,
+                    &spec.recipient,
+                    spec.position,
+                    anchor_idx,
+                );
             }
         }
         ReleaseKind::Multi(_) => {
@@ -664,7 +672,7 @@ pub fn select_winners(
                         amount: 0,
                         milestone: None,
                         paid_at: None,
-                        reputation_bump: spec.reputation_bump,
+                        reputation_bump: Some(spec.reputation_bump),
                     },
                 );
             }
@@ -723,25 +731,21 @@ pub fn claim_prize(
         return Err(Error::PrizeAlreadyClaimed);
     }
 
-    // Locate the anchor row (milestone == None) matching this recipient and
-    // position. Captures the index for in-place update, the pre-computed
-    // amount, and the manager-approved reputation_bump.
-    let count = storage::winner_count(env, event_id);
-    let mut winner_info: Option<(u32, i128, u32)> = None;
-    for idx in 0..count {
-        let w = match storage::winner_at(env, event_id, idx) {
-            Some(w) => w,
-            None => continue,
-        };
-        if w.recipient != recipient || w.position != position {
-            continue;
-        }
-        if w.milestone.is_none() && w.paid_at.is_none() {
-            winner_info = Some((idx, w.amount, w.reputation_bump));
-            break;
-        }
+    // Look up the anchor index stored at selection time (O(1) instead of
+    // a linear scan). Returns NoSubmissions if no winner matches or the
+    // prize has already been claimed (canonical guard: paid_at).
+    let anchor_idx = storage::get_winner_index(env, event_id, &recipient, position)
+        .ok_or(Error::NoSubmissions)?;
+    let w = storage::winner_at(env, event_id, anchor_idx)
+        .ok_or(Error::NoSubmissions)?;
+    if w.recipient != recipient || w.position != position || w.milestone.is_some() {
+        return Err(Error::NoSubmissions);
+    }
+    if w.paid_at.is_some() {
+        return Err(Error::PrizeAlreadyClaimed);
     }
-    let (anchor_idx, amount, reputation_bump) = winner_info.ok_or(Error::NoSubmissions)?;
+    let amount = w.amount;
+    let reputation_bump = w.reputation_bump.unwrap_or(0);
 
     if amount <= 0 {
         return Err(Error::InvalidDistribution);
@@ -782,7 +786,7 @@ pub fn claim_prize(
             amount,
             milestone: None,
             paid_at: Some(env.ledger().timestamp()),
-            reputation_bump,
+            reputation_bump: Some(reputation_bump),
         },
     );
 

contracts/events/src/grant.rs

@@ -70,7 +70,7 @@ pub fn claim_milestone(
         match w.milestone {
             None => {
                 winner_position = Some(w.position);
-                reputation_bump = w.reputation_bump;
+                reputation_bump = w.reputation_bump.unwrap_or(0);
             }
             Some(_) => {
                 already_claimed_for_recipient = already_claimed_for_recipient.saturating_add(1);
@@ -150,7 +150,7 @@ pub fn claim_milestone(
             amount,
             milestone: Some(milestone),
             paid_at: Some(env.ledger().timestamp()),
-            reputation_bump,
+            reputation_bump: Some(reputation_bump),
         },
     );
 

contracts/events/src/storage.rs

@@ -451,6 +451,21 @@ pub fn append_winner(env: &Env, id: u64, w: &Winner) {
     touch_event_persistent(env, &count_key);
 }
 
+pub fn set_winner_index(env: &Env, id: u64, recipient: &Address, position: u32, idx: u32) {
+    let key = DataKey::WinnerIndex(id, recipient.clone(), position);
+    env.storage().persistent().set(&key, &idx);
+    touch_event_persistent(env, &key);
+}
+
+pub fn get_winner_index(env: &Env, id: u64, recipient: &Address, position: u32) -> Option<u32> {
+    let key = DataKey::WinnerIndex(id, recipient.clone(), position);
+    let idx: Option<u32> = env.storage().persistent().get(&key);
+    if idx.is_some() {
+        touch_event_persistent(env, &key);
+    }
+    idx
+}
+
 pub fn winners_snapshot(env: &Env, id: u64, max: u32) -> Vec<Winner> {
     let count = winner_count(env, id);
     let upper = if count < max { count } else { max };

contracts/events/src/types.rs

@@ -129,7 +129,7 @@ pub struct Winner {
     pub amount: i128,
     pub milestone: Option<u32>,
     pub paid_at: Option<u64>,
-    pub reputation_bump: u32,
+    pub reputation_bump: Option<u32>,
 }
 
 // ============================================================
@@ -199,6 +199,9 @@ pub enum DataKey {
 
     // Added last so earlier variant discriminants remain stable on upgrade.
     PrizeClaimed(u64, Address, u32),
+
+    // Winner anchor index for O(1) claim_prize lookup (added 2026-07).
+    WinnerIndex(u64, Address, u32),
 }
 
 // ============================================================