BSV blockchainBSV blockchain

Build a wallet

Follow the six stages below to build a BRC-100BSV Request for Comments 100, the standard interface between apps and wallets wallet on @bsv/wallet-toolbox, from the interface to the backend services.

A BRC-100 wallet answers the requests of apps. Apps call methods such as createAction through BRC-100, and the wallet carries them out. It holds the keys, chooses the coins, signs, stores its outputs and checks permissions.

BSV Desktop and BSV Browser are two of these wallets. Both are built on @bsv/wallet-toolbox, the TypeScript reference implementation. Build a wallet when you make a wallet product, a wallet-like service or a port to another language. If your app only uses a wallet, start from the SDKs overview instead.

The path to a BRC-100 wallet

Each stage below builds on the one before it, from the interface your wallet answers to the servers it can run on.

Learn the interface

Start with BRC-100 Wallet Interface. It lists the method groups, the two ways createAction can end (an immediate action, or a signableTransaction that the app finishes with signAction) and the difference between labels, tags and baskets. An app written against BRC-100 expects those exact results from your wallet, without knowing which wallet answers.

Start from wallet-toolbox

@bsv/wallet-toolbox connects the @bsv/sdk primitives to the parts a wallet needs. This page was written against @bsv/wallet-toolbox 2.14.

PartWhat it does
WalletImplements the BRC-100 methods
WalletStorageManager and storage providersKeep the wallet’s records in an active store, with optional backup stores
WalletSignerBrings the wallet’s keys into the SDK signing flow
Key managersDerive keys with BRC-42BSV Key Derivation Scheme and BRC-43Security levels, protocol IDs, key IDs and counterparties, manage privileged keys and run Shamir-based recovery
ServicesConnect the wallet to broadcast, chain tracking and proof lookup
MonitorTracks confirmations, gathers Merkle proofs and rebroadcasts stalled transactions in the background
WalletPermissionsManagerChecks permissions around wallet methods
MockChainRuns wallet tests without a live network

The Setup class builds a wallet with its storage, services and monitor in one call, and the object it returns exposes each part so you can inspect or replace it. Send a payment from a server builds a wallet this way on testnet, with Setup.createWalletSQLite.

Choose the platform and storage

The toolbox ships in three packages, one per platform, and each supports different storage:

PackagePlatformStorage
@bsv/wallet-toolboxNode.jsSQLite, MySQL or another database that Knex supports
@bsv/wallet-toolbox-clientBrowserIndexedDB on the device, or remote
@bsv/wallet-toolbox-mobileReact NativeRemote

Remote storage keeps the records on a Wallet Infra server that the wallet calls over HTTPS. The records hold the derivation data of each output, so recovering a wallet needs both the root key material and these records. A seed alone cannot rebuild every output.

Add permissions

WalletPermissionsManager sits in front of the wallet and decides what each app may do. A spending authorization covers an amount: the app can spend until it reaches that amount, and then the wallet asks the user again. Permission modules take over the protocols, baskets and labels reserved by BRC-98P Protocols, the wallet permission scheme for protocols, BRC-99P Baskets, the wallet permission scheme for baskets and BRC-111P Labels, the wallet permission scheme for action labels, so a module can add its own rules for one kind of asset. For example, @bsv/btms-permission-module lets the spend prompt show a token’s value, such as $1.00 USD, instead of the 1 satoshiThe smallest unit of BitcoinSV (BSV). 100,000,000 satoshis make 1 BSV. that typically funds the token output.

Test conformance

The ts-stack repository turns BRC-100 behavior into JSON test vectors, each with its inputs and the expected outputs, under conformance/vectors/wallet/brc100/. A wallet in any language reads the same files and compares its own results. Coverage is strongest for the deterministic crypto and key methods. Stateful cases carry an explicit classification instead of counting as passes, so a vector count alone does not prove a wallet passes every case.

The same vectors are how a port proves it matches the TypeScript reference. go-wallet-toolbox and py-wallet-toolbox bring the toolbox to Go and Python, and the porting guide covers aligning another language.

Run the backend services

Two ts-stack servers run only when the wallet needs them:

  • Wallet Infra serves the toolbox storage over JSON-RPC, backed by MySQL, with mutual authentication and records scoped to each user. Wallets reach it with StorageClient. Run it to host remote storage for many wallet clients.
  • The WABWallet Authentication Backend verifies a user’s phone number with a one-time code and returns the user’s presentation keyA 256-bit key the WAB gives back after the phone check. It is one of three factors, with the password and a recovery key, and any two of them unlock the wallet. On a new device, the wallet combines that key with the user’s password to unlock the root key, and the WAB never sees the password. It can also keep optional recovery shares and pay new users a one-time faucet. Phone verification is the only sign-in method it offers for real users today, so run it when your wallet offers phone sign-in and recovery.

Run a wallet backend runs both services on testnet and connects a wallet to each.

To learn more about building a BRC-100 wallet, review these articles: