ISSUE-CU06-003: Implement UI-Contract for Claiming Prizes

[davidmelendez]

ISSUE-CU06-003: Implement UI-Contract for Claiming Prizes

✨ Issue Request

Implement the complete user interface for the prize claiming functionality (CU-06), allowing players to visualize their tickets with assigned prizes and execute the claim transaction from the frontend in an intuitive and secure manner.

📌 Description

This issue focuses exclusively on the frontend implementation for use case CU-06 "Claim Prize". The smart contract functionality must be implemented previously (see SL-CU06-001).

We need to implement:

1. Prize Claiming Page (/claim-prizes)

   • Display user's ticket list with assigned prizes
   • Filter only tickets with prize_assigned = true and claimed = false
   • Responsive and modern design

2. UI Components

   • Ticket cards with detailed information
   • "Claim prize" button with dynamic states
   • Success/error notifications
   • Loading states during transactions

3. Starknet Integration

   • Connection with wallet (Argent/Braavos)
   • Execute ClaimPrize transaction
   • Automatic UI update after claiming
   • Contract error handling

4. Custom Hooks

   • Hook to get claimable tickets
   • Hook to execute claim
   • Hook to verify transaction status

🛠️ Steps to Reproduce (if applicable)

Current context:

1. No prize claiming page exists in frontend
2. Users cannot visualize their assigned prizes
3. No integration with contract's ClaimPrize function
4. No reusable components to display tickets with prizes

🖼️ Screenshots (if applicable)

Not applicable - new functionality to implement.

Suggested design references:

• Existing profile page for style consistency
• Dashboard with ticket cards
• Scaffold-Stark components for common patterns

🎯 Expected Behavior

The implementation must meet the following requirements:

Main Page (/claim-prizes):

1. 🔹 Display title "Claim Prizes"
2. 🔹 Verify wallet connection (show message if not connected)
3. 🔹 Get all finalized draws with distribution_done = true
4. 🔹 For each draw, get user's tickets with prizes
5. 🔹 Display list of claimable ticket cards
6. 🔹 Show message if no prizes available
7. 🔹 Loading skeleton while loading data
8. 🔹 Responsive design (mobile, tablet, desktop)

ClaimPrizeCard Component:

1. 🔹 Display draw ID and date
2. 🔹 Display ticket numbers (e.g., "5 - 12 - 23 - 34 - 40")
3. 🔹 Display prize amount in STRKP with formatting
4. 🔹 Display match level (1-4 matches)
5. 🔹 "Claim" button with states:
   • Enabled: Prize available
   • Disabled: Already claimed or no prize
   • Loading: Transaction in progress
6. 🔹 Status badge (Available / Claimed)
7. 🔹 Attractive design with theme colors

Wallet Integration:

1. 🔹 Detect connected wallet
2. 🔹 Get user address
3. 🔹 Execute ClaimPrize transaction on click
4. 🔹 Show wallet confirmation modal
5. 🔹 Wait for transaction confirmation
6. 🔹 Automatically update UI after confirming

Notifications and UX:

1. 🔹 Success toast with block explorer link
2. 🔹 Error toast with descriptive message
3. 🔹 Loading spinner in button during transaction
4. 🔹 Disable button after claiming
5. 🔹 Clear visual feedback at each step
6. 🔹 Contract error handling (translate Cairo errors)

Navigation:

1. 🔹 Add link in main menu
2. 🔹 Badge with number of available prizes (optional)
3. 🔹 Accessible route: /claim-prizes or /profile/claim-prizes

🚀 Suggested Solution / Feature Request

File Structure

packages/nextjs/
├── app/
│   └── claim-prizes/
│       └── page.tsx                    # Main page
├── components/
│   └── claim-prizes/
│       ├── ClaimPrizeCard.tsx         # Individual card
│       ├── ClaimPrizesList.tsx        # Card list
│       └── EmptyClaimState.tsx        # Empty state
└── hooks/
    └── scaffold-stark/
        ├── useClaimablePrizes.ts      # Hook to get prizes
        └── useClaimPrize.ts           # Hook to claim

Implementation

[Same code examples as Spanish version above]

📌 Additional Notes

Issue Dependencies:

• SL-CU06-001: Contract's ClaimPrize function must be implemented
• Deployed Contract: Must be in deployedContracts.ts
• Wallet: User must have connected wallet (Argent/Braavos)

UX Considerations:

• Loading States: Show skeletons while loading
• Error Handling: Translate technical errors to friendly messages
• Visual Feedback: Clear success/error confirmations
• Responsiveness: Functional on mobile, tablet and desktop
• Accessibility: Use semantic HTML and ARIA labels

Internationalization:

• Consider adding translations (i18n)
• Support Spanish and English
• Format numbers according to locale

Performance:

• Paginate prize list if many
• Lazy loading of heavy components
• Optimize re-renders with React.memo

Testing (Manual):

1. ✅ Connect wallet and verify prizes load
2. ✅ Click "Claim" and sign transaction
3. ✅ Verify success notification
4. ✅ Verify button disables after claiming
5. ✅ Verify responsive on mobile
6. ✅ Test with wallet without prizes (empty state)
7. ✅ Test errors (no funds, already claimed, etc.)

⚠️ Before Applying

Please read this guide: Contributor Guidelines

Definition of Done:

• Page /claim-prizes created and functional
• Components ClaimPrizeCard, ClaimPrizesList, EmptyClaimState implemented
• Hook useClaimablePrizes working correctly
• Integration with wallet (Argent/Braavos) operational
• Transaction ClaimPrize executing correctly
• Success/error notifications implemented
• Responsive design (mobile, tablet, desktop)
• Link added in main menu
• Contract error handling translated
• Manual testing completed
• Code formatted with yarn format
• Successful build with yarn build