otx-btc-wallet-connectors 0.1.0

package/README.md

@@ -0,0 +1,554 @@
+# otx-btc-wallet-connectors
+
+Bitcoin wallet connectors, blockchain services, and PSBT utilities for the `otx-btc-wallet` library.
+
+## Installation
+
+```bash
+pnpm add otx-btc-wallet-connectors otx-btc-wallet-core
+```
+
+## Supported Wallets
+
+| Wallet | Connector | Type | Sign PSBT | Batch PSBT | Send BTC | Network Switch |
+|--------|-----------|------|-----------|------------|----------|----------------|
+| Unisat | `UnisatConnector` | Extension | Yes | Yes | Yes | Yes |
+| Xverse | `XverseConnector` | Extension | Yes | No | Yes | Yes |
+| OKX | `OKXConnector` | Extension | Yes | No | Yes | No* |
+| Phantom | `PhantomConnector` | Extension | Yes | No | Yes | No** |
+| Bitget | `BitgetConnector` | Extension | Yes | No | Yes | Yes |
+| Binance | `BinanceConnector` | Extension | Yes | No | Yes | Yes |
+| imToken | `ImTokenConnector` | Mobile | Yes | No | Yes | Yes |
+| Ledger | `LedgerConnector` | Hardware | No*** | No | Yes | N/A |
+| Trezor | `TrezorConnector` | Hardware | No*** | No | Yes | N/A |
+
+\* OKX: Users switch network in the extension manually.
+\*\* Phantom: Only supports mainnet for Bitcoin.
+\*\*\* Hardware wallets use `sendTransaction()` directly with built-in PSBT construction.
+
+## Quick Start
+
+```typescript
+import {
+  UnisatConnector,
+  XverseConnector,
+  OKXConnector,
+  PhantomConnector,
+  BitgetConnector,
+  BinanceConnector,
+  ImTokenConnector,
+  LedgerConnector,
+  TrezorConnector,
+} from 'otx-btc-wallet-connectors';
+
+// Create a connector
+const unisat = new UnisatConnector();
+
+// Check if wallet is installed
+if (unisat.ready) {
+  // Connect
+  const account = await unisat.connect('mainnet');
+  console.log(account.address, account.publicKey, account.type);
+
+  // Sign message
+  const signature = await unisat.signMessage('Hello Bitcoin!');
+
+  // Sign PSBT
+  const signedPsbt = await unisat.signPsbt(psbtHex, {
+    autoFinalize: true,
+  });
+
+  // Batch sign PSBTs (Unisat only)
+  const signedPsbts = await unisat.signPsbts([psbt1, psbt2], {
+    autoFinalize: true,
+  });
+
+  // Send Bitcoin (amount in satoshis)
+  const txid = await unisat.sendTransaction('bc1q...', 10000);
+
+  // Disconnect
+  await unisat.disconnect();
+}
+```
+
+## Connector Interface
+
+All connectors implement the `BitcoinConnector` interface from `otx-btc-wallet-core`:
+
+```typescript
+interface BitcoinConnector {
+  readonly id: string;         // Unique identifier (e.g. 'unisat')
+  readonly name: string;       // Display name (e.g. 'Unisat')
+  readonly icon: string;       // Base64 SVG/PNG icon
+  ready: boolean;              // Is the wallet installed/available?
+
+  connect(network?: BitcoinNetwork): Promise<WalletAccount>;
+  disconnect(): Promise<void>;
+  getAccounts(): Promise<WalletAccount[]>;
+  signMessage(message: string): Promise<string>;
+  signPsbt(psbtHex: string, options?: SignPsbtOptions): Promise<string>;
+  signPsbts?(psbtHexs: string[], options?: SignPsbtOptions): Promise<string[]>;
+  sendTransaction(to: string, satoshis: number): Promise<string>;
+  getNetwork(): Promise<BitcoinNetwork>;
+  switchNetwork?(network: BitcoinNetwork): Promise<void>;
+  onAccountsChanged(callback: (accounts: WalletAccount[]) => void): () => void;
+  onNetworkChanged(callback: (network: BitcoinNetwork) => void): () => void;
+}
+```
+
+## Event Listeners
+
+All connectors support account and network change events:
+
+```typescript
+// Listen for account changes
+const unsubscribe = connector.onAccountsChanged((accounts) => {
+  if (accounts.length === 0) {
+    console.log('Wallet disconnected');
+  } else {
+    console.log('Account changed:', accounts[0].address);
+  }
+});
+
+// Listen for network changes
+const unsubNetwork = connector.onNetworkChanged((network) => {
+  console.log('Network changed to:', network);
+});
+
+// Cleanup listeners
+unsubscribe();
+unsubNetwork();
+```
+
+## Hardware Wallets
+
+### Ledger
+
+Connects via WebUSB. Requires a Chromium-based browser (Chrome, Edge, Brave).
+
+```typescript
+import { LedgerConnector } from 'otx-btc-wallet-connectors';
+import type { LedgerConnectorOptions } from 'otx-btc-wallet-connectors';
+
+const ledger = new LedgerConnector({
+  addressType: 'segwit',  // 'legacy' | 'nested-segwit' | 'segwit' | 'taproot'
+});
+
+// Connect - opens USB device picker
+const account = await ledger.connect('mainnet');
+
+// Send Bitcoin (PSBT is built and signed internally)
+const txid = await ledger.sendTransaction('bc1q...', 50000);
+
+// Get multiple addresses from the device
+const addresses = await ledger.getAddresses(0, 5); // indices 0-4
+
+// Get extended public key
+const xpub = await ledger.getExtendedPublicKey();
+
+// Disconnect (closes USB transport)
+await ledger.disconnect();
+```
+
+**Ledger Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `addressType` | `AddressType` | `'segwit'` | Address derivation type |
+
+### Trezor
+
+Connects via [Trezor Connect](https://connect.trezor.io/).
+
+```typescript
+import { TrezorConnector } from 'otx-btc-wallet-connectors';
+import type { TrezorConnectorOptions } from 'otx-btc-wallet-connectors';
+
+const trezor = new TrezorConnector({
+  addressType: 'segwit',
+  manifest: {
+    email: 'your@email.com',
+    appUrl: 'https://your-app.com',
+  },
+});
+
+// Connect - opens Trezor Connect popup
+const account = await trezor.connect('mainnet');
+
+// Send Bitcoin
+const txid = await trezor.sendTransaction('bc1q...', 50000);
+
+// Get multiple addresses
+const addresses = await trezor.getAddresses(0, 5);
+
+// Get extended public key
+const xpub = await trezor.getExtendedPublicKey();
+
+// Verify address on device screen
+const verified = await trezor.getAddressWithVerification();
+
+await trezor.disconnect();
+```
+
+**Trezor Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `addressType` | `AddressType` | `'segwit'` | Address derivation type |
+| `manifest.email` | `string` | `'support@optimex.com'` | Contact email for Trezor |
+| `manifest.appUrl` | `string` | `'https://optimex.com'` | App URL for Trezor |
+
+## Custom Connectors
+
+Extend `BaseConnector` to add support for any Bitcoin wallet:
+
+```typescript
+import { BaseConnector } from 'otx-btc-wallet-connectors';
+import type {
+  WalletAccount,
+  BitcoinNetwork,
+  SignPsbtOptions,
+} from 'otx-btc-wallet-core';
+
+export class MyWalletConnector extends BaseConnector {
+  readonly id = 'my-wallet';
+  readonly name = 'My Wallet';
+  readonly icon = 'data:image/svg+xml;base64,...';
+
+  // Return the wallet's injected provider, or null if not installed
+  protected getProvider() {
+    return (window as any).myWallet ?? null;
+  }
+
+  async connect(network: BitcoinNetwork = 'mainnet'): Promise<WalletAccount> {
+    this.ensureInstalled(); // Throws if getProvider() returns null
+    const provider = this.getProvider()!;
+
+    const accounts = await provider.requestAccounts();
+    const publicKey = await provider.getPublicKey();
+
+    return {
+      address: accounts[0],
+      publicKey,
+      type: this.inferAddressType(accounts[0]), // Auto-detect from address prefix
+    };
+  }
+
+  async disconnect(): Promise<void> {
+    this.cleanup(); // Removes event listeners
+  }
+
+  async getAccounts(): Promise<WalletAccount[]> {
+    const provider = this.getProvider()!;
+    const accounts = await provider.getAccounts();
+    const publicKey = await provider.getPublicKey();
+    return accounts.map((addr: string) => ({
+      address: addr,
+      publicKey,
+      type: this.inferAddressType(addr),
+    }));
+  }
+
+  async signMessage(message: string): Promise<string> {
+    return this.getProvider()!.signMessage(message);
+  }
+
+  async signPsbt(psbtHex: string, options?: SignPsbtOptions): Promise<string> {
+    return this.getProvider()!.signPsbt(psbtHex, options);
+  }
+
+  async sendTransaction(to: string, satoshis: number): Promise<string> {
+    return this.getProvider()!.sendBitcoin(to, satoshis);
+  }
+
+  async getNetwork(): Promise<BitcoinNetwork> {
+    return this.getProvider()!.getNetwork();
+  }
+}
+```
+
+### BaseConnector Protected Methods
+
+| Method | Description |
+|--------|-------------|
+| `getProvider()` | Abstract. Return the wallet's injected provider object |
+| `ensureInstalled()` | Throws error if `getProvider()` returns null/undefined |
+| `inferAddressType(address)` | Detects address type from prefix (`1...` = legacy, `3...` = nested-segwit, `bc1q...` = segwit, `bc1p...` = taproot) |
+| `handleError(error)` | Wraps errors with connector context |
+| `emitAccountsChanged(accounts)` | Notify listeners of account changes |
+| `emitNetworkChanged(network)` | Notify listeners of network changes |
+| `cleanup()` | Remove all registered event listeners |
+
+## BtcService
+
+`BtcService` provides a unified API for querying Bitcoin blockchain data. It uses a dual-provider architecture with Mempool.space and Blockstream.info for reliability.
+
+### Basic Usage
+
+```typescript
+import { BtcService } from 'otx-btc-wallet-connectors';
+
+const service = new BtcService('mainnet');
+
+// Get UTXOs for an address
+const utxos = await service.getUtxos('bc1q...');
+
+// Get transaction hex
+const txHex = await service.getTxHex('txid...');
+
+// Get full transaction details
+const tx = await service.getTransaction('txid...');
+
+// Broadcast a signed transaction
+const txid = await service.broadcastTransaction(signedTxHex);
+
+// Get address balance
+const balance = await service.getBalance('bc1q...');
+
+// Get current fee rates (sat/vB)
+const fees = await service.getFeeRates();
+// { fastest: number, halfHour: number, hour: number, economy: number, minimum: number }
+```
+
+### Standalone Functions
+
+For convenience, you can also use standalone functions without creating an instance:
+
+```typescript
+import {
+  getUtxos,
+  getTxHex,
+  getTransaction,
+  broadcastTransaction,
+  getBalance,
+  getFeeRates,
+} from 'otx-btc-wallet-connectors';
+
+const utxos = await getUtxos('mainnet', 'bc1q...');
+const fees = await getFeeRates('mainnet');
+```
+
+### Custom RPC Endpoints
+
+Configure custom Mempool.space or Blockstream.info endpoints globally:
+
+```typescript
+import { configureBtcService } from 'otx-btc-wallet-connectors';
+
+configureBtcService({
+  mempool: {
+    mainnet: 'https://my-mempool.example.com/api',
+    testnet: 'https://my-mempool.example.com/testnet/api',
+  },
+  blockstream: {
+    mainnet: 'https://my-blockstream.example.com/api',
+  },
+  preferredProvider: 'mempool', // 'mempool' | 'blockstream' | 'race' (default)
+});
+```
+
+**Provider Modes:**
+
+| Mode | Description |
+|------|-------------|
+| `'race'` | (Default) Sends requests to both providers simultaneously, uses whichever responds first |
+| `'mempool'` | Only use Mempool.space |
+| `'blockstream'` | Only use Blockstream.info |
+
+### Per-Instance Configuration
+
+You can also pass config when creating a `BtcService` instance:
+
+```typescript
+const service = new BtcService('mainnet', {
+  mempool: { mainnet: 'https://my-mempool.example.com/api' },
+  preferredProvider: 'mempool',
+});
+```
+
+### Configuration Types
+
+```typescript
+import type { BtcServiceConfig, NetworkEndpoints } from 'otx-btc-wallet-connectors';
+
+interface NetworkEndpoints {
+  mainnet?: string;
+  testnet?: string;
+  testnet4?: string;
+  signet?: string;
+}
+
+interface BtcServiceConfig {
+  mempool?: NetworkEndpoints;
+  blockstream?: NetworkEndpoints;
+  preferredProvider?: 'mempool' | 'blockstream' | 'race';
+}
+```
+
+### Get Current Config
+
+```typescript
+import { getBtcServiceConfig } from 'otx-btc-wallet-connectors';
+
+const currentConfig = getBtcServiceConfig();
+```
+
+## Service Types
+
+```typescript
+import type {
+  Utxo,
+  UtxoWithTx,
+  FeeRates,
+  Transaction,
+  FullTransaction,
+  AddressBalance,
+  IBtcService,
+} from 'otx-btc-wallet-connectors';
+
+interface Utxo {
+  txid: string;
+  vout: number;
+  value: number;
+  status: { confirmed: boolean; block_height?: number };
+}
+
+interface FeeRates {
+  fastest: number;
+  halfHour: number;
+  hour: number;
+  economy: number;
+  minimum: number;
+}
+
+interface AddressBalance {
+  confirmed: number;
+  unconfirmed: number;
+  total: number;
+}
+```
+
+## PSBT Builder Utilities
+
+Low-level utilities for building Bitcoin transactions:
+
+```typescript
+import {
+  deriveAddressFromPublicKey,
+  detectAddressType,
+  estimateVBytes,
+  selectUtxos,
+  buildPsbt,
+} from 'otx-btc-wallet-connectors';
+```
+
+### Derive Address from Public Key
+
+```typescript
+import { deriveAddressFromPublicKey } from 'otx-btc-wallet-connectors';
+
+const address = deriveAddressFromPublicKey(
+  publicKeyHex,    // Hex-encoded public key
+  'segwit',        // 'legacy' | 'nested-segwit' | 'segwit' | 'taproot'
+  'mainnet',       // Bitcoin network
+);
+```
+
+## Individual Service Classes
+
+You can use Mempool or Blockstream services directly:
+
+```typescript
+import { MempoolService, BlockstreamService } from 'otx-btc-wallet-connectors';
+
+// Use Mempool.space directly
+const mempool = new MempoolService('mainnet');
+const utxos = await mempool.getUtxos('bc1q...');
+
+// Use Blockstream.info directly
+const blockstream = new BlockstreamService('mainnet');
+const balance = await blockstream.getBalance('bc1q...');
+
+// With custom endpoints
+const customMempool = new MempoolService('mainnet', {
+  mainnet: 'https://my-mempool.example.com/api',
+});
+```
+
+## Default API Endpoints
+
+### Mempool.space
+
+| Network | Endpoint |
+|---------|----------|
+| mainnet | `https://mempool.space/api` |
+| testnet | `https://mempool.space/testnet/api` |
+| testnet4 | `https://mempool.space/testnet4/api` |
+| signet | `https://mempool.space/signet/api` |
+
+### Blockstream.info
+
+| Network | Endpoint |
+|---------|----------|
+| mainnet | `https://blockstream.info/api` |
+| testnet | `https://blockstream.info/testnet/api` |
+| testnet4 | `https://mempool.space/testnet4/api` (fallback) |
+| signet | `https://mempool.space/signet/api` (fallback) |
+
+## Full Exports
+
+```typescript
+// Connectors
+export { UnisatConnector } from './unisat';
+export { XverseConnector } from './xverse';
+export { OKXConnector } from './okx';
+export { PhantomConnector } from './phantom';
+export { BitgetConnector } from './bitget';
+export { BinanceConnector } from './binance';
+export { ImTokenConnector } from './imtoken';
+export { LedgerConnector } from './ledger';
+export type { LedgerConnectorOptions } from './ledger';
+export { TrezorConnector } from './trezor';
+export type { TrezorConnectorOptions } from './trezor';
+
+// Base class for custom connectors
+export { BaseConnector } from './base';
+
+// Services
+export { BtcService } from './utils/btc-service';
+export { MempoolService } from './utils/mempool';
+export { BlockstreamService } from './utils/blockstream';
+
+// Configuration
+export { configureBtcService, getBtcServiceConfig } from './utils/btc-service';
+
+// PSBT Builder
+export { deriveAddressFromPublicKey } from './utils/psbt-builder';
+
+// Standalone functions
+export {
+  getUtxos,
+  getTxHex,
+  getTransaction,
+  broadcastTransaction,
+  getBalance,
+  getFeeRates,
+} from './utils/btc-service';
+
+// Types
+export type {
+  Utxo,
+  UtxoWithTx,
+  FeeRates,
+  Transaction,
+  FullTransaction,
+  AddressBalance,
+  IBtcService,
+  BtcServiceConfig,
+  NetworkEndpoints,
+} from './utils/types';
+```
+
+## License
+
+MIT

package/dist/base-IAFq7sd8.d.mts

@@ -0,0 +1,53 @@
+import { BitcoinConnector, AddressType, BitcoinNetwork, WalletAccount, SignPsbtOptions } from 'otx-btc-wallet-core';
+
+/**
+ * Abstract base class for all wallet connectors
+ * Provides common functionality and enforces the BitcoinConnector interface
+ */
+declare abstract class BaseConnector implements BitcoinConnector {
+    abstract readonly id: string;
+    abstract readonly name: string;
+    abstract readonly icon: string;
+    private _ready;
+    private _accountsChangedCallbacks;
+    private _networkChangedCallbacks;
+    constructor();
+    get ready(): boolean;
+    protected set ready(value: boolean);
+    protected abstract getProvider(): unknown;
+    protected checkReady(): void;
+    protected ensureInstalled(): void;
+    protected inferAddressType(address: string): AddressType;
+    protected handleError(error: unknown): never;
+    abstract connect(network?: BitcoinNetwork): Promise<WalletAccount>;
+    abstract disconnect(): Promise<void>;
+    abstract getAccounts(): Promise<WalletAccount[]>;
+    abstract signMessage(message: string): Promise<string>;
+    abstract signPsbt(psbtHex: string, options?: SignPsbtOptions): Promise<string>;
+    abstract sendTransaction(to: string, satoshis: number): Promise<string>;
+    abstract getNetwork(): Promise<BitcoinNetwork>;
+    signPsbts?(psbtHexs: string[], options?: SignPsbtOptions): Promise<string[]>;
+    switchNetwork?(network: BitcoinNetwork): Promise<void>;
+    /**
+     * Subscribe to account changes
+     */
+    onAccountsChanged(callback: (accounts: WalletAccount[]) => void): () => void;
+    /**
+     * Subscribe to network changes
+     */
+    onNetworkChanged(callback: (network: BitcoinNetwork) => void): () => void;
+    /**
+     * Emit account change event
+     */
+    protected emitAccountsChanged(accounts: WalletAccount[]): void;
+    /**
+     * Emit network change event
+     */
+    protected emitNetworkChanged(network: BitcoinNetwork): void;
+    /**
+     * Clean up all listeners
+     */
+    protected cleanup(): void;
+}
+
+export { BaseConnector as B };

package/dist/base-IAFq7sd8.d.ts

@@ -0,0 +1,53 @@
+import { BitcoinConnector, AddressType, BitcoinNetwork, WalletAccount, SignPsbtOptions } from 'otx-btc-wallet-core';
+
+/**
+ * Abstract base class for all wallet connectors
+ * Provides common functionality and enforces the BitcoinConnector interface
+ */
+declare abstract class BaseConnector implements BitcoinConnector {
+    abstract readonly id: string;
+    abstract readonly name: string;
+    abstract readonly icon: string;
+    private _ready;
+    private _accountsChangedCallbacks;
+    private _networkChangedCallbacks;
+    constructor();
+    get ready(): boolean;
+    protected set ready(value: boolean);
+    protected abstract getProvider(): unknown;
+    protected checkReady(): void;
+    protected ensureInstalled(): void;
+    protected inferAddressType(address: string): AddressType;
+    protected handleError(error: unknown): never;
+    abstract connect(network?: BitcoinNetwork): Promise<WalletAccount>;
+    abstract disconnect(): Promise<void>;
+    abstract getAccounts(): Promise<WalletAccount[]>;
+    abstract signMessage(message: string): Promise<string>;
+    abstract signPsbt(psbtHex: string, options?: SignPsbtOptions): Promise<string>;
+    abstract sendTransaction(to: string, satoshis: number): Promise<string>;
+    abstract getNetwork(): Promise<BitcoinNetwork>;
+    signPsbts?(psbtHexs: string[], options?: SignPsbtOptions): Promise<string[]>;
+    switchNetwork?(network: BitcoinNetwork): Promise<void>;
+    /**
+     * Subscribe to account changes
+     */
+    onAccountsChanged(callback: (accounts: WalletAccount[]) => void): () => void;
+    /**
+     * Subscribe to network changes
+     */
+    onNetworkChanged(callback: (network: BitcoinNetwork) => void): () => void;
+    /**
+     * Emit account change event
+     */
+    protected emitAccountsChanged(accounts: WalletAccount[]): void;
+    /**
+     * Emit network change event
+     */
+    protected emitNetworkChanged(network: BitcoinNetwork): void;
+    /**
+     * Clean up all listeners
+     */
+    protected cleanup(): void;
+}
+
+export { BaseConnector as B };