controller.ts

Overview

The `controller.ts` file is responsible for configuring and initializing the core service layer that interacts with Dogecoin blockchain data. It sets up connections to blockchain indexer and RPC (Remote Procedure Call) endpoints, configures the `Blockbook` client for blockchain data access, and exposes a unified `Service` instance tailored for Dogecoin UTXO (Unspent Transaction Output) management.

The file also integrates environment variable configurations, handles API key management depending on the provider (Liquify or Nownodes), and assigns the initialized service to the shared `UTXO` controller class. This enables other parts of the Dogecoin module to leverage the same service instance for querying blockchain data and performing UTXO-related operations.

Classes, Functions, and Methods

1. isXpub(pubkey: string): boolean

Checks if a given public key string corresponds to an extended public key (xpub) format specific to Dogecoin.

• Parameters:

  • pubkey (string): The public key string to test.

• Returns:

  • boolean: true if the key starts with the prefix "dgub", which is Dogecoin's xpub prefix; otherwise false.

• Usage Example:

const key = "dgub8abc123...";
console.log(isXpub(key)); // true

2. formatAddress(address: string): string

Formats a Dogecoin address string. This implementation currently returns the address unchanged but acts as a placeholder for any future address formatting logic.

• Parameters:

  • address (string): The Dogecoin address to format.

• Returns:

  • string: The formatted address.

• Usage Example:

const rawAddress = "D7Y55FqQp2h...";
const formatted = formatAddress(rawAddress);
console.log(formatted); // "D7Y55FqQp2h..."

Constants and Variables

• Environment Variables Required:

  • INDEXER_URL: Base HTTP URL for blockchain indexer API.

  • INDEXER_WS_URL: WebSocket URL for blockchain indexer.

  • INDEXER_API_KEY: Optional API key for indexer access.

  • RPC_URL: URL for blockchain RPC endpoint.

  • RPC_API_KEY: Optional API key for RPC access.

• Derived Booleans:

  • IS_LIQUIFY: Indicates if both RPC_URL and INDEXER_URL contain "liquify" (a service provider).

  • IS_NOWNODES: Indicates if both URLs contain "nownodes" (another provider).

• URLs with API keys appended:

  • httpURL, wsURL, rpcUrl are constructed with API keys appended if applicable.

• API keys for Nownodes:

  • apiKey and rpcApiKey are set only if Nownodes provider is detected.

Main Objects

logger

An instance of the `Logger` class scoped to the Dogecoin API namespace. It logs messages at a level determined by the `LOG_LEVEL` environment variable.

• Namespace: unchained > coinstacks > dogecoin > api

blockbook

An instance of the `Blockbook` client class configured with:

• httpURL and wsURL: URLs for REST and WebSocket communication.

• logger: Logger instance.

• apiKey: API key for indexer if applicable.

This client interfaces with blockchain indexer services to retrieve blockchain data such as blocks, transactions, and addresses.

service

An instance of the `Service` class that acts as the main interface for Dogecoin blockchain operations. It is configured with:

• blockbook: The above Blockbook client.

• rpcUrl: URL for RPC calls.

• rpcApiKey: Optional RPC API key.

• isXpub: The isXpub utility function to identify extended public keys.

• addressFormatter: The formatAddress function.

The `service` instance abstracts communication with both the indexer and RPC endpoints and provides UTXO-related functionality.

Integration with UTXO Controller

The file assigns the created `service` instance to the static `service` property of the `UTXO` class:

UTXO.service = service

This makes the service globally accessible within all `UTXO` controller instances, centralizing blockchain interaction logic and avoiding redundant initializations.

Important Implementation Details

• Environment Validation: The file immediately throws an error if critical environment variables (INDEXER_URL, INDEXER_WS_URL, RPC_URL) are not set, ensuring the application fails early on misconfiguration.

• Provider-specific URL and API key handling: The logic detects the provider (Liquify or Nownodes) by checking the URLs and adjusts how API keys are appended to URLs accordingly.

• Use of Blockbook Client: The Blockbook client is used as the primary indexer interface, which supports both HTTP and WebSocket protocols, enabling real-time blockchain data updates.

• Static Service Assignment: By assigning the service instance to UTXO.service, all downstream UTXO-related operations share the same configured service, promoting consistency and resource efficiency.

Interaction with Other System Parts

• Imports:

  • Blockbook from @shapeshiftoss/blockbook: Blockchain indexer client.

  • Service from UTXO service module: Core Dogecoin service class.

  • UTXO from UTXO controller module: Controller for UTXO operations.

  • Logger from @shapeshiftoss/logger: Structured logging utility.

• Exports:

  • logger: Available for logging in other modules.

  • formatAddress: Exported address formatting utility.

  • service: Exported Dogecoin blockchain service instance.

• Downstream Usage:

  • Other Dogecoin modules and components can import the service and logger from this file.

  • The UTXO controller class uses the assigned service for blockchain queries and transaction building.

  • This file acts as a configuration and initialization layer within the Dogecoin coinstack integration in the broader application.

Usage Example

import { service, logger, formatAddress } from './controller'

// Check if a public key is an xpub
const pubkey = 'dgub8xyz...'
if (service.isXpub(pubkey)) {
  logger.info('Received an extended public key')
}

// Format an address
const addr = formatAddress('D7Y55FqQp2h...')
logger.info(`Formatted address: ${addr}`)

// Use the service to fetch UTXOs, transactions, or other blockchain data
const utxos = await service.getUtxos(addr)
logger.info(`Fetched ${utxos.length} UTXOs`)

Mermaid Class Diagram

classDiagram
    class Blockbook {
        +constructor(options)
        +methods...
    }

    class Service {
        +constructor(options)
        +getUtxos(address)
        +sendTransaction(tx)
        +other blockchain methods...
    }

    class UTXO {
        <<static>>
        +service: Service
        +methods...
    }

    class Logger {
        +constructor(options)
        +info(message)
        +error(message)
        +debug(message)
        +other logging methods...
    }

    controller.ts  -->  Blockbook : instantiates
    controller.ts  -->  Service : instantiates with Blockbook
    controller.ts  -->  Logger : instantiates
    controller.ts  ..>  UTXO : assigns static service property

Summary

The `controller.ts` file is a critical configuration and bootstrap component for Dogecoin blockchain interaction within the application. It initializes the blockchain client, manages environment-based configuration, and provides a well-structured `Service` instance used by the UTXO controller and other modules. The file ensures seamless integration with different blockchain data providers while maintaining a consistent interface for Dogecoin blockchain operations.