InjectiveQL Architecture

System Overview

InjectiveQL is a multi-layered GraphQL API Gateway designed to provide unified access to Injective Protocol data with computed intelligence and developer utilities.

Architecture Diagram

graph TB
    subgraph External
        A[Injective Chain]
        B[Client Applications]
    end

    subgraph "Data Ingestion Layer"
        C[Market Ingestion Service]
        D[Orderbook Fetcher]
        E[Trade Stream]
        F[Position Tracker]
    end

    subgraph "Storage Layer"
        G[(PostgreSQL)]
        H[(Redis)]
    end

    subgraph "Processing Layer"
        I[Liquidity Calculator]
        J[Volatility Calculator]
        K[Health Scorer]
        L[Arbitrage Detector]
        M[Whale Tracker]
    end

    subgraph "API Layer"
        N[GraphQL Server]
        O[REST Endpoints]
        P[Rate Limiter]
        Q[N1NJ4 Verifier]
    end

    A -->|gRPC/REST| C
    A -->|gRPC/REST| D
    A -->|gRPC/REST| E
    A -->|gRPC/REST| F

    C --> G
    C --> H
    D --> H
    E --> H
    F --> H

    G --> I
    G --> J
    G --> K
    G --> L
    G --> M

    H --> I
    H --> J
    H --> K
    H --> L
    H --> M

    I --> N
    J --> N
    K --> N
    L --> N
    M --> N

    N --> P
    O --> P
    P --> Q
    Q --> B

Component Details

1. Data Ingestion Layer

Purpose: Fetch and normalize data from Injective Protocol

Market Ingestion Service

Orderbook Fetcher

Trade Stream

Position Tracker

2. Storage Layer

PostgreSQL

Purpose: Persistent cache and computed metrics

Tables:

Indexes:

Redis

Purpose: High-speed cache for real-time data

Keys:

TTL Strategy:

3. Processing Layer

Liquidity Calculator

Formula:

score = log10(totalDepth + 1) × (1 - spread/100) × 10

Inputs:

Output: Score 0-10 (higher = more liquid)

Cache: 5 minutes

Volatility Calculator

Method: Standard deviation of logarithmic returns

Formula:

returns[i] = log(price[i] / price[i-1])
volatility = stdDev(returns) × √(365×24) × 100

Windows:

Output: Annualized volatility percentage

Cache: 5 minutes

Market Health Scorer

Composite Score (0-100):

Status Classification:

Cache: 5 minutes

Arbitrage Detector

Logic:

  1. Group markets by base asset
  2. Compare prices across markets
  3. Calculate spread: |(price2 - price1) / price1| × 100
  4. Account for trading fees
  5. Sort by profit potential

Output: Market pairs with spread ≥ threshold

Cache: 60 seconds

Whale Tracker

Detection:

Storage: PostgreSQL whale_activity table

Events:

4. API Layer

GraphQL Server (Apollo)

Endpoint: /graphql

Features:

Type System:

Resolvers:

REST Endpoints

Base Path: /api/v1

Routes:

Format: JSON responses with error codes

Rate Limiter

Strategy: Token bucket per hour

Tiers:

Implementation:

Response (429):

{
  "error": "Rate limit exceeded",
  "limit": 100,
  "reset": 1704067200
}

N1NJ4 Verifier

Flow:

sequenceDiagram
    participant Client
    participant API
    participant Redis
    participant Injective

    Client->>API: POST /identity/verify {address}
    API->>Redis: Check cache (n1nj4:address)
    alt Cache hit
        Redis-->>API: Return cached result
    else Cache miss
        API->>Injective: Query CW721 contract
        Injective-->>API: NFT token list
        API->>API: Count NFTs, determine tier
        API->>Redis: Cache result (1h TTL)
    end
    API-->>Client: {verified, tier, nftCount, expiresAt}

Tier Logic:

Data Flow Examples

Market Query with Metrics

sequenceDiagram
    participant Client
    participant GraphQL
    participant Market Resolver
    participant Liquidity Calculator
    participant Redis
    participant PostgreSQL
    participant Injective

    Client->>GraphQL: query { market(id) { ticker, liquidityScore } }
    GraphQL->>Market Resolver: Resolve market
    Market Resolver->>PostgreSQL: SELECT * FROM markets WHERE marketId=?
    PostgreSQL-->>Market Resolver: Market data
    Market Resolver->>Liquidity Calculator: Get liquidityScore
    Liquidity Calculator->>Redis: GET liquidity:marketId
    alt Cache hit
        Redis-->>Liquidity Calculator: Cached score
    else Cache miss
        Liquidity Calculator->>Injective: Fetch orderbook
        Injective-->>Liquidity Calculator: Orderbook data
        Liquidity Calculator->>Liquidity Calculator: Calculate score
        Liquidity Calculator->>Redis: SET liquidity:marketId (5min)
        Liquidity Calculator->>PostgreSQL: INSERT metrics_cache
    end
    Liquidity Calculator-->>Market Resolver: Score
    Market Resolver-->>GraphQL: Market with score
    GraphQL-->>Client: JSON response

Scaling Considerations

Horizontal Scaling

API Servers:

Ingestion Services:

Caching Strategy

Multi-Tier Cache:

  1. Application Memory: None (stateless)
  2. Redis: Real-time data (seconds to minutes)
  3. PostgreSQL: Computed metrics (minutes to hours)
  4. Client-Side: GraphQL allows client caching

Cache Invalidation:

Database Optimization

PostgreSQL:

Redis:

Security

Authentication

Rate Limiting

Input Validation

Error Handling

Monitoring & Observability

Metrics to Track:

Health Checks:

Logging:

Future Enhancements

  1. WebSocket Subscriptions: Real-time price updates
  2. Historical Data Service: Time-series OHLCV generation
  3. Advanced Analytics: ML-based predictions
  4. Multi-Chain Support: Other Cosmos chains
  5. Personalized Alerts: Push notifications for N1NJ4 holders
  6. GraphQL Federation: Microservices architecture