API Server

Purpose

The API Server subcomponent serves as the primary interface for clients to interact with the Thorchain blockchain data and related services. It addresses the need for:

• Exposing blockchain data and operations via RESTful endpoints and WebSocket connections.

• Supporting Thorchain-specific features, such as querying affiliate fee revenue alongside standard blockchain data.

• Providing a performant, robust, and scalable server with built-in metrics, logging, and health endpoints.

This subtopic focuses on the Thorchain API server's unique responsibilities and capabilities that go beyond generic Cosmos SDK or blockchain API services, notably integrating affiliate revenue data and customized transaction handling specific to Thorchain.

Functionality

The API Server is implemented in Go and leverages several packages, including the Cosmos SDK abstraction and a custom affiliate fee indexer. Its key responsibilities and workflows include:

REST API Endpoints

• General chain info and health:

  • /api/v1/info — Returns current chain and node status.

  • /health — Provides service health and connection counts.

• Account and transaction data:

  • /api/v1/account/{pubkey} — Retrieves account details for a given public key.

  • /api/v1/account/{pubkey}/txs — Provides paginated transaction history.

  • /api/v1/tx/{txid} — Fetches specific transaction details by ID.

• Transaction submission:

  • /api/v1/send (POST) — Accepts raw transactions to broadcast to the Thorchain network.

• Gas estimation:

  • /api/v1/gas/estimate (POST) — Estimates gas costs for a proposed transaction.

• Affiliate revenue data:

  • /api/v1/affiliate/revenue — Returns total affiliate fees earned within a specified time range. Supports query parameters start and end as Unix timestamps.

WebSocket Endpoint

• The API Server manages WebSocket connections allowing clients to subscribe to pending and confirmed transactions in real-time. This enables event-driven applications to react promptly to blockchain activity.

Internal Components and Flow

• Handler Layer: Extends Cosmos SDK handler with Thorchain-specific logic, including interacting with the affiliate fee indexer.

• WebSocket Manager: Manages all WebSocket client connections, subscription handling, and message broadcasting with Prometheus metrics integration.

• HTTP Server: Configured with timeouts, CORS support, and middleware for logging and request validation.

• Prometheus Metrics: Exposes /metrics endpoint for monitoring server performance and usage.

• Swagger UI and Docs: Provides interactive API documentation served under /docs/ and /swagger.

Example: Affiliate Revenue Query Flow

When a client requests affiliate revenue via [/api/v1/affiliate/revenue](/projects/291/69281), the server:

1. Parses optional start and end query parameters, defaulting to epoch start and current time if omitted.

2. Calls the handler's GetAffiliateRevenue method with these timestamps.

3. Returns the aggregated revenue data or an error if the retrieval fails.

func (a *API) AffiliateRevenue(w http.ResponseWriter, r *http.Request) {
    start, err := strconv.Atoi(r.URL.Query().Get("start"))
    if err != nil {
        start = 0
    }

    end, err := strconv.Atoi(r.URL.Query().Get("end"))
    if err != nil {
        end = int(time.Now().UnixMilli())
    }

    affiliateRevenue, err := a.handler.GetAffiliateRevenue(start, end)
    if err != nil {
        api.HandleError(w, http.StatusInternalServerError, err.Error())
        return
    }

    api.HandleResponse(w, http.StatusOK, affiliateRevenue)
}

This integration of affiliate revenue data is unique to this subtopic and extends the parent topic's general Thorchain functionality.

Integration

The API Server acts as the central point of interaction for Thorchain blockchain data and services, tightly integrating with other subtopics:

• Affiliate Fee Indexer: The API Server calls this indexer to retrieve aggregated affiliate fee data, exposing it via REST. This adds business-specific insight beyond raw blockchain data.

• Transaction Parsing: The server uses parsed and enriched transaction data for API responses and WebSocket event messages, ensuring clients receive detailed information.

• WebSocket Event Subscription: The API Server hosts and manages WebSocket connections, allowing clients to subscribe to live transaction events streamed from the underlying indexer and node.

• Cosmos SDK Integration: By embedding a Cosmos API handler, the server reuses shared logic for chain data retrieval and transaction handling, but adds Thorchain-specific extensions.

• Monitoring & Metrics: The server exposes Prometheus metrics integrated with the project's observability stack, enabling operational insight.

This subtopic complements the parent topic by providing the API layer that exposes Thorchain blockchain data and affiliate revenue in a consistent, extensible, and developer-friendly manner.

Diagram

flowchart TD
    Client[Client Application]
    subgraph API Server
        REST[REST API Endpoints]
        WS[WebSocket Manager]
        Handler[Thorchain Handler]
        Indexer[Affiliate Fee Indexer]
        CosmosAPI[Cosmos SDK API Layer]
        Metrics[Prometheus Metrics Endpoint]
    end

    Client -->|HTTP Requests| REST
    Client -->|WebSocket| WS
    REST --> Handler
    WS --> Handler
    Handler --> CosmosAPI
    Handler --> Indexer
    REST --> Metrics

*Diagram Explanation:* Clients interact with the API Server via REST or WebSocket. The server's handler processes requests, leveraging the Cosmos SDK layer for generic blockchain data and the affiliate fee indexer for Thorchain-specific revenue data. Metrics are exposed for monitoring.