otx-btc-wallet-core 0.1.0

package/src/store/index.ts

@@ -0,0 +1,296 @@
+import { createStore as createZustandStore } from 'zustand/vanilla';
+import { persist, subscribeWithSelector } from 'zustand/middleware';
+import type { PersistOptions } from 'zustand/middleware';
+import type { BitcoinConnector } from '../types/connector';
+import type { WalletAccount } from '../types/account';
+import type { BtcWalletState, ConnectionStatus } from '../types/state';
+import type { BitcoinNetwork } from '../types/network';
+import type { Config } from '../types/config';
+
+/**
+ * Store actions
+ */
+export 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;
+};
+
+export type Store = BtcWalletState & StoreActions;
+
+/** Persisted state shape - only these fields are saved to storage */
+type PersistedState = {
+  connectorId: string | null;
+  network: string;
+};
+
+const initialState: BtcWalletState = {
+  status: 'disconnected',
+  account: null,
+  connector: null,
+  connectorId: null,
+  network: 'mainnet',
+  error: null,
+};
+
+/**
+ * Create the btc-wallet store
+ */
+export function createStore(config: Config) {
+  // Track cleanup functions for event listeners to prevent memory leaks
+  let unsubscribeAccounts: (() => void) | null = null;
+  let unsubscribeNetwork: (() => void) | null = null;
+
+  /**
+   * Cleanup all event listeners
+   */
+  const cleanupListeners = () => {
+    if (unsubscribeAccounts) {
+      unsubscribeAccounts();
+      unsubscribeAccounts = null;
+    }
+    if (unsubscribeNetwork) {
+      unsubscribeNetwork();
+      unsubscribeNetwork = null;
+    }
+  };
+
+  /**
+   * Setup event listeners for a connector
+   * This is shared between connect and reconnect to avoid code duplication
+   */
+  const setupConnectorListeners = (
+    connector: BitcoinConnector,
+    get: () => Store,
+    set: (partial: Partial<Store>) => void
+  ) => {
+    // Clean up any existing listeners first
+    cleanupListeners();
+
+    // Subscribe to account changes
+    unsubscribeAccounts = connector.onAccountsChanged((accounts) => {
+      const currentState = get();
+
+      // Only handle if this connector is still the active one
+      if (currentState.connector?.id !== connector.id) {
+        return;
+      }
+
+      if (accounts.length === 0) {
+        // Wallet disconnected from extension side
+        // Use catch to handle any errors silently
+        get().disconnect().catch(() => {
+          // Disconnect failed, but we should still clean up state
+          set({
+            status: 'disconnected',
+            account: null,
+            connector: null,
+            connectorId: null,
+            error: null,
+          });
+        });
+      } else if (accounts[0]) {
+        set({ account: accounts[0] });
+      }
+    });
+
+    // Subscribe to network changes
+    unsubscribeNetwork = connector.onNetworkChanged((network) => {
+      const currentState = get();
+
+      // Only handle if this connector is still the active one
+      if (currentState.connector?.id !== connector.id) {
+        return;
+      }
+
+      set({ network });
+    });
+  };
+
+  // Define persist options with proper typing
+  const persistOptions: PersistOptions<Store, PersistedState> = {
+    name: config.storageKey,
+    storage: config.storage
+      ? {
+          getItem: (name) => {
+            const value = config.storage?.getItem(name);
+            if (!value) return null;
+            try {
+              return JSON.parse(value) as { state: PersistedState };
+            } catch {
+              return null;
+            }
+          },
+          setItem: (name, value) => {
+            config.storage?.setItem(name, JSON.stringify(value));
+          },
+          removeItem: (name) => {
+            config.storage?.removeItem(name);
+          },
+        }
+      : undefined,
+    // Only persist connectorId and network
+    partialize: (state): PersistedState => ({
+      connectorId: state.connectorId,
+      network: state.network,
+    }),
+  };
+
+  const store = createZustandStore<Store>()(
+    subscribeWithSelector(
+      persist(
+        (set, get) => ({
+          // Initial state
+          ...initialState,
+
+          // Actions
+          connect: async (
+            connector: BitcoinConnector,
+            networkParam?: BitcoinNetwork
+          ) => {
+            const { status, network: storeNetwork } = get();
+            const network = networkParam ?? storeNetwork;
+
+            // Prevent duplicate connection attempts
+            if (status === 'connecting') {
+              throw new Error('Connection already in progress');
+            }
+
+            // Clean up any existing connection first
+            cleanupListeners();
+
+            set({ status: 'connecting', error: null, network });
+
+            try {
+              // Check if wallet is ready
+              if (!connector.ready) {
+                throw new Error(`${connector.name} wallet is not available`);
+              }
+
+              // Connect to wallet with network
+              const account = await connector.connect(network);
+
+              set({
+                status: 'connected',
+                account,
+                connector,
+                connectorId: connector.id,
+                error: null,
+              });
+
+              // Setup event listeners
+              setupConnectorListeners(connector, get, set);
+
+              return account;
+            } catch (error) {
+              const err = error instanceof Error ? error : new Error(String(error));
+              set({
+                status: 'disconnected',
+                error: err,
+              });
+              throw error;
+            }
+          },
+
+          disconnect: async () => {
+            const { connector } = get();
+
+            // Clean up listeners first
+            cleanupListeners();
+
+            try {
+              if (connector) {
+                await connector.disconnect();
+              }
+            } catch {
+              // Ignore disconnect errors (wallet might already be locked)
+            } finally {
+              set({
+                status: 'disconnected',
+                account: null,
+                connector: null,
+                connectorId: null,
+                error: null,
+              });
+            }
+          },
+
+          reconnect: async (connectors: BitcoinConnector[]) => {
+            const { connectorId, status, network } = get();
+
+            // Only reconnect if we have a saved connector and not already connected
+            if (!connectorId || status === 'connected') {
+              return;
+            }
+
+            // Find the connector
+            const connector = connectors.find((c) => c.id === connectorId);
+            if (!connector?.ready) {
+              // Clear saved connector if not available
+              set({ connectorId: null });
+              return;
+            }
+
+            set({ status: 'reconnecting' });
+
+            try {
+              const account = await connector.connect(network);
+
+              set({
+                status: 'connected',
+                account,
+                connector,
+                error: null,
+              });
+
+              // Setup event listeners (reusing shared function)
+              setupConnectorListeners(connector, get, set);
+            } catch {
+              // Reconnect failed silently, clear state
+              set({
+                status: 'disconnected',
+                connectorId: null,
+              });
+            }
+          },
+
+          setAccount: (account) => set({ account }),
+
+          setStatus: (status) => set({ status }),
+
+          setError: (error) => set({ error }),
+
+          reset: () => {
+            cleanupListeners();
+            set(initialState);
+          },
+        }),
+        persistOptions
+      )
+    )
+  );
+
+  return store;
+}
+
+export type BtcWalletStore = ReturnType<typeof createStore>;

package/src/types/account.ts

@@ -0,0 +1,26 @@
+/**
+ * Bitcoin address types supported by wallets
+ */
+export type AddressType = 'legacy' | 'nested-segwit' | 'segwit' | 'taproot';
+
+/**
+ * Wallet account information returned from connection
+ */
+export 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
+ */
+export type MultiAddressAccount = {
+  /** Payment address for BTC transfers (typically segwit) */
+  payment: WalletAccount;
+  /** Ordinals address for Ordinals/Runes (typically taproot) */
+  ordinals: WalletAccount;
+};

package/src/types/config.ts

@@ -0,0 +1,28 @@
+import type { BitcoinConnector } from './connector';
+
+/**
+ * Configuration for otx-btc-wallet
+ */
+export 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
+ */
+export type Config = {
+  connectors: BitcoinConnector[];
+  autoConnect: boolean;
+  storage: Storage | null;
+  storageKey: string;
+};

package/src/types/connector.ts

@@ -0,0 +1,109 @@
+import type { WalletAccount } from './account';
+import type { BitcoinNetwork } from './network';
+import type { SignPsbtOptions } from './psbt';
+
+/**
+ * Interface that all wallet connectors must implement
+ */
+export type NetworkType = 'mainnet' | 'testnet' | 'testnet4' | 'signet';
+
+export 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;
+}

package/src/types/index.ts

@@ -0,0 +1,12 @@
+// otx-btc-wallet-core types
+
+export type { BitcoinConnector, NetworkType } from './connector';
+export type {
+  WalletAccount,
+  AddressType,
+  MultiAddressAccount,
+} from './account';
+export type { BitcoinNetwork } from './network';
+export type { SignPsbtOptions, SignInput } from './psbt';
+export type { BtcWalletConfig, Config } from './config';
+export type { BtcWalletState, ConnectionStatus } from './state';

package/src/types/network.ts

@@ -0,0 +1,4 @@
+/**
+ * Supported Bitcoin networks
+ */
+export type BitcoinNetwork = 'mainnet' | 'testnet' | 'testnet4' | 'signet';

package/src/types/psbt.ts

@@ -0,0 +1,27 @@
+/**
+ * Options for signing a PSBT
+ */
+export 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
+ */
+export 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;
+};

package/src/types/state.ts

@@ -0,0 +1,35 @@
+import type { BitcoinConnector } from './connector';
+import type { WalletAccount } from './account';
+import type { BitcoinNetwork } from './network';
+
+/**
+ * Connection status states
+ */
+export type ConnectionStatus =
+  | 'disconnected'
+  | 'connecting'
+  | 'connected'
+  | 'reconnecting';
+
+/**
+ * Store state shape
+ */
+export 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;
+};

package/src/utils/index.ts

@@ -0,0 +1 @@
+export * from './psbt';