Core Component

DataSource Manager

The central orchestrator for Bitcoin data retrieval, providing seamless access to multiple data providers through a unified interface.

The DataSource Manager is the central component that orchestrates data retrieval from different Bitcoin data providers. It handles provider selection, fallbacks, caching, and data normalization, ensuring your application maintains consistent access to blockchain data.

┌─────────────────────────────────────────────────────────────┐
│                     Your Application                         │
└──────────────────────────┬──────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                   DataSource Manager                        │
└───────┬─────────────┬─────────────┬─────────────┬─────────┘
        │             │             │             │
        ▼             ▼             ▼             ▼
   ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
   │ Maestro │   │Sandshrew│   │ Mempool │   │ Esplora │
   └─────────┘   └─────────┘   └─────────┘   └─────────┘

Core Features

Provider Management

Seamlessly manage multiple data providers with automatic fallback and load balancing.

Intelligent Caching

Built-in caching system to optimize performance and reduce API calls.

Type-Safe Interface

Fully typed API with TypeScript for a robust development experience.

Data Normalization

Consistent data format across different providers through automatic normalization.

Core Methods

DataSourceManager Interface

interface DataSourceManager {
  // Bitcoin Operations
  getBalance(address: string): Promise<string>
  getUtxos(address: string): Promise<UTXO[]>
  getTransaction(txid: string): Promise<Transaction>
  broadcastTransaction(txHex: string): Promise<string>

  // Ordinals & Inscriptions
  getInscriptions(address: string): Promise<Inscription[]>
  getInscriptionContent(id: string): Promise<string>
  getInscriptionById(id: string): Promise<Inscription>

  // Token Operations
  getMetaBalances(address: string, type: 'brc20' | 'runes'): Promise<any[]>
  getTokenInfo(ticker: string, type: 'brc20' | 'runes'): Promise<any>

  // Network Operations
  estimateFee(targetBlocks?: number): Promise<number>
  getBlockHeight(): Promise<number>
  getAddressHistory(address: string): Promise<Transaction[]>
}

Usage Example

React Component Example

import { useLaserEyes } from '@omnisat/lasereyes-react'
import { useState, useEffect } from 'react'

function BitcoinData() {
  const { client } = useLaserEyes()
  const [balance, setBalance] = useState('0')
  const [inscriptions, setInscriptions] = useState([])
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    async function fetchData() {
      try {
        const manager = client.getDataSourceManager()
        
        // Fetch balance and inscriptions in parallel
        const [balanceResult, inscriptionsResult] = await Promise.all([
          manager.getBalance('bc1p...'),
          manager.getInscriptions('bc1p...')
        ])

        setBalance(balanceResult)
        setInscriptions(inscriptionsResult)
      } catch (error) {
        console.error('Failed to fetch data:', error)
      } finally {
        setLoading(false)
      }
    }

    fetchData()
  }, [client])

  if (loading) return <div>Loading...</div>

  return (
    <div>
      <h2>Balance: {balance} sats</h2>
      <h3>Inscriptions: {inscriptions.length}</h3>
      {/* Render inscriptions */}
    </div>
  )
}

Provider Configuration

Configuration Example

import { LaserEyesClient, createConfig, MAINNET } from '@omnisat/lasereyes-core'

const config = createConfig({
  network: MAINNET,
  dataSources: {
    // Primary providers
    maestro: {
      apiKey: process.env.MAESTRO_API_KEY,
      priority: 1
    },
    sandshrew: {
      apiKey: process.env.SANDSHREW_API_KEY,
      priority: 2
    },
    // Fallback providers
    mempool: {
      url: 'https://mempool.space/api',
      priority: 3
    },
    esplora: {
      url: 'https://blockstream.info/api',
      priority: 4
    }
  }
})

Best Practices

Multiple Providers

Configure multiple data providers with different priorities for optimal reliability and performance.

Error Handling

Implement proper error handling and retries for network issues or provider outages.

Caching Strategy

Utilize the built-in caching system effectively to reduce API calls and improve response times.

API Keys

Use environment variables for API keys and register for production keys with data providers.

DataSource System

Maestro