otx-btc-wallet-core 0.1.0

package/README.md

@@ -0,0 +1,312 @@
+# otx-btc-wallet-core
+
+Core state management, types, and configuration for the `otx-btc-wallet` library. This package provides the foundation that connectors and React hooks build on.
+
+## Installation
+
+```bash
+pnpm add otx-btc-wallet-core
+```
+
+## Overview
+
+This package includes:
+
+- **`createConfig()`** - Configuration factory that initializes the store and connectors
+- **Zustand Store** - Reactive state management with persistence and auto-reconnect
+- **TypeScript Types** - Full type definitions for connectors, accounts, networks, and PSBTs
+- **PSBT Utilities** - Hex/Base64 conversion, validation, and sighash helpers
+
+## Usage
+
+### Create Config
+
+```typescript
+import { createConfig } from 'otx-btc-wallet-core';
+import { UnisatConnector, XverseConnector } from 'otx-btc-wallet-connectors';
+
+const config = createConfig({
+  connectors: [
+    new UnisatConnector(),
+    new XverseConnector(),
+  ],
+});
+```
+
+### Config Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `connectors` | `BitcoinConnector[]` | **(required)** | Wallet connectors to register |
+| `autoConnect` | `boolean` | `true` | Auto-reconnect to last used wallet on page load |
+| `storage` | `Storage` | `localStorage` | Storage backend for persistence |
+| `storageKey` | `string` | `'optimex-btc-wallet.store'` | Key prefix for persisted state |
+
+**Validation:**
+- At least one connector must be provided
+- Duplicate connector IDs will throw an error
+
+### Access the Store Directly
+
+The config object contains a Zustand store you can use outside of React:
+
+```typescript
+const config = createConfig({ /* ... */ });
+
+// Read current state
+const { status, account, connector, network } = config.store.getState();
+
+// Subscribe to changes
+const unsubscribe = config.store.subscribe(
+  (state) => state.account,
+  (account) => console.log('Account changed:', account),
+);
+
+// Perform actions
+await config.store.getState().connect(connector);
+await config.store.getState().disconnect();
+```
+
+## Types
+
+### `BitcoinNetwork`
+
+```typescript
+type BitcoinNetwork = 'mainnet' | 'testnet' | 'testnet4' | 'signet';
+```
+
+### `AddressType`
+
+```typescript
+type AddressType = 'legacy' | 'nested-segwit' | 'segwit' | 'taproot';
+```
+
+### `WalletAccount`
+
+```typescript
+type WalletAccount = {
+  address: string;
+  publicKey: string;
+  type: AddressType;
+};
+```
+
+### `MultiAddressAccount`
+
+Used by wallets like Xverse that provide separate payment and ordinals addresses.
+
+```typescript
+type MultiAddressAccount = {
+  payment: WalletAccount;
+  ordinals: WalletAccount;
+};
+```
+
+### `BitcoinConnector`
+
+The interface all wallet connectors must implement.
+
+```typescript
+interface BitcoinConnector {
+  readonly id: string;
+  readonly name: string;
+  readonly icon: string;
+  ready: boolean;
+
+  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;
+}
+```
+
+### `SignPsbtOptions`
+
+```typescript
+type SignPsbtOptions = {
+  autoFinalize?: boolean;    // Auto-finalize inputs after signing
+  broadcast?: boolean;       // Broadcast the transaction after signing
+  toSignInputs?: SignInput[]; // Specify which inputs to sign
+};
+```
+
+### `SignInput`
+
+```typescript
+type SignInput = {
+  index: number;                  // Input index
+  address?: string;               // Address owning this input
+  publicKey?: string;             // Public key for this input
+  sighashTypes?: number[];        // Sighash types to use
+  disableTweakSigner?: boolean;   // Disable tweaked signer (taproot)
+};
+```
+
+### `ConnectionStatus`
+
+```typescript
+type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+```
+
+### `BtcWalletState`
+
+The full store state shape.
+
+```typescript
+type BtcWalletState = {
+  status: ConnectionStatus;
+  account: WalletAccount | null;
+  connector: BitcoinConnector | null;
+  connectorId: string | null;
+  network: BitcoinNetwork;
+  error: Error | null;
+};
+```
+
+### `BtcWalletConfig`
+
+```typescript
+type BtcWalletConfig = {
+  connectors: BitcoinConnector[];
+  autoConnect?: boolean;
+  storage?: Storage;
+  storageKey?: string;
+};
+```
+
+## Store
+
+The store is built on [Zustand](https://github.com/pmndrs/zustand) with `persist` and `subscribeWithSelector` middleware.
+
+### State
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | `ConnectionStatus` | Current connection status |
+| `account` | `WalletAccount \| null` | Connected account info |
+| `connector` | `BitcoinConnector \| null` | Active connector instance |
+| `connectorId` | `string \| null` | ID of the active connector |
+| `network` | `BitcoinNetwork` | Current network |
+| `error` | `Error \| null` | Last error |
+
+### Actions
+
+| Action | Signature | Description |
+|--------|-----------|-------------|
+| `connect` | `(connector, network?) => Promise<WalletAccount>` | Connect to a wallet |
+| `disconnect` | `() => Promise<void>` | Disconnect current wallet |
+| `reconnect` | `(connectors) => Promise<void>` | Reconnect to saved wallet |
+| `setAccount` | `(account) => void` | Update account state |
+| `setStatus` | `(status) => void` | Update connection status |
+| `setError` | `(error) => void` | Set error state |
+| `reset` | `() => void` | Reset to initial state |
+
+### Persistence
+
+Only `connectorId` and `network` are persisted to storage. Account data is fetched fresh from the connector on reconnect.
+
+### Auto-Reconnect
+
+When `autoConnect` is `true` (default), the store checks for a saved `connectorId` on initialization. If found, it automatically reconnects to that wallet using the `reconnect()` action.
+
+## PSBT Utilities
+
+Lightweight PSBT helpers that work in both Node.js and browser environments.
+
+### Conversion
+
+```typescript
+import { psbtHexToBase64, psbtBase64ToHex } from 'otx-btc-wallet-core';
+
+const base64 = psbtHexToBase64(psbtHex);
+const hex = psbtBase64ToHex(psbtBase64);
+```
+
+### Validation
+
+```typescript
+import { isValidPsbtHex, isValidPsbtBase64 } from 'otx-btc-wallet-core';
+
+isValidPsbtHex('70736274ff01...');  // true
+isValidPsbtBase64('cHNidP8B...');   // true
+```
+
+### Info Extraction
+
+```typescript
+import { getPsbtInfo } from 'otx-btc-wallet-core';
+
+const info = getPsbtInfo(psbtHex);
+// { isValid: boolean, version: number | null, inputCount: number | null, outputCount: number | null }
+```
+
+### Combine PSBTs
+
+```typescript
+import { combinePsbts } from 'otx-btc-wallet-core';
+
+const combined = combinePsbts([psbt1Hex, psbt2Hex]);
+```
+
+### Sighash Types
+
+```typescript
+import { SighashType, getSighashTypeName } from 'otx-btc-wallet-core';
+
+SighashType.ALL;              // 0x01
+SighashType.NONE;             // 0x02
+SighashType.SINGLE;           // 0x03
+SighashType.ANYONECANPAY;     // 0x80
+SighashType.ALL_ANYONECANPAY; // 0x81
+
+getSighashTypeName(0x01); // 'ALL'
+```
+
+## Full Exports
+
+```typescript
+// Config
+export { createConfig } from './createConfig';
+
+// Store
+export { createStore } from './store';
+export type { BtcWalletStore, Store, StoreActions } from './store';
+
+// Types
+export type {
+  BitcoinConnector,
+  WalletAccount,
+  AddressType,
+  MultiAddressAccount,
+  BitcoinNetwork,
+  SignPsbtOptions,
+  SignInput,
+  BtcWalletConfig,
+  Config,
+  BtcWalletState,
+  ConnectionStatus,
+} from './types';
+
+// PSBT Utilities
+export {
+  psbtHexToBase64,
+  psbtBase64ToHex,
+  isValidPsbtHex,
+  isValidPsbtBase64,
+  getPsbtInfo,
+  combinePsbts,
+  SighashType,
+  getSighashTypeName,
+} from './utils';
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,320 @@
+import * as zustand_vanilla from 'zustand/vanilla';
+import { PersistOptions } from 'zustand/middleware';
+
+/**
+ * Bitcoin address types supported by wallets
+ */
+type AddressType = 'legacy' | 'nested-segwit' | 'segwit' | 'taproot';
+/**
+ * Wallet account information returned from connection
+ */
+type WalletAccount = {
+    /** Bitcoin address */
+    address: string;
+    /** Hex-encoded public key */
+    publicKey: string;
+    /** Address format type */
+    type: AddressType;
+};
+/**
+ * Multi-address account for wallets supporting both payment and ordinals addresses
+ */
+type MultiAddressAccount = {
+    /** Payment address for BTC transfers (typically segwit) */
+    payment: WalletAccount;
+    /** Ordinals address for Ordinals/Runes (typically taproot) */
+    ordinals: WalletAccount;
+};
+
+/**
+ * Supported Bitcoin networks
+ */
+type BitcoinNetwork = 'mainnet' | 'testnet' | 'testnet4' | 'signet';
+
+/**
+ * Options for signing a PSBT
+ */
+type SignPsbtOptions = {
+    /** Auto-finalize inputs after signing (default: true) */
+    autoFinalize?: boolean;
+    /** Specific inputs to sign */
+    toSignInputs?: SignInput[];
+    /** Broadcast transaction after signing (where supported) */
+    broadcast?: boolean;
+};
+/**
+ * Configuration for signing a specific input
+ */
+type SignInput = {
+    /** Input index to sign */
+    index: number;
+    /** Address to use for signing */
+    address?: string;
+    /** Public key to use for signing */
+    publicKey?: string;
+    /** Allowed sighash types */
+    sighashTypes?: number[];
+    /** Disable tweak signer for taproot key-path spends */
+    disableTweakSigner?: boolean;
+};
+
+/**
+ * Interface that all wallet connectors must implement
+ */
+type NetworkType = 'mainnet' | 'testnet' | 'testnet4' | 'signet';
+interface BitcoinConnector {
+    /** Unique identifier for the connector (e.g., 'unisat') */
+    readonly id: string;
+    /** Display name for the wallet (e.g., 'Unisat Wallet') */
+    readonly name: string;
+    /** Base64 encoded icon or URL to wallet icon */
+    readonly icon: string;
+    /** Whether the wallet extension is detected and ready */
+    ready: boolean;
+    /**
+     * Connect to the wallet
+     * @returns The connected wallet account
+     * @throws ConnectionError if connection fails
+     * @throws UserRejectedError if user rejects connection
+     */
+    connect(network?: NetworkType): Promise<WalletAccount>;
+    /**
+     * Disconnect from the wallet
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Get all accounts from the wallet
+     * @returns Array of wallet accounts
+     */
+    getAccounts(): Promise<WalletAccount[]>;
+    /**
+     * Sign an arbitrary message
+     * @param message - Message to sign
+     * @returns Signature string
+     * @throws SigningError if signing fails
+     * @throws UserRejectedError if user rejects signing
+     */
+    signMessage(message: string): Promise<string>;
+    /**
+     * Sign a PSBT (Partially Signed Bitcoin Transaction)
+     * @param psbtHex - PSBT in hex format
+     * @param options - Signing options
+     * @returns Signed PSBT in hex format
+     * @throws SigningError if signing fails
+     * @throws UserRejectedError if user rejects signing
+     */
+    signPsbt(psbtHex: string, options?: SignPsbtOptions): Promise<string>;
+    /**
+     * Sign multiple PSBTs (optional, not all wallets support this)
+     * @param psbtHexs - Array of PSBTs in hex format
+     * @param options - Signing options
+     * @returns Array of signed PSBTs in hex format
+     */
+    signPsbts?(psbtHexs: string[], options?: SignPsbtOptions): Promise<string[]>;
+    /**
+     * Send a Bitcoin transaction
+     * @param to - Recipient address
+     * @param satoshis - Amount in satoshis
+     * @returns Transaction ID
+     * @throws SigningError if transaction fails
+     * @throws UserRejectedError if user rejects transaction
+     */
+    sendTransaction(to: string, satoshis: number): Promise<string>;
+    /**
+     * Get current network from the wallet
+     * @returns Current network
+     */
+    getNetwork(): Promise<BitcoinNetwork>;
+    /**
+     * Switch to a different network (optional, not all wallets support this)
+     * @param network - Network to switch to
+     * @throws NetworkError if switch fails
+     */
+    switchNetwork?(network: BitcoinNetwork): Promise<void>;
+    /**
+     * Subscribe to account changes
+     * @param callback - Called when accounts change
+     * @returns Unsubscribe function
+     */
+    onAccountsChanged(callback: (accounts: WalletAccount[]) => void): () => void;
+    /**
+     * Subscribe to network changes
+     * @param callback - Called when network changes
+     * @returns Unsubscribe function
+     */
+    onNetworkChanged(callback: (network: BitcoinNetwork) => void): () => void;
+}
+
+/**
+ * Configuration for otx-btc-wallet
+ */
+type BtcWalletConfig = {
+    /** Array of wallet connectors to support */
+    connectors: BitcoinConnector[];
+    /** Whether to auto-connect on page load (default: true) */
+    autoConnect?: boolean;
+    /** Storage implementation for persistence (default: localStorage) */
+    storage?: Storage;
+    /** Key to use for storage (default: 'optimex-btc-wallet.store') */
+    storageKey?: string;
+};
+/**
+ * Internal config with resolved defaults
+ */
+type Config = {
+    connectors: BitcoinConnector[];
+    autoConnect: boolean;
+    storage: Storage | null;
+    storageKey: string;
+};
+
+/**
+ * Connection status states
+ */
+type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+/**
+ * Store state shape
+ */
+type BtcWalletState = {
+    /** Current connection status */
+    status: ConnectionStatus;
+    /** Connected account (null if disconnected) */
+    account: WalletAccount | null;
+    /** Active connector (null if disconnected) */
+    connector: BitcoinConnector | null;
+    /** Connected connector ID (for persistence) */
+    connectorId: string | null;
+    /** Current network */
+    network: BitcoinNetwork;
+    /** Last error (null if no error) */
+    error: Error | null;
+};
+
+/**
+ * Store actions
+ */
+type StoreActions = {
+    /** Connect to a wallet */
+    connect: (connector: BitcoinConnector, network?: BitcoinNetwork) => Promise<WalletAccount>;
+    /** Disconnect from current wallet */
+    disconnect: () => Promise<void>;
+    /** Reconnect to previously connected wallet */
+    reconnect: (connectors: BitcoinConnector[]) => Promise<void>;
+    /** Set account */
+    setAccount: (account: WalletAccount | null) => void;
+    /** Set connection status */
+    setStatus: (status: ConnectionStatus) => void;
+    /** Set error */
+    setError: (error: Error | null) => void;
+    /** Reset store to initial state */
+    reset: () => void;
+};
+type Store = BtcWalletState & StoreActions;
+/** Persisted state shape - only these fields are saved to storage */
+type PersistedState = {
+    connectorId: string | null;
+    network: string;
+};
+/**
+ * Create the btc-wallet store
+ */
+declare function createStore(config: Config): Omit<Omit<zustand_vanilla.StoreApi<Store>, "subscribe"> & {
+    subscribe: {
+        (listener: (selectedState: Store, previousSelectedState: Store) => void): () => void;
+        <U>(selector: (state: Store) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
+            equalityFn?: (a: U, b: U) => boolean;
+            fireImmediately?: boolean;
+        } | undefined): () => void;
+    };
+}, "persist"> & {
+    persist: {
+        setOptions: (options: Partial<PersistOptions<Store, PersistedState>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => void | Promise<void>;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: Store) => void) => () => void;
+        onFinishHydration: (fn: (state: Store) => void) => () => void;
+        getOptions: () => Partial<PersistOptions<Store, PersistedState>>;
+    };
+};
+type BtcWalletStore = ReturnType<typeof createStore>;
+
+/**
+ * Resolved config with store instance
+ */
+type ResolvedConfig = Config & {
+    store: BtcWalletStore;
+};
+/**
+ * Create otx-btc-wallet configuration
+ *
+ * @example
+ * ```ts
+ * import { createConfig } from 'otx-btc-wallet-core';
+ * import { UnisatConnector } from 'otx-btc-wallet-connectors/unisat';
+ *
+ * const config = createConfig({
+ *   connectors: [new UnisatConnector()],
+ *   autoConnect: true,
+ * });
+ * ```
+ */
+declare function createConfig(options: BtcWalletConfig): ResolvedConfig;
+
+/**
+ * PSBT (Partially Signed Bitcoin Transaction) utilities
+ */
+/**
+ * Convert PSBT hex to base64
+ */
+declare function psbtHexToBase64(hex: string): string;
+/**
+ * Convert PSBT base64 to hex
+ */
+declare function psbtBase64ToHex(base64: string): string;
+/**
+ * Validate PSBT hex format
+ * PSBT magic bytes: 0x70736274ff (psbt\xff)
+ */
+declare function isValidPsbtHex(hex: string): boolean;
+/**
+ * Validate PSBT base64 format
+ */
+declare function isValidPsbtBase64(base64: string): boolean;
+/**
+ * Extract basic info from PSBT hex (without full parsing)
+ * This is a lightweight check - for full parsing use a library like bitcoinjs-lib
+ */
+declare function getPsbtInfo(psbtHex: string): {
+    isValid: boolean;
+    version: number | null;
+    inputCount: number | null;
+    outputCount: number | null;
+};
+/**
+ * Combine multiple signed PSBTs into one
+ * Note: This is a basic implementation. For complex cases, use bitcoinjs-lib.
+ *
+ * @param psbts - Array of PSBT hex strings to combine
+ * @returns Combined PSBT hex
+ */
+declare function combinePsbts(psbts: string[]): string;
+/**
+ * Sighash types for Bitcoin transactions
+ */
+declare const SighashType: {
+    readonly ALL: 1;
+    readonly NONE: 2;
+    readonly SINGLE: 3;
+    readonly ANYONECANPAY: 128;
+    readonly ALL_ANYONECANPAY: 129;
+    readonly NONE_ANYONECANPAY: 130;
+    readonly SINGLE_ANYONECANPAY: 131;
+};
+type SighashType = (typeof SighashType)[keyof typeof SighashType];
+/**
+ * Get human-readable name for sighash type
+ */
+declare function getSighashTypeName(sighash: number): string;
+
+export { type AddressType, type BitcoinConnector, type BitcoinNetwork, type BtcWalletConfig, type BtcWalletState, type BtcWalletStore, type Config, type ConnectionStatus, type MultiAddressAccount, type ResolvedConfig, SighashType, type SignInput, type SignPsbtOptions, type Store, type StoreActions, type WalletAccount, combinePsbts, createConfig, createStore, getPsbtInfo, getSighashTypeName, isValidPsbtBase64, isValidPsbtHex, psbtBase64ToHex, psbtHexToBase64 };