config.json

Overview

The `config.json` file serves as the primary configuration source for a Blockbook Indexer Service instance tailored to a specific UTXO-based blockchain (in this case, Bitcoin). It outlines critical parameters required to connect to the blockchain daemon (RPC node), configure mempool processing, manage caching policies, and integrate with external fiat currency rate providers.

This JSON-formatted configuration enables the Blockbook indexer to operate efficiently by specifying:

• Blockchain coin identifiers and network-specific protocol details.

• RPC credentials and connection settings.

• Worker thread counts for parallel mempool transaction processing.

• External service endpoints and parameters for fetching fiat exchange rates and alternative fee estimations.

• Data retention policies for indexed blockchain data.

• Message queue endpoints for inter-service communication.

By adjusting these settings, operators can fine-tune the indexer to match the performance, security, and integration requirements of their deployment environment.

Detailed Explanation of Configuration Properties

Usage Examples

Example: RPC Connection Configuration

The indexer connects to the Bitcoin node via RPC using the following configuration parameters:

{
  "rpc_url": "http://localhost:8332",
  "rpc_user": "user",
  "rpc_pass": "password",
  "rpc_timeout": 25
}

This specifies the RPC endpoint, credentials, and a timeout value. The indexer uses these to fetch blockchain data like blocks and transactions.

Example: Fiat Rates Integration

The indexer periodically fetches fiat currency rates from CoinGecko to provide up-to-date conversion values:

{
  "fiat_rates": "coingecko",
  "fiat_rates_vs_currencies": "USD,EUR,JPY,BTC,ETH",
  "fiat_rates_params": "{\"url\": \"https://api.coingecko.com/api/v3\", \"coin\": \"bitcoin\", \"periodSeconds\": 900}"
}

This configuration instructs the service to query the CoinGecko API every 900 seconds (15 minutes), retrieving Bitcoin rates against listed currencies.

Example: Mempool Worker Configuration

To optimize unconfirmed transaction processing, the indexer uses multiple worker threads:

{
  "mempool_workers": 8,
  "mempool_sub_workers": 2
}

This configures 8 primary workers, each with 2 sub-workers, enabling concurrent mempool transaction handling for improved throughput.

Important Implementation Details

• Extended Public Key Magic Bytes:
  The xpub_magic, xpub_magic_segwit_p2sh, and xpub_magic_segwit_native correspond to the version bytes that distinguish different types of extended public keys in hierarchical deterministic wallets (BIP32/BIP44). These values are critical for the indexer to correctly parse and validate wallet data.

• Message Queue Binding:
  The message_queue_binding field configures the messaging endpoint where the indexer listens or publishes blockchain event notifications, enabling inter-service communication and data synchronization in distributed deployments.

• Alternative Estimate Fee:
  The fee estimation method is currently disabled ("whatthefee-disabled"), but the parameters indicate support for fetching fee data from external services with a refresh period, which can be enabled if desired.

• JSON-Encoded Parameter Strings:
  Some configurations, such as alternative_estimate_fee_params and fiat_rates_params, are JSON encoded as strings rather than nested objects. This design allows flexible parsing and dynamic extension without changing the main schema.

Interaction with Other Components

The `config.json` is loaded by the Blockbook indexer service at startup and guides its behavior in the following ways:

• Blockchain Daemon Nodes:
  The RPC parameters (rpc_url, rpc_user, rpc_pass) connect the indexer to the blockchain daemon node for fetching block and transaction data.

• Message Queue Systems:
  The message_queue_binding enables connectivity to message queue services (e.g., ZeroMQ) that propagate new block and mempool transaction events from the daemon to the indexer.

• Fiat Rate Providers:
  The fiat rate parameters tell the indexer how to query and refresh exchange rates from external APIs like CoinGecko, enriching blockchain data with fiat currency valuations.

• Mempool Processing:
  Worker configurations (mempool_workers, mempool_sub_workers) determine concurrency levels for parsing and indexing unconfirmed transactions, affecting performance and responsiveness.

• API Servers:
  The indexer serves data to API servers, which rely on the configuration to ensure the indexer is synchronized with the correct blockchain node and provides accurate, timely data.

Mermaid Diagram: Configuration Structure Flow

flowchart TD
    Config[config.json]

    Config -->|Defines RPC connection| RPC[RPC Parameters]
    Config -->|Configures mempool| Mempool[Mempool Workers]
    Config -->|Sets coin info| Coin[Coin Identification]
    Config -->|Specifies fiat rates| Fiat[Fiat Rates Provider]
    Config -->|Message queue| MQ[Message Queue Binding]
    Config -->|Fee estimation| Fee[Alternative Fee Estimation]
    Config -->|Caching policy| Cache[Block Addresses Cache]

    RPC --> RPC_URL["rpc_url"]
    RPC --> RPC_USER["rpc_user"]
    RPC --> RPC_PASS["rpc_pass"]
    RPC --> RPC_TIMEOUT["rpc_timeout"]

    Mempool --> MEMP_WORKERS["mempool_workers"]
    Mempool --> MEMP_SUB_WORKERS["mempool_sub_workers"]

    Coin --> COIN_NAME["coin_name"]
    Coin --> COIN_SHORTCUT["coin_shortcut"]
    Coin --> COIN_LABEL["coin_label"]
    Coin --> XPUB_MAGIC["xpub_magic"]
    Coin --> XPUB_SEGWIT_P2SH["xpub_magic_segwit_p2sh"]
    Coin --> XPUB_SEGWIT_NATIVE["xpub_magic_segwit_native"]

    Fiat --> FIAT_PROVIDER["fiat_rates"]
    Fiat --> FIAT_CURRENCIES["fiat_rates_vs_currencies"]
    Fiat --> FIAT_PARAMS["fiat_rates_params"]

    MQ --> MQ_BINDING["message_queue_binding"]

    Fee --> FEE_PROVIDER["alternative_estimate_fee"]
    Fee --> FEE_PARAMS["alternative_estimate_fee_params"]

    Cache --> BLOCK_ADDRESSES["block_addresses_to_keep"]

*This flowchart illustrates the major configuration sections and their key properties, showing how the `config.json` organizes settings that influence different functional areas of the Blockbook indexer.*

Summary

The `config.json` file is a centralized, structured configuration artifact that defines critical operational parameters for the Blockbook indexer service. It enables customization of blockchain node connectivity, concurrency settings for mempool processing, integration with external fiat rate and fee estimation services, and caching policies.

By externalizing these settings into a JSON file, the system achieves:

• Flexibility: Easy modifications without recompilation or code changes.

• Scalability: Configurable concurrency to match deployment resources.

• Maintainability: Clear separation of configuration from code.

• Interoperability: Defined interfaces for external API endpoints and messaging.

This file is essential for the correct initialization and runtime behavior of the indexer, facilitating its role as a performant middleware layer within the broader multi-blockchain architecture.