otx-btc-wallet-connectors 0.1.0

package/src/utils/btc-service.ts

@@ -0,0 +1,364 @@
+import type { BitcoinNetwork } from 'otx-btc-wallet-core';
+import type {
+  IBtcService,
+  Utxo,
+  UtxoWithTx,
+  FeeRates,
+  Transaction,
+  FullTransaction,
+  AddressBalance,
+  BtcServiceConfig,
+} from './types';
+import { MempoolService } from './mempool';
+import { BlockstreamService } from './blockstream';
+
+/**
+ * Global configuration for BtcService
+ * This is applied to all new BtcService instances and standalone functions
+ */
+let globalConfig: BtcServiceConfig = {};
+
+/**
+ * Configure global BtcService settings
+ *
+ * @example
+ * ```typescript
+ * import { configureBtcService } from 'otx-btc-wallet-connectors';
+ *
+ * // Use custom mempool instance
+ * configureBtcService({
+ *   mempool: {
+ *     mainnet: 'https://my-mempool.com/api',
+ *     testnet: 'https://my-mempool.com/testnet/api',
+ *   }
+ * });
+ *
+ * // Use only mempool provider (no race)
+ * configureBtcService({
+ *   preferredProvider: 'mempool',
+ *   mempool: {
+ *     mainnet: 'https://custom-api.example.com/api',
+ *   }
+ * });
+ *
+ * // Reset to defaults
+ * configureBtcService({});
+ * ```
+ */
+export function configureBtcService(config: BtcServiceConfig): void {
+  globalConfig = config;
+  // Reset default service so it picks up new config
+  defaultService = null;
+}
+
+/**
+ * Get current global BtcService configuration
+ */
+export function getBtcServiceConfig(): BtcServiceConfig {
+  return { ...globalConfig };
+}
+
+/**
+ * Race promises and return first result
+ */
+function race<T>(promises: Promise<T>[]): Promise<T> {
+  return Promise.race(promises);
+}
+
+/**
+ * Bitcoin Service that combines Mempool and Blockstream APIs
+ * Uses Promise.race for reliability and speed
+ *
+ * @example
+ * ```typescript
+ * // Default usage
+ * const btcService = new BtcService('mainnet');
+ *
+ * // With custom configuration
+ * const btcService = new BtcService('mainnet', {
+ *   mempool: {
+ *     mainnet: 'https://my-mempool-proxy.com/api',
+ *   },
+ *   preferredProvider: 'mempool', // Only use mempool
+ * });
+ *
+ * // Get balance (uses fastest responding API if preferredProvider is 'race')
+ * const balance = await btcService.getBalance('bc1q...');
+ *
+ * // Get UTXOs with tx hex (for Ledger signing)
+ * const utxos = await btcService.getUtxosWithTxHex('bc1q...');
+ *
+ * // Broadcast transaction
+ * const txid = await btcService.broadcastTransaction(signedTxHex);
+ * ```
+ */
+export class BtcService implements IBtcService {
+  readonly name = 'btc-service';
+  private _network: BitcoinNetwork;
+  private _mempool: MempoolService;
+  private _blockstream: BlockstreamService;
+  private _config: BtcServiceConfig;
+
+  constructor(network: BitcoinNetwork = 'mainnet', config?: BtcServiceConfig) {
+    this._network = network;
+    // Merge with global config, instance config takes precedence
+    this._config = { ...globalConfig, ...config };
+    this._mempool = new MempoolService(network, this._config.mempool);
+    this._blockstream = new BlockstreamService(network, this._config.blockstream);
+  }
+
+  get network(): BitcoinNetwork {
+    return this._network;
+  }
+
+  /**
+   * Get the underlying Mempool service for direct access
+   */
+  get mempool(): MempoolService {
+    return this._mempool;
+  }
+
+  /**
+   * Get the underlying Blockstream service for direct access
+   */
+  get blockstream(): BlockstreamService {
+    return this._blockstream;
+  }
+
+  /**
+   * Get current configuration
+   */
+  get config(): BtcServiceConfig {
+    return { ...this._config };
+  }
+
+  setNetwork(network: BitcoinNetwork): void {
+    this._network = network;
+    this._mempool.setNetwork(network);
+    this._blockstream.setNetwork(network);
+  }
+
+  /**
+   * Update configuration
+   */
+  setConfig(config: BtcServiceConfig): void {
+    this._config = { ...this._config, ...config };
+    if (config.mempool) {
+      this._mempool.setCustomEndpoints(config.mempool);
+    }
+    if (config.blockstream) {
+      this._blockstream.setCustomEndpoints(config.blockstream);
+    }
+  }
+
+  /**
+   * Execute method based on preferred provider setting
+   */
+  private async executeWithProvider<T>(
+    mempoolFn: () => Promise<T>,
+    blockstreamFn: () => Promise<T>
+  ): Promise<T> {
+    const provider = this._config.preferredProvider ?? 'race';
+
+    switch (provider) {
+      case 'mempool':
+        return mempoolFn();
+      case 'blockstream':
+        return blockstreamFn();
+      case 'race':
+      default:
+        return race([mempoolFn(), blockstreamFn()]);
+    }
+  }
+
+  // ============ UTXO Methods ============
+
+  async getUtxos(address: string): Promise<Utxo[]> {
+    return this.executeWithProvider(
+      () => this._mempool.getUtxos(address),
+      () => this._blockstream.getUtxos(address)
+    );
+  }
+
+  async getUtxosWithTxHex(address: string): Promise<UtxoWithTx[]> {
+    return this.executeWithProvider(
+      () => this._mempool.getUtxosWithTxHex(address),
+      () => this._blockstream.getUtxosWithTxHex(address)
+    );
+  }
+
+  // ============ Transaction Methods ============
+
+  async getTxHex(txid: string): Promise<string> {
+    return this.executeWithProvider(
+      () => this._mempool.getTxHex(txid),
+      () => this._blockstream.getTxHex(txid)
+    );
+  }
+
+  async getTransaction(txid: string): Promise<Transaction> {
+    return this.executeWithProvider(
+      () => this._mempool.getTransaction(txid),
+      () => this._blockstream.getTransaction(txid)
+    );
+  }
+
+  async getFullTransaction(txid: string): Promise<FullTransaction> {
+    return this.executeWithProvider(
+      () => this._mempool.getFullTransaction(txid),
+      () => this._blockstream.getFullTransaction(txid)
+    );
+  }
+
+  async broadcastTransaction(txHex: string): Promise<string> {
+    return this.executeWithProvider(
+      () => this._mempool.broadcastTransaction(txHex),
+      () => this._blockstream.broadcastTransaction(txHex)
+    );
+  }
+
+  // ============ Address Methods ============
+
+  async getAddressInfo(address: string): Promise<AddressBalance> {
+    return this.executeWithProvider(
+      () => this._mempool.getAddressInfo(address),
+      () => this._blockstream.getAddressInfo(address)
+    );
+  }
+
+  async getBalance(address: string): Promise<number> {
+    return this.executeWithProvider(
+      () => this._mempool.getBalance(address),
+      () => this._blockstream.getBalance(address)
+    );
+  }
+
+  async getConfirmedBalance(address: string): Promise<number> {
+    return this.executeWithProvider(
+      () => this._mempool.getConfirmedBalance(address),
+      () => this._blockstream.getConfirmedBalance(address)
+    );
+  }
+
+  // ============ Fee Methods ============
+
+  async getFeeRates(): Promise<FeeRates> {
+    return this.executeWithProvider(
+      () => this._mempool.getFeeRates(),
+      () => this._blockstream.getFeeRates()
+    );
+  }
+}
+
+// ============ Standalone Functions ============
+
+/**
+ * Default service instance (mainnet)
+ */
+let defaultService: BtcService | null = null;
+
+function getDefaultService(network: BitcoinNetwork = 'mainnet'): BtcService {
+  if (!defaultService || defaultService.network !== network) {
+    defaultService = new BtcService(network);
+  }
+  return defaultService;
+}
+
+/**
+ * Get UTXOs for an address
+ */
+export async function getUtxos(
+  address: string,
+  network: BitcoinNetwork = 'mainnet'
+): Promise<Utxo[]> {
+  return getDefaultService(network).getUtxos(address);
+}
+
+/**
+ * Get UTXOs with raw transaction hex
+ */
+export async function getUtxosWithTxHex(
+  address: string,
+  network: BitcoinNetwork = 'mainnet'
+): Promise<UtxoWithTx[]> {
+  return getDefaultService(network).getUtxosWithTxHex(address);
+}
+
+/**
+ * Get raw transaction hex
+ */
+export async function getTxHex(
+  txid: string,
+  network: BitcoinNetwork = 'mainnet'
+): Promise<string> {
+  return getDefaultService(network).getTxHex(txid);
+}
+
+/**
+ * Get transaction details
+ */
+export async function getTransaction(
+  txid: string,
+  network: BitcoinNetwork = 'mainnet'
+): Promise<Transaction> {
+  return getDefaultService(network).getTransaction(txid);
+}
+
+/**
+ * Get full transaction with inputs and outputs (for Trezor refTxs)
+ */
+export async function getFullTransaction(
+  txid: string,
+  network: BitcoinNetwork = 'mainnet'
+): Promise<FullTransaction> {
+  return getDefaultService(network).getFullTransaction(txid);
+}
+
+/**
+ * Broadcast a signed transaction
+ */
+export async function broadcastTransaction(
+  txHex: string,
+  network: BitcoinNetwork = 'mainnet'
+): Promise<string> {
+  return getDefaultService(network).broadcastTransaction(txHex);
+}
+
+/**
+ * Get address info
+ */
+export async function getAddressInfo(
+  address: string,
+  network: BitcoinNetwork = 'mainnet'
+): Promise<AddressBalance> {
+  return getDefaultService(network).getAddressInfo(address);
+}
+
+/**
+ * Get balance for an address
+ */
+export async function getBalance(
+  address: string,
+  network: BitcoinNetwork = 'mainnet'
+): Promise<number> {
+  return getDefaultService(network).getBalance(address);
+}
+
+/**
+ * Get confirmed balance for an address
+ */
+export async function getConfirmedBalance(
+  address: string,
+  network: BitcoinNetwork = 'mainnet'
+): Promise<number> {
+  return getDefaultService(network).getConfirmedBalance(address);
+}
+
+/**
+ * Get current fee rates
+ */
+export async function getFeeRates(
+  network: BitcoinNetwork = 'mainnet'
+): Promise<FeeRates> {
+  return getDefaultService(network).getFeeRates();
+}

package/src/utils/index.ts

@@ -0,0 +1,56 @@
+// Types
+export type {
+  Utxo,
+  UtxoWithTx,
+  FeeRates,
+  Transaction,
+  FullTransaction,
+  AddressBalance,
+  IBtcService,
+  BtcServiceConfig,
+  NetworkEndpoints,
+} from './types';
+
+// Services
+export { MempoolService } from './mempool';
+export { BlockstreamService } from './blockstream';
+export { BtcService } from './btc-service';
+
+// Configuration functions
+export { configureBtcService, getBtcServiceConfig } from './btc-service';
+
+// Standalone functions
+export {
+  getUtxos,
+  getUtxosWithTxHex,
+  getTxHex,
+  getTransaction,
+  getFullTransaction,
+  broadcastTransaction,
+  getAddressInfo,
+  getBalance,
+  getConfirmedBalance,
+  getFeeRates,
+} from './btc-service';
+
+// PSBT Builder utilities
+export {
+  generatePsbtForSend,
+  finalizeAllInputs,
+  finalizeAndBroadcast,
+  selectUtxos,
+  hexToBytes,
+  bytesToHex,
+  toXOnly,
+  getAddressType,
+  getBitcoinJsNetwork,
+  getInputVBytes,
+  getOutputVBytes,
+  getDustThreshold,
+  deriveAddressFromPublicKey,
+} from './psbt-builder';
+
+export type {
+  GeneratePsbtOptions,
+  GeneratePsbtResult,
+} from './psbt-builder';

package/src/utils/mempool.ts

@@ -0,0 +1,232 @@
+import type { BitcoinNetwork } from 'otx-btc-wallet-core';
+import type {
+  IBtcService,
+  Utxo,
+  UtxoWithTx,
+  FeeRates,
+  Transaction,
+  FullTransaction,
+  AddressBalance,
+  NetworkEndpoints,
+} from './types';
+
+/**
+ * Default API endpoints for mempool.space
+ */
+const DEFAULT_MEMPOOL_ENDPOINTS: Record<BitcoinNetwork, string> = {
+  mainnet: 'https://mempool.space/api',
+  testnet: 'https://mempool.space/testnet/api',
+  testnet4: 'https://mempool.space/testnet4/api',
+  signet: 'https://mempool.space/signet/api',
+};
+
+/**
+ * Fetch with timeout helper
+ */
+async function fetchWithTimeout(
+  url: string,
+  options?: RequestInit,
+  timeout: number = 10000
+): Promise<Response> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await fetch(url, {
+      ...options,
+      signal: controller.signal,
+    });
+    clearTimeout(timeoutId);
+    return response;
+  } catch (error) {
+    clearTimeout(timeoutId);
+    throw error;
+  }
+}
+
+/**
+ * Mempool.space Bitcoin Service
+ *
+ * @see https://mempool.space/docs/api
+ *
+ * @example
+ * ```typescript
+ * // Default usage
+ * const service = new MempoolService('mainnet');
+ *
+ * // With custom endpoints
+ * const service = new MempoolService('mainnet', {
+ *   mainnet: 'https://my-mempool-proxy.com/api',
+ *   testnet: 'https://my-mempool-proxy.com/testnet/api',
+ * });
+ * ```
+ */
+export class MempoolService implements IBtcService {
+  readonly name = 'mempool';
+  private _network: BitcoinNetwork;
+  private _customEndpoints: NetworkEndpoints;
+
+  constructor(network: BitcoinNetwork = 'mainnet', customEndpoints?: NetworkEndpoints) {
+    this._network = network;
+    this._customEndpoints = customEndpoints ?? {};
+  }
+
+  get network(): BitcoinNetwork {
+    return this._network;
+  }
+
+  private get baseUrl(): string {
+    // Use custom endpoint if provided, otherwise use default
+    return this._customEndpoints[this._network] ?? DEFAULT_MEMPOOL_ENDPOINTS[this._network];
+  }
+
+  setNetwork(network: BitcoinNetwork): void {
+    this._network = network;
+  }
+
+  /**
+   * Set custom endpoints for this service
+   */
+  setCustomEndpoints(endpoints: NetworkEndpoints): void {
+    this._customEndpoints = { ...this._customEndpoints, ...endpoints };
+  }
+
+  /**
+   * Get current endpoints configuration
+   */
+  getEndpoints(): Record<BitcoinNetwork, string> {
+    return {
+      mainnet: this._customEndpoints.mainnet ?? DEFAULT_MEMPOOL_ENDPOINTS.mainnet,
+      testnet: this._customEndpoints.testnet ?? DEFAULT_MEMPOOL_ENDPOINTS.testnet,
+      testnet4: this._customEndpoints.testnet4 ?? DEFAULT_MEMPOOL_ENDPOINTS.testnet4,
+      signet: this._customEndpoints.signet ?? DEFAULT_MEMPOOL_ENDPOINTS.signet,
+    };
+  }
+
+  // ============ UTXO Methods ============
+
+  async getUtxos(address: string): Promise<Utxo[]> {
+    const response = await fetchWithTimeout(`${this.baseUrl}/address/${address}/utxo`);
+
+    if (!response.ok) {
+      throw new Error(`Mempool API error: ${response.status} ${response.statusText}`);
+    }
+
+    return response.json() as Promise<Utxo[]>;
+  }
+
+  async getUtxosWithTxHex(address: string): Promise<UtxoWithTx[]> {
+    const utxos = await this.getUtxos(address);
+
+    const utxosWithTx = await Promise.all(
+      utxos.map(async (utxo): Promise<UtxoWithTx> => {
+        const txHex = await this.getTxHex(utxo.txid);
+        return { ...utxo, txHex };
+      })
+    );
+
+    return utxosWithTx;
+  }
+
+  // ============ Transaction Methods ============
+
+  async getTxHex(txid: string): Promise<string> {
+    const response = await fetchWithTimeout(`${this.baseUrl}/tx/${txid}/hex`);
+
+    if (!response.ok) {
+      throw new Error(`Mempool API error: ${response.status} ${response.statusText}`);
+    }
+
+    return response.text();
+  }
+
+  async getTransaction(txid: string): Promise<Transaction> {
+    const response = await fetchWithTimeout(`${this.baseUrl}/tx/${txid}`);
+
+    if (!response.ok) {
+      throw new Error(`Mempool API error: ${response.status} ${response.statusText}`);
+    }
+
+    return response.json() as Promise<Transaction>;
+  }
+
+  async getFullTransaction(txid: string): Promise<FullTransaction> {
+    const response = await fetchWithTimeout(`${this.baseUrl}/tx/${txid}`);
+
+    if (!response.ok) {
+      throw new Error(`Mempool API error: ${response.status} ${response.statusText}`);
+    }
+
+    return response.json() as Promise<FullTransaction>;
+  }
+
+  async broadcastTransaction(txHex: string): Promise<string> {
+    const response = await fetchWithTimeout(
+      `${this.baseUrl}/tx`,
+      {
+        method: 'POST',
+        body: txHex,
+        headers: { 'Content-Type': 'text/plain' },
+      },
+      30000
+    );
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Mempool broadcast error: ${error}`);
+    }
+
+    return response.text();
+  }
+
+  // ============ Address Methods ============
+
+  async getAddressInfo(address: string): Promise<AddressBalance> {
+    const response = await fetchWithTimeout(`${this.baseUrl}/address/${address}`);
+
+    if (!response.ok) {
+      throw new Error(`Mempool API error: ${response.status} ${response.statusText}`);
+    }
+
+    return response.json() as Promise<AddressBalance>;
+  }
+
+  async getBalance(address: string): Promise<number> {
+    const info = await this.getAddressInfo(address);
+    const confirmedBalance =
+      info.chain_stats.funded_txo_sum - info.chain_stats.spent_txo_sum;
+    const unconfirmedBalance =
+      info.mempool_stats.funded_txo_sum - info.mempool_stats.spent_txo_sum;
+    return confirmedBalance + unconfirmedBalance;
+  }
+
+  async getConfirmedBalance(address: string): Promise<number> {
+    const info = await this.getAddressInfo(address);
+    return info.chain_stats.funded_txo_sum - info.chain_stats.spent_txo_sum;
+  }
+
+  // ============ Fee Methods ============
+
+  async getFeeRates(): Promise<FeeRates> {
+    const response = await fetchWithTimeout(`${this.baseUrl}/v1/fees/recommended`);
+
+    if (!response.ok) {
+      throw new Error(`Mempool API error: ${response.status} ${response.statusText}`);
+    }
+
+    const fees = (await response.json()) as {
+      fastestFee: number;
+      halfHourFee: number;
+      hourFee: number;
+      economyFee: number;
+      minimumFee: number;
+    };
+    return {
+      fastest: fees.fastestFee,
+      halfHour: fees.halfHourFee,
+      hour: fees.hourFee,
+      economy: fees.economyFee,
+      minimum: fees.minimumFee,
+    };
+  }
+}