A Web3 Spaceship Racing Game on Somnia Testnet
Bet against the house, unlock NFT achievements, and hit jackpots in this fully on-chain spaceship racing game!
🎲 100% On-Chain Randomness & Trustless Gaming
Every race is powered by provably fair on-chain randomness using block data, timestamps, and player addresses. The chaos factor system adds an exciting twist - any spaceship can win regardless of initial odds! With 10 turns per race, unexpected comebacks and dramatic finishes are guaranteed. All game logic is verifiable on-chain and completely trustless.
🤖 Fully Automated Gameplay
Simply place your bet and watch the AI run the entire race! Each turn is generated on the blockchain using EVM randomness, then perfectly simulated on the frontend exactly as it was computed on-chain. No human intervention, no delays - just instant, automated racing action powered by smart contract logic.
🏆 Somnia v1 Mini-Games Hackathon Submission
Timeline: July 21 - August 11, 2025
🎮 Game is live at https://rush.cosmicrafts.com/
- Install MetaMask and configure it for Somnia Testnet
- Connect your wallet to the Cosmic Rush dApp
- Automated switch to Somnia Testnet (RPC: https://testnet.somnia.network)
- Get your STT on Somnia Testnet
- Click the faucet button to claim 1,000 SPIRAL tokens
- Wait for confirmation - tokens will appear in your wallet
- SPIRAL tokens are used for all betting and rewards (8 decimals)
- Browse the 8 unique spaceships with different odds and chaos factors
- Study each ship's stats - speed, acceleration, and special abilities
- Select your preferred ship based on your risk tolerance
- Enter bet amount (10-1,000 SPIRAL per race)
- Confirm your bet - this triggers an instant race simulation
- Watch the race unfold with real-time animations and chaos events
- Check your results - win tokens based on ship placement, achievement unlock or hittin the jackpot
- Unlock achievements - earn NFT badges for milestones
- Hit jackpots - win massive payouts on rare combinations
- View global rankings - see top players by total winnings
- Check player profiles - click on any player to view their match history
- Track your progress - monitor your position and earnings
- Username system - register a custom username and avatar for recognition
Cosmic Rush is built as a decentralized application (dApp) with a two-part architecture: a robust on-chain smart contract on the Somnia Testnet handling all game logic and finances, and a reactive, modern frontend built with Nuxt 3.
- SpaceshipRace.sol - Main game contract with betting, racing, and jackpot systems
- ShipConfiguration.sol - Centralized ship stats and chaos factor management
- ChaosManager.sol - Handles all chaos factor calculations and random events
- AchievementNFT.sol - ERC721 NFTs for achievement badges with metadata
- SpiralToken.sol - ERC20 token for betting and rewards (8 decimals)
- Nuxt 3 - Vue.js framework with SSR and modern tooling
- TypeScript - Type-safe development
- Tailwind CSS - Utility-first styling with cosmic theme
- Web3 Integration - MetaMask wallet connection and contract interaction
Each spaceship has unique characteristics, base stats, and chaos factors. Win rates are balanced with only 8-16% deviation between ships, ensuring any spaceship can win or lose - making every race unpredictable!
The chaos factor system adds unpredictability and excitement to every race. Each spaceship has a unique chaos factor that can trigger during races.
| Ship | Image | Speed | Acceleration | Chaos Factor | Image |
|---|---|---|---|---|---|
| The Comet |  |
77 | 11 | Overdrive: 10% chance to triple speed |  |
| The Juggernaut |  |
92 | 8 | Unstable Engine: 35% chance to triple acceleration |  |
| The Shadow |  |
89 | 12 | Slipstreamer: 40% chance +50 speed when trailing |  |
| The Phantom |  |
69 | 9 | Quantum Tunneling: 40% chance teleport 25% + speed boost |  |
| The Phoenix |  |
91 | 10 | Last Stand Protocol: 10% chance x4 speed in final turns |  |
| The Vanguard |  |
80 | 10 | Micro-warp Engine: 55% chance x2 acceleration |  |
| The Wildcard |  |
88 | 14 | Rogue AI: 20% chance random effect |  |
| The Apex |  |
99 | 16 | Graviton Brake: 77% chance slow 2nd place |  |
Your winnings are based on your spaceship's final placement in the race:
| Placement | Emoji | Payout | Description |
|---|---|---|---|
| 1st Place | 🥇 | 4X Bet | Champion payout - quadruple your bet! |
| 2nd Place | 🥈 | 2X Bet | Runner-up - double your bet |
| 3rd Place | 🥉 | 1X Bet | Bronze finish - get your bet back |
| 4th Place | 4️⃣ | 0.5X Bet | Fourth place - half your bet back |
| 5th Place | 5️⃣ | 0.35X Bet | Fifth place - 35% of your bet |
| 6th Place | 6️⃣ | 0.25X Bet | Sixth place - 25% of your bet |
| 7th Place | 7️⃣ | 0.1X Bet | Seventh place - 10% of your bet |
| 8th Place | 8️⃣ | 0X Bet | Last place - no payout |
House Edge: 10% of each bet goes to jackpot pools and contract maintenance
- Minimum Bet: 10 SPIRAL tokens
- Maximum Bet: 1,000 SPIRAL tokens
The game features three jackpot tiers funded by the house edge:
| Jackpot | Image | Chance | House Edge Allocation |
|---|---|---|---|
| Mini Jackpot |  |
5% | 10% of house edge |
| Mega Jackpot |  |
3% | 25% of house edge |
| Super Jackpot |  |
1% | 65% of house edge |
💰 Jackpot Pool Funding:
- House Edge: 10% of every bet goes to jackpot pools
- Mini Jackpot: Receives 10% of house edge (1% of total bet)
- Mega Jackpot: Receives 25% of house edge (2.5% of total bet)
- Super Jackpot: Receives 65% of house edge (6.5% of total bet)
- Random Triggers: Jackpots are triggered randomly on every bet
- Multiple Wins: Multiple jackpots can be won in a single race
- Immediate Payouts: Jackpot amounts are paid out immediately
- Independent Chances: Jackpot chances are independent of race placement
The game features a comprehensive achievement system with three categories:
- Bet 5 times on each spaceship (8 achievements)
- Bet 25 times on each spaceship (8 achievements)
- Bet 100 times on each spaceship (8 achievements)
- 1st place 3 times with each spaceship (8 achievements)
- 1st place 10 times with each spaceship (8 achievements)
- 2nd place 5 times with each spaceship (8 achievements)
- 2nd place 20 times with each spaceship (8 achievements)
- 3rd place 10 times with each spaceship (8 achievements)
- 3rd place 50 times with each spaceship (8 achievements)
- 4th place 15 times with each spaceship (8 achievements)
- 4th place 75 times with each spaceship (8 achievements)
- Novice Racer: Complete 10 races
- Veteran Racer: Complete 50 races
- Master Racer: Complete 100 races
- High Roller: Win 1000+ SPIRAL in a single race
- Cosmic Luck: Hit any jackpot
Each achievement unlocks:
- Unique NFT Badge with metadata (name, description, type, spaceship, threshold)
- Token Rewards in SPIRAL tokens
- MetaMask Compatible - NFTs appear in your wallet
- On-chain Metadata - Base64 encoded JSON with external image URLs
Compete with players worldwide on the live leaderboard:
- Real-time Updates - Rankings update instantly after each race
- Total Winnings - Players ranked by cumulative SPIRAL earnings
- Player Profiles - Click any player to view their complete match history
- Username System - Register custom usernames and avatars for recognition
- 🏆 Top Players - See who's dominating the cosmic racing scene
- 💰 Total Winnings - Track cumulative earnings across all races
- 👤 Player Identity - Display usernames or anonymous addresses
- 📊 Match History - Detailed race records for every player
- 🔄 Live Updates - Real-time leaderboard refreshes
- Global Rankings - Compete against players worldwide
- Persistent Stats - All data stored on-chain for transparency
- Achievement Tracking - See who's unlocking the most achievements
- Jackpot Winners - Celebrate players who hit massive jackpots
placeBet(uint8 spaceship, uint256 amount) // Place bet and trigger race
getPlayerStats(address player) // Get player statistics
getGameStats() // Get game statistics
getSpaceshipInfo(uint8 spaceshipId) // Get spaceship details
getPlayerAchievementsCount(address player) // Get achievement count
claimFaucet() // Claim SPIRAL tokens
registerUsername(string username, uint8 avatarId) // Register username and avatar- Instant Resolution: Each bet triggers immediate race simulation
- On-chain Randomness: Uses blockhash, timestamp, and player address
- House Edge: 10% fee funds jackpots and contract maintenance
- Automatic Payouts: Winnings sent directly to player wallet
- Chaos Factor Integration: Real-time chaos events during race simulation
- ERC721 Standard: Compatible with all NFT marketplaces
- Dynamic Metadata: Generated on-chain for each achievement
- External Images: Points to hosted artwork folders
- Immediate Transfer: NFTs sent to player wallet upon achievement unlock
- ✅ Smart Contracts: Fully tested and production-ready
- ✅ SpiralToken: ERC20 token with 8 decimals
- ✅ AchievementNFT: ERC721 with metadata generation
- ✅ SpaceshipRace: Main game contract with all features
- ✅ ShipConfiguration: Centralized ship stats management
- ✅ ChaosManager: Chaos factor system implementation
- ✅ Comprehensive Testing: 100 races with full verification
- ✅ Financial Tracking: Accurate spending vs rewards analysis
- 🔄 Frontend: Ready for integration
- Node.js (v18 or higher)
- MetaMask wallet with Somnia Testnet configured
- SPIRAL Tokens - Claim from in-game faucet
-
Clone the repository
git clone https://github.com/cosmicrafts/cosmic-rush.git cd cosmic-rush -
Install dependencies
npm i
-
Configure environment
# Create .env and add your private key without 0x and RPC URLs PRIVATE_KEY=here_your_private_key -
Test locally
npx hardhat run scripts/deploy-modular.js --network localhost
-
Deploy to Somnia Testnet
npx hardhat run scripts/deploy-modular.js --network somniaTestnet
# Compile contracts
npm run compile
# Test locally (100 races with full verification)
npm run test
# Deploy to local network
npm run deploy:local
# Deploy to Somnia testnet
npm run deploy:somnia
# Verify contracts on Somnia
npm run verify:somnia
# Start local hardhat node
npm run node
# Clean build artifacts
npm run cleanOur comprehensive testing shows:
- 100 Races: Full simulation with random betting
- Achievement System: 19/61 achievements unlocked
- NFT Minting: 19 NFTs successfully minted and verified
- Financial Tracking: Accurate spending vs rewards analysis
- Jackpot System: 5 mini jackpots hit in 100 races
- Token Rewards: 4,100 SPIRAL distributed for achievements
- Player Profit: 25,354 SPIRAL profit in test run
- Success Rate: 18% (realistic for casino-style game)
- Achievement Rate: 31.15% (19 out of 61 achievements)
- NFT Minting Success: 100%
- Jackpot Hit Rate: 5% (5 mini jackpots in 100 races)
✅ Creativity & Originality: Unique single-player casino system with NFT achievements
✅ Technical Excellence: Fully deployed on Somnia with comprehensive testing
✅ User Experience: Instant race resolution with dual token/NFT rewards
✅ Onchain Impact: 100% on-chain with provably fair randomness
✅ Community Fit: Perfect for Somnia's gaming ecosystem with quick rounds
- Live Demo: [Coming Soon]
- Smart Contract: [Deployed on Somnia Testnet]
- GitHub Repository: [Your Repository URL]
- Somnia Testnet: https://testnet.somnia.network
- Discord: [https://cosmicrafts.com/assets/discord-BlISsN3U.svg]
- X: [https://cosmicrafts.com/assets/discord-BlISsN3U.svg]
- Email: [contact@cosmicrafts.com]
Built for Somnia v1 Mini-Games Hackathon
Timeline: July 21 - August 11, 2025