Wallet Domain

Higher-layer packages for key management, balance tracking, transaction signing, token operations, and mobile wallet pairing. These packages provide persistent state, BRC-100 wallet implementation, and framework-agnostic permission systems.

The wallet domain builds on top of @bsv/sdk. If you only need transaction building without persistent state or key management, use the SDK directly. If you need full wallet functionality with storage, key derivation, background monitoring, or token support, use packages from this domain.

Packages in this Domain

Package	Purpose
@bsv/wallet-toolbox	Node BRC-100 wallet implementation with SQLite/MySQL storage, background monitoring, Shamir key sharing, and permission management
@bsv/wallet-toolbox-client	Browser-safe wallet, IndexedDB, and remote storage distribution
@bsv/wallet-toolbox-mobile	React Native/mobile-safe wallet and remote storage distribution
@bsv/btms	UTXO-based token issuance, transfer, burning, and ownership proof validation
@bsv/btms-permission-module	Framework-agnostic BRC-98/99 permission hooks for BTMS token spending with custom UI callback
@bsv/wallet-relay	Mobile-to-desktop wallet pairing via QR codes and encrypted WebSocket relay with React components

Common Use Cases

I'm building an app and need user signatures

Use @bsv/wallet-toolbox to create a full wallet with persistent storage and signing, or integrate with user-installed wallets via the BRC-100 interface.

I'm building a web app that integrates with user wallets

Use @bsv/wallet-toolbox for local wallet, or @bsv/wallet-relay for mobile wallet pairing via QR code.

I need to issue and manage tokens

Use @bsv/btms for token operations (issue, send, accept, burn). Integrate with @bsv/wallet-toolbox for wallet signing and @bsv/btms-permission-module for permission control.

I'm building a wallet application myself

Use @bsv/wallet-toolbox as reference implementation. It demonstrates BRC-100 compliance, storage abstraction, key management, and background monitoring patterns.

I need mobile-to-desktop signing without downloading wallet software

Use @bsv/wallet-relay for QR pairing. Desktop shows QR, mobile scans, then mobile wallet signs and relays responses back encrypted.

I want fine-grained permission control over token operations

Use @bsv/btms-permission-module with your custom permission handler (modal, alert, web component, etc.).

Key Concepts

• BRC-100 Wallet Interface — Standard interface implemented by all wallet packages. Apps can work with any wallet (desktop, mobile, hardware) without code changes.
• Action — High-level transaction intent. App specifies outputs; wallet picks inputs internally for privacy and flexibility.
• SignableTransaction — Opaque reference to a created action. App requests wallet to sign this reference; wallet handles ECDSA signing.
• Storage Backend — Pluggable abstraction layer. Same wallet code works with SQLite (Node.js), IndexedDB (browser), or remote HTTPS server.
• Key Derivation — BRC-42/43 hierarchical key generation. Each protocol can request keys from wallet without exposing root key.
• Monitor — Background daemon that polls blockchain for transaction confirmations, acquires merkle proofs, and rebroadcasts stalled transactions.
• BTMS Token — UTXO-based token identified by canonical asset ID ({txid}.{vout}). Each token is a separate on-chain output with metadata.
• Ownership Proof — Cryptographic proof of token ownership without revealing private key. Used for collateral, escrow, access control.
• Relay Session — Encrypted tunnel between desktop and mobile wallet. QR encodes relay URL + session ID; mobile scans and establishes WebSocket connection.
• Permission Module — BRC-98/99 hooks that intercept special operations (token spend, burn) and prompt user via custom callback.

Architecture Overview

Storage & Platform Support

Package	Node.js	Browser	Mobile
wallet-toolbox	SQLite, MySQL	—	—
wallet-toolbox-client	Build tooling	IndexedDB, Remote	Hybrid/WebView dependent
wallet-toolbox-mobile	Build tooling	—	Remote
btms	✓	✓	✓
btms-permission-module	✓	✓	✓
wallet-relay	Server	React components	Supported via relay

When to Use Each Package

Wallet Toolbox

• You're building a wallet application
• You need persistent transaction history and UTXO state
• You want BRC-100 compliance
• You need key derivation for multiple protocols
• You want background transaction monitoring
• You need different storage for different platforms

BTMS

• You're building token issuance/transfer system
• You need UTXO-based tokens with on-chain metadata
• You want automated PushDrop encoding/decoding
• You need ownership proofs for collateral/escrow

BTMS Permission Module

• You want user approval for token operations
• You need framework-agnostic permission callbacks
• You're building a wallet with permission control
• You want custom UI for permission prompts

Wallet Relay

• You're building a web app needing mobile signatures
• You want QR-based pairing (no software download)
• You need encrypted communication over untrusted networks
• You want stateless session management

NOT for these

• Don't use wallet packages if you only need transaction building — use @bsv/sdk directly
• Don't use wallet-toolbox if you only need BRC-100 interface types — import from SDK instead

Next Steps

• @bsv/wallet-toolbox — Full wallet implementation
• @bsv/wallet-toolbox-client — Browser distribution
• @bsv/wallet-toolbox-mobile — Mobile distribution
• @bsv/btms — Token protocol
• @bsv/wallet-relay — Mobile pairing
• @bsv/btms-permission-module — Token permissions
• SDK Domain — Cryptography and transactions