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.
Your app
Asks for what it wants done, such as a payment. It never holds a key.
The wallet
Holds the keys and decides whether and how to do it. BSV Desktop and BSV Browser are wallets.
Services
Each does one job, as the table below explains.
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:
| Service | What it does for your app | Product or package |
|---|---|---|
| Broadcast | Sends your transaction to the network and tells you its status. | BSV Broadcaster |
| Block headers | Provides 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 box | Keeps encrypted messages for a recipient who is offline. | @bsv/message-box-client |
| Overlays | Index the transactions your app cares about, so it can look them up later without scanning the chain. | @bsv/overlay |
| File storage | Stores 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.
Your app calls this package, and it makes the wallet calls for you.
Needed only if you build a wallet: storage, signing and the services a wallet uses.
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,listActionsandinternalizeAction. 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/browseris for apps that use the user’s own wallet. It wraps the SDKWalletClient, 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/serveris for a backend service or an automated agent.ServerWallet.createtakes a private key, anetworkand an optionalstorageUrl, so the server manages its own key.
Which package to use
Pick the package by what you want to do:
| If you want to | Use |
|---|---|
| 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 hash | UHRP, 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.
Related articles
To learn more about how the pieces of the stack work on the BSV blockchain, review these articles: