@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.

Remote StorageClient calls accept authFetchOptions in the existing third constructor argument. For a longer authenticated request, configure both requestTimeoutMs and responseTimeoutMs with an SDK that supports the latter. Omission preserves the installed SDK defaults; existing SDK peer ranges and consumer calls are unchanged. See the remote storage timeout guide.

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.

Local recovery capability boundary

The coordinated 2.15.0 source candidate preserves this wrapper's existing APIs and SDK peer range. Core's new local SQLite action/funding recovery controllers are separate Node deep imports; this package does not bundle or expose them. An upgrade does not give IndexedDB, mobile or remote storage a durable operation journal. Ordinary BRC-100 methods retain their existing behavior.

When a host separately adopts core recovery, preserve its whole consistent wallet database and keys. Ordinary entity export/sync does not include those auxiliary journals. Reconcile outstanding core operations before rollback; wrapper retries or a new payment cannot substitute for retained recovery state. See the local recovery guide.

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

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.

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.

SDK4 hotfix peer requirement

The SDK4 peer alternative starts at @bsv/sdk ^4.0.1, which restores numeric wallet results and legacy wire compatibility. Existing SDK2/3 alternatives and lower bounds remain unchanged. SDK4 users should install the 4.0.1 hotfix; no application-wallet wire or data migration is required.