BSV blockchainBSV blockchain

BRC-100: Wallet Application Interface

The Wallet Application Interface (BRC-100BSV Request for Comments 100, the standard interface between apps and wallets) is the interface between your app’s code and a wallet’s code. A full BRC-100 wallet exposes the same 28 methods, so the same app code works with BSV Desktop, BSV Browser or a wallet inside your own server. Read this before your app calls a wallet. By the end, you know how a request reaches the wallet and have run one script that makes the same calls to a wallet inside your process and to the user’s wallet.

Why your app does not hold the key

A wallet holds keys and signs transactions. It does not hold coins, since the coins are unspent outputs (UTXOsUnspent transaction output) on the blockchain that its keys can spend. In BRC-100 the wallet does the work that needs a key, and your app asks.

The diagram follows a request from your app to the wallet. Select a call and press Play to see which of the wallet’s steps use the key.

Try itPick a call, then press Play
Your appcreateActionasks, and waitsHolds no private keyBRC-100The wallet1Checks permissions2Selects the coins3Signs with the key4BroadcastsHolds the private key

The app asks for a transaction: a description and the outputs it wants.

0 of 6. The app asks for a transaction: a description and the outputs it wants.

What this means for your app:

  • The wallet derives keys, signs, encrypts and decrypts, and it selects the coins, sets the fee and broadcasts. When the wallet is a separate application, the private key never reaches your app, so a bug or a leak in your app cannot expose it, and your app does not track outputs.
  • Permissions are applied by the wallet, which uses the originator of each request to decide whether to ask the user. In BSV Desktop, a spend waits for Authorize in the Spending Request.
  • The user can change wallet without your app changing, since the two sides only share the interface.

What your app can ask a wallet to do

A BRC-100 wallet answers a fixed set of methods, grouped by what they do.

The five groups of methods

GroupPurposeMethods
ActionsBuild and manage transactionscreateAction, signAction, abortAction, listActions, internalizeAction
OutputsQuery and release tracked outputslistOutputs, relinquishOutput
Keys and cryptoKeys, signing and encryptiongetPublicKey, encrypt, decrypt, createHmac, verifyHmac, createSignature, verifySignature, revealCounterpartyKeyLinkage, revealSpecificKeyLinkage
CertificatesIdentity certificatesacquireCertificate, listCertificates, proveCertificate, relinquishCertificate, discoverByIdentityKey, discoverByAttributes
Wallet stateAuthentication, chain and wallet informationisAuthenticated, waitForAuthentication, getHeight, getHeaderForHeight, getNetwork, getVersion

The parameters and results of each method are in the Wallet API reference.

What createAction can return

createAction is how an app asks for a transaction, which BRC-100 calls an action. The result depends on who has to sign:

OutcomeWhat the app receivesWhat happens next
Immediate actionA txid and the transaction as an AtomicBEEFAtomic BEEF (BRC-95): one transaction packaged with the proofs of its ancestors in txThe wallet funded, signed and processed the transaction.
Signable action, when the request spends an output the wallet does not control, such as one locked to a key your app holdsOnly signableTransaction: { tx, reference }, with the transaction in txYour app signs the inputs it controls, then calls signAction({ reference, spends }) with the unlocking script of each input. The wallet adds its signatures and returns the txid.

Labels, tags and baskets

Three different indexes group what the wallet tracks, and they are not interchangeable:

ConceptApplies toUsed by
LabelsA whole actioncreateAction, listActions
TagsOne outputcreateAction, listOutputs
BasketsA named group of outputslistOutputs, internalizeAction

How a request reaches the wallet

Where the wallet runs decides the channel your request takes: a computer, a phone or your own server.

The diagram shows what WalletClient('auto') does on its first call. Switch a substrate on to mark that a wallet answers there, then press Play to see which one it keeps. Select Only XDM to see the last resort, or None to see the call fail.

Try itSwitch substrates on or off, then press Play
Your appWalletClient('auto')asks getVersionwindow.CWIInjected in the pageWallet wirehttp://localhost:3301JSON API, securehttps://localhost:2121JSON APIhttp://localhost:3321React Native WebViewpostMessage bridgeLast resort, only if none answeredXDMCross-document postMessage

Switch a substrate on to say that a wallet answers there. WalletClient asks the first five at once and gives each up to 1 s.

Switch a substrate on to say that a wallet answers there. WalletClient asks the first five at once and gives each up to 1 s.

How an app finds the wallet

BRC-100 defines the methods, not the channel that carries them. A wallet reaches your app over a substrate. WalletClient from @bsv/sdk supports these:

SubstrateWhere the wallet isAddress
window.CWIThe wallet injects a window.CWI object into the pageIn the same browserNot applicable
Wallet wireA wallet on the user’s machine, over a binary protocolhttp://localhost:3301
Secure JSON APIA wallet on the user’s machine, over JSON and HTTPShttps://localhost:2121, named secure-json-api
JSON APIA wallet on the user’s machine, over JSONhttp://localhost:3321, named json-api
React Native WebViewA native wallet that embeds the web app, such as BSV BrowserA postMessage bridge
XDMCross-document messagingA wallet in another frame or windowCross-document postMessage

In @bsv/sdk 4.x, new WalletClient('auto', 'YOUR_APP_DOMAIN') does not connect to a wallet until the first call. On that call it asks every substrate except XDM for getVersion in parallel and waits up to one second. It keeps the first one that answers, in the order of the table, and asks XDM last, with a 200 ms wait. When none answers, the call fails with No wallet available over any communication substrate.

The second argument is the originator, the domain name of your app, with an optional port and without a scheme or a path. WalletClient sends it with every method. You can also name one substrate, for example new WalletClient('json-api', 'YOUR_APP_DOMAIN'), or pass any object that implements the interface.

Desktop and phone

On a computer, WalletClient reaches a wallet such as BSV Desktop through a localhost port. On a phone, BSV Browser embeds the web app and exposes the same methods through a bridge. Only the substrate changes, so the same app code works on both.

Where the wallet runs

The interface does not say where the wallet is. It can be a separate application, as above, or an object in your own process, such as a server wallet built with @bsv/wallet-toolbox. In that case your process holds the key. The app and the wallet are the same program.

ProtoWallet in @bsv/sdk is not a full wallet. It holds one private key and implements only the nine methods of the keys and crypto group, so it cannot build a transaction.

The key in this script exists only while it runs. Never paste a real private key into code or commit one.

To try it, save this standalone script as roundtrip.mts, install the packages with npm install @bsv/sdk tsx and run it with npx tsx roundtrip.mts. It was written against @bsv/sdk 4.x, and the function takes any wallet that has encrypt and decrypt:

roundtrip.mts
import { WalletClient, ProtoWallet, PrivateKey } from '@bsv/sdk'
import type { WalletInterface } from '@bsv/sdk'

async function roundTrip(wallet: Pick<WalletInterface, 'encrypt' | 'decrypt'>) {
  const args = { protocolID: [1, 'demo app'] as [1, string], keyID: '1', counterparty: 'self' }
  const { ciphertext } = await wallet.encrypt({ ...args, plaintext: [1, 2, 3] })
  const { plaintext } = await wallet.decrypt({ ...args, ciphertext })
  return plaintext
}

const inProcess = new ProtoWallet(PrivateKey.fromRandom())
console.log(await roundTrip(inProcess))

const userWallet = new WalletClient('auto', 'YOUR_APP_DOMAIN')
console.log(await roundTrip(userWallet))
  • The first call prints [ 1, 2, 3 ], with a key generated for the run.
  • The second call needs a BRC-100 wallet running, such as BSV Desktop, and the wallet may ask the user to approve the request. It prints [ 1, 2, 3 ] too. When no wallet answers, it rejects with No wallet available over any communication substrate.
  • Replace YOUR_APP_DOMAIN with the domain name of your app, for example localhost while you develop. The .mts extension makes the script an ES module, which the top-level await needs, and tsx runs the TypeScript.

What BRC-100 does not cover

BRC-100 standardizes how an app talks to a wallet. It does not define how a wallet recovers from a lost key or a dead device. That is the wallet’s own job, and the wallet has to keep the recoverable keys and the records that go with them, such as the derivation data and the output history. Link to the recovery controls of the user’s wallet instead of backing up wallet data in your app. Never collect wallet secrets. For BSV Desktop, see Back up and recover a wallet.

To learn more about wallets and keys on the BSV blockchain, review these articles: