# How the BSV blockchain stack fits together

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

How an app, a wallet and the services behind it work together on the BSV blockchain, and where each package sits from cryptography up to your app.

import StackOverview from '/snippets/StackOverview.jsx';
import StackLayers from '/snippets/StackLayers.jsx';

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.

<StackOverview />

The diagram has three boxes. Your app asks for what it wants done and never holds a key. It talks to the wallet through BRC-100. The wallet holds the keys and decides whether and how to do it, and BSV Desktop and BSV Browser are wallets. The wallet uses services: broadcast, block headers, message box, overlays and file storage.

The app and the wallet talk through BRC-100 (The 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 Chaintracks (A 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. | UHRP (Universal 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.

<StackLayers />

The diagram has three layers, from the top down. The application layer is `@bsv/simple`, which your app calls. The wallet layer is `@bsv/wallet-toolbox`, needed only if you build a wallet. The foundation is `@bsv/sdk`, which both layers above use. The BRC-100 interface sits between the application layer and the wallet layer.

### 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, BEEF (BRC-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 to | Use |
| --- | --- |
| Build an app | `@bsv/simple`, see the [SDKs overview](https://bsvblockchain.com/docs/sdk/) |
| Work with keys, Script, transactions and proofs | `@bsv/sdk`, see the [SDKs overview](https://bsvblockchain.com/docs/sdk/) |
| Build a wallet | `@bsv/wallet-toolbox` |
| Charge for API requests | `@bsv/402-pay`, see [Gate an API behind payments](https://bsvblockchain.com/docs/guides/payments/) |
| Send messages to users who may be offline | `@bsv/message-box-client`, see [Send messages between users](https://bsvblockchain.com/docs/guides/messaging/) |
| Index the transactions your app cares about | `@bsv/overlay` and `@bsv/overlay-express`, see [Track transactions with overlays](https://bsvblockchain.com/docs/guides/overlays/) |
| Authenticate users with their wallet | `@bsv/auth-express-middleware`, see [Authenticate users with their wallet](https://bsvblockchain.com/docs/guides/identity-auth/) |
| Look up a user by a Paymail handle | `@bsv/paymail`, see [Look up a user's identity key with Paymail](https://bsvblockchain.com/docs/standards/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:

- [How wallets and BRC-100 work](https://bsvblockchain.com/docs/concepts/wallet-model/)
- [SDKs overview](https://bsvblockchain.com/docs/sdk/)