feat: Implement ClaimPrize with Prize Token System and UI Support (CU-06)

[davidmelendez]

Implement ClaimPrize with Prize Token System and UI Support (CU-06)

📌 Description

This PR implements the complete prize claiming functionality for the lottery smart contract (CU-06), including:

• Secure prize token marking system using mark_as_prize() instead of minting
• Full ClaimPrize() implementation with token transfers from vault to winners
• New GetUserWinningTickets() function for UI to display claimable prizes
• Automatic role assignment in deployment script
• Removal of dangerous assign_prize_tokens() function that could mint infinite tokens

🎯 Motivation and Context

The existing ClaimPrize function had critical issues:

1. Used old CheckMatches system instead of new distribution system (CU-05)
2. Had a TODO comment - no actual token transfer implementation
3. Did not mark transferred tokens as "prize tokens" (needed for STRK conversion)
4. No way for UI to query only winning tickets (had to fetch all tickets)
5. The assign_prize_tokens() function was a security risk - it minted tokens from nothing, breaking the project's economy

Security Improvements:

• Replaced assign_prize_tokens() (mints tokens) with mark_as_prize() (only marks existing tokens)
• Prevents infinite token inflation
• Maintains proper token accounting for prize-to-STRK conversions
• Follows Checks-Effects-Interactions (CEI) pattern
• Uses reentrancy guard protection

Closes #546

🛠️ How to Test the Change (if applicable)

Testing the complete prize claiming flow:

Backend Testing (Contracts):

1. 🔹 Compile contracts: cd packages/snfoundry/contracts && scarb build
2. 🔹 Run tests: scarb test (test_CU02.cairo validates the new prize marking system)
3. 🔹 Deploy to devnet: cd ../.. && yarn deploy

Manual Flow Testing:

1. 🔹 Create a draw and buy tickets
2. 🔹 Execute DrawNumbers to finalize the draw
3. 🔹 Execute DistributePrizes (CU-05) to assign prizes to winning tickets
4. 🔹 Call GetUserWinningTickets(drawId, playerAddress) to get claimable prizes
5. 🔹 Execute ClaimPrize(drawId, ticketId) for each winning ticket
6. 🔹 Verify:
   • Player balance increased by prize_amount
   • Vault balance decreased by prize_amount
   • Ticket marked as claimed = true
   • Player's prize_balance increased (can convert to STRK)
7. 🔹 Try claiming again (should fail with 'Prize already claimed')

Error Case Testing:

• Try claiming with active draw → 'Draw still active'
• Try claiming without distribution → 'Distribution not done'
• Try claiming another player's ticket → 'Not ticket owner'
• Try claiming already claimed prize → 'Prize already claimed'

🖼️ Screenshots (if applicable)

N/A - Backend smart contract changes

🔍 Type of Change

• 🐞 Bugfix - Fixes an existing issue or bug in the code.
• ✨ New Feature - Adds a new feature or functionality.
• 🚀 Hotfix - A quick fix for a critical issue in production.
• 🔄 Refactoring - Improves the code structure without changing its behavior.
• 📖 Documentation - Updates or creates new documentation.
• ❓ Other (please specify) - Any other change that does not fit into the categories above.

✅ Checklist Before Merging

• 🧪 I have tested the code and it works as expected.
• 🎨 My changes follow the project's coding style.
• 📖 I have updated the documentation if necessary.
• ⚠️ No new warnings or errors were introduced.
• 🔍 I have reviewed and approved my own code before submitting.

📌 Additional Notes

Key Implementation Details:

1. StarkPlayERC20.cairo Changes:

• ✅ Added mark_as_prize() function - only increments prize_balance, does NOT mint
• ✅ Removed assign_prize_tokens() - dangerous function that minted tokens
• ✅ Maintains security by requiring PRIZE_ASSIGNER_ROLE

2. Lottery.cairo Changes:

• ✅ Fully implemented ClaimPrize() with:
  • Validates draw is finalized and distribution is done
  • Validates ticket ownership and prize assignment
  • Transfers tokens from vault using transfer_from()
  • Marks tokens as prize tokens using mark_as_prize()
  • Protects against reentrancy attacks
  • Follows CEI pattern for security
• ✅ Added GetUserWinningTickets() for UI support:
  • Returns only tickets with prize_assigned=true, prize_amount>0, claimed=false
  • Optimized for frontend prize claiming interface

3. Deploy Script Changes:

• ✅ Automatically assigns PRIZE_ASSIGNER_ROLE to Lottery contract
• ✅ Consistent with other role assignments (MINTER_ROLE, BURNER_ROLE)

4. Test Updates:

• ✅ Updated test_CU02.cairo to use mark_as_prize() instead of assign_prize_tokens()
• ✅ Translated all Spanish comments to English
• ✅ All tests passing

Files Modified (5 files):

1. packages/snfoundry/contracts/src/StarkPlayERC20.cairo
2. packages/snfoundry/contracts/src/Lottery.cairo
3. packages/snfoundry/contracts/tests/test_CU02.cairo
4. packages/snfoundry/scripts-ts/deploy.ts
5. packages/nextjs/contracts/deployedContracts.ts

Post-Deployment Configuration:

Important: The vault must approve the Lottery contract to transfer tokens:

// Execute from vault owner after deployment:
vault.approve(lottery_address, MAX_ALLOWANCE)

Security Guarantees:

• ✅ No infinite token minting
• ✅ Prize tokens properly tracked for STRK conversion
• ✅ Reentrancy protection
• ✅ Ownership validation
• ✅ Double-claiming prevention
• ✅ CEI pattern compliance

UI Integration Ready:

The new GetUserWinningTickets() function enables the UI to:

1. Display winning tickets for connected wallet
2. Show: draw ID, ticket ID, numbers, prize amount
3. Enable one-by-one prize claiming
4. Auto-refresh after each claim

---

Related Issue: Issue SL-CU06-001 - Implement ClaimPrize in Smart Contract (Backend)