Skip to content

index.md

Latest commit

 

History

History
157 lines (114 loc) · 9.74 KB

index.md

File metadata and controls

157 lines (114 loc) · 9.74 KB
Raw
id wallet-domain
title Wallet
kind meta
domain wallet
version n/a
last_updated 2026-09-24
last_verified 2026-09-24
review_cadence_days 30
status stable
tags
domain
wallet

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/ecpm-permission-module BRC-98 semantic module for applying and removing wallet-derived scalars from secp256k1 points
@bsv/color-permission-module BRC-207 module for holding, sending and receiving BRC-162 fungible tokens
@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.).

I need wallet-native point multiplication

Use @bsv/ecpm-permission-module to install the p ecpm scheme. It reuses getPublicKey, so applications can apply or remove a BRC-42/43-derived scalar from a named point without extending the BRC-100 wallet interface or exposing the scalar.

I need BRC-162 tokens in a wallet

Use @bsv/color-permission-module to install the BRC-207 color scheme. Applications send, receive and list tokens through the ordinary BRC-100 calls; the module selects, signs and verifies token outputs against the asset overlays.

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.
  • Semantic Permission Module — A BRC-98 module that owns a P-scheme's meaning and returns a conforming result without requiring the underlying BRC-100 method to retain its ordinary behavior.

Architecture Overview

Wallet domain architecture: btms, btms-permission-module and wallet-relay sit on top of wallet-toolbox, which itself contains storage, services, key management, and permissions modules — all building on @bsv/sdk for cryptography and transactions

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 ✓ ✓ ✓
ecpm-permission-module ✓ ✓ Host-dependent
color-permission-module ✓ ✓ Host-dependent
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

Backup and recovery

Wallet recovery needs both key material and records/derivation metadata. Browser storage, remote replication and key-manager snapshots each cover only part of that requirement. Use the recovery guide, BRC-38/39 API guide and recovery drill before shipping a wallet.

Next Steps