2025-06-22 08:10:09 +03:00
cmt
2025-06-22 06:45:56 +03:00
cmt
2025-06-22 06:45:56 +03:00
2025-06-22 08:15:15 +03:00
cmt
2025-06-22 06:45:56 +03:00
cmt
2025-06-22 06:45:56 +03:00
2025-06-22 14:09:49 +03:00
cmt
2025-06-22 06:45:56 +03:00
cmt
2025-06-22 06:45:56 +03:00
cmt
2025-06-22 06:45:56 +03:00

๐Ÿš€ StellarPrice Oracle - Real-time Crypto Oracle on Stellar

Demo Video

https://drive.google.com/file/d/1dhQchLIvAp9XcbpCoD8ROnsYxg-0AewQ/view?usp=sharing

A hackathon-ready price oracle that fetches real crypto prices from DexScreener API and stores them on the Stellar blockchain.

โšก Quick Start (5 minutes)

# 1. Install prerequisites
# - Node.js 18+
# - Stellar CLI: https://stellar.org/developers-blog/how-to-install-stellar-cli

# 2. Setup Stellar CLI
stellar network add --global testnet \
  --rpc-url https://soroban-testnet.stellar.org:443 \
  --network-passphrase "Test SDF Network ; September 2015"

# 3. Create and fund account
stellar keys generate alice --global
stellar keys fund alice --network testnet

# 4. Run setup script
chmod +x complete-setup.sh
./complete-setup.sh

# 5. Deploy and start
chmod +x quick-deploy.sh
./quick-deploy.sh

# 6. Edit .env with your Stellar secret key

# 7. Start the whole app (backend + frontend)
chmod +x start.sh
./start.sh

# 8. Visit http://localhost:3000 ๐ŸŽ‰

๐Ÿš€ Deployment & Setup

For a full guided setup, use the included deployment script:

chmod +x deploy-setup.sh
./deploy-setup.sh
  • This script checks prerequisites, builds/contracts, updates .env, installs dependencies, and provides one-click startup/test scripts:
    • ./start-oracle.sh โ€“ Start both backend and frontend
    • ./test-oracle.sh โ€“ Test API and frontend health
    • ./start.sh โ€“ Start the whole app (recommended)

Manual quick start:
See below or use the script above for a smoother experience.

๐ŸŽฏ What You Get

  • โœ… Real DexScreener API data (BTC, ETH, SOL, XLM, WBTC, WETH, WSOL, etc.)
  • โœ… Soroban contract (stores prices on-chain)
  • โœ… Beautiful React dashboard (animated price cards, live charts)
  • โœ… Manual data submission (perfect for demos)
  • โœ… One-click deployment

๐Ÿ—๏ธ Architecture

DexScreener API โ†’ Oracle Service โ†’ Soroban Contract โ†’ React Frontend
     โ†“                โ†“               โ†“                โ†“
  BTC: $67K      โ†’ Format data   โ†’ Store on-chain   โ†’ Live charts

๐Ÿ“ Project Structure

stellar-price-oracle/
โ”œโ”€โ”€ ๐Ÿ“‹ README.md
โ”œโ”€โ”€ ๐Ÿš€ quick-deploy.sh         # One-click deployment
โ”œโ”€โ”€ โš™๏ธ .env.example
โ”‚
โ”œโ”€โ”€ ๐Ÿฆ€ contract/               # Simple Soroban Contract
โ”‚   โ”œโ”€โ”€ Cargo.toml
โ”‚   โ””โ”€โ”€ src/
โ”‚       โ””โ”€โ”€ lib.rs            # Minimal price oracle contract
โ”‚
โ”œโ”€โ”€ ๐ŸŒ oracle-service/         # Node.js Price Fetcher
โ”‚   โ”œโ”€โ”€ package.json
โ”‚   โ”œโ”€โ”€ index.js              # Main oracle service
โ”‚   โ””โ”€โ”€ ...                   # Price fetcher, Stellar client
โ”‚
โ”œโ”€โ”€ ๐ŸŽจ frontend/               # React Dashboard
โ”‚   โ”œโ”€โ”€ package.json
โ”‚   โ”œโ”€โ”€ vite.config.ts
โ”‚   โ”œโ”€โ”€ tailwind.config.js
โ”‚   โ”œโ”€โ”€ src/
โ”‚   โ”‚   โ”œโ”€โ”€ App.tsx           # Main app
โ”‚   โ”‚   โ”œโ”€โ”€ components/
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ PriceCard.tsx     # Animated price cards
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ LiveChart.tsx     # Real-time charts
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ NetworkStatus.tsx # Oracle health
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ SubmitData.tsx    # Manual data submission
โ”‚   โ”‚   โ”œโ”€โ”€ hooks/
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ useOracle.ts      # Oracle data hook
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ usePrices.ts      # Price data hook
โ”‚   โ”‚   โ”œโ”€โ”€ services/
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ stellar.ts        # Stellar integration
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ api.ts            # Backend API
โ”‚   โ”‚   โ””โ”€โ”€ types/
โ”‚   โ”‚       โ””โ”€โ”€ oracle.ts         # TypeScript types
โ”‚   โ””โ”€โ”€ public/
โ”‚
โ”œโ”€โ”€ ๐Ÿ“š docs/
โ”‚   โ”œโ”€โ”€ DEMO.md                   # Demo script
โ”‚   โ””โ”€โ”€ DEPLOY.md                 # Quick deployment guide

๐Ÿ”— Smart Contract to App Integration Flow

1. RUST CONTRACT (contract/src/lib.rs)
   โ†“ compiles to WASM
2. WASM FILE (target/wasm32-unknown-unknown/release/price_oracle.wasm)
   โ†“ deploys to Stellar
3. CONTRACT ID (e.g., CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA)
   โ†“ stored in .env
4. ORACLE SERVICE (oracle-service/index.js)
   โ†“ reads contract ID, submits prices
5. FRONTEND (frontend/src)
   โ†“ calls oracle API, displays data

๐Ÿฆ€ Build & Deploy Flow

  1. Build Rust contract:
    cd contract && cargo build --target wasm32-unknown-unknown --release
  2. Deploy contract:
    stellar contract deploy --wasm target/wasm32-unknown-unknown/release/price_oracle.wasm --source alice --network testnet
  3. Update .env with CONTRACT_ID
    (or use the deployment script to automate)
  4. Oracle service reads CONTRACT_ID and submits prices
  5. Frontend displays on-chain prices via the oracle API

See ../deploy-setup.sh for a full automated script.

๐ŸŽช Perfect for Hackathons

  1. "Live BTC price from DexScreener API" (show real data)
  2. "Stored on Stellar testnet" (show contract)
  3. "Updates every 30 seconds" (watch animation)
  4. "I can submit custom data" (live interaction)
  5. "Built in 6 hours!" (win judges)

Built with โค๏ธ for the Stellar ecosystem

๐Ÿš€ Simple Commands & Quick Reference

See SIMPLE_COMMANDS.md for a full list of one-liners, troubleshooting, and hackathon demo tips. See SIMPLE_COMMANDS.md for a full list of one-liners, troubleshooting, and hackathon demo tips.

Description
106121
Readme 104 MiB
Languages
Rust 56.3%
D 30.7%
TypeScript 6.8%
Shell 3.9%
JavaScript 1.8%
Other 0.4%