otx-btc-wallet-connectors 0.1.0

package/src/ledger/LedgerConnector.ts

@@ -0,0 +1,1019 @@
+import type {
+  WalletAccount,
+  BitcoinNetwork,
+  SignPsbtOptions,
+  AddressType,
+} from 'otx-btc-wallet-core';
+import { BaseConnector } from '../base';
+import {
+  BtcService,
+  getAddressType,
+  getDustThreshold,
+  getInputVBytes,
+  getOutputVBytes,
+} from '../utils';
+
+// Ledger wallet icon
+const LEDGER_ICON =
+  'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjAwIiBoZWlnaHQ9IjIwMCIgdmlld0JveD0iMCAwIDIwMCAyMDAiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxnIGNsaXAtcGF0aD0idXJsKCNjbGlwMF83MDM1XzUxMTApIj4KPHJlY3Qgd2lkdGg9IjIwMCIgaGVpZ2h0PSIyMDAiIHJ4PSIzMiIgZmlsbD0id2hpdGUiLz4KPHBhdGggZD0iTTE0Mi4yMzkgMzcuNUg4NS4wOTY0VjExNC41ODJIMTYyLjIzOVY1Ny40MzkzQzE2Mi4yMzggNTQuODE2IDE2MS43MiA1Mi4yMTg2IDE2MC43MTQgNDkuNzk1OUMxNTkuNzA4IDQ3LjM3MzIgMTU4LjIzMyA0NS4xNzI4IDE1Ni4zNzYgNDMuMzIwN0MxNTQuNTE4IDQxLjQ2ODUgMTUyLjMxMyA0MC4wMDExIDE0OS44ODcgMzkuMDAyM0MxNDcuNDYyIDM4LjAwMzUgMTQ0Ljg2MyAzNy40OTMgMTQyLjIzOSAzNy41WiIgZmlsbD0iYmxhY2siLz4KPHBhdGggZD0iTTY3LjI5MjkgMzcuNUg1Ny40NDY0QzUyLjE1NjMgMzcuNSA0Ny4wODI5IDM5LjYwMTUgNDMuMzQyMiA0My4zNDIyQzM5LjYwMTUgNDcuMDgyOSAzNy41IDUyLjE1NjMgMzcuNSA1Ny40NDY0TDM3LjUgNjcuMjkyOUg2Ny4yOTI5VjM3LjVaIiBmaWxsPSJibGFjayIvPgo8cGF0aCBkPSJNMzcuNSA4NS4xMDM2SDY3LjI5MjlWMTE0Ljg5NkgzNy41Vjg1LjEwMzZaIiBmaWxsPSJibGFjayIvPgo8cGF0aCBkPSJNMTMyLjcwNyAxNjIuMjQ2SDE0Mi41NTNDMTQ1LjE3NyAxNjIuMjQ2IDE0Ny43NzYgMTYxLjcyOSAxNTAuMTk5IDE2MC43MjNDMTUyLjYyMyAxNTkuNzE3IDE1NC44MjQgMTU4LjI0MyAxNTYuNjc3IDE1Ni4zODVDMTU4LjUzIDE1NC41MjcgMTU5Ljk5OCAxNTIuMzIyIDE2MC45OTcgMTQ5Ljg5NkMxNjEuOTk2IDE0Ny40NyAxNjIuNTA3IDE0NC44NyAxNjIuNSAxNDIuMjQ2VjEzMi43MDdIMTMyLjcwN1YxNjIuMjQ2WiIgZmlsbD0iYmxhY2siLz4KPHBhdGggZD0iTTg1LjEwMzUgMTMyLjcwN0gxMTQuODk2VjE2Mi41SDg1LjEwMzVWMTMyLjcwN1oiIGZpbGw9ImJsYWNrIi8+CjxwYXRoIGQ9Ik0zNy41IDEzMi43MDdWMTQyLjU1NEMzNy41IDE0NS4xNzMgMzguMDE1OSAxNDcuNzY3IDM5LjAxODMgMTUwLjE4N0M0MC4wMjA3IDE1Mi42MDcgNDEuNDkgMTU0LjgwNiA0My4zNDIyIDE1Ni42NThDNDUuMTk0NCAxNTguNTEgNDcuMzkzMiAxNTkuOTc5IDQ5LjgxMzMgMTYwLjk4MkM1Mi4yMzMzIDE2MS45ODQgNTQuODI3IDE2Mi41IDU3LjQ0NjQgMTYyLjVINjcuMjkyOVYxMzIuNzA3SDM3LjVaIiBmaWxsPSJibGFjayIvPgo8L2c+CjxkZWZzPgo8Y2xpcFBhdGggaWQ9ImNsaXAwXzcwMzVfNTExMCI+CjxyZWN0IHdpZHRoPSIyMDAiIGhlaWdodD0iMjAwIiBmaWxsPSJ3aGl0ZSIvPgo8L2NsaXBQYXRoPgo8L2RlZnM+Cjwvc3ZnPgo=';
+
+/**
+ * Ledger address type configuration
+ */
+export type LedgerAddressType = 'legacy' | 'nested-segwit' | 'segwit' | 'taproot';
+
+/**
+ * Ledger connector options
+ */
+export interface LedgerConnectorOptions {
+  /** Address type for derivation (default: 'segwit') */
+  addressType?: LedgerAddressType;
+  /** Account index (default: 0) */
+  accountIndex?: number;
+  /** Address index (default: 0) */
+  addressIndex?: number;
+}
+
+/**
+ * Address type to BIP path mapping
+ */
+const ADDRESS_TYPE_TO_PATH: Record<LedgerAddressType, number> = {
+  'legacy': 44,
+  'nested-segwit': 49,
+  'segwit': 84,
+  'taproot': 86,
+};
+
+/**
+ * Address type to Ledger format mapping
+ */
+const ADDRESS_TYPE_TO_FORMAT: Record<LedgerAddressType, 'legacy' | 'p2sh' | 'bech32' | 'bech32m'> = {
+  'legacy': 'legacy',
+  'nested-segwit': 'p2sh',
+  'segwit': 'bech32',
+  'taproot': 'bech32m',
+};
+
+// Define minimal types for Ledger libraries to avoid type issues
+interface LedgerTransport {
+  close(): Promise<void>;
+  on(event: 'disconnect', callback: () => void): void;
+  send(cla: number, ins: number, p1: number, p2: number, data?: Buffer): Promise<Buffer>;
+}
+
+interface LedgerBtcApp {
+  getWalletPublicKey(
+    path: string,
+    opts?: { verify?: boolean; format?: 'legacy' | 'p2sh' | 'bech32' | 'bech32m' }
+  ): Promise<{ publicKey: string; bitcoinAddress: string; chainCode: string }>;
+  getWalletXpub(arg: { path: string; xpubVersion: number }): Promise<string>;
+  signMessage(path: string, messageHex: string): Promise<{ v: number; r: string; s: string }>;
+  splitTransaction(
+    transactionHex: string,
+    isSegwitSupported?: boolean | null,
+    hasExtraData?: boolean,
+    additionals?: string[]
+  ): LedgerTransaction;
+  createPaymentTransaction(arg: {
+    inputs: Array<[LedgerTransaction, number, string | null | undefined, number?]>;
+    associatedKeysets: string[];
+    changePath?: string;
+    outputScriptHex: string;
+    lockTime?: number;
+    sigHashType?: number;
+    segwit?: boolean;
+    additionals?: string[];
+    expiryHeight?: Buffer;
+    useTrustedInputForSegwit?: boolean;
+  }): Promise<string>;
+  serializeTransactionOutputs(tx: LedgerTransaction): Buffer;
+}
+
+/**
+ * Ledger Transaction type (returned by splitTransaction)
+ */
+interface LedgerTransaction {
+  version: Buffer;
+  inputs: Array<{
+    prevout: Buffer;
+    script: Buffer;
+    sequence: Buffer;
+  }>;
+  outputs?: Array<{
+    amount: Buffer;
+    script: Buffer;
+  }>;
+  locktime?: Buffer;
+  witness?: Buffer;
+}
+
+/**
+ * UTXO input for createPaymentTransaction
+ */
+export interface LedgerUtxoInput {
+  /** Raw transaction hex that created this UTXO */
+  txHex: string;
+  /** Output index in the transaction */
+  outputIndex: number;
+  /** BIP32 derivation path for signing (e.g., "84'/0'/0'/0/0") */
+  derivationPath: string;
+  /** Optional redeem script for P2SH inputs */
+  redeemScript?: string;
+  /** Optional sequence number (default: 0xffffffff) */
+  sequence?: number;
+}
+
+/**
+ * Output for createPaymentTransaction
+ */
+export interface LedgerTxOutput {
+  /** Recipient address */
+  address: string;
+  /** Amount in satoshis */
+  satoshis: number;
+}
+
+/**
+ * Options for sendBitcoin method
+ */
+export interface SendBitcoinOptions {
+  /** Fee rate in sat/vB (optional, defaults to "hour" priority) */
+  feeRate?: number;
+}
+
+/**
+ * Ledger Hardware Wallet Connector
+ *
+ * @see https://developers.ledger.com/docs/transport/overview
+ * @see https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-btc
+ */
+export class LedgerConnector extends BaseConnector {
+  readonly id = 'ledger';
+  readonly name = 'Ledger';
+  readonly icon = LEDGER_ICON;
+
+  private _transport: LedgerTransport | null = null;
+  private _btcApp: LedgerBtcApp | null = null;
+  private _account: WalletAccount | null = null;
+  private _network: BitcoinNetwork = 'mainnet';
+  private _options: Required<LedgerConnectorOptions>;
+  private _derivationPath: string = '';
+
+  // Connection timeout in milliseconds
+  private static readonly CONNECTION_TIMEOUT = 30000;
+
+  constructor(options: LedgerConnectorOptions = {}) {
+    super();
+    this._options = {
+      addressType: options.addressType ?? 'segwit',
+      accountIndex: options.accountIndex ?? 0,
+      addressIndex: options.addressIndex ?? 0,
+    };
+  }
+
+  /**
+   * Override checkReady - Ledger is always "ready" since it doesn't require browser extension
+   * The actual device connection happens when connect() is called
+   */
+  protected checkReady(): void {
+    this.ready = true;
+  }
+
+  /**
+   * Get the provider - for Ledger this is the Bitcoin app instance
+   */
+  protected getProvider(): LedgerBtcApp | null {
+    return this._btcApp;
+  }
+
+  /**
+   * Get current address type
+   */
+  getAddressType(): LedgerAddressType {
+    return this._options.addressType;
+  }
+
+  /**
+   * Set address type options before connecting
+   * Call this before connect() to change the address derivation path
+   */
+  setOptions(options: LedgerConnectorOptions): void {
+    this._options = {
+      addressType: options.addressType ?? this._options.addressType,
+      accountIndex: options.accountIndex ?? this._options.accountIndex,
+      addressIndex: options.addressIndex ?? this._options.addressIndex,
+    };
+  }
+
+  /**
+   * Get available address types for UI selection
+   */
+  static getAvailableAddressTypes(): Array<{ type: LedgerAddressType; label: string; description: string }> {
+    return [
+      { type: 'legacy', label: 'Legacy (P2PKH)', description: "Starts with '1' or 'm/n'" },
+      { type: 'nested-segwit', label: 'Nested SegWit (P2SH-P2WPKH)', description: "Starts with '3' or '2'" },
+      { type: 'segwit', label: 'Native SegWit (P2WPKH)', description: "Starts with 'bc1q' or 'tb1q'" },
+      { type: 'taproot', label: 'Taproot (P2TR)', description: "Starts with 'bc1p' or 'tb1p'" },
+    ];
+  }
+
+  /**
+   * Check if WebUSB is supported in the current browser
+   */
+  async isSupported(): Promise<boolean> {
+    if (typeof window === 'undefined') return false;
+    try {
+      const TransportWebUSB = (await import('@ledgerhq/hw-transport-webusb')).default;
+      return await TransportWebUSB.isSupported();
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Initialize transport with timeout
+   * Uses request() instead of create() to always show device selection popup
+   */
+  private async initTransport(): Promise<LedgerTransport> {
+    console.log('[LedgerConnector] initTransport() called');
+
+    // Close existing transport if any
+    await this.closeTransport();
+
+    // Import WebUSB transport
+    console.log('[LedgerConnector] Importing TransportWebUSB...');
+    const TransportWebUSB = (await import('@ledgerhq/hw-transport-webusb')).default;
+    console.log('[LedgerConnector] TransportWebUSB imported');
+
+    // Use request() to always show device selection popup
+    // create() would auto-connect to previously paired device without showing popup
+    console.log('[LedgerConnector] Requesting device selection...');
+    const transportPromise = TransportWebUSB.request();
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => {
+        reject(new Error('Connection timeout. Please make sure your Ledger is connected and unlocked.'));
+      }, LedgerConnector.CONNECTION_TIMEOUT);
+    });
+
+    const transport = await Promise.race([transportPromise, timeoutPromise]);
+    console.log('[LedgerConnector] Transport created successfully');
+    return transport as unknown as LedgerTransport;
+  }
+
+  /**
+   * Get BTC app instance, initializing if needed
+   */
+  private async getBtcAppInstance(): Promise<LedgerBtcApp> {
+    console.log('[LedgerConnector] getBtcAppInstance() called');
+
+    if (this._btcApp) {
+      console.log('[LedgerConnector] Returning existing BTC app instance');
+      return this._btcApp;
+    }
+
+    const transport = await this.initTransport();
+    this._transport = transport;
+
+    // Check if Bitcoin app is open by sending a test command
+    console.log('[LedgerConnector] Checking if Bitcoin app is open...');
+    try {
+      // CLA=0xB0 INS=0x01 is get app version - works as a ping
+      await transport.send(0xb0, 0x01, 0x00, 0x00);
+      console.log('[LedgerConnector] Bitcoin app is open');
+    } catch (error) {
+      console.error('[LedgerConnector] Bitcoin app check failed:', error);
+      await this.closeTransport();
+      throw new Error('Please open the Bitcoin app on your Ledger device');
+    }
+
+    // Import and initialize BTC app
+    console.log('[LedgerConnector] Importing AppBtc...');
+    const AppBtc = (await import('@ledgerhq/hw-app-btc')).default;
+    console.log('[LedgerConnector] AppBtc imported');
+
+    const currency = this._network === 'mainnet' ? 'bitcoin' : 'bitcoin_testnet';
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    this._btcApp = new AppBtc({ transport: transport as any, currency }) as unknown as LedgerBtcApp;
+    console.log('[LedgerConnector] BTC app instance created');
+
+    return this._btcApp;
+  }
+
+  /**
+   * Connect to Ledger device
+   * IMPORTANT: This must be called within a user gesture (click event)
+   */
+  async connect(network: BitcoinNetwork = 'mainnet'): Promise<WalletAccount> {
+    console.log('[LedgerConnector] connect() called with network:', network);
+
+    try {
+      // Check WebUSB support
+      console.log('[LedgerConnector] Checking WebUSB support...');
+      const supported = await this.isSupported();
+      console.log('[LedgerConnector] WebUSB supported:', supported);
+
+      if (!supported) {
+        throw new Error('WebUSB is not supported in this browser. Please use Chrome or a Chromium-based browser.');
+      }
+
+      // Set network before initializing app
+      this._network = network;
+
+      // Initialize BTC app (this also creates transport)
+      console.log('[LedgerConnector] Initializing BTC app...');
+      const btcApp = await this.getBtcAppInstance();
+      console.log('[LedgerConnector] BTC app initialized');
+
+      // Build derivation path
+      const coinType = network === 'mainnet' ? 0 : 1;
+      const purpose = ADDRESS_TYPE_TO_PATH[this._options.addressType];
+      this._derivationPath = `${purpose}'/${coinType}'/${this._options.accountIndex}'/0/${this._options.addressIndex}`;
+      console.log('[LedgerConnector] Derivation path:', this._derivationPath);
+
+      // Get address and public key from device
+      const format = ADDRESS_TYPE_TO_FORMAT[this._options.addressType];
+      console.log('[LedgerConnector] Getting wallet public key...');
+      const result = await btcApp.getWalletPublicKey(this._derivationPath, {
+        verify: false,
+        format,
+      });
+      console.log('[LedgerConnector] Got wallet public key:', result.bitcoinAddress);
+
+      this._account = {
+        address: result.bitcoinAddress,
+        publicKey: result.publicKey,
+        type: this.mapLedgerAddressType(this._options.addressType),
+      };
+
+      // Setup disconnect listener
+      this.setupDisconnectListener();
+
+      console.log('[LedgerConnector] Connection successful!');
+      return this._account;
+    } catch (error) {
+      console.error('[LedgerConnector] Connection error:', error);
+      await this.closeTransport();
+      this.handleLedgerError(error);
+    }
+  }
+
+  /**
+   * Get address with verification on device
+   */
+  async getAddressWithVerification(): Promise<WalletAccount> {
+    if (!this._btcApp) {
+      throw new Error('Not connected to Ledger device');
+    }
+
+    try {
+      const format = ADDRESS_TYPE_TO_FORMAT[this._options.addressType];
+      const result = await this._btcApp.getWalletPublicKey(this._derivationPath, {
+        verify: true, // Show address on device for verification
+        format,
+      });
+
+      return {
+        address: result.bitcoinAddress,
+        publicKey: result.publicKey,
+        type: this.mapLedgerAddressType(this._options.addressType),
+      };
+    } catch (error) {
+      this.handleLedgerError(error);
+    }
+  }
+
+  private setupDisconnectListener(): void {
+    if (!this._transport) return;
+
+    this._transport.on('disconnect', () => {
+      this._transport = null;
+      this._btcApp = null;
+      this._account = null;
+      this.emitAccountsChanged([]);
+    });
+  }
+
+  private async closeTransport(): Promise<void> {
+    if (this._transport) {
+      try {
+        await this._transport.close();
+      } catch {
+        // Ignore close errors
+      }
+      this._transport = null;
+      this._btcApp = null;
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    await this.closeTransport();
+    this._account = null;
+    this.cleanup();
+  }
+
+  async getAccounts(): Promise<WalletAccount[]> {
+    if (!this._account) {
+      return [];
+    }
+    return [this._account];
+  }
+
+  async signMessage(message: string): Promise<string> {
+    if (!this._btcApp) {
+      throw new Error('Not connected to Ledger device');
+    }
+
+    try {
+      // Convert message to hex
+      const messageHex = Buffer.from(message, 'utf8').toString('hex');
+
+      // Sign message on device
+      const result = await this._btcApp.signMessage(this._derivationPath, messageHex);
+
+      // Construct signature (v || r || s) and encode as base64
+      const v = result.v;
+      const r = result.r;
+      const s = result.s;
+
+      // Format: 1 byte v + 32 bytes r + 32 bytes s
+      const vHex = v.toString(16).padStart(2, '0');
+      const signature = Buffer.from(vHex + r + s, 'hex');
+
+      return signature.toString('base64');
+    } catch (error) {
+      this.handleLedgerError(error);
+    }
+  }
+
+  /**
+   * Sign a PSBT with Ledger
+   *
+   * Note: Ledger hardware wallets don't support direct PSBT signing through the standard API.
+   * Use the createTransaction method or sendTransaction instead.
+   */
+  async signPsbt(_psbtHex: string, _options?: SignPsbtOptions): Promise<string> {
+    void _psbtHex;
+    void _options;
+
+    throw new Error('SignPsbt is not supported for Ledger Wallet. Use createTransaction or sendTransaction instead.');
+  }
+
+  /**
+   * Sign multiple PSBTs
+   */
+  async signPsbts(psbtHexs: string[], options?: SignPsbtOptions): Promise<string[]> {
+    const results: string[] = [];
+    for (const psbtHex of psbtHexs) {
+      const signed = await this.signPsbt(psbtHex, options);
+      results.push(signed);
+    }
+    return results;
+  }
+
+  /**
+   * Send a Bitcoin transaction
+   *
+   * @param to - Recipient address
+   * @param satoshis - Amount to send in satoshis
+   * @param options - Send options (feeRate, etc.)
+   * @returns Transaction ID after broadcast
+   *
+   * @example
+   * ```typescript
+   * const txid = await ledger.sendTransaction('bc1q...', 50000);
+   * // With custom fee rate
+   * const txid = await ledger.sendTransaction('bc1q...', 50000, { feeRate: 10 });
+   * ```
+   */
+  async sendTransaction(to: string, satoshis: number, options?: SendBitcoinOptions): Promise<string> {
+    if (!this._btcApp || !this._account) {
+      throw new Error('Not connected to Ledger device');
+    }
+
+    const btcService = new BtcService(this._network);
+
+    // 1. Get UTXOs with tx hex (Ledger requires raw tx hex for each UTXO)
+    const utxos = await btcService.getUtxosWithTxHex(this._account.address);
+    if (utxos.length === 0) {
+      throw new Error('No UTXOs available for spending');
+    }
+
+    // 2. Get fee rate if not provided
+    let feeRate = options?.feeRate;
+    if (!feeRate) {
+      const feeRates = await btcService.getFeeRates();
+      feeRate = feeRates.hour;
+    }
+
+    // 3. Get address types using utility functions
+    const fromAddressType = getAddressType(this._account.address);
+    const toAddressType = getAddressType(to);
+
+    // 4. Get vBytes estimates using utility functions
+    const inputVBytes = getInputVBytes(fromAddressType);
+    const outputVBytes = getOutputVBytes(toAddressType);
+    const changeOutputVBytes = getOutputVBytes(fromAddressType);
+    const baseVBytes = 10.5; // Base transaction overhead
+
+    // 5. Select UTXOs using greedy algorithm (sorted by value descending)
+    const sortedUtxos = [...utxos].sort((a, b) => b.value - a.value);
+    const selectedUtxos: typeof utxos = [];
+    let totalInputValue = 0;
+
+    for (const utxo of sortedUtxos) {
+      selectedUtxos.push(utxo);
+      totalInputValue += utxo.value;
+
+      // Calculate fee with 2 outputs (recipient + change)
+      const estimatedVBytes = baseVBytes + selectedUtxos.length * inputVBytes + outputVBytes + changeOutputVBytes;
+      const estimatedFee = Math.ceil(estimatedVBytes * feeRate);
+
+      if (totalInputValue >= satoshis + estimatedFee) {
+        break;
+      }
+    }
+
+    // 6. Calculate final fee
+    let estimatedVBytes = baseVBytes + selectedUtxos.length * inputVBytes + outputVBytes + changeOutputVBytes;
+    let estimatedFee = Math.ceil(estimatedVBytes * feeRate);
+
+    // Check if we have enough funds
+    if (totalInputValue < satoshis + estimatedFee) {
+      throw new Error(
+        `Insufficient funds. Available: ${totalInputValue} sats, Required: ${satoshis + estimatedFee} sats (including fee)`
+      );
+    }
+
+    // 7. Calculate change
+    let changeAmount = totalInputValue - satoshis - estimatedFee;
+
+    // 8. Build outputs
+    const outputs: LedgerTxOutput[] = [{ address: to, satoshis }];
+
+    // Add change output if above dust threshold
+    const dustThreshold = getDustThreshold(fromAddressType);
+
+    if (changeAmount > dustThreshold) {
+      outputs.push({ address: this._account.address, satoshis: changeAmount });
+    } else {
+      // No change output - recalculate fee without change output
+      estimatedVBytes = baseVBytes + selectedUtxos.length * inputVBytes + outputVBytes;
+      estimatedFee = Math.ceil(estimatedVBytes * feeRate);
+      changeAmount = 0;
+
+      // Verify we still have enough
+      if (totalInputValue < satoshis + estimatedFee) {
+        throw new Error(
+          `Insufficient funds after fee adjustment. Available: ${totalInputValue} sats, Required: ${satoshis + estimatedFee} sats`
+        );
+      }
+    }
+
+    // 9. Build inputs for createTransaction
+    const inputs: LedgerUtxoInput[] = selectedUtxos.map((utxo) => ({
+      txHex: utxo.txHex,
+      outputIndex: utxo.vout,
+      derivationPath: this._derivationPath,
+    }));
+
+    // 10. Create and sign transaction using Ledger's native API
+    const signedTxHex = await this.createTransaction(inputs, outputs);
+
+    // 11. Broadcast transaction
+    const txid = await btcService.broadcastTransaction(signedTxHex);
+
+    return txid;
+  }
+
+  /**
+   * Create and sign a Bitcoin transaction using Ledger
+   *
+   * This method requires you to provide UTXOs (unspent transaction outputs) which
+   * must be fetched from a blockchain API (e.g., Blockstream, Mempool.space, etc.)
+   *
+   * @param inputs - Array of UTXO inputs to spend
+   * @param outputs - Array of outputs (recipients)
+   * @param changePath - Optional BIP32 path for change output
+   * @returns Signed transaction hex ready for broadcast
+   *
+   * @example
+   * ```typescript
+   * const signedTx = await ledger.createTransaction(
+   *   [{
+   *     txHex: '0100000001...', // Raw tx hex that created the UTXO
+   *     outputIndex: 0,
+   *     derivationPath: "84'/0'/0'/0/0",
+   *   }],
+   *   [{
+   *     address: 'bc1q...',
+   *     satoshis: 50000,
+   *   }],
+   *   "84'/0'/0'/1/0" // Change address path
+   * );
+   * ```
+   */
+  async createTransaction(
+    inputs: LedgerUtxoInput[],
+    outputs: LedgerTxOutput[],
+    changePath?: string
+  ): Promise<string> {
+    if (!this._btcApp) {
+      throw new Error('Not connected to Ledger device');
+    }
+
+    if (inputs.length === 0) {
+      throw new Error('At least one input is required');
+    }
+
+    if (outputs.length === 0) {
+      throw new Error('At least one output is required');
+    }
+
+    try {
+      // Determine if we're using segwit based on address type
+      const isSegwit = this._options.addressType !== 'legacy';
+      const additionals = this.getAdditionals();
+
+      // Parse input transactions
+      const parsedInputs: Array<[LedgerTransaction, number, string | null | undefined, number?]> = [];
+      const associatedKeysets: string[] = [];
+
+      for (const input of inputs) {
+        const tx = this._btcApp.splitTransaction(input.txHex, isSegwit, false, additionals);
+        parsedInputs.push([
+          tx,
+          input.outputIndex,
+          input.redeemScript ?? null,
+          input.sequence ?? 0xffffffff,
+        ]);
+        associatedKeysets.push(input.derivationPath);
+      }
+
+      // Build output script
+      const outputScriptHex = this.buildOutputScript(outputs);
+
+      // Create and sign the transaction
+      const txArgs: Parameters<LedgerBtcApp['createPaymentTransaction']>[0] = {
+        inputs: parsedInputs,
+        associatedKeysets,
+        outputScriptHex,
+        segwit: isSegwit,
+        additionals,
+        useTrustedInputForSegwit: isSegwit,
+      };
+
+      if (changePath) {
+        txArgs.changePath = changePath;
+      }
+
+      const signedTx = await this._btcApp.createPaymentTransaction(txArgs);
+
+      return signedTx;
+    } catch (error) {
+      this.handleLedgerError(error);
+    }
+  }
+
+  /**
+   * Build output script hex from outputs array
+   * Format: varint(output_count) + [amount(8 bytes LE) + varint(script_len) + script]...
+   */
+  private buildOutputScript(outputs: LedgerTxOutput[]): string {
+    let script = '';
+
+    // Output count as varint
+    script += this.encodeVarint(outputs.length);
+
+    for (const output of outputs) {
+      // Amount as 8-byte little-endian
+      const amountHex = this.uint64ToLittleEndian(output.satoshis);
+      script += amountHex;
+
+      // Script pubkey
+      const scriptPubKey = this.addressToScriptPubKey(output.address);
+      script += this.encodeVarint(scriptPubKey.length / 2);
+      script += scriptPubKey;
+    }
+
+    return script;
+  }
+
+  /**
+   * Convert address to scriptPubKey hex
+   */
+  private addressToScriptPubKey(address: string): string {
+    console.log('[LedgerConnector] addressToScriptPubKey called with:', address);
+
+    // Detect address type and convert to scriptPubKey
+    if (address.startsWith('bc1q') || address.startsWith('tb1q')) {
+      // Native SegWit (P2WPKH) - bech32
+      const decoded = this.decodeBech32(address);
+      console.log('[LedgerConnector] P2WPKH decoded length:', decoded.length, 'hex:', decoded);
+      // decoded is hex string, so 20 bytes = 40 hex chars
+      if (decoded.length !== 40) {
+        throw new Error(`Invalid P2WPKH address: expected 40 hex chars, got ${decoded.length}`);
+      }
+      // OP_0 <20-byte-hash>
+      return '0014' + decoded;
+    } else if (address.startsWith('bc1p') || address.startsWith('tb1p')) {
+      // Taproot (P2TR) - bech32m
+      const decoded = this.decodeBech32(address);
+      console.log('[LedgerConnector] P2TR decoded length:', decoded.length, 'hex:', decoded);
+      // decoded is hex string, so 32 bytes = 64 hex chars
+      if (decoded.length !== 64) {
+        throw new Error(`Invalid P2TR address: expected 64 hex chars, got ${decoded.length}`);
+      }
+      // OP_1 <32-byte-pubkey>
+      return '5120' + decoded;
+    } else if (address.startsWith('3') || address.startsWith('2')) {
+      // P2SH
+      const decoded = this.decodeBase58Check(address);
+      // OP_HASH160 <20-byte-hash> OP_EQUAL
+      return 'a914' + decoded + '87';
+    } else if (address.startsWith('1') || address.startsWith('m') || address.startsWith('n')) {
+      // P2PKH (Legacy)
+      const decoded = this.decodeBase58Check(address);
+      // OP_DUP OP_HASH160 <20-byte-hash> OP_EQUALVERIFY OP_CHECKSIG
+      return '76a914' + decoded + '88ac';
+    } else {
+      throw new Error(`Unsupported address format: ${address}`);
+    }
+  }
+
+  /**
+   * Decode bech32/bech32m address to hex
+   */
+  private decodeBech32(address: string): string {
+    const CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+
+    // Find separator
+    const pos = address.lastIndexOf('1');
+    if (pos < 1) throw new Error('Invalid bech32 address');
+
+    const data = address.slice(pos + 1);
+
+    // Decode data characters
+    const values: number[] = [];
+    for (const char of data) {
+      const idx = CHARSET.indexOf(char.toLowerCase());
+      if (idx === -1) throw new Error('Invalid bech32 character');
+      values.push(idx);
+    }
+
+    // Remove checksum (last 6 characters)
+    const dataValues = values.slice(0, -6);
+
+    // Skip witness version (first value)
+    const witnessData = dataValues.slice(1);
+
+    // Convert from 5-bit to 8-bit
+    let acc = 0;
+    let bits = 0;
+    const result: number[] = [];
+
+    for (const value of witnessData) {
+      acc = (acc << 5) | value;
+      bits += 5;
+      while (bits >= 8) {
+        bits -= 8;
+        result.push((acc >> bits) & 0xff);
+      }
+    }
+
+    return Buffer.from(result).toString('hex');
+  }
+
+  /**
+   * Decode base58check address to hex (without version byte)
+   */
+  private decodeBase58Check(address: string): string {
+    const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+    let num = BigInt(0);
+    for (const char of address) {
+      const idx = ALPHABET.indexOf(char);
+      if (idx === -1) throw new Error('Invalid base58 character');
+      num = num * BigInt(58) + BigInt(idx);
+    }
+
+    // Convert to hex and pad
+    let hex = num.toString(16);
+    if (hex.length % 2 !== 0) hex = '0' + hex;
+
+    // Handle leading zeros
+    let leadingZeros = 0;
+    for (const char of address) {
+      if (char === '1') leadingZeros++;
+      else break;
+    }
+
+    hex = '00'.repeat(leadingZeros) + hex;
+
+    // Remove version byte (1 byte) and checksum (4 bytes)
+    // Result is the 20-byte hash
+    return hex.slice(2, -8);
+  }
+
+  /**
+   * Encode number as varint hex
+   */
+  private encodeVarint(n: number): string {
+    if (n < 0xfd) {
+      return n.toString(16).padStart(2, '0');
+    } else if (n <= 0xffff) {
+      return 'fd' + this.uint16ToLittleEndian(n);
+    } else if (n <= 0xffffffff) {
+      return 'fe' + this.uint32ToLittleEndian(n);
+    } else {
+      return 'ff' + this.uint64ToLittleEndian(n);
+    }
+  }
+
+  /**
+   * Convert uint16 to little-endian hex
+   */
+  private uint16ToLittleEndian(n: number): string {
+    const buf = Buffer.alloc(2);
+    buf.writeUInt16LE(n);
+    return buf.toString('hex');
+  }
+
+  /**
+   * Convert uint32 to little-endian hex
+   */
+  private uint32ToLittleEndian(n: number): string {
+    const buf = Buffer.alloc(4);
+    buf.writeUInt32LE(n);
+    return buf.toString('hex');
+  }
+
+  /**
+   * Convert uint64 to little-endian hex
+   */
+  private uint64ToLittleEndian(n: number): string {
+    const buf = Buffer.alloc(8);
+    buf.writeBigUInt64LE(BigInt(n));
+    return buf.toString('hex');
+  }
+
+  /**
+   * Get additionals array based on address type
+   */
+  private getAdditionals(): string[] {
+    switch (this._options.addressType) {
+      case 'segwit':
+        return ['bech32'];
+      case 'taproot':
+        return ['bech32m'];
+      case 'nested-segwit':
+        return [];
+      case 'legacy':
+      default:
+        return [];
+    }
+  }
+
+  async getNetwork(): Promise<BitcoinNetwork> {
+    return this._network;
+  }
+
+  /**
+   * Get extended public key (xpub/ypub/zpub) for account
+   */
+  async getExtendedPublicKey(): Promise<string> {
+    if (!this._btcApp) {
+      throw new Error('Not connected to Ledger device');
+    }
+
+    try {
+      const coinType = this._network === 'mainnet' ? 0 : 1;
+      const purpose = ADDRESS_TYPE_TO_PATH[this._options.addressType];
+      const accountPath = `${purpose}'/${coinType}'/${this._options.accountIndex}'`;
+
+      // Get appropriate xpub version bytes based on address type and network
+      const xpubVersion = this.getXpubVersion();
+
+      const xpub = await this._btcApp.getWalletXpub({
+        path: accountPath,
+        xpubVersion,
+      });
+
+      return xpub;
+    } catch (error) {
+      this.handleLedgerError(error);
+    }
+  }
+
+  /**
+   * Get multiple addresses for the account
+   */
+  async getAddresses(startIndex: number, count: number): Promise<WalletAccount[]> {
+    if (!this._btcApp) {
+      throw new Error('Not connected to Ledger device');
+    }
+
+    const accounts: WalletAccount[] = [];
+    const coinType = this._network === 'mainnet' ? 0 : 1;
+    const purpose = ADDRESS_TYPE_TO_PATH[this._options.addressType];
+    const format = ADDRESS_TYPE_TO_FORMAT[this._options.addressType];
+
+    for (let i = startIndex; i < startIndex + count; i++) {
+      const path = `${purpose}'/${coinType}'/${this._options.accountIndex}'/0/${i}`;
+      const result = await this._btcApp.getWalletPublicKey(path, {
+        verify: false,
+        format,
+      });
+
+      accounts.push({
+        address: result.bitcoinAddress,
+        publicKey: result.publicKey,
+        type: this.mapLedgerAddressType(this._options.addressType),
+      });
+    }
+
+    return accounts;
+  }
+
+  /**
+   * Get current derivation path
+   */
+  getDerivationPath(): string {
+    return this._derivationPath;
+  }
+
+  /**
+   * Check if device is connected
+   */
+  isConnected(): boolean {
+    return this._transport !== null && this._btcApp !== null;
+  }
+
+  /**
+   * Get the Ledger Bitcoin app instance for advanced operations
+   * This allows users to call createPaymentTransaction directly
+   */
+  getBtcApp(): LedgerBtcApp | null {
+    return this._btcApp;
+  }
+
+  private mapLedgerAddressType(addressType: LedgerAddressType): AddressType {
+    switch (addressType) {
+      case 'legacy':
+        return 'legacy';
+      case 'nested-segwit':
+        return 'nested-segwit';
+      case 'segwit':
+        return 'segwit';
+      case 'taproot':
+        return 'taproot';
+      default:
+        return 'segwit';
+    }
+  }
+
+  private getXpubVersion(): number {
+    const isMainnet = this._network === 'mainnet';
+
+    switch (this._options.addressType) {
+      case 'legacy':
+        return isMainnet ? 0x0488b21e : 0x043587cf; // xpub / tpub
+      case 'nested-segwit':
+        return isMainnet ? 0x049d7cb2 : 0x044a5262; // ypub / upub
+      case 'segwit':
+        return isMainnet ? 0x04b24746 : 0x045f1cf6; // zpub / vpub
+      case 'taproot':
+        return isMainnet ? 0x0488b21e : 0x043587cf; // xpub / tpub (taproot uses standard)
+      default:
+        return isMainnet ? 0x04b24746 : 0x045f1cf6;
+    }
+  }
+
+  private handleLedgerError(error: unknown): never {
+    // Handle specific Ledger errors
+    if (error instanceof Error) {
+      const message = error.message.toLowerCase();
+
+      if (message.includes('locked') || message.includes('0x6982')) {
+        throw new Error('Ledger device is locked. Please unlock it and try again.');
+      }
+
+      if (message.includes('denied') || message.includes('rejected') || message.includes('0x6985')) {
+        throw new Error('User rejected the request on Ledger device.');
+      }
+
+      if (message.includes('app') && message.includes('open')) {
+        throw new Error('Please open the Bitcoin app on your Ledger device.');
+      }
+
+      if (message.includes('transportopenusercancelled')) {
+        throw new Error('Connection cancelled. Please try again.');
+      }
+
+      if (message.includes('no device selected')) {
+        throw new Error('No Ledger device selected. Please connect your device and try again.');
+      }
+    }
+
+    this.handleError(error);
+  }
+}