Oracle Price Monitor API

Modern Oracle price monitoring service with unified Feed API and Proxy Round ID system for Web UI integration.

🚀 Features

• Unified Proxy Round ID System: Complete migration to Chainlink-compatible round ID format
• Feed-based Architecture: Unified API design with Feed ID abstraction
• Multi-Strategy Support: Supports both Push and Pull data acquisition models
• Real-time Price Monitoring: Live price feeds from Pyth Network with enhanced round tracking
• Web UI Integration: Specialized API endpoints for dashboard applications with Proxy Round ID information
• Phase Management: Support for multi-phase aggregator upgrades
• Extensible Design: Easy to add new data sources and strategies

🔧 Configuration

Environment Variables

# Ethereum Network
PRIVATE_KEY=your_private_key_here
ETHEREUM_PROVIDER=your_provider_url

🚀 Usage

Development

npm run dev

Production

npm run build
npm start

Docker

docker build -t oracle-price-monitor .
docker run -e PRIVATE_KEY=xxx -e ETHEREUM_PROVIDER=xxx oracle-price-monitor

Key Features

• Proxy Round ID System: Unified Chainlink-compatible round ID format with Phase management
• Feed-based API: Unified interface using Feed IDs for all price data
• Real-time Monitoring: Live price feeds from Pyth Network with enhanced round tracking
• Dashboard Integration: Complete API for Web UI dashboard with Proxy Round ID information
• Multi-Strategy Support: Extensible architecture for different data sources
• Status Monitoring: Comprehensive health checks and feed status tracking

Proxy Round ID System

The service uses a unified Proxy Round ID system compatible with Chainlink's EACAggregatorProxy pattern:

Proxy Round ID = (Phase ID << 64) | Original Round ID

Example

• Phase ID: 7
• Original Round ID: 7221
• Proxy Round ID: 129127208515966870709

Benefits

• Unified Interface: Single round ID system eliminates complexity
• Chainlink Compatibility: Full compatibility with industry standards
• Phase Support: Ready for multi-phase aggregator upgrades
• Enhanced Monitoring: Rich debugging information

Prerequisites

• Node.js 16+
• A blockchain provider (e.g., Infura, Alchemy, or local node)
• Private key with sufficient funds to submit transactions (if running in active mode)
• Network access to Pyth Hermes API

Configuration

The service is configured via a JSON file in src/config/default.json. Key configuration options:

{
  "server": {
    "port": 3001,
    "host": "0.0.0.0"
  },
  "pyth": {
    "hermesUrl": "https://hermes.pyth.network"
  },
  "ethereum": {
    "provider": "YOUR_PROVIDER_URL",
    "privateKey": "YOUR_PRIVATE_KEY"
  },
  "assets": [
    {
      "name": "BTC/USD",
      "pythPriceId": "e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43",
      "oracleAddress": "YOUR_ORACLE_CONTRACT_ADDRESS",
      "updateThreshold": 0.001,
      "cooldownMinutes": 5
    }
  ]
}

Environment Variables

Configuration can be overridden with environment variables:

• ETHEREUM_PROVIDER: Blockchain provider URL
• ETHEREUM_PRIVATE_KEY: Private key for signing transactions
• SERVER_PORT: Port for the health check API
• PYTH_HERMES_URL: Pyth Hermes API URL

Getting Started

Local Development

1. Clone the repository
2. Install dependencies:

   npm install

3. Configure the service by editing src/config/default.json
4. Build the TypeScript code:

   npm run build

5. Start the service:

   npm start

Docker Deployment

1. Build the Docker image:

   docker build -t price-monitor-service .

2. Run the container:

   docker run -d \
     -p 3001:3001 \
     -e ETHEREUM_PROVIDER=YOUR_PROVIDER_URL \
     -e ETHEREUM_PRIVATE_KEY=YOUR_PRIVATE_KEY \
     --name price-monitor \
     price-monitor-service

API Endpoints

Oracle Feed API

Unified Feed API for Web UI integration:

Dashboard

• GET /api/oracle/dashboard: Get complete oracle dashboard data

  {
    "success": true,
    "data": {
      "summary": {
        "totalFeeds": 3,
        "activeFeeds": 3,
        "lastUpdate": "2025-01-24T14:06:00Z",
        "systemStatus": "healthy"
      },
      "feeds": [...],
      "networkInfo": {
        "name": "Bitlayer Main",
        "chainId": 200901
      },
      "triggerParams": {
        "deviationThreshold": "0.1%",
        "heartbeat": "00:49:02"
      }
    }
  }

Feed Data

• GET /api/oracle/feeds: Get list of all feeds
• GET /api/oracle/feed/{feedId}: Get specific feed price data
• GET /api/oracle/feed/{feedId}/history?timeframe=24h: Get feed historical data
• GET /api/oracle/feeds/status: Get status of all feeds

Example Usage

# Get dashboard data
curl http://localhost:3001/api/oracle/dashboard

# Get BTC/USD feed (Feed ID: 1)
curl http://localhost:3001/api/oracle/feed/1

# Get all feeds
curl http://localhost:3001/api/oracle/feeds

# Get feed history
curl http://localhost:3001/api/oracle/feed/1/history?timeframe=24h

Feed Configuration

Feeds are configured in config/feeds.json:

{
  "feeds": {
    "1": {
      "asset": "BTC/USD",
      "strategy": "pyth-push",
      "enabled": true,
      "config": {
        "pythId": "e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43",
        "updateThreshold": 0.005,
        "maxUpdateInterval": 30
      }
    }
  }
}

Testing New Endpoints

Use the provided test script:

node test-new-endpoints.js

License

MIT