BSV blockchainBSV blockchain

How the BSV blockchain stack fits together

A BSV blockchain app is made of a wallet that holds the keys, a few services that broadcast transactions, serve block headers, deliver messages, index data and store files, and the packages that connect them. Knowing where each part sits tells you which package to start with.

How the pieces fit

Your app asks a wallet for what it needs, such as a payment, and the wallet relies on a handful of services to carry it out.

1

Your app

Asks for what it wants done, such as a payment. It never holds a key.

2

The wallet

Holds the keys and decides whether and how to do it. BSV Desktop and BSV Browser are wallets.

3

Services

Each does one job, as the table below explains.

BroadcastBlock headersMessage boxOverlaysFile storage

The app and the wallet talk through BRC-100The standard interface between app code and wallet code, a standard interface, so any BRC-100 wallet can take the place of another one without a change in your app. BSV Desktop and BSV Browser are two of these wallets.

What the services do

The wallet and your app use five services, and each one does a single job:

ServiceWhat it does for your appProduct or package
BroadcastSends your transaction to the network and tells you its status.BSV Broadcaster
Block headersProvides the block headers that a wallet checks a transaction’s proof against.BSV Broadcaster, or a ChaintracksA block header service. A wallet uses it to check Merkle paths against the block headers. client in wallet toolbox
Message boxKeeps encrypted messages for a recipient who is offline.@bsv/message-box-client
OverlaysIndex the transactions your app cares about, so it can look them up later without scanning the chain.@bsv/overlay
File storageStores public files and finds them by their hash.UHRPUniversal Hash Resolution Protocol (BRC-26): file storage where a file is found by the hash of its content

How an API charges for a request

HTTP 402 lets an API ask for payment in the request itself. The client asks for a resource, the server answers 402 with the price in the x-bsv-sats header, the wallet pays, and the same request goes again with the payment attached. BRC-121 specifies this flow, and the @bsv/402-pay package is built for it.

Open standards

The interfaces between these parts are published as BRC standards, such as BRC-100 for the wallet and BRC-121 for 402 payments, so a wallet or a service can be built by anyone against the same specification. SDKs are available for TypeScript, Go and Python, and a Rust SDK is in development.

Layers and packages

The packages of the TypeScript stack follow the same shape, as roles rather than as an npm dependency chain. There are three main layers, plus a set of capabilities that connect to them from the side.

Application layer@bsv/simple

Your app calls this package, and it makes the wallet calls for you.

Wallet layer@bsv/wallet-toolbox

Needed only if you build a wallet: storage, signing and the services a wallet uses.

Foundation@bsv/sdk

Keys, Script, transactions and proofs. Both layers above use it.

The wallet boundary

BRC-100 separates app code from wallet code:

  • Above the line, your app calls methods such as createAction, signAction, listOutputs, listActions and internalizeAction. It does not manage keys or storage.
  • Below the line, the wallet handles storage, signing, key derivation, choosing which outputs to spend and gathering Merkle proofs.

What the SDK covers

@bsv/sdk has no runtime dependencies, and the other packages list it as a peer dependency. It covers keys and cryptography, Script, transactions and the fee model, BEEFBRC-62, the format for sending a transaction with its proof and Merkle proofs (Beef and MerklePath), broadcasting with ARC, and checking proofs against block headers with chain trackers such as BlockHeadersService.

The two ways to use @bsv/simple

  • @bsv/simple/browser is for apps that use the user’s own wallet. It wraps the SDK WalletClient, which finds the wallet available on the user’s machine, so your app never holds a private key. wallet.getClient() returns the raw BRC-100 client.
  • @bsv/simple/server is for a backend service or an automated agent. ServerWallet.create takes a private key, a network and an optional storageUrl, so the server manages its own key.

Which package to use

Pick the package by what you want to do:

If you want toUse
Build an app@bsv/simple, see the SDKs overview
Work with keys, Script, transactions and proofs@bsv/sdk, see the SDKs overview
Build a wallet@bsv/wallet-toolbox
Charge for API requests@bsv/402-pay, see Gate an API behind payments
Send messages to users who may be offline@bsv/message-box-client, see Send messages between users
Index the transactions your app cares about@bsv/overlay and @bsv/overlay-express, see Track transactions with overlays
Authenticate users with their wallet@bsv/auth-express-middleware, see Authenticate users with their wallet
Look up a user by a Paymail handle@bsv/paymail, see Look up a user’s identity key with Paymail
Store public files by their hashUHRP, in @bsv/sdk (StorageUploader and StorageDownloader)
Work with tokens@bsv/btms

Your app can also call overlays, message box servers and UHRP storage directly, without the wallet. The wallet is only involved when an operation needs a private key.

To learn more about how the pieces of the stack work on the BSV blockchain, review these articles: