A secure, verifiable spinning wheel game built with Zama FHEVM (Fully Homomorphic Encryption Virtual Machine) that provides confidential rewards and private gameplay on Ethereum blockchain.

Author: @trungkts29

• Encrypted Game State: All player data (spins, GM tokens, pending ETH, scores) are encrypted on-chain
• Private Transactions: Game actions are performed with encrypted inputs
• Zero-Knowledge Proofs: Verifiable gameplay without revealing outcomes
• User-Decrypt Authorization: Players control their own data decryption

• Daily Check-in: Receive +1 spin daily (resets at 00:00 UTC)
• GM Token System: Buy GM tokens with ETH (1 ETH = 1000 GM)
• Spin Rewards:
  • Slot 0: 0.1 ETH (1% chance)
  • Slot 1: 0.01 ETH (1% chance)
  • Slots 2-4: Miss (no reward)
  • Slot 5: 5 GM tokens
  • Slot 6: 15 GM tokens
  • Slot 7: 30 GM tokens
• Leaderboard: Publish scores to compete with other players
• KMS Claim System: Decentralized ETH claiming with Key Management Service

• Smart Contract: LuckySpinFHE_KMS_Final.sol - Optimized for HCU efficiency
• Frontend: React + TypeScript with FHE SDK integration
• Backend: Express.js API for user state aggregation and oracle attestations
• Relayer: Zama Relayer for encrypted transaction processing
• Network: Sepolia Testnet (Ethereum)

• Node.js 18+
• MetaMask wallet
• Sepolia ETH for gas fees

1. Clone the repository

git clone https://github.com/ntclick/luckyspingameFHE.git
cd luckyspingameFHE

2. Install dependencies

# Frontend
cd frontend-fhe-spin
npm install

# Backend (optional - for local development)
cd ../server
npm install

3. Configure environment

# Copy .env.example to .env
cp .env.example .env

# Update with your configuration
REACT_APP_FHEVM_CONTRACT_ADDRESS=0x561D05BbaE5a2D93791151D02393CcD26d9749a2
REACT_APP_RELAYER_URL=https://relayer.testnet.zama.cloud
REACT_APP_SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/your-api-key
REACT_APP_ETHERSCAN_API_KEY=your-etherscan-api-key

4. Start the application

# Frontend
cd frontend-fhe-spin
npm start

# Backend (optional)
cd ../server
npm start

5. Connect your wallet

• Open MetaMask and connect to Sepolia Testnet
• Connect your wallet to the application
• Grant user-decrypt authorization when prompted

• Connect your MetaMask wallet
• Perform daily check-in to receive free spins
• Buy GM tokens if you need more spins

• Click the spin wheel to start
• Wait for the wheel to stop and reveal your outcome
• Prizes are automatically settled on-chain

• GM Tokens: Automatically added to your balance
• ETH Rewards: Use the "Claim ETH" button to withdraw to your wallet
• Leaderboard: Publish your score to compete with others

Sepolia: 0x561D05BbaE5a2D93791151D02393CcD26d9749a2 (LuckySpinFHE_KMS_Final)

• spinLite() - Consume a spin and compute outcome
• settlePrize(uint8 slot) - Apply rewards for a specific slot
• dailyGm() - Daily check-in for free spins
• buyGmTokensFHE(bytes32 handle, bytes calldata inputProof) - Buy GM tokens with ETH

• requestClaimETH(uint256 amountWei) - Request ETH withdrawal
• onClaimDecrypted(address user, uint256 amountWei) - KMS callback for actual transfer

• getUserSpins(address user) - Get encrypted spin count
• getUserGmBalance(address user) - Get encrypted GM balance
• getEncryptedPendingEthWei(address user) - Get encrypted pending ETH
• getEncryptedScore(address user) - Get encrypted score

luckyspingameFHE/
├── contracts/
│   ├── LuckySpinFHE_KMS_Final.sol    # Main smart contract
│   ├── LuckySpinFHE_Strict.sol       # Backup contract
│   └── LuckySpinFHE_ACL_Simple.sol   # ACL test contract
├── frontend-fhe-spin/
│   ├── src/
│   │   ├── App.tsx                   # Main React component
│   │   ├── components/               # UI components
│   │   ├── hooks/                    # Custom hooks
│   │   ├── utils/                    # Utility functions
│   │   ├── abi/                      # Contract ABIs
│   │   └── config.ts                 # Configuration
│   └── public/
│       └── wasm/                     # FHE WASM files
├── server/                           # Express API server
├── deploy/                           # Deployment scripts
├── scripts/                          # Utility scripts
└── README.md

• React 18 - UI framework
• TypeScript - Type safety
• Ethers.js - Ethereum interaction
• Zama FHE SDK - Encrypted operations

• Solidity - Smart contract language
• FHE Solidity - Homomorphic encryption
• Hardhat - Development framework

• Zama Relayer - Encrypted transaction processing
• MetaMask - Wallet connection
• Sepolia Testnet - Ethereum test network

# Compile contracts
npx hardhat compile

# Deploy to Sepolia
npx hardhat run deploy/06b_deploy_kms_final_js.js --network sepolia

# Start frontend
cd frontend-fhe-spin
npm start

# Start backend
cd server
npm start

# Build for production
cd frontend-fhe-spin
npm run build

• All sensitive data encrypted on-chain using FHE
• User controls decryption through UDSIG (User Decryption Signature)
• No plaintext data stored on-chain

• ACL (Access Control List) system for data permissions
• User-decrypt authorization required for data access
• Contract-level permission management

• EIP-712 signatures for secure authorization
• Input proofs for encrypted transaction validation
• Commitment scheme for spin outcomes

• RPC URL: https://rpc.sepolia.org
• Chain ID: 11155111
• Block Explorer: https://sepolia.etherscan.io
• Faucet: https://sepoliafaucet.com

• Etherscan: https://sepolia.etherscan.io/address/0x561D05BbaE5a2D93791151D02393CcD26d9749a2
• ABI: Available in frontend-fhe-spin/src/abi/

REACT_APP_FHEVM_CONTRACT_ADDRESS=0x561D05BbaE5a2D93791151D02393CcD26d9749a2
REACT_APP_SEPOLIA_RPC_URL=https://rpc.sepolia.org
REACT_APP_CHAIN_ID=11155111
REACT_APP_RELAYER_URL=https://relayer.testnet.zama.cloud
REACT_APP_BACKEND_API_URL=/api
REACT_APP_ETHERSCAN_API_KEY=your_etherscan_api_key

PORT=4009
REACT_APP_SEPOLIA_RPC_URL=https://rpc.sepolia.org
REACT_APP_ETHERSCAN_API_KEY=your_etherscan_api_key
REACT_APP_RELAYER_URL=https://relayer.testnet.zama.cloud
REACT_APP_DECRYPTION_ADDRESS=0xb6E160B1ff80D67Bfe90A85eE06Ce0A2613607D1
REACT_APP_FHEVM_CONTRACT_ADDRESS=0x561D05BbaE5a2D93791151D02393CcD26d9749a2
ORACLE_PRIVATE_KEY=your_oracle_private_key

1. Connect repository to Vercel/Netlify
2. Set environment variables
3. Deploy automatically on push

1. Deploy server to cloud platform
2. Set environment variables
3. Update frontend REACT_APP_BACKEND_API_URL

# Deploy to Sepolia
npx hardhat run deploy/06b_deploy_kms_final_js.js --network sepolia

# Verify on Etherscan
npx hardhat verify --network sepolia CONTRACT_ADDRESS

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Follow TypeScript best practices
• Add proper error handling
• Include comprehensive tests
• Update documentation for new features

This project is licensed under the MIT License - see the LICENSE file for details.

• Zama Team - For the amazing FHEVM technology
• Ethereum Foundation - For the blockchain infrastructure
• MetaMask - For wallet integration
• Hardhat - For development tools

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Author: @trungkts29

⚠️ Disclaimer: This is a demo application for educational purposes. Use at your own risk and never use real funds on testnet applications.