BSV Wallet Toolbox

A BRC-100 conforming wallet implementation for the BSV blockchain, built on the BSV SDK. Provides persistent storage, protocol-based key derivation, transaction monitoring, chain tracking, and signing — everything needed to build wallet-powered applications on BSV.

Overview

The Wallet Toolbox is the reference implementation of the BRC-100 wallet interface. It connects the BSV SDK's cryptographic primitives to real storage backends, network services, and signing flows so that application developers don't have to wire these layers together themselves.

What's Inside

| Module | Description | |--------|-------------| | Wallet | Full BRC-100 wallet — action creation, signing, certificate management, identity discovery, output tracking | | Storage | Pluggable persistence with three backends: SQLite/MySQL (via Knex), IndexedDB (browser/mobile), and remote (client/server over HTTP) | | Services | Network layer — ARC transaction broadcasting, chain tracking (Chaintracks), merkle proof verification, UTXO lookups via WhatsOnChain | | Monitor | Background daemon that watches pending transactions, rebroadcasts failures, handles chain reorganizations, and manages proof acquisition | | Signer | WalletSigner bridges any BRC-100 wallet to the SDK's Transaction signing interface | | Key Management | PrivilegedKeyManager for secure key storage with Shamir secret sharing and obfuscation; protocol-based key derivation per BRC-42/43 | | Permissions | WalletPermissionsManager for fine-grained per-app, per-protocol permission control with grouped approval flows | | MockChain | In-memory blockchain for testing — mock mining, UTXO tracking, and merkle proof generation without a network | | Entropy | EntropyCollector gathers mouse/touch entropy for high-quality randomness in browser environments |

Packages

The toolbox publishes three npm packages from this repo:

• @bsv/wallet-toolbox — Full package with all storage backends (SQLite, MySQL, IndexedDB, remote)
• @bsv/wallet-toolbox-client — Browser build; excludes Node-only backends (Knex/SQLite/MySQL)
• @bsv/wallet-toolbox-mobile — Mobile build; IndexedDB and remote storage only

Getting Started

Installation

# Full (Node.js servers, CLIs)
npm install @bsv/wallet-toolbox

# Browser apps
npm install @bsv/wallet-toolbox-client

# React Native / mobile
npm install @bsv/wallet-toolbox-mobile

Quick Example

import { SetupWallet } from '@bsv/wallet-toolbox'

// Create a wallet with SQLite storage and default mainnet services
const wallet = await SetupWallet({
  env: 'main',
  endpointUrl: 'https://your-storage-server.example.com'
})

// Create a transaction
const result = await wallet.createAction({
  description: 'Send payment',
  outputs: [{
    lockingScript: '76a914...88ac',
    satoshis: 1000,
    outputDescription: 'payment'
  }]
})

Documentation

Full API documentation is available on GitHub Pages.

The codebase has detailed JSDoc annotations throughout — these will surface inline in editors like VS Code.

Development

git clone https://github.com/bsv-blockchain/wallet-toolbox.git
cd wallet-toolbox
npm install
npm run build
npm test

Tests use Jest. Files named *.man.test.ts are manual/integration tests excluded from CI — they require network access or long runtimes and are run locally by developers.

Contributing

We welcome bug reports, feature requests, and pull requests.

1. Fork and clone the repository
2. npm install
3. Create a feature branch
4. Make your changes and ensure npm test passes
5. Open a pull request

See CONTRIBUTING.md for full guidelines.

Contributors

| | Name | GitHub | Role | |---|------|--------|------| | | Tone Engel | @tonesnotes | Lead developer, maintainer | | | Darren Kellenschwiler | @sirdeggen | Core contributor | | | Brayden Langley | @BraydenLangley | Core contributor | | | Ty Everett | @ty-everett | Core contributor, reviewer | | | Jackie Lu | @jackielu3 | Contributor | | | David Case | @shruggr | Contributor | | | Stephen Thomson | @Stephen-Thomson | Contributor | | | Chance Barimbao | @ChanceBarimbao | Contributor |

License

Released under the Open BSV License.