otx-btc-wallet-connectors 0.1.0

package/src/utils/psbt-builder.ts

@@ -0,0 +1,492 @@
+/**
+ * PSBT Builder Utility
+ * Reusable functions for building PSBTs across different wallet connectors
+ */
+
+import type { BitcoinNetwork, AddressType } from 'otx-btc-wallet-core';
+import * as bitcoin from 'bitcoinjs-lib';
+import { BtcService } from './btc-service';
+
+/**
+ * UTXO type
+ */
+export interface Utxo {
+  txid: string;
+  vout: number;
+  value: number;
+  status?: {
+    confirmed: boolean;
+    block_height?: number;
+  };
+}
+
+/**
+ * Options for generating a send PSBT
+ */
+export interface GeneratePsbtOptions {
+  /** Fee rate in sat/vB */
+  feeRate?: number;
+  /** Fee rate multiplier */
+  feeRateMultiplier?: number;
+}
+
+/**
+ * Result from generating a send PSBT
+ */
+export interface GeneratePsbtResult {
+  /** The constructed PSBT */
+  psbt: bitcoin.Psbt;
+  /** PSBT as hex string */
+  psbtHex: string;
+  /** PSBT as base64 string */
+  psbtBase64: string;
+  /** Bitcoin network used */
+  btcNetwork: bitcoin.Network;
+  /** Selected UTXOs used in the transaction */
+  selectedUtxos: Utxo[];
+  /** Total input value in satoshis */
+  totalInputValue: number;
+  /** Estimated fee in satoshis */
+  estimatedFee: number;
+  /** Change amount in satoshis (0 if no change output) */
+  changeAmount: number;
+  /** Inputs to sign (for wallet APIs that require this) */
+  inputsToSign: Array<{ address: string; index: number }>;
+}
+
+/**
+ * Helper to convert hex string to Uint8Array
+ */
+export function hexToBytes(hex: string): Uint8Array {
+  const cleanHex = hex.replace(/^0x/, '');
+  const bytes = new Uint8Array(cleanHex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(cleanHex.substring(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * Helper to convert Uint8Array to hex string
+ */
+export function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Helper to convert public key to x-only (for Taproot)
+ */
+export function toXOnly(pubKey: Uint8Array): Uint8Array {
+  return pubKey.subarray(1, 33);
+}
+
+/**
+ * Get address type from address string
+ */
+export function getAddressType(address: string): AddressType {
+  if (address.startsWith('bc1q') || address.startsWith('tb1q')) {
+    return 'segwit';
+  }
+  if (address.startsWith('bc1p') || address.startsWith('tb1p')) {
+    return 'taproot';
+  }
+  if (address.startsWith('3') || address.startsWith('2')) {
+    return 'nested-segwit';
+  }
+  return 'legacy';
+}
+
+/**
+ * Get bitcoinjs-lib network object from BitcoinNetwork
+ */
+export function getBitcoinJsNetwork(network: BitcoinNetwork): bitcoin.Network {
+  switch (network) {
+    case 'mainnet':
+      return bitcoin.networks.bitcoin;
+    case 'testnet':
+    case 'testnet4':
+    case 'signet':
+      return bitcoin.networks.testnet;
+    default:
+      return bitcoin.networks.bitcoin;
+  }
+}
+
+/**
+ * Estimate vBytes per input based on address type
+ */
+export function getInputVBytes(addressType: AddressType): number {
+  switch (addressType) {
+    case 'taproot':
+      return 58; // P2TR input
+    case 'segwit':
+      return 68; // P2WPKH input
+    case 'nested-segwit':
+      return 91; // P2SH-P2WPKH input
+    default:
+      return 148; // P2PKH input
+  }
+}
+
+/**
+ * Estimate vBytes per output based on address type
+ */
+export function getOutputVBytes(addressType: AddressType): number {
+  switch (addressType) {
+    case 'taproot':
+      return 43; // P2TR output
+    case 'segwit':
+      return 31; // P2WPKH output
+    case 'nested-segwit':
+      return 32; // P2SH output
+    default:
+      return 34; // P2PKH output
+  }
+}
+
+/**
+ * Get dust threshold for address type
+ */
+export function getDustThreshold(addressType: AddressType): number {
+  return addressType === 'legacy' ? 546 : 294;
+}
+
+/**
+ * Select UTXOs for transaction using a simple greedy algorithm
+ */
+export function selectUtxos(
+  utxos: Utxo[],
+  fromAddressType: AddressType,
+  toAddressType: AddressType,
+  amount: number,
+  feeRate: number
+): { selectedUtxos: Utxo[]; totalValue: number; estimatedFee: number } {
+  const inputVBytes = getInputVBytes(fromAddressType);
+  const outputVBytes = getOutputVBytes(toAddressType);
+  const baseVBytes = 10.5; // Base transaction overhead
+
+  // Sort UTXOs by value (descending) for better selection
+  const sortedUtxos = [...utxos].sort((a, b) => b.value - a.value);
+
+  const selectedUtxos: Utxo[] = [];
+  let totalValue = 0;
+
+  for (const utxo of sortedUtxos) {
+    selectedUtxos.push(utxo);
+    totalValue += utxo.value;
+
+    // Calculate fee with current selection (2 outputs: recipient + change)
+    const estimatedVBytes =
+      baseVBytes + selectedUtxos.length * inputVBytes + 2 * outputVBytes;
+    const estimatedFee = Math.ceil(estimatedVBytes * feeRate);
+
+    if (totalValue >= amount + estimatedFee) {
+      return { selectedUtxos, totalValue, estimatedFee };
+    }
+  }
+
+  // If we get here, we don't have enough funds
+  // Return what we have and let the caller handle the error
+  const estimatedVBytes =
+    baseVBytes + selectedUtxos.length * inputVBytes + 2 * outputVBytes;
+  const estimatedFee = Math.ceil(estimatedVBytes * feeRate);
+
+  return { selectedUtxos, totalValue, estimatedFee };
+}
+
+/**
+ * Generate a PSBT for sending Bitcoin
+ *
+ * @param toAddress - Recipient address
+ * @param amount - Amount to send in satoshis
+ * @param fromAddress - Sender address
+ * @param publicKey - Sender's public key (hex string)
+ * @param network - Bitcoin network
+ * @param options - Additional options (feeRate, feeRateMultiplier)
+ * @returns GeneratePsbtResult containing the PSBT and related info
+ */
+export async function generatePsbtForSend(
+  toAddress: string,
+  amount: number,
+  fromAddress: string,
+  publicKey: string,
+  network: BitcoinNetwork,
+  options?: GeneratePsbtOptions
+): Promise<GeneratePsbtResult> {
+  const btcService = new BtcService(network);
+  const btcNetwork = getBitcoinJsNetwork(network);
+
+  // 1. Get UTXOs (only confirmed)
+  const allUtxos = await btcService.getUtxos(fromAddress);
+  const confirmedUtxos = allUtxos.filter(
+    (utxo) => utxo.status?.confirmed !== false
+  );
+
+  if (confirmedUtxos.length === 0) {
+    throw new Error('No confirmed UTXOs available for spending');
+  }
+
+  // 2. Get fee rate
+  let feeRate = options?.feeRate;
+  if (!feeRate) {
+    const feeRates = await btcService.getFeeRates();
+    feeRate = feeRates.hour;
+  }
+  if (options?.feeRateMultiplier) {
+    feeRate = Math.ceil(feeRate * options.feeRateMultiplier);
+  }
+
+  // 3. Get address types
+  const fromAddressType = getAddressType(fromAddress);
+  const toAddressType = getAddressType(toAddress);
+
+  // 4. Select UTXOs
+  const { selectedUtxos, totalValue, estimatedFee } = selectUtxos(
+    confirmedUtxos,
+    fromAddressType,
+    toAddressType,
+    amount,
+    feeRate
+  );
+
+  if (totalValue < amount + estimatedFee) {
+    throw new Error(
+      `Insufficient funds. Available: ${totalValue} sats, Required: ${amount + estimatedFee} sats (including fee)`
+    );
+  }
+
+  // 5. Calculate change
+  const dustThreshold = getDustThreshold(fromAddressType);
+  let changeAmount = totalValue - amount - estimatedFee;
+
+  // If change is below dust threshold, add it to fee
+  if (changeAmount > 0 && changeAmount <= dustThreshold) {
+    changeAmount = 0;
+  }
+
+  // 6. Build PSBT
+  const psbt = new bitcoin.Psbt({ network: btcNetwork });
+  const publicKeyBytes = hexToBytes(publicKey);
+  const inputsToSign: Array<{ address: string; index: number }> = [];
+
+  // Add inputs
+  for (let i = 0; i < selectedUtxos.length; i++) {
+    const utxo = selectedUtxos[i]!;
+    const script = bitcoin.address.toOutputScript(fromAddress, btcNetwork);
+
+    if (fromAddressType === 'taproot') {
+      // P2TR - Taproot
+      psbt.addInput({
+        hash: utxo.txid,
+        index: utxo.vout,
+        witnessUtxo: {
+          script,
+          value: BigInt(utxo.value),
+        },
+        tapInternalKey: toXOnly(publicKeyBytes),
+      });
+    } else if (fromAddressType === 'segwit') {
+      // P2WPKH - Native SegWit
+      psbt.addInput({
+        hash: utxo.txid,
+        index: utxo.vout,
+        witnessUtxo: {
+          script,
+          value: BigInt(utxo.value),
+        },
+      });
+    } else if (fromAddressType === 'nested-segwit') {
+      // P2SH-P2WPKH - Nested SegWit
+      const p2wpkh = bitcoin.payments.p2wpkh({
+        pubkey: publicKeyBytes,
+        network: btcNetwork,
+      });
+      if (!p2wpkh.output) {
+        throw new Error('Failed to generate P2WPKH redeem script');
+      }
+      psbt.addInput({
+        hash: utxo.txid,
+        index: utxo.vout,
+        witnessUtxo: {
+          script,
+          value: BigInt(utxo.value),
+        },
+        redeemScript: p2wpkh.output,
+      });
+    } else {
+      // Legacy P2PKH
+      psbt.addInput({
+        hash: utxo.txid,
+        index: utxo.vout,
+        witnessUtxo: {
+          script,
+          value: BigInt(utxo.value),
+        },
+      });
+    }
+
+    inputsToSign.push({ address: fromAddress, index: i });
+  }
+
+  // Add recipient output
+  psbt.addOutput({
+    address: toAddress,
+    value: BigInt(amount),
+  });
+
+  // Add change output if needed
+  if (changeAmount > 0) {
+    psbt.addOutput({
+      address: fromAddress,
+      value: BigInt(Math.floor(changeAmount)),
+    });
+  }
+
+  return {
+    psbt,
+    psbtHex: psbt.toHex(),
+    psbtBase64: psbt.toBase64(),
+    btcNetwork,
+    selectedUtxos,
+    totalInputValue: totalValue,
+    estimatedFee,
+    changeAmount,
+    inputsToSign,
+  };
+}
+
+/**
+ * Finalize all inputs in a signed PSBT
+ */
+export function finalizeAllInputs(
+  signedPsbt: bitcoin.Psbt,
+  inputCount: number
+): void {
+  for (let i = 0; i < inputCount; i++) {
+    try {
+      signedPsbt.finalizeInput(i);
+    } catch (finalizeError) {
+      console.warn(
+        `Failed to finalize input ${i}, attempting alternative finalization:`,
+        finalizeError
+      );
+      // For complex input types, try finalization with empty witness
+      try {
+        signedPsbt.finalizeInput(i, () => ({
+          finalScriptSig: undefined,
+          finalScriptWitness: undefined,
+        }));
+      } catch {
+        // If that also fails, just skip - the transaction might still work
+        console.warn(`Could not finalize input ${i}`);
+      }
+    }
+  }
+}
+
+/**
+ * Extract and broadcast a signed PSBT
+ *
+ * @param signedPsbtHex - Signed PSBT hex string
+ * @param network - Bitcoin network
+ * @param inputCount - Number of inputs to finalize
+ * @returns Transaction ID
+ */
+export async function finalizeAndBroadcast(
+  signedPsbtHex: string,
+  network: BitcoinNetwork,
+  inputCount: number
+): Promise<string> {
+  const btcNetwork = getBitcoinJsNetwork(network);
+  const btcService = new BtcService(network);
+
+  // Parse signed PSBT
+  const signedPsbt = bitcoin.Psbt.fromHex(signedPsbtHex, { network: btcNetwork });
+
+  // Finalize all inputs
+  finalizeAllInputs(signedPsbt, inputCount);
+
+  // Extract transaction
+  const tx = signedPsbt.extractTransaction();
+  const txHex = tx.toHex();
+
+  // Broadcast
+  return await btcService.broadcastTransaction(txHex);
+}
+
+/**
+ * Derive Bitcoin address from public key based on address type
+ *
+ * @param publicKeyHex - Public key in hex format (33 bytes compressed)
+ * @param addressType - Type of address to derive (legacy, nested-segwit, segwit, taproot)
+ * @param network - Bitcoin network
+ * @returns Derived Bitcoin address
+ */
+export function deriveAddressFromPublicKey(
+  publicKeyHex: string,
+  addressType: AddressType,
+  network: BitcoinNetwork
+): string {
+  const btcNetwork = getBitcoinJsNetwork(network);
+  const publicKeyBytes = hexToBytes(publicKeyHex);
+
+  switch (addressType) {
+    case 'legacy': {
+      // P2PKH - Legacy address (starts with 1 or m/n)
+      const p2pkh = bitcoin.payments.p2pkh({
+        pubkey: publicKeyBytes,
+        network: btcNetwork,
+      });
+      if (!p2pkh.address) {
+        throw new Error('Failed to derive legacy address from public key');
+      }
+      return p2pkh.address;
+    }
+
+    case 'nested-segwit': {
+      // P2SH-P2WPKH - Nested SegWit (starts with 3 or 2)
+      const p2wpkh = bitcoin.payments.p2wpkh({
+        pubkey: publicKeyBytes,
+        network: btcNetwork,
+      });
+      const p2sh = bitcoin.payments.p2sh({
+        redeem: p2wpkh,
+        network: btcNetwork,
+      });
+      if (!p2sh.address) {
+        throw new Error('Failed to derive nested-segwit address from public key');
+      }
+      return p2sh.address;
+    }
+
+    case 'segwit': {
+      // P2WPKH - Native SegWit (starts with bc1q or tb1q)
+      const p2wpkh = bitcoin.payments.p2wpkh({
+        pubkey: publicKeyBytes,
+        network: btcNetwork,
+      });
+      if (!p2wpkh.address) {
+        throw new Error('Failed to derive segwit address from public key');
+      }
+      return p2wpkh.address;
+    }
+
+    case 'taproot': {
+      // P2TR - Taproot (starts with bc1p or tb1p)
+      const xOnlyPubKey = toXOnly(publicKeyBytes);
+      const p2tr = bitcoin.payments.p2tr({
+        internalPubkey: xOnlyPubKey,
+        network: btcNetwork,
+      });
+      if (!p2tr.address) {
+        throw new Error('Failed to derive taproot address from public key');
+      }
+      return p2tr.address;
+    }
+
+    default:
+      throw new Error(`Unsupported address type: ${addressType}`);
+  }
+}

package/src/utils/types.ts

@@ -0,0 +1,183 @@
+import type { BitcoinNetwork } from 'otx-btc-wallet-core';
+
+/**
+ * UTXO (Unspent Transaction Output) interface
+ */
+export interface Utxo {
+  txid: string;
+  vout: number;
+  value: number; // in satoshis
+  status: {
+    confirmed: boolean;
+    block_height?: number;
+    block_hash?: string;
+    block_time?: number;
+  };
+}
+
+/**
+ * UTXO with raw transaction hex (needed for Ledger signing)
+ */
+export interface UtxoWithTx extends Utxo {
+  txHex: string;
+}
+
+/**
+ * Fee rates response
+ */
+export interface FeeRates {
+  fastest: number;
+  halfHour: number;
+  hour: number;
+  economy: number;
+  minimum: number;
+}
+
+/**
+ * Transaction details
+ */
+export interface Transaction {
+  txid: string;
+  version: number;
+  locktime: number;
+  size: number;
+  weight: number;
+  fee: number;
+  status: {
+    confirmed: boolean;
+    block_height?: number;
+    block_hash?: string;
+    block_time?: number;
+  };
+}
+
+/**
+ * Full transaction with inputs and outputs (for Trezor refTxs)
+ */
+export interface FullTransaction extends Transaction {
+  vin: Array<{
+    txid: string;
+    vout: number;
+    sequence: number;
+    scriptsig: string;
+    scriptsig_asm?: string;
+    witness?: string[];
+    prevout?: {
+      scriptpubkey: string;
+      scriptpubkey_asm?: string;
+      scriptpubkey_type?: string;
+      scriptpubkey_address?: string;
+      value: number;
+    };
+  }>;
+  vout: Array<{
+    scriptpubkey: string;
+    scriptpubkey_asm?: string;
+    scriptpubkey_type?: string;
+    scriptpubkey_address?: string;
+    value: number;
+  }>;
+}
+
+/**
+ * Address balance
+ */
+export interface AddressBalance {
+  address: string;
+  chain_stats: {
+    funded_txo_count: number;
+    funded_txo_sum: number;
+    spent_txo_count: number;
+    spent_txo_sum: number;
+    tx_count: number;
+  };
+  mempool_stats: {
+    funded_txo_count: number;
+    funded_txo_sum: number;
+    spent_txo_count: number;
+    spent_txo_sum: number;
+    tx_count: number;
+  };
+}
+
+/**
+ * Bitcoin service interface that both Mempool and Blockstream services implement
+ */
+export interface IBtcService {
+  readonly name: string;
+  readonly network: BitcoinNetwork;
+
+  setNetwork(network: BitcoinNetwork): void;
+
+  // UTXO methods
+  getUtxos(address: string): Promise<Utxo[]>;
+  getUtxosWithTxHex(address: string): Promise<UtxoWithTx[]>;
+
+  // Transaction methods
+  getTxHex(txid: string): Promise<string>;
+  getTransaction(txid: string): Promise<Transaction>;
+  getFullTransaction(txid: string): Promise<FullTransaction>;
+  broadcastTransaction(txHex: string): Promise<string>;
+
+  // Address methods
+  getBalance(address: string): Promise<number>;
+  getConfirmedBalance(address: string): Promise<number>;
+  getAddressInfo(address: string): Promise<AddressBalance>;
+
+  // Fee methods
+  getFeeRates(): Promise<FeeRates>;
+}
+
+/**
+ * Network-specific endpoint URLs
+ */
+export interface NetworkEndpoints {
+  mainnet?: string;
+  testnet?: string;
+  testnet4?: string;
+  signet?: string;
+}
+
+/**
+ * Configuration for BtcService endpoints
+ *
+ * @example
+ * ```typescript
+ * // Use custom mempool instance
+ * const config: BtcServiceConfig = {
+ *   mempool: {
+ *     mainnet: 'https://my-mempool.com/api',
+ *     testnet: 'https://my-mempool.com/testnet/api',
+ *   }
+ * };
+ *
+ * // Or use only one provider
+ * const config: BtcServiceConfig = {
+ *   preferredProvider: 'mempool',
+ *   mempool: {
+ *     mainnet: 'https://custom-mempool.example.com/api',
+ *   }
+ * };
+ * ```
+ */
+export interface BtcServiceConfig {
+  /**
+   * Custom Mempool.space API endpoints
+   * Default: https://mempool.space/api (mainnet)
+   */
+  mempool?: NetworkEndpoints;
+
+  /**
+   * Custom Blockstream.info API endpoints
+   * Default: https://blockstream.info/api (mainnet)
+   */
+  blockstream?: NetworkEndpoints;
+
+  /**
+   * Preferred provider to use ('mempool' | 'blockstream' | 'race')
+   * - 'mempool': Only use Mempool API
+   * - 'blockstream': Only use Blockstream API
+   * - 'race': Use both and return fastest response (default)
+   */
+  preferredProvider?: 'mempool' | 'blockstream' | 'race';
+}