BSV blockchainBSV blockchain

BRC-100 wallet standard

Learn what BRC-100BSV Request for Comments 100, the standard interface between apps and wallets defines between an app and a wallet, and what each wallet decides, so you know which behavior you can rely on across wallets. The full text of the specification is on bsv.brc.dev. To see how an app finds and reaches a wallet, read BRC-100 wallet interface.

What the standard defines

The specification defines six things.

The methods

BRC-100 defines 28 methods, each with a request and a result type and a call code from 1 to 28. The BRC-100 wallet interface page groups them by what an app does with them, and the Wallet API reference has the parameters and results of every method.

Types and limits

A value means the same to every wallet because the types are defined. A SatoshiValue is a number of satoshisThe smallest unit of BitcoinSV (BSV): 100,000,000 satoshis make 1 BSV from 1 to 2.1 × 10^15, a Byte is an integer from 0 to 255, and string limits count UTF-8 bytes, not characters.

Names

Protocol IDs and basket names control what an app can reach, so the standard defines their form:

RuleProtocol IDBasket name
Length5 to 400 characters (430 for the specific key linkage revelation protocol)5 to 300 characters
CharactersLowercase letters, numbers and single spacesLowercase letters, numbers and single spaces
Cannot end with protocol basket
Cannot start withp (kept for future permission schemes, BRC-98) and admin (kept for the wallet, BRC-44)p (kept for future permission schemes, BRC-99) and admin
Cannot bedefault

The text of BRC-100 allows a basket name of up to 400 characters, but its TypeScript types and @bsv/sdk limit it to 300, so stay within 300.

A key ID is 1 to 800 bytes long.

Errors

An error has a status of error, a code, a description and an optional context. The specification leaves the names of the codes and the way an error travels to each implementation, as long as the description is clear. It lists ERR_MISSING_PARAMETER, ERR_INVALID_PARAMETER_VALUE and ERR_CONFLICTING_PARAMETERS only as examples, so a code name from one wallet may not exist in another, and the description is the part the specification requires.

Who is asking

A request names the app that sends it with the originator, the domain of the app, so the wallet can check permissions and ask the user. The originator is an optional parameter of every method, and each wallet decides how to handle a request that has none. A method that uses keys also takes a privileged option. Where a wallet implements it, it selects a second set of keys, kept apart from the everyday ones, and the wallet expects a reason for it.

The binary format

For a wallet reached over a binary channel, BRC-100 also defines how a request looks as bytes. The call codes are listed in the ABIApplication Binary Interface: the exact byte layout of a request and a response section of the specification. A request is one frame: one byte with the call code, one byte with the length of the originator, the originator domain in UTF-8, then the parameters of the method. A response starts with one byte for the error code, 0 for success, followed by the result, or by the error message when the code is not 0. A transport that carries JSON, such as the HTTP JSON API of the Wallet API reference, does not use the frame.

For example, a getPublicKey request from example.com starts with these bytes:

08 0b 65 78 61 6d 70 6c 65 2e 63 6f 6d

The 08 is the call code of getPublicKey, the 0b is the length of the domain (11 bytes), and the rest is example.com.

What BRC-100 builds on

BRC-100 points to these standards instead of repeating them. They define the key, encryption, signature, payment, certificate and transaction behavior behind the methods. The specification names a few more where they apply, such as BRC-97, BRC-98 and BRC-99:

BRCUsed for
BRC-2Encryption and decryption with AES-256-GCMAES with a 256-bit key in Galois/Counter Mode, an encryption that also detects tampering, using keys derived between the two parties.
BRC-3Digital signatures with ECDSAElliptic Curve Digital Signature Algorithm, the signature scheme the BSV blockchain uses, private to one counterparty or verifiable by anyone.
BRC-29Payments to a derived key, and how a wallet internalizes a received payment.
BRC-42Key derivation between two parties, the BSV Key Derivation Scheme.
BRC-43Security levels, protocol IDs, key IDs and counterparties, which decide who may use which key.
BRC-44Key derivation protocols reserved for the wallet and closed to apps.
BRC-45Treating a UTXOUnspent transaction output as a token.
BRC-46Baskets, the named groups of outputs a wallet tracks for apps.
BRC-52Identity certificates, with selective revelation of their fields.
BRC-62BEEFBackground Evaluation Extended Format: a transaction with the proof a host needs to verify it, the format wallets should use to build, send and check transactions.
BRC-67SPVSimplified Payment Verification: checking a transaction against block headers with a Merkle proof, without the whole chain, the steps a wallet follows to verify a transaction.
BRC-69Revealing the link between derived keys, so an interaction can be audited.
BRC-72Protecting key linkage information while it travels.

Any other BRC is in the BRC specifications index.

What stays the same

An established method keeps working across implementations and releases, major versions included. A revision keeps the request and result types, the default bytes on the wire and the authorization behavior. A new capability is additive and is selected or negotiated explicitly, without changing a connection that already exists. An extension that a wallet does not support fails with an error, and the wallet does not guess a response format or automatically replay a financial operation to find out.

What each wallet decides

Each wallet chooses its own interface, storage, services and the way apps reach it, so two wallets can ask for permission differently and still answer the same methods. The permission behavior therefore differs between wallets and is worth checking in each wallet you target. brc100.org, the site of the standard, has an API explorer and a list of wallets and apps that support it.

To learn more about BRC-100 on the BSV blockchain, review these articles: