@bsv/wallet-toolbox-client

@bsv/wallet-toolbox-client is the browser-safe Wallet Toolbox distribution. It includes the BRC-100 wallet, signer, services, IndexedDB storage, and remote storage client without Node-only Knex, SQLite, MySQL, or filesystem adapters. The built-in BRC-177 p nosend expiry module works with local IndexedDB or a 2.11-compatible remote storage service; the active provider owns durable expiry monitoring, synchronized lifecycle state, and pre-signed reclaim submission. IndexedDB listOutputs results keep totalOutputs equal to the full matching count across short final and out-of-range pages. BRC-177 anchors cover both the delivery and an economic reclaim. When the reclaim floor is larger, the protected action pays the bounded surplus as miner fee while retaining no wallet change. Upgrade the active storage implementation to receive this funding fix; no wire or database migration is required.

Prepared BEEF persistence remains a server-side Knex capability. Browser IndexedDB uses the canonical path, and compatible remote servers can enable the optimization without a browser configuration or wire change. Wallet snapshots are wallet-equivalent secrets and belong only in browser or extension storage backed by an OS Keychain or comparably trusted store, never ordinary localStorage, logs, analytics, or unprotected sync. Remote storage and credential-bearing Arcade SSE require HTTPS except for explicit loopback development, and transport debugging cannot expose credentials. Spending approvals are never cached or coalesced; certificate acquisition and identity discovery require valid certifier signatures before storage or trust scoring. Related browser noSend chains retain local action batching, while unrelated actions cannot join or commit the active workspace. Supported remote providers can resume a soft-expired workspace using its exact persisted inputs. WalletStorageManager.getStores() retains each remote provider's configured endpointURL after production bundlers minify class names, so backup selection and make-primary flows remain stable. Immediate browser actions can chain wallet-managed change from a delayed parent only after completed and unproven liquidity is exhausted or exact serialized-cost comparison proves that a pathological settled plan is larger. Pending funds are never hidden. IndexedDB wallets migrate exact untouched 144-output / 32-satoshi defaults to a progressive 5,000-satoshi preference. Durable permission tokens retain delayed broadcast so permission approval does not inherit network latency. Opt-in remote-storage timing spans retain trace and parent-span correlation in the telemetry sink without adding headers to authenticated requests.

The browser distribution also exposes the WAB UMP ambiguity fallback and OTP-verified startPhoneNumberChange / completePhoneNumberChange flow. A settings UI may submit the current number to force a fresh presentation hash; it must persist the wallet snapshot immediately after success. Browser authentication accepts one verified matching UMP token as an existing account. When no token verifies, one clean empty overlay response establishes a new account even if other hosts fail or return malformed records.

The browser build includes the fetch-based, credential-free ChainTracks v2 client and reconnecting SSE adapter without Node-only modules. Public defaults cover mainnet, testnet, and TerraTestNet; STN/TSTN use an injected or configured endpoint.

The portable local controller coalesces stale height refresh and immutable object loads, applies failed-load backoff, and validates through the asynchronous InlineBulkFileDataValidator without importing Node worker or filesystem code.

BEEF requests and schema-declared storage response bytes use the existing negotiated compact binary JSON codec. Legacy peers retain numeric-array JSON and identical transaction/proof bytes. Authentication and payload ceilings remain unchanged; upgrade both clients and active storage for the savings.

IndexedDB treats empty certificate certifier/type, transaction status and output-tag ID arrays like omitted optional filters, matching Knex. Nonempty arrays, partial predicates and user ownership remain enforced. No API, wire or database migration is required.

Internalizing an unproven transaction new to a user attempts broadcast before storing recipient outputs, including a sender's no-send transaction already known to shared storage. Rejected broadcasts return a review-actions error and store no recipient outputs. Transactions backed by a mining proof are not rebroadcast. Upgrade active storage; no API, wire or schema migration is required.

Backup and recovery

Recover both key material and wallet records; a manager snapshot or device keystore alone is not a complete data backup. IndexedDB can be evicted or lost with the browser profile. Keep an independent data copy and test recovery on a clean profile. Use the recovery guide, BRC-38/39 integration and recovery drill. The portable helpers require a concrete provider and a tested consistency/resource-limit strategy.

Install

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

Use

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

The package publishes browser/import ESM and CommonJS conditions with matching declarations. Its installed-consumer gate bundles the exact tarball with Vite and esbuild, rejects Node-only modules, validates source maps, and enforces compressed and uncompressed size budgets.

This single bundle also exports WalletMonitorTask (the base class for a custom task passed to Monitor.addTask), attemptToPostReqsToNetwork with its PostReqsToNetworkResult type, parseJsonRpc / stringifyJsonRpc (the storage remoting wire format), and verifyUnlockScripts with its UnlockScriptVerificationResult type, so a host no longer needs an unsupported deep import to reach them:

import {
  WalletMonitorTask,
  attemptToPostReqsToNetwork,
  parseJsonRpc,
  stringifyJsonRpc,
  verifyUnlockScripts
} from '@bsv/wallet-toolbox-client'

Remote Wallet Storage often serves public web, extension, WUI, and mobile clients from origins unknown at build time. The client imposes no origin allowlist. Operators may explicitly configure one at the service edge, but CORS is not authentication; storage authorization and identity isolation remain mandatory in either mode.

See the package README for complete remote and IndexedDB setup.

License

Open BSV License Version 6. See the package license.

Faucet output authorization

The source candidate adds exact completed-action binding for independently validated local storage fees and change. The SDK capability marker is completeBoundAction.outputAuthorizationVersion=1; upgrade the wallet and SDK together. Existing SDK2 peers retain strict behavior. The separate SDK3 migration still applies; SDK2 consumers need an additive backport or that migration. Serialized wallet results do not carry local authority. The fee fix does not change signup persistence or interrupted-funding reconciliation. See the package README and release and migration ledger.