@bsv/wallet-toolbox-mobile

Mobile build of @bsv/wallet-toolbox — the reference BRC-100 wallet implementation. It provides mobile-safe wallet, signer, services, monitor, and remote storage APIs without Knex, SQLite/MySQL native bindings, IndexedDB, or Node-only IO.

Use this package in:

• React Native apps
• Capacitor / Cordova mobile apps
• Other mobile runtimes that provide fetch, Web Crypto, and the required web-compatible globals

For Node servers, use @bsv/wallet-toolbox. For browsers, use @bsv/wallet-toolbox-client.

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. App removal or device loss can remove locally retained secrets and state. Test the independent key and data recovery paths on a replacement device.

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-mobile @bsv/sdk

Package targets

The package publishes:

• an ESM React Native/import target with source maps;
• a CommonJS require target with source maps;
• matching declarations for ESM and CommonJS;
• explicit react-native, import, and require export conditions.

The packed package is validated with Metro and compiled to optimized Hermes bytecode. Node.js 22 or newer is required for the published tooling and contributor workflow, not as an on-device runtime.

Password derivation without WebAssembly

Argon2id password derivation uses hash-wasm when WebAssembly is available. React Native engines such as Hermes that do not expose WebAssembly use an asynchronously yielding JavaScript fallback with identical parameters and output. Existing UMP v3 wallets remain compatible, and users do not need to change a device setting or migrate their account.

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-mobile'
import { KeyDeriver, PrivateKey } from '@bsv/sdk'

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

// Remote storage over HTTPS is the default mobile-safe backend.
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)

const { tx } = await wallet.createAction({
  description: 'mobile send',
  outputs: [{ satoshis: 1000, lockingScript: recipientScript }]
})

The mobile wallet includes the built-in BRC-177 p nosend expiry module. Its active remote storage must run a migrated Wallet Toolbox 2.11-or-newer service and default monitor, which owns expiry enforcement across restarts and devices. Capability negotiation fails before prefunding against an older server. See the full expiry guide.

Use cases

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.

Self-custody BSV wallet on a phone

Run the BRC-100 wallet entirely on-device, with remote storage for cross-device sync.

Companion-app signer for a desktop wallet

Use mobile as the signer over a paired channel while a desktop runs the heavier services.

Receive-only mobile app

Spin up a minimal wallet that watches for inbound payments via a remote storage backend.

What's excluded vs @bsv/wallet-toolbox

| Excluded | Why | | ------------------------------------- | ------------------------------------------------------------- | | StorageKnex (SQLite, MySQL) | Native bindings unavailable on React Native / mobile WebViews | | StorageIdb | IndexedDB is not a uniform React Native storage primitive | | Node-only filesystem and os helpers | Not available on mobile |

The mobile entry includes Wallet, WalletSigner, WalletStorageManager, the mobile StorageClient, Services, Monitor, WalletPermissionsManager, WalletSettingsManager, ArcSSEClient, and related mobile-safe APIs. It does not export StorageIdb, StorageKnex, SetupClient, or test-only chain implementations.

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 in the iOS Keychain, Android Keystore-backed encrypted storage, or a comparably trusted secret store. Do not use ordinary AsyncStorage, logs, analytics, crash reports, clipboard data, or unprotected device/cloud backups. 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 during development. SSE dependency debug logging is disabled so callback tokens and authorization headers do not reach device logs.

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

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

CORS, CSP, and public services

This client does not impose an origin allowlist. Native mobile requests are not governed by browser CORS, while WebView and hybrid clients can be. A remote Storage service should remain reachable by its intended public apps, WUI, browser, extension, and mobile callers. 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 applies to WebViews or other embedding web applications. 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

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

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

The gate installs the packed packages in a clean project, bundles them with Metro, checks the public export and mobile-safe module contracts, validates source maps, compiles the result with Hermes, and enforces compressed and uncompressed size budgets.

The reviewed 2.14.2 identity candidate b088c1bef measures Metro 2,379,919 / 612,262 / 462,261 bytes and Hermes 4,629,563 / 1,943,675 / 1,510,174 bytes (raw/gzip/Brotli). Compared with the preceding unpublished 2.14.2 candidate, Metro gzip grows by 3,553 bytes (0.58%). This is the required SDK/Toolbox identity matcher, portable text tokenization and direct-filter guards; no new dependency, Node adapter or public export was introduced. The packed consumer passes the module/runtime composition and source-map checks and compiles with Hermes. The versioned budgets retain at least 10% headroom above these reviewed measurements, rounded up to 5,000 bytes, following the shared artifact policy. All composition and byte-dimension gates remain enforced.

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 mobile build.