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

$3

`typescript
import { createConfig } from 'otx-btc-wallet-core';
import { UnisatConnector, XverseConnector } from 'otx-btc-wallet-connectors';

const config = createConfig({
connectors: [
new UnisatConnector(),
new XverseConnector(),
],
});
`

$3

| 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

$3

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

$3

`typescript
type BitcoinNetwork = 'mainnet' | 'testnet' | 'testnet4' | 'signet';
`

$3

`typescript
type AddressType = 'legacy' | 'nested-segwit' | 'segwit' | 'taproot';
`

$3

`typescript
type WalletAccount = {
address: string;
publicKey: string;
type: AddressType;
};
`

$3

Used by wallets like Xverse that provide separate payment and ordinals addresses.

`typescript
type MultiAddressAccount = {
payment: WalletAccount;
ordinals: WalletAccount;
};
`

$3

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;
disconnect(): Promise;
getAccounts(): Promise;
signMessage(message: string): Promise;
signPsbt(psbtHex: string, options?: SignPsbtOptions): Promise;
signPsbts?(psbtHexs: string[], options?: SignPsbtOptions): Promise;
sendTransaction(to: string, satoshis: number): Promise;
getNetwork(): Promise;
switchNetwork?(network: BitcoinNetwork): Promise;
onAccountsChanged(callback: (accounts: WalletAccount[]) => void): () => void;
onNetworkChanged(callback: (network: BitcoinNetwork) => void): () => void;
}
`

$3

`typescript
type SignPsbtOptions = {
autoFinalize?: boolean; // Auto-finalize inputs after signing
broadcast?: boolean; // Broadcast the transaction after signing
toSignInputs?: SignInput[]; // Specify which inputs to sign
};
`

$3

`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)
};
`

$3

`typescript
type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
`

$3

The full store state shape.

`typescript
type BtcWalletState = {
status: ConnectionStatus;
account: WalletAccount | null;
connector: BitcoinConnector | null;
connectorId: string | null;
network: BitcoinNetwork;
error: Error | null;
};
`

$3

`typescript
type BtcWalletConfig = {
connectors: BitcoinConnector[];
autoConnect?: boolean;
storage?: Storage;
storageKey?: string;
};
`

Store

The store is built on Zustand with persist and subscribeWithSelector middleware.

$3

| 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 |

$3

| Action | Signature | Description |
|--------|-----------|-------------|
| connect | (connector, network?) => Promise | Connect to a wallet |
| disconnect | () => Promise | Disconnect current wallet |
| reconnect | (connectors) => Promise | 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 |

$3

Only connectorId and network are persisted to storage. Account data is fetched fresh from the connector on reconnect.

$3

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.

$3

`typescript
import { psbtHexToBase64, psbtBase64ToHex } from 'otx-btc-wallet-core';

const base64 = psbtHexToBase64(psbtHex);
const hex = psbtBase64ToHex(psbtBase64);
`

$3

`typescript
import { isValidPsbtHex, isValidPsbtBase64 } from 'otx-btc-wallet-core';

isValidPsbtHex('70736274ff01...'); // true
isValidPsbtBase64('cHNidP8B...'); // true
`

$3

`typescript
import { getPsbtInfo } from 'otx-btc-wallet-core';

const info = getPsbtInfo(psbtHex);
// { isValid: boolean, version: number | null, inputCount: number | null, outputCount: number | null }
`

$3

`typescript
import { combinePsbts } from 'otx-btc-wallet-core';

const combined = combinePsbts([psbt1Hex, psbt2Hex]);
`

$3

`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