@bsv/wallet-toolbox-client

Browser build of @bsv/wallet-toolbox — the reference BRC-100 wallet implementation. It provides browser-safe wallet, signer, services, monitor, local IndexedDB, and remote storage APIs without the full package's Node-only storage adapters.

Use this package in:

• Web apps that talk to a remote StorageServer
• Browser extensions
• Electron renderers

For Node servers, use @bsv/wallet-toolbox. For React Native / mobile, use @bsv/wallet-toolbox-mobile.

Receiving already-broadcast payments

The 2.14.9 source candidate completes broadcast results even when storage already marks the request unmined or completed. This fixes first receipt without a mining proof on shared storage, and the same result path when another storage worker advances the request before the broadcast result refresh. The stored advanced state remains intact; unsuccessful provider results still reject receipt and do not credit new recipient outputs. Repeated successful receipt remains idempotent. A payment carrying its valid mining proof follows the existing proof path without rebroadcast.

Remote SQL storage also needs the 2.14.9 storage migration and coordinated server rollout: a durable user/TXID claim serializes receipts across pods while preserving historical rows. The browser's local IndexedDB provider does not use that SQL claim. No public API or wire migration is required. Source versions are candidates until published through the protected release workflow; upgrading an app alone does not upgrade its remote storage server.

BRC-100 result compatibility

Version 2.14.1 keeps internal exact-spend accounting off public createAction results, fixing strict binary bridge failures after the wallet operation while retaining fee and service-charge authorization. Upgrade the wallet and permission manager together. Existing JSON bridges that remove internal metadata retain their behavior; no application, BRC-39 or account-recovery migration is required. Check wallet history before retrying an action whose response failed on an older host.

Backup and recovery

A BRC-100 wallet needs both recoverable keys and wallet records/derivation metadata. BRC-39 exports contain wallet data, not root keys or manager snapshots. IndexedDB can be evicted or lost with the browser profile. Keep an independent data copy and test recovery on a clean profile.

Read Wallet backup and recovery, BRC-38/39 integration and the recovery checklist. Portable helpers require a concrete local StorageProvider; a remote client is not one. Qualify the local-copy path and device memory limits before adding export/import UI.

Large wallet records

Compatible providers negotiate authenticated, integrity-checked transfers for records that exceed a single HTTP message. Uploads resume saved pieces after interruption; ordinary pages and legacy providers retain their existing protocol. Version 1 is bounded to 64 MiB per frame and requires an upgraded provider. See the transfer and migration guide.

Install

Install the @bsv/sdk peer dependency alongside this package:

npm install @bsv/wallet-toolbox-client @bsv/sdk

Package targets

The package publishes:

• an ESM browser/import target with source maps;
• a CommonJS require target with source maps;
• matching declarations for ESM and CommonJS;
• explicit browser, import, and require export conditions.

Use a current browser bundler such as Vite or esbuild. Node.js 22 or newer is required for the published tooling and contributor workflow; browser runtime support is determined by your application's target configuration.

Optional native Argon2id backend

Import registerArgon2idBackend, unregisterArgon2idBackend, and the AsyncArgon2idBackend type from this package's root export. Register a host implementation only after verifying its interoperability; isReady() must remain false until that verification succeeds. A ready backend is authoritative: derivation errors and malformed output are surfaced without switching implementations.

Concurrent cold derivations share one background preload() attempt and keep the portable path. Later calls can retry after that attempt settles. Hosts must make preload() and isReady() reentrant and cache permanent failures or apply backoff. Unregister the same backend object when the host no longer owns it.

Remote storage example

import { Wallet, WalletSigner, WalletStorageManager, StorageClient, Services } from '@bsv/wallet-toolbox-client'
import { KeyDeriver, PrivateKey } from '@bsv/sdk'

const chain = 'main'
const keyDeriver = new KeyDeriver(new PrivateKey(privateKeyHex, 'hex'))

// Remote storage over HTTPS — no SQLite/MySQL in the browser bundle.
const storageManager = new WalletStorageManager(keyDeriver.identityKey)
await storageManager.addWalletStorageProvider(new StorageClient(keyDeriver, 'https://storage.example.com'))
await storageManager.makeAvailable()

const services = new Services(chain)
const signer = new WalletSigner(chain, keyDeriver, storageManager)
const wallet = new Wallet(signer, services)

// Use the BRC-100 interface as usual.
const { tx } = await wallet.createAction({
  description: 'pay alice',
  outputs: [{ satoshis: 1000, lockingScript: aliceP2PKH }]
})

Use cases

BRC-100 wallet inside a browser extension

Talk to a remote StorageServer over HTTPS, sign locally with a key the user controls.

Authenticated app with WalletClient

import { WalletClient } from '@bsv/sdk'

const wallet = new WalletClient() // delegates to the user's installed wallet
// ...or build your own with the toolbox classes above

Run an in-app embedded wallet against IndexedDB

import { StorageIdb } from '@bsv/wallet-toolbox-client'
await storageManager.addWalletStorageProvider(new StorageIdb(...))

IndexedDB listOutputs results keep totalOutputs equal to the full matching count across every page, including a short final page or an offset at or past the end.

Prepared BEEF (COOK) persistence is a server-side Knex capability. Browser IndexedDB keeps the canonical BEEF path, while a compatible remote storage server can enable prepared reads and writes without a browser configuration or wire-format change.

The browser wallet includes the built-in BRC-177 p nosend expiry module. Embedded IndexedDB wallets use the default local monitor. When remote storage is active, its migrated Wallet Toolbox 2.11-or-newer service and monitor own expiry enforcement; capability negotiation fails before prefunding against an older server. See the full expiry guide.

What's excluded vs @bsv/wallet-toolbox

The browser entry includes Wallet, WalletSigner, WalletStorageManager, StorageClient, StorageIdb, Services, Monitor, WalletPermissionsManager, WalletSettingsManager, and related browser-safe APIs. It does not promise every full-package or test-only export.

Wallet snapshot security

Wallet-manager snapshots contain root key material and intentionally include the decryption key needed by their self-contained format, so access to the snapshot is access to the wallet. Store the complete snapshot only through a browser or extension facility backed by an OS Keychain or comparably trusted secret store. Do not use ordinary localStorage, logs, analytics, crash reports, clipboard data, or unprotected synchronization. Treat any snapshot that leaves trusted storage as a wallet-credential compromise and rotate the affected wallet.

StorageClient and credential-bearing Arcade SSE clients require HTTPS for remote endpoints. Plain HTTP is accepted only for explicit loopback hosts such as localhost during development. SSE dependency debug logging is disabled so callback tokens and authorization headers do not reach application logs.

See the @bsv/wallet-toolbox README for full documentation.

CORS, CSP, and public services

This client does not impose an origin allowlist. A remote Storage service controls its own CORS policy and should remain reachable by its intended public web, WUI, extension, and mobile clients. Operators can keep public access enabled by default or configure an explicit allowlist when their deployment requires one; deployments should not assume a single calling domain.

CSP is an application and deployment concern rather than a package-level access control. Add the service's HTTPS origin to the consuming application's connect-src policy. Keep authentication and authorization at the protocol/service layer instead of treating CORS as an authentication mechanism.

Contributor checks

Final overlay identity discovery copies bounded resolver receipts, verifies the complete transaction graph and canonical anchors with the configured wallet Services ChainTracker, and validates the standard subject-signed certificate envelope. Cached transaction evidence is rechecked before use; local contacts retain their separate policy. See the identity verification guide for C01/C02/C03 compatibility characterization and limits. Inclusion is not proof of freshness or unspentness. Current package and packed-consumer validation remains pending the release review.

From the repository root, build the SDK and package before running the installed-consumer browser gate:

pnpm --filter @bsv/sdk build
pnpm --filter @bsv/wallet-toolbox-client build
pnpm --filter @bsv/wallet-toolbox-client test:browser

The gate installs the packed packages in a clean project, bundles them with Vite and esbuild, checks the public export and browser-only module contracts, validates source maps, and enforces compressed and uncompressed size budgets.

License

This package is released under the Open BSV License Version 6. The accompanying THIRD_PARTY_NOTICES.md and LICENSES/ preserve earlier Open BSV grants compiled into the browser build.

Local sync database upgrade

IndexedDB automatically upgrades to schema version 6, adding a non-unique transaction-ID/user index without replacing wallet records. Exact transaction, reference, reclaim, commission, and relation lookups avoid repeated full-wallet scans during restores. Legacy duplicate transaction IDs remain intact. Clients that request an older IndexedDB schema version cannot reopen this database; retain a compatible client when using the local backup.

WAB faucet fee compatibility

Version 2.14.6 carries the local signer's independently validated fee/change outputs through the permissions manager to SDK completed-action binding. Upgrade with an SDK exposing completeBoundAction.outputAuthorizationVersion=1; older SDK peers preserve their strict behavior and do not receive the fee-bearing faucet fix. Use wallet and authentication manager from the same package instance. Serialized results discard local authorization. See the full toolbox README for SDK3 migration and the unchanged signup retry/reconciliation limitations.

Pre-construction conflict recovery

The 2.14.7 candidate preserves remote storage's empty attempted-TXID sentinel only for a bounded double-spend review before transaction construction. It does not authorize a retry. Applications must verify complete competing transactions against the requested explicit inputs, synchronize the accepted winner, then read fresh state before rebuilding. Upgrade the application SDK alongside the wallet parser. Use the existing JSON wallet API for structured review errors; the binary wire format is unchanged. No database or call migration is required.