Blockbook WebSocket

Purpose

Blockbook WebSocket focuses on enabling real-time event subscription for blockchain data streams, specifically new blocks and transactions. Unlike the parent topic of blockchain data indexing and caching, which primarily addresses efficient data retrieval via REST APIs or cached queries, this subtopic solves the problem of delivering immediate notifications about blockchain state changes. This is crucial for applications requiring low-latency updates, such as wallets updating balances instantaneously or services reacting to new confirmed transactions without polling.

Functionality

The core functionality revolves around a specialized WebSocket client that connects to a Blockbook indexer’s real-time event interface. Key workflows and features include:

• Connection Establishment and Management: The client initializes a WebSocket connection with the Blockbook endpoint, optionally appending an API key for access control.

• Subscription Handling:

  • Automatically subscribes to new block notifications upon connection.

  • Allows dynamic subscription to specific blockchain addresses to receive transaction events relevant to those addresses.

• Event Processing and Dispatch:

  • Listens for incoming WebSocket messages.

  • Parses and distinguishes between new block events (subscribeNewBlock) and new transaction events (subscribeAddresses).

  • Dispatches these events to registered asynchronous handler functions, supporting multiple handlers for each event type.

• Resilience:

  • Implements reset logic on receiving new block or transaction events to maintain a stable WebSocket session.

• Address Subscription Updates:

  • Supports updating the set of subscribed addresses at runtime, sending updated subscription requests without reconnecting.

This approach enables client applications or backend services to react promptly to blockchain changes as they occur.

Critical Interaction Example

// Subscribe to new blocks and address-specific transactions
const wsClient = new WebsocketClient(
  'wss://blockbook.example.com',
  {
    transactionHandler: async (tx) => { /* handle new tx */ },
    blockHandler: async (block) => { /* handle new block */ },
  }
);

// Dynamically subscribe to address updates
wsClient.subscribeAddresses(['bc1qaddress1...', 'bc1qaddress2...']);

Integration with Parent Topic and Other Subtopics

Blockbook WebSocket complements the broader **Blockchain Data Indexing** topic by providing the real-time event layer that sits on top of indexed blockchain data. While the **Blockbook API** subtopic enables querying historical data efficiently, Blockbook WebSocket pushes incremental updates to clients, ensuring they maintain up-to-date views without polling.

It also closely integrates with the **WebSocket Event Subscription** subtopic by implementing the client-side mechanics to manage subscriptions, event reception, and dispatching. This subtopic uniquely introduces the specific handling and protocol details for Blockbook’s WebSocket API, including subscription message formats and event parsing.

By bridging data indexing and real-time updates, Blockbook WebSocket enables a seamless developer experience where applications can query historical data and subscribe to live blockchain events through consistent interfaces.

Diagram

sequenceDiagram
    participant Client
    participant WebsocketClient
    participant BlockbookWS as Blockbook WebSocket Server

    Client->>WebsocketClient: Initialize with handlers
    WebsocketClient->>BlockbookWS: Connect WebSocket
    WebsocketClient->>BlockbookWS: Subscribe to newBlock events
    BlockbookWS-->>WebsocketClient: newBlock event
    WebsocketClient->>Client: Invoke blockHandler(newBlock)

    Client->>WebsocketClient: subscribeAddresses([addr1, addr2])
    WebsocketClient->>BlockbookWS: Subscribe to addresses' newTx events
    BlockbookWS-->>WebsocketClient: newTx event for addr1
    WebsocketClient->>Client: Invoke transactionHandler(newTx)

This diagram illustrates the lifecycle of the WebSocket client from initialization, subscribing to new blocks and addresses, and dispatching incoming events to client handlers.

Blockbook WebSocket thus forms a vital real-time event subscription layer atop the indexed blockchain data, enabling reactive blockchain applications with minimal latency.