🏎️ Oracle Racer

A Decentralized Racing Game Powered by RedStone Pull Oracles

Race crypto assets in real-time using live price movements. Each player selects a cryptocurrency (ETH, BTC, SOL, etc.) and competes to see whose asset performs best during the race duration.

🏁 Race crypto assets in real-time! 🏁

🎮 What is Oracle Racer?

Oracle Racer is a multiplayer on-chain racing game where:

Players race crypto assets, not traditional cars
Each race lasts 30-300 seconds
Winners are determined by real-time price performance
Prices are fetched using RedStone Pull Oracles (only 2 reads per race)
Automatic race start when full
Points-based leaderboard system

🏎️ The Racing Cars

Each cryptocurrency asset is represented as a racing car on the track. Here are all the available cars you can race with:

Supported Assets

The game supports 8 different cryptocurrency assets, each with its own unique logo displayed as racing cars during races:

🏎️ Available Racing Cars

ETH Ethereum	BTC Bitcoin	SOL Solana	AVAX Avalanche
LINK Chainlink	UNI Uniswap	AAVE Aave	ARB Arbitrum

These asset logos are displayed as racing cars on the track, moving in real-time based on price performance. Each car represents a player's chosen cryptocurrency, and their position on the track reflects how well that asset is performing compared to others.

✨ Features

🏁 Gameplay

Create & Join Races - Set duration (30-300s) and player count (2-8)
Auto-Start - Race begins automatically when full
Live Racing - Watch cars move in real-time based on price changes
Dynamic Commentary - Real-time race updates in English
Points System - Earn points based on race position (100, 70, 50, 35, 25, 15, 10, 5)
Global Leaderboard - Compete for the top spot

🔮 Oracle Integration

RedStone Pull Model - On-demand price fetching
Minimal Gas Usage - Only 2 oracle reads per race
Fresh Prices - Always up-to-date data from RedStone Gateway
No On-Chain Storage - Prices read directly from transaction calldata

🎨 Modern UI

Glassmorphism Design - Beautiful glass-effect cards
Real-Time Updates - Live price feeds every second during races
Responsive Layout - Works on desktop and mobile
Smooth Animations - Cars move based on price performance

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    USER (Wallet)                         │
│              createRace() / joinRace()                    │
└─────────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│              FRONTEND (Next.js + Wagmi)                  │
│  - Race list & creation                                  │
│  - Live race visualization                               │
│  - Leaderboard & history                                 │
└─────────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│         BACKEND RELAYER (Next.js API Routes)             │
│  - Auto-finish races                                     │
│  - Fetch RedStone price data                             │
│  - Send transactions with oracle payload                  │
└─────────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│              REDSTONE GATEWAY                            │
│  - Signed price data packages                            │
│  - 3+ independent signers                                │
└─────────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│           BASE SEPOLIA BLOCKCHAIN                        │
│                                                          │
│  ┌────────────────────────────────────┐                 │
│  │   OracleRacerSimple.sol             │                 │
│  │  - Game logic                       │                 │
│  │  - Oracle Pull reads                │                 │
│  │  - Scoring & winner                 │                 │
│  │  - Leaderboard                      │                 │
│  └────────────────────────────────────┘                 │
└─────────────────────────────────────────────────────────┘

🚀 Quick Start

Prerequisites

Node.js 18+ and npm
A wallet with Base Sepolia ETH for gas
Git

Installation

Clone the repository

git clone <repository-url>
cd oracle-racer-v2

Install dependencies
```
npm install
```

Configure environment variables

cp .env.example .env.local

Edit .env.local with your configuration:

PRIVATE_KEY=your_relayer_private_key
NEXT_PUBLIC_CONTRACT_ADDRESS=0x27DDfB306Fb37868ED865F84e69b8444A8A405E9
NEXT_PUBLIC_RPC_URL=https://base-sepolia.g.alchemy.com/v2/YOUR_API_KEY
NEXT_PUBLIC_REDSTONE_GATEWAY_URL=https://oracle-gateway-1.a.redstone.finance
NEXT_PUBLIC_REDSTONE_DATA_SERVICE=redstone-primary-prod
NEXT_PUBLIC_REDSTONE_UNIQUE_SIGNERS=3
NEXT_PUBLIC_FALLBACK_RPC_URL=https://sepolia.base.org

Run development server
```
npm run dev
```
Open your browser
```
http://localhost:3000
```

🎯 How It Works

Race Lifecycle

Create Race
- Choose duration (30-300 seconds)
- Set player count (2-8)
- Select your asset (ETH, BTC, SOL, etc.)
- Race is created and you automatically join
Join Race
- Other players join with different assets
- Each asset can only be used once per race
- Race auto-starts when full
Race Active
- Watch cars move in real-time
- Positions update based on price performance
- Live commentary provides race updates
- Prices fetched every second for visualization
Race Finish
- Final prices recorded on-chain
- Winner determined by best price performance
- Points awarded to all participants
- Leaderboard updated

Scoring System

The winner is determined by the highest price percentage change:

score = (endPrice - startPrice) * 1e12 / startPrice

Points Distribution:

🥇 1st place: 100 points
🥈 2nd place: 70 points
🥉 3rd place: 50 points
4th: 35 points
5th: 25 points
6th: 15 points
7th: 10 points
8th: 5 points

🔧 Smart Contract

OracleRacerSimple.sol

Deployed on Base Sepolia: 0x27DDfB306Fb37868ED865F84e69b8444A8A405E9

Key Functions:

createRace(duration, maxPlayers, feedId) - Create and join a race
joinRace(raceId, feedId) - Join an existing race
finishRace(raceId) - Finish race and determine winner (requires RedStone payload)

Oracle Integration:

// Start prices (recorded when race auto-starts)
racer.startPrice = getOracleNumericValueFromTxMsg(racer.feedId);

// End prices (recorded when race finishes)
racer.endPrice = getOracleNumericValueFromTxMsg(racer.feedId);

Only 2 Oracle Reads Per Race:

When the last player joins → race auto-starts → start prices recorded
When race finishes → end prices recorded → winner determined

🛠️ Development

Build for Production

npm run build

Deploy to Vercel

Push your code to GitHub
Import project in Vercel
Add environment variables in Vercel dashboard
Deploy!

Required Environment Variables on Vercel:

PRIVATE_KEY - Relayer private key (for auto-finishing races)
NEXT_PUBLIC_CONTRACT_ADDRESS - Deployed contract address
NEXT_PUBLIC_RPC_URL - Base Sepolia RPC endpoint
NEXT_PUBLIC_REDSTONE_GATEWAY_URL - RedStone Gateway URL
NEXT_PUBLIC_REDSTONE_DATA_SERVICE - RedStone data service name
NEXT_PUBLIC_REDSTONE_UNIQUE_SIGNERS - Number of required signers

📁 Project Structure

oracle-racer-v2/
├── contracts/
│   └── racer_game.sol          # Main game contract
├── public/
│   └── images/                  # Asset logos
│       ├── eth.png
│       ├── btc.png
│       ├── sol.png
│       └── ...
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── finish-race/     # Auto-finish race endpoint
│   │   │   ├── prices/          # CoinGecko prices API
│   │   │   └── redstone-prices/ # RedStone prices API
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/
│   │   ├── RaceCard.tsx         # Individual race display
│   │   ├── RaceList.tsx         # List of all races
│   │   ├── CreateRace.tsx      # Race creation form
│   │   ├── Leaderboard.tsx      # Global leaderboard
│   │   ├── History.tsx          # User race history
│   │   └── ...
│   ├── config/
│   │   ├── contract.ts         # Contract ABI
│   │   └── wagmi.ts            # Wagmi configuration
│   └── lib/
│       └── redstone.ts          # RedStone integration
└── package.json

🔐 Security

✅ RedStone Signature Verification - All prices are cryptographically signed
✅ Reentrancy Protection - Using OpenZeppelin's ReentrancyGuard
✅ Relayer Locking - Prevents concurrent race settlements
✅ Input Validation - All parameters validated on-chain
✅ Access Control - Owner-only functions protected

🎨 UI Features

Race Visualization

During active races, you'll see:

Live race track with cars moving based on price performance
Real-time prices updating every second
Dynamic commentary providing race updates
Timer showing time remaining
Price changes displayed in real-time

Asset Selection

Choose from 8 supported cryptocurrencies:

Each asset has a unique logo and color
Assets are displayed in a grid for easy selection
Only available assets can be selected (no duplicates)

📊 Technology Stack

Frontend: Next.js 15, React 19, TypeScript
Styling: Tailwind CSS with custom glassmorphism theme
Web3: Wagmi v2, Viem, Ethers.js
Oracle: RedStone Pull Model
Blockchain: Base Sepolia
Deployment: Vercel

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

MIT License

🔗 Links

Contract Address (Base Sepolia): 0x27DDfB306Fb37868ED865F84e69b8444A8A405E9
RedStone Documentation: docs.redstone.finance
Base Sepolia Explorer: sepolia.basescan.org

🙏 Acknowledgments

RedStone Finance for the amazing oracle infrastructure
Base for the fast and affordable L2
OpenZeppelin for security best practices

Built with ❤️ using RedStone Pull Oracles

🏎️ Race on! 🏎️

Name		Name	Last commit message	Last commit date
artifacts		artifacts
cache		cache
contracts		contracts
public		public
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
hardhat.config.js		hardhat.config.js
next.config.js		next.config.js
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Navigation Menu

Repository files navigation

🏎️ Oracle Racer

🎮 What is Oracle Racer?

🏎️ The Racing Cars

Supported Assets

🏎️ Available Racing Cars

✨ Features

🏁 Gameplay

🔮 Oracle Integration

🎨 Modern UI

🏗️ Architecture

🚀 Quick Start

Prerequisites

Installation

🎯 How It Works

Race Lifecycle

Scoring System

🔧 Smart Contract

OracleRacerSimple.sol

🛠️ Development

Build for Production

Deploy to Vercel

📁 Project Structure

🔐 Security

🎨 UI Features

Race Visualization

Asset Selection

📊 Technology Stack

🤝 Contributing

📝 License

🔗 Links

🙏 Acknowledgments

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🏎️ Oracle Racer

🎮 What is Oracle Racer?

🏎️ The Racing Cars

Supported Assets

🏎️ Available Racing Cars

✨ Features

🏁 Gameplay

🔮 Oracle Integration

🎨 Modern UI

🏗️ Architecture

🚀 Quick Start

Prerequisites

Installation

🎯 How It Works

Race Lifecycle

Scoring System

🔧 Smart Contract

OracleRacerSimple.sol

🛠️ Development

Build for Production

Deploy to Vercel

📁 Project Structure

🔐 Security

🎨 UI Features

Race Visualization

Asset Selection

📊 Technology Stack

🤝 Contributing

📝 License

🔗 Links

🙏 Acknowledgments

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages