Optimistic Oracle

Truth by Default, Verified by Economics

An optimistic oracle protocol built on Solana that enables decentralized data feeds with economic guarantees. Data is assumed true unless challenged, providing sub-second finality with cryptoeconomic security.

🌐 Live: optimisticoracle.com
📊 Dashboard: [Work in Progress]
📖 Docs: optimisticoracle.com/docs 🔗 $OPTIM: 86BMwo29TgobuYTCFU7tf3DBhgNvgeCkNTQXbAvUpump

🚀 Features

⚡ Lightning Fast - Sub-second finality on Solana
💰 Cost Effective - $0.01 per query, 100x cheaper than traditional oracles
🔒 Cryptographically Secure - Economic incentives backed by bonding mechanisms
🌐 Multi-Purpose - Supports DeFi pricing, prediction markets, event verification, IoT data
🔄 Dispute Resolution - Transparent challenge mechanism with economic penalties
📈 Scalable - Built for Web3 scale with high throughput
💳 X402 Payment Protocol - HTTP 402 Payment Required for seamless micropayments
🔗 PayAI Integration - Automated payment verification and settlement
💱 Auto Conversion - USDC to SOL conversion for all payments

🛠 Tech Stack

Smart Contracts

Rust - Program logic
Anchor Framework - Solana development framework
Solana - Blockchain network (Devnet)

Frontend

React + TypeScript - UI framework
Vite - Build tool
CSS3 - Styling with animations

Backend

Node.js + Express - REST API
TypeScript - Type safety

SDK

TypeScript - Client library for interacting with smart contracts

📦 Project Structure

optimistic_oracle/
├── programs/
│   └── optimistic_oracle/     # Rust smart contract
│       ├── src/
│       │   ├── lib.rs         # Main program logic
│       │   ├── constants.rs   # Program constants
│       │   └── error.rs       # Custom errors
│       └── Cargo.toml
├── packages/
│   ├── api-x402/              # X402-enabled REST API 
│   │   ├── src/
│   │   │   ├── routes/        # API endpoints
│   │   │   ├── services/      # Business logic
│   │   │   ├── middleware/    # X402 payment middleware
│   │   │   └── index.ts
│   │   └── package.json
│   ├── sdk-x402/              # TypeScript SDK 
│   │   ├── src/
│   │   │   ├── client/        # API client
│   │   │   ├── payments/      # X402 payment handler
│   │   │   ├── types/         # Type definitions
│   │   │   └── utils/         # Utilities
│   │   └── package.json
│   ├── dashboard-x402/        # React Dashboard 
│   │   ├── src/
│   │   │   ├── components/    # UI components
│   │   │   ├── App.tsx        # Main app
│   │   │   └── WalletProvider.tsx
│   │   └── package.json
│   └── landing/               # Landing page
│       ├── src/
│       │   ├── App.tsx
│       │   └── App.css
│       └── package.json
├── docs/                      # Documentation
├── scripts/                   # Deployment scripts
├── Anchor.toml
├── package.json
└── README.md

🏃 Quick Start

Prerequisites

Node.js >= 18.0.0
Rust >= 1.70.0
Solana CLI >= 1.18.0
Anchor CLI >= 0.30.0

Installation

# Clone the repository
git clone https://github.com/optimisticoracle/optimistic-oracle.git
cd optimistic-oracle

# Install dependencies
npm install

# Build smart contract
anchor build

# Deploy to devnet
anchor deploy --provider.cluster devnet

Running Locally

1. Start the X402 API Server

cd packages/api-x402
npm install
npm run dev

API will run on http://localhost:3000

2. Start the Dashboard

cd packages/dashboard-x402
npm install
npm run dev

Dashboard will run on http://localhost:5175

3. Start the Landing Page

cd packages/landing
npm install
npm run dev

Landing page will run on http://localhost:5174

💳 X402 Payment Integration

The Optimistic Oracle now supports HTTP 402 Payment Required protocol for seamless micropayments!

Architecture

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│   Client    │────────▶│  API Server  │────────▶│   Solana    │
│  (X-PAYMENT)│         │  (Express)   │         │  (Devnet)   │
└─────────────┘         └──────────────┘         └─────────────┘
                               │
                               ▼
                        ┌──────────────┐
                        │    PayAI     │
                        │ Facilitator  │
                        └──────────────┘

Packages

📦 api-x402 - REST API Server with X402 support

HTTP 402 Payment Required flows
PayAI facilitator integration
USDC to SOL conversion
Bond-based security
View Documentation

📦 sdk-x402 - TypeScript SDK

Type-safe API client
X402 payment handler
Automatic payment flows
Wallet adapter integration
View Documentation

📦 dashboard-x402 - React Dashboard

Solana wallet connection (Phantom, Solflare)
Create/Propose/Dispute UI
Real-time request tracking
Responsive modern design
View Documentation

Payment Flow

Client makes request → API returns 402 Payment Required
SDK creates payment → User signs Solana transaction
PayAI verifies → Payment confirmed on-chain
API processes → Returns successful result

All payments are economically secured with bonds and escrows!

🌐 Deployment

Deploy to Vercel (Landing Page)

Install Vercel CLI
```
npm i -g vercel
```

Set Environment Variables

Copy .env.example files:

cp packages/landing/.env.example packages/landing/.env
cp packages/dashboard/.env.example packages/dashboard/.env
cp packages/api/.env.example packages/api/.env

Update with your production values.

Deploy
```
# From project root
vercel --prod
```
Configure Custom Domain
- Add domain in Vercel dashboard
- Update DNS records
- Set environment variables in Vercel dashboard

Deploy API (Separate Hosting)

The API needs to be deployed separately (e.g., Railway, Render, Fly.io):

cd packages/api
npm run build
npm start

🔧 Environment Variables

Landing Page (`packages/landing/.env`)

VITE_DASHBOARD_URL=https://dashboard.optimisticoracle.com
VITE_DOCS_URL=https://docs.optimisticoracle.com
VITE_GITHUB_URL=https://github.com/optimisticoracle/optimistic-oracle
VITE_API_URL=https://api.optimisticoracle.com

Dashboard (`packages/dashboard/.env`)

VITE_API_URL=https://api.optimisticoracle.com

API (`packages/api/.env`)

PORT=3000
NODE_ENV=production
BASE_URL=https://api.optimisticoracle.com
CORS_ORIGIN=https://optimisticoracle.com,https://dashboard.optimisticoracle.com

📖 Using the SDK

import { OptimisticOracleSDK } from '@optimistic-oracle/sdk';

// Initialize SDK
const sdk = new OptimisticOracleSDK('devnet', './wallet.json');

// Create a request
const request = await sdk.createRequest(
  "Will BTC reach $100k by end of 2025?",
  60,    // expiry in minutes
  0.1,   // reward in SOL
  0.05,  // bond in SOL
  1      // challenge period in hours
);

// Get all requests
const requests = await sdk.getAllRequests();

// Get specific request
const request = await sdk.getRequest(1);

🧪 Testing

# Run smart contract tests
anchor test

# Run SDK tests
cd packages/sdk
npm test

# Run API tests
cd packages/api
npm test

📝 Smart Contract Details

Program ID (Devnet): 4qdXVoVkqjHWXKTMii1kk98e8mCw3Ps7ctsgGNMgdkFU

Key Features:

Create oracle requests with customizable parameters
Propose answers with bond requirements
Challenge incorrect proposals
Automatic resolution after challenge period
Economic incentives for honest behavior

🤝 Contributing

Contributions are welcome! Please follow these steps:

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

Development Guidelines

Write clean, documented code
Follow TypeScript best practices
Add tests for new features
Update documentation as needed

📄 License

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

🔗 Links

Website: optimisticoracle.com
Dashboard: [Work in Progress]
Documentation: optimisticoracle.com/docs
GitHub: github.com/optimisticoracle/optimistic-oracle
Twitter: @OptimOracle
Solscan: $OPTIM

🙏 Acknowledgments

Built on Solana
Inspired by UMA Protocol
Powered by Anchor Framework

📞 Support

For questions or support, please:

Open an issue on GitHub
Join our [Discord]
Follow us on Twitter

Built with ⚡ by the Optimistic Oracle Team

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
branding		branding
docs		docs
migrations		migrations
packages		packages
programs/optimistic_oracle		programs/optimistic_oracle
scripts		scripts
tests		tests
.gitignore		.gitignore
.prettierignore		.prettierignore
Anchor.toml		Anchor.toml
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
DEPLOYMENT_GUIDE.md		DEPLOYMENT_GUIDE.md
LICENSE		LICENSE
QUICK_REFERENCE.md		QUICK_REFERENCE.md
README.md		README.md
gitignore:Zone.Identifier		gitignore:Zone.Identifier
initialize-state.ts		initialize-state.ts
package-lock.json		package-lock.json
package.json		package.json
rust-toolchain.toml		rust-toolchain.toml
tsconfig.json		tsconfig.json
vercel.json		vercel.json
yarn.lock		yarn.lock

License

optimisticoracle/optimistic-oracle

Folders and files

Latest commit

History

Repository files navigation

Optimistic Oracle

🚀 Features

🛠 Tech Stack

Smart Contracts

Frontend

Backend

SDK

📦 Project Structure

🏃 Quick Start

Prerequisites

Installation

Running Locally

1. Start the X402 API Server

2. Start the Dashboard

3. Start the Landing Page

💳 X402 Payment Integration

Architecture

Packages

Payment Flow

🌐 Deployment

Deploy to Vercel (Landing Page)

Deploy API (Separate Hosting)

🔧 Environment Variables

Landing Page (packages/landing/.env)

Dashboard (packages/dashboard/.env)

API (packages/api/.env)

📖 Using the SDK

🧪 Testing

📝 Smart Contract Details

🤝 Contributing

Development Guidelines

📄 License

🔗 Links

🙏 Acknowledgments

📞 Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Landing Page (`packages/landing/.env`)

Dashboard (`packages/dashboard/.env`)

API (`packages/api/.env`)

Packages