Discover. Merge. Evolve.
A fully implemented Web3 NFT game where players merge virtual starter entities to create unique hybrid creature NFTs using blockchain technology, AI-generated images, and verifiable randomness.
🎮 Play Now: https://hybridhaven.runs.my.id
🌊 OpenSea Collection: HybridHaven on OpenSea
📂 Source Code: GitHub Repository
HybridHaven is a complete Web3 gaming platform that combines:
- Instant Virtual Starters: 35 virtual entities available immediately upon wallet connection
- Real NFT Creation: Merge any two entities to mint unique hybrid NFTs on Ethereum
- AI-Powered Generation: Google Gemini creates unique images and descriptions for each hybrid
- Verifiable Randomness: Chainlink VRF ensures fair and unpredictable rarity outcomes
- Decentralized Storage: IPFS stores all NFT metadata and images permanently
- 🔗 Wallet Connection: Connect with MetaMask and other Web3 wallets
- 🎁 Virtual Starter Collection: Access 35 virtual starter entities instantly
- ⚡ Entity Merging: Combine any two entities (starters or hybrids) to create unique NFTs
- 🎲 Verifiable Randomness: Chainlink VRF for provably fair rarity generation (1-5 stars)
- 🤖 AI-Generated Content: Google Gemini creates unique hybrid creature images and names
- 📦 IPFS Storage: Decentralized storage for images and metadata via Pinata
- 🔄 Auto-Finalization: Automatic processing of merge requests when VRF completes
- 🦊 MetaMask Integration: Auto-add newly created NFTs to your wallet
- 🏆 OpenSea Compatible: Full ERC-721 compliance with marketplace support
web3-project/
├── fullstack/ # Next.js frontend + backend API
├── smart-contract/ # Solidity contracts + deployment scripts
├── proposal/ # Original project proposal (Slidev)
└── report/ # Final implementation report (Slidev)
-
Frontend Application (Next.js 15 + TypeScript)
- Real-time game interface with entity management
- Web3 wallet integration and transaction handling
- Auto-updating UI with merge progress tracking
-
Backend Services (Next.js API Routes)
- AI image generation via Google Gemini
- IPFS metadata upload via Pinata
- Blockchain event monitoring and auto-finalization
-
Smart Contracts (Solidity)
GameContract.sol: Core game logic and merge mechanicsNFTContract.sol: ERC-721 NFT managementChainlinkVRFConsumer.sol: Verifiable randomness oracle
-
External Integrations
- Chainlink VRF v2.5: Secure randomness for rarity calculation
- Google Gemini AI: Dynamic image and description generation
- IPFS + Pinata: Decentralized metadata storage
- Connect Wallet: Connect MetaMask to Sepolia testnet
- Instant Access: Get immediate access to 35 virtual starter entities
- Select Entities: Choose any two entities (starters or hybrids) to merge
- Pay & Request: Pay 0.0001 ETH + gas to submit merge request
- Wait for Magic: Chainlink VRF generates randomness, AI creates your hybrid
- Receive NFT: New hybrid NFT is minted to your wallet automatically
Rarity is calculated on-chain using Chainlink VRF randomness:
- ⭐ 1-Star (Common): 20% chance
- ⭐⭐ 2-Star (Uncommon): 30% chance
- ⭐⭐⭐ 3-Star (Rare): 40% chance
- ⭐⭐⭐⭐ 4-Star (Epic): 9.9% chance
- ⭐⭐⭐⭐⭐ 5-Star (Legendary): 0.1% chance
Players get instant access to 35 virtual starter entities:
Elements: Fire, Water, Earth, Air, Light, Shadow, Metal, Crystal, Lightning, Ice
Nature: Plant, Beast, Aquatic, Avian, Insect
Cosmic: Stellar, Lunar, Solar, Void, Nebula
Environments: Forest, Desert, Ocean, Mountain, Swamp
Animals: Wolf, Tiger, Eagle, Bear, Fox
Plants: Oak, Rose, Cactus, Lotus, Fern
- Framework: Next.js 15 with TypeScript
- Styling: Tailwind CSS with custom animations
- Web3: ethers.js for blockchain interactions
- State Management: React hooks with real-time updates
- Network: Ethereum Sepolia Testnet
- Smart Contracts: Solidity with OpenZeppelin standards
- Randomness: Chainlink VRF v2.5
- AI: Google Gemini Flash 2.0
- Storage: IPFS with Pinata pinning service
- Smart Contracts: Hardhat with TypeScript
- Testing: Comprehensive test suite with Mocha/Chai
- Deployment: Automated scripts with verification
- Documentation: Slidev for interactive presentations
- Node.js 18+ and npm
- MetaMask or Web3 wallet
- Sepolia testnet ETH (get from faucets)
-
Clone repository:
git clone https://github.com/runsdev/hybridhaven cd hybridhaven -
Setup frontend:
cd fullstack npm install cp .env.example .env.local # Configure environment variables npm run dev
-
Deploy contracts (optional):
cd smart-contract npm install npx hardhat compile npx hardhat run scripts/deploy.ts --network sepolia
# Frontend
NEXT_PUBLIC_GAME_CONTRACT_ADDRESS=0x3b20dB5784862D3a615e089923b6aD1d6e65A28f
NEXT_PUBLIC_NFT_CONTRACT_ADDRESS=0x906834aeC6B6F486F306D66DEDd5925B30cfEB3c
NEXT_PUBLIC_VRF_CONTRACT_ADDRESS=0x48796e7CFdf0ad487875891ad651c7d9562dBa43
NEXT_PUBLIC_RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY
# Backend Services
GOOGLE_AI_API_KEY=your_google_ai_api_key
PINATA_API_KEY=your_pinata_api_key
PINATA_SECRET_API_KEY=your_pinata_secret_key
BACKEND_PRIVATE_KEY=your_backend_wallet_private_key| Contract | Address | Verified |
|---|---|---|
| GameContract | 0x3b20dB5784862D3a615e089923b6aD1d6e65A28f |
✅ |
| NFTContract | 0x906834aeC6B6F486F306D66DEDd5925B30cfEB3c |
✅ |
| VRFConsumer | 0x48796e7CFdf0ad487875891ad651c7d9562dBa43 |
✅ |
The project includes comprehensive testing:
cd smart-contract
npm test # Run all tests
REPORT_GAS=true npm test # Test with gas reportingTest coverage includes:
- Contract deployment and configuration
- Entity minting and management
- Merge request flow with VRF integration
- Access controls and security measures
- Error handling and edge cases
- Access Control: Role-based permissions with OpenZeppelin
- Payment Validation: Smart contract enforces payment requirements
- Ownership Verification: Contract validates entity ownership before merging
- Cooldown Protection: 5-minute cooldown prevents spam/abuse
- VRF Security: Chainlink VRF ensures unpredictable randomness
- Input Validation: Comprehensive validation for all user inputs
- Merge Cost: 0.0001 ETH per merge (fixed)
- Gas Fees: Variable based on network congestion
- Payment Destination: Contract owner address
- No Refunds: Failed merges due to cooldown/ownership issues
fullstack/README.md- Complete frontend/backend guidesmart-contract/README.md- Smart contract documentationsmart-contract/IMPLEMENTATION_GUIDE.md- Backend integration guideproposal/slides.md- Original project proposalreport/slides.md- Final implementation report
- VRF Timing: 30 seconds to 2 minutes for randomness
- AI Generation: 10-30 seconds for image creation
- IPFS Upload: 5-15 seconds for metadata storage
- Total Merge Time: Typically 1-3 minutes end-to-end
- Success Rate: 100% completion rate for valid merges
Common issues and solutions:
- "Contract not initialized": Verify contract addresses and network
- "Merge cooldown active": Wait 5 minutes between merges
- "Insufficient funds": Ensure wallet has 0.0001 ETH + gas
- "Entity not found": Verify entity ownership and selection
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Chainlink for VRF oracle services and reliable randomness
- Google for Gemini AI integration and creative image generation
- Pinata for IPFS pinning services and reliable storage
- OpenZeppelin for secure smart contract libraries
- Ethereum for decentralized blockchain infrastructure
Ready to start your hybrid creature collection? 🚀
Connect your wallet and begin merging! Each combination creates a unique NFT with AI-generated artwork.