API Servers

Purpose

API Servers provide the crucial interface layer between client applications and the underlying blockchain data and services. This subtopic addresses the need for exposing blockchain information and transaction capabilities through standardized, developer-friendly RESTful and WebSocket APIs. These servers abstract away blockchain-specific complexities, allowing clients to query account data, transaction history, send transactions, estimate fees, and subscribe to real-time blockchain events.

While the parent topic covers the modular implementations of blockchain nodes and APIs, the API Servers subtopic focuses specifically on the server-side application logic that enables interaction with blockchain node daemons and indexers. It solves the challenge of unifying various blockchain data sources into a consistent API surface, ensuring scalability, real-time updates, and extensibility across different blockchains.

Functionality

API Servers implement the following key workflows and features:

• REST API Endpoints: Serve HTTP routes for querying blockchain data such as account details, transaction history, transaction details, sending raw transactions, and gas/fee estimation. These endpoints validate inputs, orchestrate calls to service layers, and format blockchain-specific data into consistent JSON responses.

• WebSocket Real-Time Subscriptions: Maintain WebSocket servers that allow clients to subscribe to live blockchain events such as new blocks and transactions. This enables event-driven updates for wallets and dApps.

• Integration with Blockchain Indexers: Connect to Blockbook or other indexer WebSocket endpoints to receive blockchain event streams. Incoming blocks and transactions trigger handlers that process and cache data, update internal registries, and dispatch updates to subscribed clients.

• Registry Management: A central registry tracks WebSocket subscriptions by address, manages event dispatch, and formats addresses to standardized forms. This ensures efficient routing of blockchain event notifications only to interested clients.

• Prometheus Metrics Exposure: Collect and expose service metrics (request counts, WebSocket connections, errors) for observability and monitoring.

• Swagger/OpenAPI Documentation: Serve interactive API documentation with Swagger UI, facilitating developer onboarding and API exploration.

• Error Handling and Middleware: Implement common middleware for logging, error handling, and input validation to maintain robust server operation.

• Chain-Specific Controllers: Each blockchain API server includes specialized service and controller logic to accommodate chain-specific transaction formats, internal transaction tracing, and fee estimation. For example:

  • Ethereum and Layer 2 chains handle internal transaction traces for richer transaction data.

  • UTXO chains like Bitcoin and Litecoin use Blockbook transaction parsing.

  • Thorchain’s Go API server exposes additional affiliate fee endpoints.

Example Workflow: New Block Event Handling

1. The server’s WebSocket client listens to the indexer’s block event stream.

2. On receiving a new block, the blockHandler asynchronously fetches and processes transactions via service controllers.

3. Transactions are parsed, enriched (e.g., internal txs for Ethereum), and relevant addresses are extracted.

4. The registry updates subscriptions and dispatches notifications to WebSocket clients subscribed to those addresses.

This flow ensures clients receive timely updates about the blockchain state changes they care about.

const blockHandler: BlockHandler<NewBlock, Array<BlockbookTx>> = async (block) => {
  const txs = await service.handleBlock(block.hash)
  return { txs }
}

Integration

API Servers are tightly integrated within the broader blockchain node ecosystem:

• They consume data from indexer services (e.g., Blockbook) through WebSocket clients to receive blockchain event streams.

• They interact with daemon nodes indirectly by sending raw transactions or querying node RPC endpoints when necessary.

• They serve client applications by exposing stable REST and WebSocket APIs, hiding blockchain protocol intricacies.

• They collaborate with other subtopics:

  • Use health and readiness probes to report service status.

  • Provide metrics data for Prometheus & Grafana monitoring.

  • Incorporate deployment automation configurations for Kubernetes.

  • Leverage common API libraries for middleware, logging, connection handling, and subscription registry management.

The API Servers complement daemon node management and indexer services by acting as the gateway layer that ensures efficient, scalable, and user-friendly access to blockchain data and operations.

Diagram

sequenceDiagram
  participant Client as Client Application
  participant APIServer as API Server (Express.js / Go)
  participant Registry as Subscription Registry
  participant Blockbook as Blockchain Indexer (Blockbook)
  participant Daemon as Blockchain Daemon Node

  Client->>APIServer: REST Request (e.g., Tx History)
  APIServer->>Registry: Query cached data / services
  Registry->>Blockbook: Query blockchain data
  Blockbook-->>Registry: Return blockchain data
  Registry-->>APIServer: Formatted response data
  APIServer-->>Client: JSON response

  Client->>APIServer: WS Subscription (addresses)
  APIServer->>Registry: Register subscription

  Blockbook->>APIServer: New block / tx event (WS)
  APIServer->>Registry: Process block/tx
  Registry-->>Client: Push relevant event updates

  Client->>APIServer: POST Send Transaction
  APIServer->>Daemon: Broadcast raw transaction
  Daemon-->>APIServer: Tx broadcast result
  APIServer-->>Client: Tx hash / status

This sequence highlights how API Servers mediate between clients, blockchain data providers, and node daemons to deliver real-time and on-demand blockchain services.

This subtopic focuses on API Servers’ specialized role in delivering blockchain data and operations through robust REST and WebSocket endpoints, leveraging chain-specific logic to provide a unified and extensible interface for diverse blockchain ecosystems.