otx-btc-wallet-core 0.1.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -0,0 +1,342 @@
+'use strict';
+
+var vanilla = require('zustand/vanilla');
+var middleware = require('zustand/middleware');
+
+// src/store/index.ts
+var initialState = {
+  status: "disconnected",
+  account: null,
+  connector: null,
+  connectorId: null,
+  network: "mainnet",
+  error: null
+};
+function createStore(config) {
+  let unsubscribeAccounts = null;
+  let unsubscribeNetwork = null;
+  const cleanupListeners = () => {
+    if (unsubscribeAccounts) {
+      unsubscribeAccounts();
+      unsubscribeAccounts = null;
+    }
+    if (unsubscribeNetwork) {
+      unsubscribeNetwork();
+      unsubscribeNetwork = null;
+    }
+  };
+  const setupConnectorListeners = (connector, get, set) => {
+    cleanupListeners();
+    unsubscribeAccounts = connector.onAccountsChanged((accounts) => {
+      const currentState = get();
+      if (currentState.connector?.id !== connector.id) {
+        return;
+      }
+      if (accounts.length === 0) {
+        get().disconnect().catch(() => {
+          set({
+            status: "disconnected",
+            account: null,
+            connector: null,
+            connectorId: null,
+            error: null
+          });
+        });
+      } else if (accounts[0]) {
+        set({ account: accounts[0] });
+      }
+    });
+    unsubscribeNetwork = connector.onNetworkChanged((network) => {
+      const currentState = get();
+      if (currentState.connector?.id !== connector.id) {
+        return;
+      }
+      set({ network });
+    });
+  };
+  const persistOptions = {
+    name: config.storageKey,
+    storage: config.storage ? {
+      getItem: (name) => {
+        const value = config.storage?.getItem(name);
+        if (!value)
+          return null;
+        try {
+          return JSON.parse(value);
+        } catch {
+          return null;
+        }
+      },
+      setItem: (name, value) => {
+        config.storage?.setItem(name, JSON.stringify(value));
+      },
+      removeItem: (name) => {
+        config.storage?.removeItem(name);
+      }
+    } : void 0,
+    // Only persist connectorId and network
+    partialize: (state) => ({
+      connectorId: state.connectorId,
+      network: state.network
+    })
+  };
+  const store = vanilla.createStore()(
+    middleware.subscribeWithSelector(
+      middleware.persist(
+        (set, get) => ({
+          // Initial state
+          ...initialState,
+          // Actions
+          connect: async (connector, networkParam) => {
+            const { status, network: storeNetwork } = get();
+            const network = networkParam ?? storeNetwork;
+            if (status === "connecting") {
+              throw new Error("Connection already in progress");
+            }
+            cleanupListeners();
+            set({ status: "connecting", error: null, network });
+            try {
+              if (!connector.ready) {
+                throw new Error(`${connector.name} wallet is not available`);
+              }
+              const account = await connector.connect(network);
+              set({
+                status: "connected",
+                account,
+                connector,
+                connectorId: connector.id,
+                error: null
+              });
+              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();
+            cleanupListeners();
+            try {
+              if (connector) {
+                await connector.disconnect();
+              }
+            } catch {
+            } finally {
+              set({
+                status: "disconnected",
+                account: null,
+                connector: null,
+                connectorId: null,
+                error: null
+              });
+            }
+          },
+          reconnect: async (connectors) => {
+            const { connectorId, status, network } = get();
+            if (!connectorId || status === "connected") {
+              return;
+            }
+            const connector = connectors.find((c) => c.id === connectorId);
+            if (!connector?.ready) {
+              set({ connectorId: null });
+              return;
+            }
+            set({ status: "reconnecting" });
+            try {
+              const account = await connector.connect(network);
+              set({
+                status: "connected",
+                account,
+                connector,
+                error: null
+              });
+              setupConnectorListeners(connector, get, set);
+            } catch {
+              set({
+                status: "disconnected",
+                connectorId: null
+              });
+            }
+          },
+          setAccount: (account) => set({ account }),
+          setStatus: (status) => set({ status }),
+          setError: (error) => set({ error }),
+          reset: () => {
+            cleanupListeners();
+            set(initialState);
+          }
+        }),
+        persistOptions
+      )
+    )
+  );
+  return store;
+}
+
+// src/createConfig.ts
+function createConfig(options) {
+  if (!options.connectors || options.connectors.length === 0) {
+    throw new Error("At least one connector is required");
+  }
+  const connectorIds = /* @__PURE__ */ new Set();
+  for (const connector of options.connectors) {
+    if (connectorIds.has(connector.id)) {
+      throw new Error(`Duplicate connector ID: ${connector.id}`);
+    }
+    connectorIds.add(connector.id);
+  }
+  const config = {
+    connectors: options.connectors,
+    autoConnect: options.autoConnect ?? true,
+    storage: getStorage(options.storage),
+    storageKey: options.storageKey ?? "optimex-btc-wallet.store"
+  };
+  const store = createStore(config);
+  if (config.autoConnect) {
+    setTimeout(() => {
+      void store.getState().reconnect(config.connectors);
+    }, 0);
+  }
+  return {
+    ...config,
+    store
+  };
+}
+function getStorage(storage) {
+  if (storage !== void 0) {
+    return storage;
+  }
+  if (typeof window !== "undefined" && window.localStorage) {
+    return window.localStorage;
+  }
+  return null;
+}
+
+// src/utils/psbt.ts
+function psbtHexToBase64(hex) {
+  const cleanHex = hex.replace(/\s/g, "");
+  if (!/^[0-9a-fA-F]*$/.test(cleanHex)) {
+    throw new Error("Invalid hex string");
+  }
+  if (cleanHex.length % 2 !== 0) {
+    throw new Error("Hex string must have even length");
+  }
+  const bytes = new Uint8Array(cleanHex.length / 2);
+  for (let i = 0; i < cleanHex.length; i += 2) {
+    bytes[i / 2] = parseInt(cleanHex.substring(i, i + 2), 16);
+  }
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64");
+  }
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function psbtBase64ToHex(base64) {
+  let bytes;
+  if (typeof Buffer !== "undefined") {
+    bytes = Buffer.from(base64, "base64");
+  } else {
+    const binary = atob(base64);
+    bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+  }
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function isValidPsbtHex(hex) {
+  const cleanHex = hex.replace(/\s/g, "").toLowerCase();
+  if (cleanHex.length < 10) {
+    return false;
+  }
+  return cleanHex.startsWith("70736274ff");
+}
+function isValidPsbtBase64(base64) {
+  try {
+    const hex = psbtBase64ToHex(base64);
+    return isValidPsbtHex(hex);
+  } catch {
+    return false;
+  }
+}
+function getPsbtInfo(psbtHex) {
+  if (!isValidPsbtHex(psbtHex)) {
+    return {
+      isValid: false,
+      version: null,
+      inputCount: null,
+      outputCount: null
+    };
+  }
+  return {
+    isValid: true,
+    version: null,
+    // Would need full parsing
+    inputCount: null,
+    // Would need full parsing
+    outputCount: null
+    // Would need full parsing
+  };
+}
+function combinePsbts(psbts) {
+  if (psbts.length === 0) {
+    throw new Error("No PSBTs provided");
+  }
+  if (psbts.length === 1) {
+    return psbts[0];
+  }
+  console.warn(
+    "combinePsbts: For proper PSBT combination, use bitcoinjs-lib. This function returns the first PSBT as a fallback."
+  );
+  return psbts[0];
+}
+var SighashType = {
+  ALL: 1,
+  NONE: 2,
+  SINGLE: 3,
+  ANYONECANPAY: 128,
+  ALL_ANYONECANPAY: 129,
+  NONE_ANYONECANPAY: 130,
+  SINGLE_ANYONECANPAY: 131
+};
+function getSighashTypeName(sighash) {
+  switch (sighash) {
+    case SighashType.ALL:
+      return "SIGHASH_ALL";
+    case SighashType.NONE:
+      return "SIGHASH_NONE";
+    case SighashType.SINGLE:
+      return "SIGHASH_SINGLE";
+    case SighashType.ANYONECANPAY:
+      return "SIGHASH_ANYONECANPAY";
+    case SighashType.ALL_ANYONECANPAY:
+      return "SIGHASH_ALL|ANYONECANPAY";
+    case SighashType.NONE_ANYONECANPAY:
+      return "SIGHASH_NONE|ANYONECANPAY";
+    case SighashType.SINGLE_ANYONECANPAY:
+      return "SIGHASH_SINGLE|ANYONECANPAY";
+    default:
+      return `UNKNOWN(${sighash})`;
+  }
+}
+
+exports.SighashType = SighashType;
+exports.combinePsbts = combinePsbts;
+exports.createConfig = createConfig;
+exports.createStore = createStore;
+exports.getPsbtInfo = getPsbtInfo;
+exports.getSighashTypeName = getSighashTypeName;
+exports.isValidPsbtBase64 = isValidPsbtBase64;
+exports.isValidPsbtHex = isValidPsbtHex;
+exports.psbtBase64ToHex = psbtBase64ToHex;
+exports.psbtHexToBase64 = psbtHexToBase64;
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.js.map