A comprehensive blockchain oracle solution providing decentralized data feeds, VRF (Verifiable Random Functions), and request-response services.
X Oracle is a decentralized oracle network that provides reliable, tamper-proof data to smart contracts. Built as a monorepo, it includes smart contracts, core services, CLI tools, and web interfaces for managing oracle operations.
- 🔗 Data Feeds: Real-time price feeds and market data
- 🎲 VRF (Verifiable Random Functions): Cryptographically secure randomness
- 🔄 Request-Response: On-demand data requests
- 🏗️ Smart Contracts: Deployable oracle infrastructure
- 🖥️ CLI Tools: Command-line interface for management
- 🌐 Web Interface: User-friendly dashboard
- 🔌 API Services: RESTful APIs for integration
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend │ │ API Layer │ │ Core Services │
│ (Next.js) │◄──►│ (NestJS) │◄──►│ (Node.js) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Database │ │ Blockchain │
│ (PostgreSQL) │ │ (Contracts) │
└─────────────────┘ └─────────────────┘
| Package | Description | Tech Stack | Status |
|---|---|---|---|
contracts/ |
Smart contracts for oracle services | Solidity, Hardhat | ✅ |
core/ |
Core oracle services and workers | Node.js, TypeScript | ✅ |
cli/ |
Command-line interface | Node.js, TypeScript | ✅ |
vrf/ |
Verifiable Random Functions | TypeScript, ECVRF | ✅ |
api/ |
REST API for price feeds | NestJS, TypeScript | ✅ |
open/ |
Referral system API | NestJS, Prisma | ✅ |
fe/ |
Web frontend dashboard | Next.js, React | ✅ |
- Node.js >= 18.12
- Yarn package manager
- PostgreSQL database
- Redis cache server
- Git
-
Clone the repository
git clone <repository-url> cd x-oracle
-
Install dependencies for all packages
# Install contracts dependencies cd contracts && yarn install && cd .. # Install core dependencies cd core && yarn install && cd .. # Install CLI dependencies cd cli && yarn install && cd .. # Install VRF dependencies cd vrf && yarn install && cd .. # Install API dependencies cd api && yarn install && cd .. # Install open API dependencies cd open && yarn install && cd .. # Install frontend dependencies cd fe && yarn install && cd ..
-
Set up environment variables
# Copy example environment files cp contracts/.env.example contracts/.env cp core/.env.example core/.env cp cli/.env.example cli/.env cp api/.env.example api/.env cp open/.env.example open/.env cp fe/.env.dev fe/.env.local -
Set up databases
# Start PostgreSQL and Redis brew services start postgresql brew services start redis # Set up database schemas cd api && npx prisma generate && npx prisma db push && cd .. cd open && npx prisma generate && npx prisma db push && cd ..
Smart contracts for oracle services including data feeds, VRF, and request-response functionality.
Quick Commands
cd contracts
# Compile contracts
yarn compile
# Run tests
yarn test
# Deploy to local network
yarn deploy:localhost:prepayment
yarn deploy:localhost:vrf
yarn deploy:localhost:rr
yarn deploy:localhost:aggregator
# Build package
yarn buildKey Features
- Data Feed Aggregators: Price feed contracts
- VRF Contracts: Verifiable random number generation
- Request-Response: On-demand data requests
- Prepayment System: Gas fee management
- Multi-network Support: Deploy to various networks
Core oracle services including workers, listeners, and queue management.
Quick Commands
cd core
# Build the project
yarn build
# Start workers
yarn start:worker:vrf
yarn start:worker:dataFeed
yarn start:worker:rr
# Start listeners
yarn start:listener:vrf
yarn start:listener:rr
# Run tests
yarn testKey Features
- Worker Services: Process oracle requests
- Listener Services: Monitor blockchain events
- Queue Management: BullMQ integration
- Multi-service Support: VRF, Data Feed, Request-Response
Command-line interface for managing oracle operations and configurations.
Quick Commands
cd cli
# Build the CLI
yarn build
# Run CLI commands
yarn cli --help
# Run tests
yarn test
# Lint code
yarn lintKey Features
- Configuration Management: Set up oracle parameters
- Service Communication: Connect to API, Fetcher, Delegator
- Network Management: Multi-chain support
- Interactive Commands: User-friendly CLI interface
Verifiable Random Functions implementation based on ECVRF standard.
Quick Commands
cd vrf
# Build the package
yarn build
# Run tests
yarn test
# Lint code
yarn lintKey Features
- ECVRF Implementation: Standards-compliant VRF
- Cryptographic Security: Elliptic curve cryptography
- Proof Generation: Verifiable random number proofs
- TypeScript Support: Full type definitions
REST API service for price feeds and oracle data access.
Quick Commands
cd api
# Install dependencies
yarn install
# Generate Prisma client
npx prisma generate
# Start development server
yarn start:dev
# Build for production
yarn build
# Start production server
yarn start:prodKey Features
- RESTful API: HTTP endpoints for data access
- Swagger Documentation: Auto-generated API docs
- Database Integration: Prisma ORM with PostgreSQL
- Queue Processing: Background job handling
Referral system API with social referral features.
Quick Commands
cd open
# Install dependencies
yarn install
# Generate Prisma client
npx prisma generate
# Update database schema
npx prisma db push
# Start development server
yarn start:dev
# Build for production
yarn buildKey Features
- Referral System: User referral tracking
- Social Integration: Social media referral features
- Database Management: Prisma with PostgreSQL
- NestJS Framework: Scalable API architecture
Web-based dashboard for oracle management and monitoring.
Quick Commands
cd fe
# Start development server
yarn dev
# Build for production
yarn build:prod
# Start production server
yarn start
# Lint code
yarn lintKey Features
- Modern UI: Next.js with Tailwind CSS
- Web3 Integration: Wallet connection with RainbowKit
- Real-time Data: Live oracle feed updates
- Multi-language: Internationalization support
- Responsive Design: Mobile-friendly interface
-
Start all services
# Terminal 1: Start PostgreSQL and Redis brew services start postgresql brew services start redis # Terminal 2: Start API services cd api && yarn start:dev # Terminal 3: Start core services cd core && yarn start:worker:vrf # Terminal 4: Start frontend cd fe && yarn dev
-
Deploy contracts locally
cd contracts npx hardhat node --hostname 127.0.0.1 --no-deploy # In another terminal yarn deploy:localhost:prepayment yarn deploy:localhost:vrf yarn deploy:localhost:rr
# Run tests for all packages
cd contracts && yarn test && cd ..
cd cli && yarn test && cd ..
cd vrf && yarn test && cd ..
cd api && yarn test && cd ..
cd open && yarn test && cd ..# Lint all packages
cd contracts && yarn lint && cd ..
cd cli && yarn lint && cd ..
cd vrf && yarn lint && cd ..
cd core && yarn lint && cd ..
cd api && yarn lint && cd ..
cd open && yarn lint && cd ..
cd fe && yarn lint && cd ..We welcome contributions! Please follow these steps:
-
Fork the repository
-
Create a feature branch
git checkout -b feature/your-feature-name
-
Make your changes
-
Run tests and linting
# Run tests yarn test # Run linting yarn lint
-
Commit your changes
git commit -m "feat: add your feature description" -
Push to your branch
git push origin feature/your-feature-name
-
Create a Pull Request
- Use TypeScript for all new code
- Follow ESLint and Prettier configurations
- Write comprehensive tests
- Update documentation for new features
- Use conventional commits for commit messages
This project is licensed under the MIT License - see the LICENSE file for details.
- Documentation: GitHub Wiki
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Built with ❤️ by the X Oracle Team
