🎵 RANKr

The Ultimate Decentralized Music Ranking Game 🏆

Where music meets blockchain, and your taste could win you ETH! 🎶💰

Live Demo • Play Now • Documentation • Report Bug

---

🌟 What is RANKr?

RANKr is a decentralized, autonomous game where players compete by ranking songs on-chain. Submit your favorite tracks, rank them against others, and win ETH if your taste matches the crowd! Built on Ethereum using cutting-edge FHE (Fully Homomorphic Encryption) technology for truly private on-chain voting.

🎮 How It Works

1. 🎵 Submit Phase: Players add their favorite songs (artist, title, URL)
2. 🗳️ Ranking Phase: Pay entry fee (0.0001 ETH) and rank all songs from best to worst
3. 🏆 Winner Determination: Smart contract uses Borda count to compute the collective ranking
4. 💰 Prize Distribution: Player(s) whose ranking matches the final order most closely win the prize pool!

---

✨ Key Features

🔐 Privacy-First Voting

• RankrFHE Contract: Encrypted on-chain voting using Fully Homomorphic Encryption (Zama fhEVM)
• Rankings stay private during the game to prevent manipulation

🎯 Fair & Transparent

• Deterministic winner selection using the Borda count algorithm
• All game logic runs autonomously on-chain
• No centralized authority or intermediaries

💎 Autonomous Rounds

• Games auto-start and auto-complete when thresholds are met
• Automatic prize pool distribution to winners
• Seamless reset for the next round

🚀 Built on Modern Tech

• Next.js 15 with React 19 for blazing-fast UI
• RainbowKit for beautiful wallet connections
• Wagmi & Viem for type-safe Ethereum interactions
• Scaffold-ETH 2 for rapid dApp development
• DaisyUI + Tailwind CSS for stunning UI components

📱 Mobile-First Design

• Fully responsive on all devices
• Farcaster Mini App integration
• Social sharing features built-in

---

🎲 Game Rules

Parameter	Value
Entry Fee	0.0001 ETH
Songs per Round	3
Max Players	2 (configurable)
Ranking Method	Borda Count
Prize Pool	100% of entry fees
Winner Criteria	Best match to collective ranking

How Winners Are Determined

1. Each player's ranking contributes to a cumulative Borda count
2. Final song order is determined by highest scores
3. Player rankings are compared position-by-position with the final order
4. Player(s) with the most matching positions win
5. Prize pool is split equally among winners (with remainder to first winner)

---

🛠️ Tech Stack

Smart Contracts

• Solidity ^0.8.24+ - Smart contract language
• Hardhat - Ethereum development environment
• Zama fhEVM - Fully Homomorphic Encryption for Ethereum
• OpenZeppelin - Secure smart contract standards

Frontend

• Next.js 15 - React framework with App Router
• React 19 - UI library
• TypeScript - Type-safe development
• Wagmi v2 - React Hooks for Ethereum
• Viem - TypeScript Ethereum interface
• RainbowKit - Wallet connection UI
• TanStack Query - Data fetching & caching
• Tailwind CSS - Utility-first CSS
• DaisyUI - Beautiful UI components

Infrastructure

• Vercel - Frontend hosting
• Alchemy - RPC provider
• IPFS - Decentralized storage option
• Farcaster SDK - Mini app integration

---

🚀 Quick Start

Prerequisites

• Node.js >= v20.18.3
• Yarn v1 or v2+
• Git
• MetaMask or compatible Ethereum wallet

Installation

1. Clone the repository

git clone https://github.com/yourusername/RANKr.git
cd RANKr

2. Install dependencies

yarn install

3. Start local blockchain

yarn chain

4. Deploy contracts (in a new terminal)

yarn deploy

5. Start the frontend (in a new terminal)

yarn start

6. Open your browser

http://localhost:3000

You're ready to play! 🎉

---

📁 Project Structure

RANKr/
├── packages/
│   ├── hardhat/              # Smart contracts & deployment
│   │   ├── contracts/
│   │   │   ├── Rankr.sol     # Main game contract
│   │   │   └── RankrFHE.sol  # FHE-enabled contract
│   │   ├── deploy/           # Deployment scripts
│   │   ├── test/             # Contract tests
│   │   └── hardhat.config.ts
│   │
│   └── nextjs/               # Frontend application
│       ├── app/              # Next.js App Router
│       ├── components/       # React components
│       │   ├── game/         # Game-specific components
│       │   └── scaffold-eth/ # Scaffold-ETH components
│       ├── contracts/        # Contract ABIs & addresses
│       ├── hooks/            # Custom React hooks
│       └── utils/            # Utility functions
│
└── README.md                 # You are here!

---

🎮 Smart Contracts

Rankr.sol

The main game contract with transparent voting.

Key Functions:

• addItem(ItemInput) - Submit a song to the round
• rankItems(uint8[3]) - Submit your ranking (payable)
• getCurrentItems() - View current songs
• getPlayers() - View current players
• getPrizePool() - View current prize pool
• getWinners() - View winner addresses

Events:

• ItemAdded - Song added to round
• RankingSubmitted - Player submitted ranking
• RoundCompleted - Round ended, winners paid
• RoundReset - New round started

RankrFHE.sol

Advanced contract with encrypted voting using Zama fhEVM.

Additional Features:

• Encrypted vote storage on-chain
• Private ranking submissions
• FHE-based vote counting

---

🌐 Deployed Contracts

Base Mainnet

• Rankr: [Contract Address]
• Block Explorer: View on Basescan

Sepolia Testnet

• Rankr: [Contract Address]
• RankrFHE: [Contract Address]
• Block Explorer: View on Etherscan

Localhost

Automatically deployed when running yarn deploy

---

🧪 Development

Run Tests

yarn hardhat:test

Compile Contracts

yarn compile

Deploy to Network

# Sepolia
yarn workspace @se-2/hardhat deploy --network sepolia

# Base
yarn workspace @se-2/hardhat deploy --network base

Verify Contracts

yarn verify

Lint & Format

yarn format
yarn lint

---

🎨 Frontend Development

Key Components

Game Flow Components

• WelcomeModal - Game introduction & rules
• SongsScreen - Song submission interface
• VotingScreen - Ranking interface with drag & drop
• GameStatusCards - Real-time game status
• PrizePoolBanner - Live prize pool display

Result Components

• WinnerOverlay - Winner celebration screen
• NotWinnerOverlay - Better luck next time screen
• VotedConfirmationCard - Post-vote confirmation

Shared Components

• SongCard - Individual song display
• SongTile - Draggable ranking tile
• AddSongDialog - Song submission form

Configuration

Edit packages/nextjs/scaffold.config.ts to customize:

• Target networks
• RPC endpoints
• Wallet providers
• Polling intervals

---

🎯 Roadmap

• Core game mechanics
• FHE integration for private voting
• Farcaster Mini App integration
• Social sharing features
• Multi-chain deployment (Optimism, Arbitrum)
• NFT rewards for winners
• Tournament mode with multiple rounds
• Spotify API integration
• DAO governance for game parameters
• Mobile app (React Native)

---

🤝 Contributing

We love contributions! Whether it's bug fixes, new features, or documentation improvements.

How to Contribute

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

Please read CONTRIBUTING.md for details on our code of conduct and development process.

---

📜 License

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

---

🙏 Acknowledgments

• Scaffold-ETH 2 - Incredible toolkit for Ethereum development
• Zama - Pioneering FHE technology
• BuidlGuidl - Amazing builder community
• Farcaster - Decentralized social protocol
• All contributors who make this project possible! ❤️

---

📬 Contact & Community

• Twitter: @your_twitter
• Discord: Join our community
• Telegram: RANKr Chat
• Email: your@email.com

---

⚠️ Disclaimer

RANKr is an experimental dApp. Use at your own risk. Always verify smart contract code before interacting. Never invest more than you can afford to lose.

---

Built with ❤️ by the RANKr Team

⭐ Star us on GitHub — it helps!

⬆ Back to Top