Bigmi Best Practices Guide

This guide covers best practices for building robust, performant, and secure Bitcoin applications with Bigmi, based on patterns from the actual codebase.

Client Configuration

Transport Configuration with Fallbacks

Always use multiple providers for reliability:

import { createClient, fallback, blockchair, ankr, mempool, bitcoin } from '@bigmi/core'

const client = createClient({
  chain: bitcoin,
  transport: fallback([
    blockchair(),
    ankr({ apiKey: 'YOUR_API_KEY' }),
    mempool(),
  ], {
    rank: true,        // Auto-optimize provider selection
    retryCount: 3,     // Retry failed requests
    retryDelay: 1000,  // Delay between retries
  })
})

Timeout and Retry Strategy

Configure appropriate timeouts per operation:

const client = createClient({
  transport: http('https://api.provider.com', {
    timeout: 30_000,  // 30 seconds for most operations
    retryCount: 3,
    retryDelay: 1000  // 1 second delay between retries
  })
})

Use fallback with timeout config for individual transports:

const client = createClient({
  chain: bitcoin,
  transport: fallback([
    blockchair({
      timeout: 10_000,  // 10 seconds for fast provider
      retryCount: 2,
    }),
    ankr({ 
      apiKey: 'YOUR_API_KEY',
      timeout: 20_000,  // 20 seconds for reliable provider
      retryCount: 3,
    }),
    mempool({
      timeout: 30_000,  // 30 seconds for slower provider
      retryCount: 1,
    }),
  ], {
    rank: true,
    retryCount: 3,
    retryDelay: 1000,
  })
})

Caching Strategy

Configure appropriate cache times:

const client = createClient({
  cacheTime: 4_000,        // Cache responses for 4 seconds
  pollingInterval: 4_000,  // Poll for updates every 4 seconds
})

Retry Logic with withRetry

Use Bigmi’s built-in retry utility:

import { withRetry, TimeoutError } from '@bigmi/core'

const result = await withRetry(
  () => riskyOperation(),
  {
    delay: 1000, // 1 second delay between retries
    retryCount: 3,
    shouldRetry: ({ error }) => {
      // Don't retry user errors or permanent failures
      return !(error instanceof UserRejectedRequestError)
    }
  }
)

Transaction Management

UTXO Selection Best Practices

Filter and select UTXOs efficiently:

import { getUTXOs, getBalance } from '@bigmi/core'

// Check balance first
const balance = await getBalance(client, { address })
if (balance < requiredAmount + estimatedFee) {
  throw new Error('Insufficient balance')
}

// Get UTXOs with filtering
const utxos = await getUTXOs(client, {
  address,
  minValue: requiredAmount + estimatedFee
})

// Select optimal UTXOs (largest-first strategy)
const selectedUTXOs = utxos
  .sort((a, b) => b.value - a.value)
  .reduce((acc, utxo) => {
    if (acc.totalValue < requiredAmount + estimatedFee) {
      acc.utxos.push(utxo)
      acc.totalValue += utxo.value
    }
    return acc
  }, { utxos: [], totalValue: 0 })

Fee Estimation Strategy

Use dynamic fee estimation with multiple sources:

import { getBlockStats, getBlockCount } from '@bigmi/core'

async function estimateFee(client, priority = 'standard') {
  const blockHeight = await getBlockCount(client)
  const blockStats = await getBlockStats(client, {
    blockNumber: blockHeight,
    stats: ['avgfeerate', 'minfeerate']
  })
  
  const feeRates = {
    economy: blockStats.minfeerate || 1,
    standard: blockStats.avgfeerate || 5,
    priority: (blockStats.avgfeerate || 5) * 2
  }
  
  return feeRates[priority]
}

RBF (Replace-By-Fee) Implementation

Always enable RBF and handle replacements:

import { waitForTransaction, sendUTXOTransaction } from '@bigmi/core'

// Enable RBF when creating transaction
psbt.setInputSequence(0, 0xfffffffd) // RBF-enabled

// Monitor for replacements
const receipt = await waitForTransaction(client, {
  txId,
  txHex,
  confirmations: 1,
  timeout: 300_000, // 5 minutes
  onReplaced: ({ reason, transaction }) => {
    console.log(`Transaction replaced: ${reason}`)
    // Update UI with new transaction
    updateTransactionStatus(transaction)
  }
})

Address Validation

Always validate addresses before use:

import { getAddressChainId } from '@bigmi/core'

function validateAddress(address, expectedChainId = ChainId.BITCOIN_MAINNET) {
  try {
    const addressChainId = getAddressChainId(address)
    
    if (addressChainId !== expectedChainId) {
      throw new Error(`Address is for ${addressChainId}, expected ${expectedChainId}`)
    }
    
    return true
  } catch (error) {
    throw new Error(`Invalid Bitcoin address: ${error.message}`)
  }
}

Wallet Integration

Multi-Wallet Support

Configure multiple connectors for broader compatibility:

import { createConfig } from '@bigmi/client'
import { bitcoin, http } from '@bigmi/core'
import { phantom, xverse, unisat, binance } from '@bigmi/client'

const config = createConfig({
  chains: [bitcoin],
  connectors: [
    phantom(),
    xverse(),
    unisat(),
    binance({ shimDisconnect: true }), // Handle disconnect issues
  ],
  transports: {
    [bitcoin.id]: http('https://api.provider.com')
  }
})

Connection Error Handling

Handle wallet-specific errors gracefully:

import { useConnect } from '@bigmi/react'
import { 
  ProviderNotFoundError, 
  UserRejectedRequestError,
} from '@bigmi/client'

function WalletConnector() {
  const { connect, connectors, isPending, error } = useConnect()

  const handleConnect = async (connector) => {
    try {
      await connect({ connector })
    } catch (error) {
      if (error instanceof ProviderNotFoundError) {
        alert(`Please install ${connector.name} wallet extension`)
      } else if (error instanceof UserRejectedRequestError) {
        console.log('User rejected connection')
      } else {
        console.error('Connection failed:', error)
      }
    }
  }

  return (
    <div>
      {connectors.map((connector) => (
        <button
          key={connector.id}
          onClick={() => handleConnect(connector)}
          disabled={isPending}
        >
          Connect {connector.name}
        </button>
      ))}
      {error && <p>Error: {error.message}</p>}
    </div>
  )
}

Production Deployment

Environment Configuration

Use different configurations for development and production:

const config = createConfig({
  chains: [process.env.NODE_ENV === 'production' ? bitcoin : testnet],
  connectors: [phantom(), xverse()],
  transports: {
    [bitcoin.id]: fallback([
      // Use paid providers in production for reliability
      ankr({ apiKey: process.env.ANKR_API_KEY }),
      blockchair(),
      mempool(),
      http('private_rpc_url')
    ]),
    [testnet.id]: fallback([
      // update the base URL for this transport, as it defaults to a mainnet URL
        mempool({baseUrl: 'https://mempool.space/testnet/api'}),
    ])

  }
})

Monitoring and Logging

Implement proper error tracking:

import { BaseError } from '@bigmi/core'

function logError(error, context) {
  if (error instanceof BaseError) {
    console.error('Bigmi Error:', {
      name: error.name,
      message: error.message,
      details: error.details,
      context
    })
  } else {
    console.error('Unknown Error:', error, context)
  }
  
  // Send to error tracking service in production
  if (process.env.NODE_ENV === 'production') {
    errorTracker.captureException(error, { extra: context })
  }
}

Summary

Following these best practices will help you build robust, performant, and secure Bitcoin applications with Bigmi:

Always use fallback providers for reliability
Handle errors gracefully with specific error types
Implement proper retry logic with exponential backoff
Validate all inputs including addresses and transactions
Use efficient state management to minimize re-renders
Configure appropriate timeouts for different operations
Enable RBF and handle transaction replacements
Support multiple wallets for better user coverage
Use Bigmi’s built-in utilities like withRetry for reliability

​Bigmi Best Practices Guide

​Client Configuration

​Transport Configuration with Fallbacks

​Timeout and Retry Strategy

​Caching Strategy

​Retry Logic with withRetry

​Transaction Management

​UTXO Selection Best Practices

​Fee Estimation Strategy

​RBF (Replace-By-Fee) Implementation

​Address Validation

​Wallet Integration

​Multi-Wallet Support

​Connection Error Handling

​Production Deployment

​Environment Configuration

​Monitoring and Logging

​Summary