169 lines
6.5 KiB
Markdown
169 lines
6.5 KiB
Markdown
# Animated Draw System Documentation
|
|
|
|
## Overview
|
|
|
|
The LuckyChit app now includes a comprehensive animated draw system that provides transparency, fairness, and an engaging user experience for monthly chit fund draws. The system uses a provably fair algorithm combined with beautiful animations to ensure all members can trust the draw process.
|
|
|
|
## Features
|
|
|
|
### 1. Animated Spinning Wheel
|
|
- **Visual Appeal**: Beautiful spinning wheel animation with member names displayed
|
|
- **Real-time Animation**: Smooth 4-second spinning animation with easing curves
|
|
- **Member Display**: Each segment shows member names with color-coded highlighting
|
|
- **Winner Highlighting**: Selected winner is highlighted with a pulsing green border
|
|
|
|
### 2. Provably Fair Algorithm
|
|
- **Server Seed**: Randomly generated server seed that's hashed before the draw
|
|
- **Client Seed**: Optional client seed that can be provided by users
|
|
- **Nonce**: Unique timestamp-based nonce for each draw
|
|
- **Cryptographic Hash**: SHA-256 hash of combined seeds to determine winner
|
|
- **Transparency**: All seeds and hashes are visible to participants
|
|
|
|
### 3. Draw Verification System
|
|
- **Real-time Verification**: Automatic verification of draw fairness
|
|
- **Step-by-step Process**: Clear display of each verification step
|
|
- **Hash Verification**: Confirms server seed hash matches the provided seed
|
|
- **Winner Calculation**: Shows how the winner was determined from the hash
|
|
- **Error Handling**: Displays any verification failures with retry options
|
|
|
|
### 4. Complete Draw Simulation
|
|
- **Pre-draw Information**: Shows eligible members, prize amount, and draw method
|
|
- **Provably Fair Explanation**: Educational content about the fairness system
|
|
- **Animated Draw Process**: Full spinning wheel animation with winner selection
|
|
- **Result Display**: Beautiful winner announcement with prize information
|
|
- **Verification Widget**: Integrated verification system showing all steps
|
|
|
|
## Technical Implementation
|
|
|
|
### Files Created/Modified
|
|
|
|
1. **`lib/shared/widgets/animated_draw_wheel.dart`**
|
|
- Custom animated spinning wheel component
|
|
- Handles member display and winner selection
|
|
- Implements provably fair algorithm
|
|
- Smooth animations with proper easing
|
|
|
|
2. **`lib/interfaces/manager/animated_draw_simulation.dart`**
|
|
- Complete draw simulation dialog
|
|
- Integrates wheel animation with verification
|
|
- Handles draw state management
|
|
- Provides educational content about provably fair system
|
|
|
|
3. **`lib/shared/widgets/draw_verification_widget.dart`**
|
|
- Standalone verification component
|
|
- Real-time verification of draw fairness
|
|
- Step-by-step verification process
|
|
- Error handling and retry functionality
|
|
|
|
4. **`lib/interfaces/manager/conduct_draw_dialog.dart`** (Modified)
|
|
- Added "Animated Draw" button
|
|
- Integrated with new simulation system
|
|
- Maintains backward compatibility with quick draw
|
|
|
|
5. **`lib/test_animated_draw.dart`**
|
|
- Test page for demonstrating the animation system
|
|
- Accessible via floating action button in manager dashboard
|
|
- Shows all components working together
|
|
|
|
### Dependencies Added
|
|
|
|
- **`crypto: ^3.0.3`**: For SHA-256 hashing in provably fair algorithm
|
|
|
|
## How It Works
|
|
|
|
### 1. Draw Initialization
|
|
```dart
|
|
// Generate server seed and hash
|
|
_serverSeed = _generateServerSeed();
|
|
_serverSeedHash = _generateServerSeedHash(_serverSeed!);
|
|
_nonce = DateTime.now().millisecondsSinceEpoch;
|
|
```
|
|
|
|
### 2. Winner Calculation
|
|
```dart
|
|
// Combine seeds and generate hash
|
|
final combinedSeed = '${serverSeed}:${clientSeed}:${nonce}';
|
|
final hash = _generateHash(combinedSeed);
|
|
final randomValue = _hashToNumber(hash);
|
|
final selectedIndex = randomValue % eligibleMembers.length;
|
|
```
|
|
|
|
### 3. Verification Process
|
|
```dart
|
|
// Verify server seed hash
|
|
final calculatedHash = _generateServerSeedHash(serverSeed);
|
|
if (calculatedHash != providedHash) {
|
|
throw Exception('Server seed hash verification failed');
|
|
}
|
|
```
|
|
|
|
## User Experience
|
|
|
|
### For Managers
|
|
1. **Easy Access**: Click "Animated Draw" button in conduct draw dialog
|
|
2. **Educational**: Learn about provably fair system through explanations
|
|
3. **Transparent**: See all verification steps and hashes
|
|
4. **Professional**: Beautiful animations that build trust with members
|
|
|
|
### For Members
|
|
1. **Transparent**: Can verify draw fairness using provided information
|
|
2. **Engaging**: Watch the spinning wheel animation
|
|
3. **Trustworthy**: All steps are verifiable and transparent
|
|
4. **Educational**: Understand how provably fair systems work
|
|
|
|
## Security Features
|
|
|
|
### 1. Cryptographic Security
|
|
- Uses SHA-256 for all hash operations
|
|
- Server seed is generated with cryptographically secure random numbers
|
|
- Client seed allows user input for additional verification
|
|
|
|
### 2. Transparency
|
|
- All seeds and hashes are visible before and after the draw
|
|
- Verification can be performed by anyone with the draw data
|
|
- No hidden or secret processes
|
|
|
|
### 3. Audit Trail
|
|
- Complete record of all verification steps
|
|
- Timestamps for each step
|
|
- Error logging for failed verifications
|
|
|
|
## Testing
|
|
|
|
### Test Page Access
|
|
1. Open the manager dashboard
|
|
2. Click the purple casino chip floating action button
|
|
3. This opens the test page with sample data
|
|
|
|
### Test Features
|
|
- **Wheel Animation**: Watch the spinning wheel select a winner
|
|
- **Verification**: See the verification widget in action
|
|
- **Full Simulation**: Test the complete draw dialog
|
|
- **Reset Functionality**: Reset and test multiple times
|
|
|
|
## Future Enhancements
|
|
|
|
### Potential Improvements
|
|
1. **Sound Effects**: Add audio feedback during animation
|
|
2. **Video Recording**: Record draw sessions for audit purposes
|
|
3. **Blockchain Integration**: Store draw results on blockchain
|
|
4. **Multi-language Support**: Translate verification messages
|
|
5. **Advanced Animations**: More sophisticated wheel animations
|
|
6. **Real-time Streaming**: Live streaming of draws to members
|
|
|
|
### Performance Optimizations
|
|
1. **Animation Caching**: Cache animation frames for better performance
|
|
2. **Lazy Loading**: Load verification components only when needed
|
|
3. **Memory Management**: Optimize memory usage for large member lists
|
|
|
|
## Conclusion
|
|
|
|
The animated draw system provides a perfect balance of:
|
|
- **Transparency**: Complete visibility into the draw process
|
|
- **Fairness**: Provably fair algorithm ensures unbiased results
|
|
- **Engagement**: Beautiful animations make draws exciting
|
|
- **Trust**: Verification system builds confidence in the platform
|
|
- **Education**: Users learn about fair draw systems
|
|
|
|
This system sets LuckyChit apart from traditional chit fund management by providing modern, transparent, and engaging draw experiences that all participants can trust and verify.
|