A provably fair, blockchain-based lottery system combining transparent gaming, tokenomics innovation, and sustainable user engagement.
Traditional lotteries suffer from:
- ❌ Lack of transparency - Players can't verify fairness
- ❌ Centralization risks - Single point of failure and manipulation
- ❌ Poor user retention - Win once, never come back
- ❌ High barriers to entry - Geographic restrictions and KYC requirements
CrystalChain solves these with blockchain technology:
- ✅ Provably Fair - Chainlink VRF ensures verifiable randomness
- ✅ Fully Decentralized - Smart contracts on Arbitrum Layer 2
- ✅ Engaging Rewards - Staking and gift systems beyond just winning
- ✅ Global Access - Open to anyone with a crypto wallet
- Fast 5-Minute Rounds - Leveraging Arbitrum's low latency
- Multi-Tier Prizes - Win with 2, 3, 4, or 5 number matches (800x max multiplier!)
- Flexible Betting - Minimum 1 PTK, maximum 1000 PTK per round
- Verifiable Randomness - Powered by Chainlink VRF v2.5
- Platform Token (PTK) - ERC20 with staking capabilities
- Stake-to-Play Model - 10 PTK minimum stake unlocks betting
- Deflationary Mechanism - 5% of winnings burned automatically
- Passive Rewards - Gift distribution to active stakers
- Creator Gifts - Platform creator receives rewards each round
- User Gifts - Random selection of eligible users get bonuses
- Consecutive Play Bonuses - Rewards for 3+ consecutive rounds
- Staking Weight System - Higher stakes = better gift eligibility
- Role-Based Access Control - Using OpenZeppelin's battle-tested libraries
- Timelock Governance - 24-hour delay on critical parameter changes
- Emergency Pause - Admin controls for unforeseen issues
- Full Reentrancy Guards - Protection on all state-changing functions
┌──────────────────────────────────────────────────────────┐
│ Frontend (React) │
│ Vite + TypeScript + Wagmi + TailwindCSS + shadcn/ui │
└────────────────────┬─────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────┐
│ Arbitrum Sepolia │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │ Platform │◄─┤ Lottery │◄─┤ Lottery │ │
│ │ Token (PTK) │ │ GameCore │ │ Gift │ │
│ │ │ │ │ │ │ │
│ │ • Staking │ │ • Betting │ │ • Distribution│ │
│ │ • Burning │ │ • Rounds │ │ • Selection │ │
│ │ • Rewards │ │ • Claiming │ │ • Cooldowns │ │
│ └─────────────┘ └──────────────┘ └───────────────┘ │
│ ▲ ▲ │
│ │ │ │
│ └──────────────────┼─────────────────────────┐ │
│ │ │ │
│ ┌───────────▼────────┐ ┌───────────▼─┐ │
│ │ Lottery Admin │ │ Chainlink │ │
│ │ • Governance │ │ VRF v2.5 │ │
│ │ • Timelocks │ │ • RNG │ │
│ │ • Emergency Pause │ │ • Callbacks │ │
│ └────────────────────┘ └─────────────┘ │
└──────────────────────────────────────────────────────────┘
Smart Contracts
- Solidity 0.8.27
- Foundry (Forge, Cast, Anvil)
- OpenZeppelin Contracts v5.1.0
- Chainlink VRF v2.5
Frontend
- React 18.3.1 + TypeScript
- Vite 5.4 (Fast build tool)
- Wagmi v2 + Viem v2 (Ethereum interactions)
- TailwindCSS + shadcn/ui (Modern UI)
- React Query (State management)
Infrastructure
- Arbitrum Sepolia Testnet
- Alchemy RPC Endpoints
- Etherscan Verification
- Git/GitHub for version control
| Matches | Payout Multiplier | Example (10 PTK bet) | Probability |
|---|---|---|---|
| 5/5 | 800x | 8,000 PTK | ~1 in 1.9M |
| 4/5 | 80x | 800 PTK | ~1 in 9,800 |
| 3/5 | 8x | 80 PTK | ~1 in 344 |
| 2/5 | 2x | 20 PTK | ~1 in 57 |
| 0-1/5 | 0x | 0 PTK | - |
All payouts subject to 5% house edge (burned to create deflationary pressure)
-
Get PTK Tokens
- Claim signup bonus from the platform - Or purchase on DEX (when available) -
Stake Your Tokens
Minimum 10 PTK required to unlock betting -
Place Your Bet
- Choose 5 unique numbers (1-49) - Set bet amount (1-1000 PTK) - Confirm transaction -
Wait for Draw
- Rounds last 5 minutes - Chainlink VRF generates winning numbers - Check your matches! -
Claim Winnings
- Winners can claim anytime after the round - 5% burned, rest deposited to wallet
# Clone the repository
git clone https://github.com/agwara/arbitrum-game
cd arbitrum-game
# Smart Contracts Setup
cd smart-contracts
forge install
forge test
# Frontend Setup
cd ../frontend
npm install
npm run dev| Contract | Address | Description |
|---|---|---|
| PlatformToken | 0x... (Add your address) |
ERC20 with staking |
| LotteryGameCore | 0x... (Add your address) |
Main lottery logic |
| LotteryGift | 0x... (Add your address) |
Gift distribution |
| LotteryAdmin | 0x... (Add your address) |
Governance & admin functions |
Verify on Arbiscan: View Contracts
-
Set up environment variables
cp .env.example .env # Edit .env with your keys -
Deploy smart contracts
cd smart-contracts forge script script/DeployLottery.s.sol \ --rpc-url $ARBITRUM_SEPOLIA_RPC \ --broadcast \ --verify
-
Configure Chainlink VRF
Visit https://vrf.chain.link Create subscription → Fund with LINK → Add consumer -
Launch frontend
cd ../frontend npm run dev
For detailed deployment instructions, see smart-contracts/README.md
- Core lottery mechanics
- Chainlink VRF integration
- Staking system
- Gift distribution
- Basic frontend UI
- Arbitrum Sepolia deployment
- Real-time leaderboard
- Live activity feed
- Analytics dashboard (TVL, users, volume)
- Mobile-responsive design
- NFT achievement system
- Multi-chain deployment (Base, Optimism)
- DAO governance for prize structure
- Automated lottery pools (syndicates)
- Telegram/Discord bot integration
- Prediction market for lottery outcomes
- Layer 3 gasless betting (Account abstraction)
- Liquidity provider rewards
- Cross-chain lottery via Chainlink CCIP
- Charity donation mode
- Professional security audit
- ✅ Audited Libraries - Using OpenZeppelin v5.1.0
- ✅ Reentrancy Protection - Guards on all critical functions
- ✅ Access Controls - Role-based permissions (ADMIN_ROLE, GIFT_MANAGER_ROLE)
- ✅ Timelocks - 24-hour delay on sensitive parameter changes
- ✅ Emergency Pause - Circuit breaker for unforeseen issues
- ✅ Input Validation - Comprehensive checks on user inputs
- ✅ Overflow Protection - Solidity 0.8+ built-in checks
⚠️ Not Mainnet Ready - Independent audit recommended before production
| Feature | Ethereum Mainnet | Arbitrum One/Sepolia |
|---|---|---|
| Transaction Cost | $5-50 | $0.01-0.10 |
| Block Time | ~12 seconds | ~0.25 seconds |
| Round Duration | Not feasible | 5 minutes ✅ |
| User Experience | Slow & expensive | Fast & cheap ✅ |
Result: Arbitrum makes micro-betting and frequent rounds economically viable!
- Smart Contracts Documentation - Detailed contract guides
- API Reference - Function signatures
- Deployment Guide - Step-by-step deployment
We welcome contributions! Here's how you can help:
- Fork the repository
- Create a feature branch (
git checkout -b feature/AmazingFeature) - Make your changes with tests
- Commit your changes (
git commit -m 'Add AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
- Write tests for all new features
- Follow Solidity style guide
- Add NatSpec documentation
- Keep gas optimization in mind
This project is licensed under the MIT License - see the LICENSE file for details.
- OpenZeppelin - Secure smart contract libraries
- Chainlink - Decentralized oracle network for VRF
- Foundry - Modern Solidity development framework
- Arbitrum - Layer 2 scaling solution
- shadcn/ui - Beautiful React components
This software is provided "as is" without warranty of any kind.
- This is experimental software for educational and hackathon purposes
- No independent security audit has been conducted
- Users should conduct their own due diligence before deploying to mainnet
- Gambling may be subject to legal restrictions in your jurisdiction
- Always play responsibly and never bet more than you can afford to lose
- GitHub: github.com/agwara/crystalChain
- Demo: [Live Demo Link] (Coming soon)
- Documentation: Project Wiki
- Twitter: [@YourHandle] (Optional)
Built with ❤️ for the decentralized future