UTXO API Controllers

Purpose

This component addresses the unique requirements of UTXO-based blockchains such as Bitcoin. Unlike account-based chains, UTXO blockchains track spendable outputs rather than balances directly, necessitating specialized logic to retrieve account details, transaction history, unspent outputs, and raw transaction data. The UTXO API Controllers provide a standardized RESTful interface for clients to interact with these features, abstracting blockchain-specific complexities while maintaining consistency within the unified API layer.

Functionality

The UTXO API Controllers expose several key workflows essential for UTXO blockchain interactions:

• Account Information Retrieval: Fetches comprehensive account data by address or extended public key (xpub), including confirmed and unconfirmed balances, associated addresses, and derivation indexes for generating new addresses.

• Transaction History Pagination: Supports paginated retrieval of historical transactions tied to an address or xpub, enabling efficient browsing through large sets of transaction data.

• Unspent Transaction Outputs (UTXOs): Retrieves all spendable outputs for an address or xpub, facilitating wallet balance calculations and transaction construction.

• Transaction Details: Provides detailed transaction data, both as parsed and raw hex formats, directly sourced from the blockchain node via Blockbook.

• Transaction Broadcasting: Accepts serialized raw transactions and submits them to the blockchain network through RPC calls to a full node.

• Network Fee Estimation: Returns current recommended fee rates for different confirmation speeds, aiding clients in setting appropriate transaction fees.

These workflows are implemented by the `UTXO` controller class delegating to a `Service` layer that interacts with the Blockbook indexer and blockchain RPC endpoints.

Example Controller Method

@Get('account/{pubkey}/txs')
async getTxHistory(@Path() pubkey: string, @Query() cursor?: string, @Query() pageSize = 10): Promise<TxHistory> {
  return UTXO.service.getTxHistory(pubkey, cursor, pageSize)
}

This method handles paginated transaction history requests by forwarding parameters to the service, which manages cursor decoding, pagination logic, and data transformation.

Key Service Responsibilities

• Address vs. XPUB Detection: Determines whether the input is a single address or an extended public key to route calls appropriately to Blockbook's APIs.

• Data Formatting: Converts raw blockchain data into consistent, enriched API response models, including transaction inputs/outputs, fees, and confirmations.

• Error Handling: Wraps external API calls with unified error processing to return meaningful HTTP error responses.

• Fee Estimation: Queries Blockbook fee estimations and converts them into standard units (satoshis per kilobyte) mapped against confirmation speed categories.

Integration

UTXO API Controllers form a critical submodule within the broader Unified API Layer. They complement sibling subtopics such as the EVM API Controllers by specializing in UTXO blockchain semantics and data models. The `Service` class depends on the Blockbook indexer component to retrieve cached blockchain data efficiently, while the controller layer exposes this data via the REST API.

This subtopic introduces UTXO-specific handling that is not covered by the parent topic or EVM-focused subtopics, such as managing extended public keys (xpubs), UTXO sets, and raw transaction broadcasting via RPC. It integrates seamlessly with shared infrastructure like error handling, logging, and API routing established in the parent Unified API Layer.

Diagram

The following flowchart illustrates the core process of handling a transaction history request in the UTXO API Controllers, highlighting the interaction between client requests, controller methods, service logic, and external blockchain data sources.

flowchart TD
  Client[Client Request: Tx History] --> Controller[UTXO Controller]
  Controller --> Service[UTXO Service]
  Service -->|Is XPUB?| Decision{Is XPUB?}
  Decision -->|Yes| BlockbookXpub[Blockbook getXpub API]
  Decision -->|No| BlockbookAddr[Blockbook getAddress API]
  BlockbookXpub --> DataFormat[Format Tx Data]
  BlockbookAddr --> DataFormat
  DataFormat --> Pagination[Handle Pagination & Cursor]
  Pagination --> Response[Return Paginated TxHistory]
  Response --> Client

This flow highlights the decision logic for address vs. xpub handling and the layered processing before returning the response.

This subtopic encapsulates the UTXO blockchain-specific API logic, enabling clients to efficiently query and operate on UTXO-based blockchains within the unified API framework.