How zkusd-protocol/oracle-price-provider works
Project Type and Purpose
• This is a backend microservice (“Oracle Price Provider”) written in Node.js. It aggregates cryptocurrency prices from multiple external REST APIs, computes a weighted average, signs the result, caches data in Redis, and exposes an HTTP endpoint for consumers.
High-Level Components
a. Configuration & Bootstrap
• docker-entrypoint.sh / local-setup.sh – scripts that validate environment variables, generate src/config/providers.js and src/config/others.js, then launch the Node.js app.
• .env / .env.example – environment variables (Redis, deployer key, chain selection, provider toggles & weights, polling intervals).
b. Core Application
• Express HTTP Server (src/index.js + src/routes/price.js) – exposes /price endpoint.
• PriceService (src/services/priceService.js) – reads cached prices, applies weights, computes final price.
• CertificateService (src/services/certificateService.js) – polls and caches certificates.
• Polling Service (src/services/polling.js) – orchestrates periodic fetching from data providers.
c. Data Providers Layer
• Provider clients (in src/utils/clients) – HTTP clients for Redis, signature service, and DNS-over-HTTPS (DoH.js).
• Provider Helpers (src/utils/providerHelpers.js) – normalizes responses.
• src/config/providers.js and src/constants/data_providers.js – defines enabled providers and their weights.
d. Storage
• Redis – used for intermediate caching of raw provider prices, certificates, and final signed prices.
e. External Systems
• Third-party price-feed APIs (Binance, CoinGecko, etc.)
• Optional DNS-over-HTTPS service for secure lookups
• Signature service (using deployer key)
Interactions and Data Flow
1. On startup, the bootstrap script reads env vars → generates providers.js and others.js.
2. Poller timers (configurable intervals) trigger:
a. Price polling: calls each enabled provider’s API → normalizes result → stores in Redis.
b. Certificate polling: fetches certificates → caches in Redis.
3. PriceService aggregates the latest prices from Redis, applies provider weights, signs the payload via the signature client → writes signed result back into Redis.
4. HTTP GET /price route invokes PriceService → returns JSON response to client.
Architectural Patterns & Principles
• Layered / modular design: Separation of config/boot, polling, business logic (aggregation & signing), and API layers.
• Configuration-driven behavior: environment variables define enabled providers, weights, and polling intervals.
• Stateless compute + external state (Redis) → easy to scale horizontally.
• Dockerized microservice → can be deployed via Docker Compose or Kubernetes.
2. Inside, place:
• Config Generator → outputs providers & others configs.
• Polling Module (two sub-blocks: Price Polling, Certificate Polling).
• PriceService & CertificateService block.
• Express HTTP Server block with /price route.
• Redis Client.
• Signature Client & DoH Client.
3. Outside container:
• Redis Server (connected to Redis Client).
• External Provider APIs (fan-out from Polling Module).
• Optional DNS-over-HTTPS service (connected to DoH Client).
• Config Generator → Polling & Service modules (loading config).
• Polling → Provider APIs → back to Redis.
• Service modules ↔ Redis.
• Service modules → Signature Client → back to Redis.
• HTTP Server → Service modules → Redis → HTTP Server → Client.
5. Labels: “ENV VARS”, “Polling Interval = 180s (default)”, “Signed Price Cache”, etc.