Blockchain Data Indexing

Overview

The Blockchain Data Indexing module provides a structured and efficient mechanism for querying and caching blockchain data such as transaction histories, balances, blocks, and unspent outputs. Its primary purpose is to abstract away the complexity of interacting directly with blockchain nodes by leveraging an indexing service—Blockbook—to offer normalized and enriched blockchain data through a consistent API interface.

This module addresses the challenges of querying large blockchain datasets efficiently, ensuring quick access to transactional and balance information across multiple blockchain types. It supports both UTXO-based and account-based blockchains by providing a unified data representation and access patterns.

Core Concepts and Purpose

Key Functionalities and Workflows

1. REST API Client and Controller

The module exposes a set of RESTful API endpoints to fetch blockchain data. It relies on an HTTP client (`axios`) configured with retry mechanisms and timeout policies to communicate with the Blockbook indexer backend.

For example, the `Blockbook` class (in `blockbook/src/controller.ts`) provides methods such as:

Each method wraps HTTP requests to the Blockbook backend, returning typed results or throwing wrapped errors (`ApiError`) on failure.

2. Data Normalization and Type Definitions

The module defines extensive TypeScript interfaces (in `blockbook/src/models.ts`) representing the blockchain data structures such as transactions (`Tx`), addresses (`Address`), blocks (`Block`), tokens, and unspent outputs (`Utxo`). These interfaces ensure consistent data models across different blockchain implementations, facilitating uniform API consumption.

For example, the `Tx` interface covers common transaction fields and coin-specific extensions like `ethereumSpecific`, allowing clients to handle details relevant to each blockchain.

3. Error Handling and Retries

The HTTP client is enhanced with `axios-retry` to automatically retry failed requests based on network errors or HTTP status codes indicative of transient failures. Timeouts are managed to prevent hanging requests. This design ensures higher reliability when querying the indexing service.

4. API Endpoint Annotations and Documentation

The code is decorated with metadata using [tsoa](/projects/291/68848) decorators (`@Route`, `@Get`, `@Example`) to define API routes, HTTP methods, and example responses. This supports automated OpenAPI documentation generation, promoting clarity and ease of integration.

5. Interaction with Other System Components

Design Patterns and Approaches

Code Example Snippets

Blockbook REST API Method Example

@Get('tx/{txid}')
async getTransaction(@Path() txid: string): Promise<Tx> {
  const { data } = await this.instance.get<Tx>(`api/v2/tx/${txid}`)
  return data
}

Address Query with Pagination and Detail Levels

@Get('address/{address}')
async getAddress(
  @Path() address: string,
  @Query() page?: number,
  @Query() pageSize?: number,
  @Query() details?: 'basic' | 'tokens' | 'tokenBalances' | 'txids' | 'txslight' | 'txs',
): Promise<Address> {
  const { data } = await this.instance.get<Address>(`api/v2/address/${address}`, {
    params: { page, pageSize, details }
  })
  return data
}

Visualization: Flowchart of Blockchain Data Indexing Query Workflow

flowchart TD
  Client[Client Request] -->|REST API Call| API_Module[Blockchain Data Indexing Module]
  API_Module -->|HTTP Request| Blockbook[Blockbook Indexer Backend]
  Blockbook -->|Indexed Blockchain Data| API_Module
  API_Module -->|Normalized Response| Client
  API_Module -->|Logs & Metrics| Logger[Logging & Monitoring]

This detailed documentation covers the Blockchain Data Indexing module’s purpose, design, and operation within the system, illustrating how it provides efficient, normalized access to blockchain data via the Blockbook indexer.