# zkusd-protocol/oracle-price-provider architecture

> Architecture diagram of the GitHub repository zkusd-protocol/oracle-price-provider, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zkusd-protocol/oracle-price-provider
- Repository: https://github.com/zkusd-protocol/oracle-price-provider

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Container" 
        direction TB
        ENV["ENV VARS (.env)"]:::config
        ConfigGen["Config Generator"]:::app
        subgraph "Core Application"
            direction TB
            HTTP["Express HTTP Server\n(src/index.js, /price)"]:::app
            Services["Service Layer"]:::app
            subgraph "Services"
                direction TB
                PriceSvc["PriceService"]:::app
                CertSvc["CertificateService"]:::app
            end
        end
        subgraph "Polling Module"
            direction TB
            PricePoll["Price Polling"]:::app
            CertPoll["Certificate Polling"]:::app
        end
        RedisClient["Redis Client\n(src/utils/clients/redis.js)"]:::app
        SigClient["Signature Client\n(src/utils/clients/signature.js)"]:::app
        DoHClient["DoH Client\n(src/utils/security/DoH.js)"]:::app
        ProviderHelper["Provider Helper\n(src/utils/providerHelpers.js)"]:::app
        subgraph "Config & Constants"
            direction TB
            ProvidersCfg["providers.js\n(src/config/providers.js)"]:::config
            OthersCfg["others.js\n(src/config/others.js)"]:::config
            DoHCfg["doh.js\n(src/config/doh.js)"]:::config
            NetworksCfg["networks.js\n(src/config/networks.js)"]:::config
            DataConsts["data_providers.js\n(src/constants/data_providers.js)"]:::config
            OthersConsts["others.js\n(src/constants/others.js)"]:::config
        end
        ENV -->|loads| ConfigGen
        ConfigGen -->|generates| ProvidersCfg
        ConfigGen --> OthersCfg
        ProvidersCfg --> PricePoll
        ProvidersCfg --> CertPoll
        OthersCfg --> HTTP
        OthersCfg --> Services
        PricePoll -->|uses| ProviderHelper
        CertPoll -->|uses| DoHClient
        PricePoll -->|stores raw prices| RedisClient
        CertPoll -->|stores certs| RedisClient
        Services --> PriceSvc
        Services --> CertSvc
        PriceSvc -->|read/write| RedisClient
        CertSvc -->|read/write| RedisClient
        PriceSvc -->|sign payload| SigClient
        SigClient -->|writes signed price| RedisClient
        HTTP -->|GET /price| PriceSvc
        HTTP -->|returns JSON| Client
        RedisClient --> RedisServer
    end

    subgraph "External Systems"
        direction TB
        Client["API Consumer"]:::external
        RedisServer["Redis Server"]:::infra
        PriceAPIs["Price Feed APIs\n(Binance, CoinGecko)"]:::external
        DoHService["DNS-over-HTTPS"]:::external
    end

    PricePoll -->|fetch| PriceAPIs
    CertPoll -->|fetch| DoHService

    classDef app fill:#BBE1FA,stroke:#333,stroke-width:1px
    classDef infra fill:#C3FDB8,stroke:#333,stroke-width:1px
    classDef external fill:#FFDCA8,stroke:#333,stroke-width:1px
    classDef config fill:#FFE4E1,stroke:#333,stroke-width:1px

    click ConfigGen "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/docker-entrypoint.sh"
    click ConfigGen "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/local-setup.sh"
    click ENV "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/.env.example"
    click HTTP "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/src/index.js"
    click HTTP "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/src/routes/price.js"
    click PriceSvc "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/src/services/priceService.js"
    click CertSvc "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/src/services/certificateService.js"
    click PricePoll "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/src/services/polling.js"
    click RedisClient "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/src/utils/clients/redis.js"
    click SigClient "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/src/utils/clients/signature.js"
    click DoHClient "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/src/utils/security/DoH.js"
    click ProviderHelper "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/src/utils/providerHelpers.js"
    click ProvidersCfg "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/src/config/providers.js"
    click DoHCfg "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/src/config/doh.js"
    click NetworksCfg "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/src/config/networks.js"
    click DataConsts "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/src/constants/data_providers.js"
    click OthersConsts "https://github.com/zkusd-protocol/oracle-price-provider/blob/main/src/constants/others.js"
```
