Core state management and types for otx-btc-wallet
npm install otx-btc-wallet-coreCore state management, types, and configuration for the otx-btc-wallet library. This package provides the foundation that connectors and React hooks build on.
``bash`
pnpm add otx-btc-wallet-core
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
`typescript
import { createConfig } from 'otx-btc-wallet-core';
import { UnisatConnector, XverseConnector } from 'otx-btc-wallet-connectors';
const config = createConfig({
connectors: [
new UnisatConnector(),
new XverseConnector(),
],
});
`
| 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
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();
`
`typescript`
type BitcoinNetwork = 'mainnet' | 'testnet' | 'testnet4' | 'signet';
`typescript`
type AddressType = 'legacy' | 'nested-segwit' | 'segwit' | 'taproot';
`typescript`
type WalletAccount = {
address: string;
publicKey: string;
type: AddressType;
};
Used by wallets like Xverse that provide separate payment and ordinals addresses.
`typescript`
type MultiAddressAccount = {
payment: WalletAccount;
ordinals: WalletAccount;
};
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;
}
`
`typescript`
type SignPsbtOptions = {
autoFinalize?: boolean; // Auto-finalize inputs after signing
broadcast?: boolean; // Broadcast the transaction after signing
toSignInputs?: SignInput[]; // Specify which inputs to sign
};
`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)
};
`typescript`
type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
The full store state shape.
`typescript`
type BtcWalletState = {
status: ConnectionStatus;
account: WalletAccount | null;
connector: BitcoinConnector | null;
connectorId: string | null;
network: BitcoinNetwork;
error: Error | null;
};
`typescript`
type BtcWalletConfig = {
connectors: BitcoinConnector[];
autoConnect?: boolean;
storage?: Storage;
storageKey?: string;
};
The store is built on Zustand with persist and subscribeWithSelector middleware.
| 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 |
| 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 |
Only connectorId and network are persisted to storage. Account data is fetched fresh from the connector on 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.
Lightweight PSBT helpers that work in both Node.js and browser environments.
`typescript
import { psbtHexToBase64, psbtBase64ToHex } from 'otx-btc-wallet-core';
const base64 = psbtHexToBase64(psbtHex);
const hex = psbtBase64ToHex(psbtBase64);
`
`typescript
import { isValidPsbtHex, isValidPsbtBase64 } from 'otx-btc-wallet-core';
isValidPsbtHex('70736274ff01...'); // true
isValidPsbtBase64('cHNidP8B...'); // true
`
`typescript
import { getPsbtInfo } from 'otx-btc-wallet-core';
const info = getPsbtInfo(psbtHex);
// { isValid: boolean, version: number | null, inputCount: number | null, outputCount: number | null }
`
`typescript
import { combinePsbts } from 'otx-btc-wallet-core';
const combined = combinePsbts([psbt1Hex, psbt2Hex]);
`
`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'
`
`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';
``
MIT