KUSD Oracle System

A custom oracle system for the KUSD stablecoin, providing reliable price feeds for collateral assets on KalyChain. Currently centralized for testnet, with a clear roadmap to full decentralization.

🏗️ Architecture

Smart Contracts

KUSDOracle: Individual oracle contract for each asset (BTC, ETH, etc.)
KUSDOracleFactory: Factory for deploying and managing oracle contracts

Oracle Nodes

Node.js application that fetches prices from multiple sources
Multi-source validation with median calculation
Automatic price updates every minute
Health monitoring and alerting

Price Sources

Binance API - Major CEX with high liquidity
GeckoTerminal API - DEX aggregator (Uniswap, Curve, etc.) - Free, no API key required
Coinbase API - Trusted US-based exchange
KuCoin API - Global exchange with wide coverage
CryptoCompare API - Multi-source aggregation
Kraken API - Established exchange (since 2011) - Free, no API key required
OKX API - Major global exchange with high volume - Free, no API key required

🚀 Quick Start

1. Installation

npm install

2. Configuration

# Copy environment template
cp .env.example .env

# Edit .env with your configuration
nano .env

3. Deploy Contracts

# Compile contracts
npm run build

# Deploy to testnet
npm run deploy:testnet

# Deploy to mainnet
npm run deploy:mainnet

4. Start Oracle Node

# Development mode
npm run dev

# Production mode
npm start

📋 Configuration

Environment Variables

Network Configuration

KALYCHAIN_TESTNET_RPC=https://testnetrpc.kalychain.io/rpc
KALYCHAIN_MAINNET_RPC=https://rpc.kalychain.io/rpc
PRIVATE_KEY=your_private_key_here

Oracle Configuration

ORACLE_NODE_ID=kusd-oracle-node-1
ORACLE_UPDATE_INTERVAL=60000  # 1 minute
ORACLE_MAX_DEVIATION=1000     # 10%

API Keys (Optional - all sources work without keys)

# Optional: Higher rate limits with API keys
BINANCE_API_KEY=your_binance_api_key
CRYPTOCOMPARE_API_KEY=your_cryptocompare_api_key

# GeckoTerminal - No API key required (free DEX data)

Contract Addresses (filled after deployment)

KUSD_ORACLE_FACTORY=0x...
BTC_ORACLE_ADDRESS=0x...
ETH_ORACLE_ADDRESS=0x...
USDT_ORACLE_ADDRESS=0x...
USDC_ORACLE_ADDRESS=0x...
DAI_ORACLE_ADDRESS=0x...

🔧 Development

Running Tests

npm test

Local Development

# Start local hardhat node
npm run node

# Deploy to local network
npx hardhat run scripts/deploy.js --network localhost

# Start oracle node
npm run dev

Code Structure

src/
├── contracts/           # Solidity contracts
│   ├── KUSDOracle.sol
│   └── KUSDOracleFactory.sol
├── api/                 # Price source APIs
│   ├── BinanceAPI.js
│   ├── GeckoTerminalAPI.js
│   ├── CoinbaseAPI.js
│   ├── KucoinAPI.js
│   ├── CryptoCompareAPI.js
│   ├── KrakenAPI.js
│   ├── OKXAPI.js
│   └── CoinGeckoAPI.js  # (deprecated, not used)
├── oracle-node/         # Oracle node software
│   └── OracleNode.js
└── index.js            # Main entry point

📊 Oracle Node Features

Price Validation

Multi-source aggregation: Fetches from 5+ sources
Median calculation: Uses median to filter outliers
Deviation limits: Rejects prices >10% from median
Staleness detection: Marks old prices as invalid

Health Monitoring

Blockchain connectivity: Monitors RPC connection
Contract health: Checks oracle contract responses
API availability: Tests all price source APIs
Automatic alerts: Sends notifications on failures

Security Features

Node authorization: Only registered nodes can update prices
Authorization system: Ward-based permissions (no token staking yet)
Emergency controls: Governance can invalidate prices
Circuit breakers: Automatic stops on anomalies

🔌 Integration with KUSD DSS

Spotter Integration

// Connect oracles to KUSD spotter
spotter.file("BTC-A", "pip", BTC_ORACLE_ADDRESS);
spotter.file("ETH-A", "pip", ETH_ORACLE_ADDRESS);
spotter.file("USDT-A", "pip", USDT_ORACLE_ADDRESS);
spotter.file("USDC-A", "pip", USDC_ORACLE_ADDRESS);
spotter.file("DAI-A", "pip", DAI_ORACLE_ADDRESS);

Price Reading

// DSS contracts call this automatically
(bytes32 price, bool valid) = oracle.peek();

🗺️ Decentralization Roadmap

Phase 1: Testnet (Current)

Single oracle node (deployer only)
Purpose: Testing and development
Security: Centralized but sufficient for testnet

Phase 2: Mainnet Launch (Month 2-3)

3 oracle nodes on different servers/providers
Purpose: Production launch with redundancy
Security: Semi-decentralized, trusted operators

Phase 3: Public Network (Month 3-4)

Open oracle network to community
KUSD staking and reward system
Economic incentives for oracle operators

Phase 4: DAO Governance (Month 6)

KalyDAO control of oracle parameters
Community governance of node registration
Full decentralization achieved

🖥️ Production Deployment

Server Requirements

CPU: 2+ cores
RAM: 4GB+
Storage: 20GB SSD
Network: Reliable internet connection
Uptime: 99.9%+ required

Recommended Setup

# Use PM2 for process management
npm install -g pm2

# Start oracle node with PM2
pm2 start src/index.js --name kusd-oracle

# Setup auto-restart
pm2 startup
pm2 save

Monitoring

# Check node status
pm2 status

# View logs
pm2 logs kusd-oracle

# Monitor resources
pm2 monit

🚨 Alerts & Monitoring

Health Checks

Price update failures: >5 consecutive failures
API source failures: >50% sources down
Blockchain connectivity: RPC connection lost
Large price movements: >10% in 5 minutes

Alert Channels

Discord webhooks: Real-time notifications
Email alerts: Critical issues
Slack integration: Team notifications
Log files: Detailed error tracking

🔐 Security Considerations

Node Security

Private key protection: Use hardware wallets or HSMs
Network security: VPN and firewall protection
Access control: Limited SSH access
Regular updates: Keep software updated

Oracle Security

Multi-source validation: Prevents single source manipulation
Deviation limits: Rejects extreme price movements
Time-based validation: Prevents replay attacks
Emergency controls: Governance override capabilities

📈 Performance Metrics

Target Metrics

Update frequency: Every 60 seconds
Price accuracy: <1% deviation from market
Uptime: 99.9%+
Response time: <10 seconds for price updates

Monitoring Dashboard

Price charts: Real-time price tracking
Source status: API health monitoring
Node performance: Update success rates
System health: Overall system status

🛠️ Troubleshooting

Common Issues

Oracle Node Won't Start

# Check configuration
npm run test

# Verify network connection
curl https://testnetrpc.kalychain.io/rpc

# Check private key
echo $PRIVATE_KEY

Price Updates Failing

# Check API keys
curl "https://api.binance.com/api/v3/ticker/price?symbol=BTCUSDT"

# Verify contract addresses
npx hardhat console --network testnet

High Gas Costs

# Adjust gas price in config
ORACLE_GAS_PRICE=20000000000  # 20 gwei

📞 Support

Documentation

Smart Contract Docs: See contract comments
API Documentation: Check individual API files
Deployment Guide: Follow scripts/deploy.js

Community

GitHub Issues: Report bugs and feature requests
Discord: Join the KUSD community
Email: support@kusd.io

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

Contract Addresses (deployed to mainnet)

KUSD_ORACLE_FACTORY=0x3775a8585f241Eb32b7D32bE08Ee3fda1d093f69 BTC_ORACLE_ADDRESS=0x28f51A114Ffcf36FB77D6ded40807a6415782f5d ETH_ORACLE_ADDRESS=0x80E64f28656e1C95F4dF231536D8dC411822053c USDT_ORACLE_ADDRESS=0xC5342aDDbecabF78d92Ca3c218879d4F767a0D30 USDC_ORACLE_ADDRESS=0xF89dE104147bb36f5473c30eC1d2C067c81ff04E DAI_ORACLE_ADDRESS=0x7Ef8fe406191CB2a7C2671FF724f2eAbCbbd22cF

Contract Addresses (deployed to testnet)

KUSD_ORACLE_FACTORY=0x1D6c4196e135F0Fa1Ad5c5e28E0aed6BD4C0a739 BTC_ORACLE_ADDRESS=0x85a8386367755965C95E31B06778B2c89082E316 ETH_ORACLE_ADDRESS=0x935216C74e1838E7090f31756ce0f64a34A5aAce USDT_ORACLE_ADDRESS=0xf8Be6Ed01e7AE968118cf3db72E7641C59A9Dc4f USDC_ORACLE_ADDRESS=0x930e5F6D686A19794bc7a1615a40032182D359D7 DAI_ORACLE_ADDRESS=0x301F4fbd60156568d87932c42b3C17Bd5F0f33BD

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
deployments		deployments
scripts		scripts
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
hardhat.config.js		hardhat.config.js
package-lock.json		package-lock.json
package.json		package.json

License

frosty720/K_Oracles

Folders and files

Latest commit

History

Repository files navigation