# How @bsv/simple is built

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

@bsv/simple puts a BRC-100 wallet, the @bsv/sdk classes and a few hosted services behind one wallet object, in the browser and on the server.

import BlueTable from '/snippets/BlueTable.jsx';

`@bsv/simple` is a helper library on top of `@bsv/sdk`. It gives you one wallet object with methods such as `send()`, `pay()` and `createToken()`, and builds the scripts and wallet calls behind each of them. This page shows what that object is made of, so you can tell when a method fits your app and when to call the BRC-100 (BSV Request for Comments 100, the standard interface between apps and wallets) wallet yourself. It was written against `@bsv/simple` 0.7.2.

For where the package sits in the stack, see [How the BSV blockchain stack fits together](https://bsvblockchain.com/docs/concepts/architecture/).

## One object, two kinds of wallet

You create the wallet object in one of two ways. The methods are the same in both, and only the wallet underneath changes:

<BlueTable>

| Where your code runs | How you create it | Wallet underneath | Who holds the key |
| --- | --- | --- | --- |
| Browser | `createWallet()` from `@bsv/simple` | `WalletClient` from `@bsv/sdk`, connected to the user's wallet | The user's wallet app |
| Server | `ServerWallet.create()` from `@bsv/simple/server` | `Wallet` from `@bsv/wallet-toolbox` | Your server |

</BlueTable>

In the browser, `createWallet()` connects to the wallet app the user has, such as [BSV Desktop](https://bsvblockchain.com/docs/wallets/bsv-desktop/) on a computer or [BSV Browser](https://bsvblockchain.com/docs/wallets/bsv-browser/) on a phone. That app signs each transaction, within the spending limits the user set in it.

On the server, `ServerWallet.create()` takes the private key in hex, a `network` and an optional `storageUrl`. The wallet keeps its records on a remote storage server, `https://storage.babbage.systems` unless you set `storageUrl`. The package needs Node 22 or later.

> On the server, every transaction goes out with no one approving it, and a broadcast transaction cannot be undone. Pass `network: 'testnet'` while you test, because the network is `main` when you leave it out.

> On the server, your code holds the private key. Read it from an environment variable and keep it out of your repository. If you use `ServerWalletManager` without that variable, it saves a generated key to `.server-wallet.json` in the working folder, so add that file to `.gitignore`.

> `getWalletInfo()` reports the network from the options you passed to `createWallet()`, which is `main` by default, not the network of the user's wallet. To read the wallet's network, call `getNetwork()` on `getClient()`.

## What the object can do

The object is built in two layers. A base class, `WalletCore`, has the methods for sending transactions. When the wallet is created, seven modules add their methods to the same object:

<BlueTable>

| Layer | Examples of methods | What it is for |
| --- | --- | --- |
| Base class | `send()`, `pay()`, `getBalance()` | Sending transactions and reading the balance |
| Tokens | `createToken()`, `sendToken()` | Tokens that carry your own data |
| Inscriptions | `inscribeText()`, `inscribeJSON()` | Data written on chain |
| MessageBox | `sendMessageBoxPayment()`, `lookupIdentityByTag()` | Payments and messages through a message box (A server that holds messages and payments for a recipient until the recipient collects them) |
| Certification | `acquireCertificateFrom()` | Certificates from a certifier (A server that checks a claim about a user and signs a certificate for their identity key) |
| Overlay | `advertiseSHIP()`, `broadcastAction()` | Publishing to overlay (Services that track selected transactions and answer queries about them) services |
| DID | `getDID()`, `resolveDID()` | DIDs (Decentralized identifier, a W3C identifier that the holder controls) for an identity key (The public key that identifies a wallet to apps and other users) |
| Credentials | `acquireCredential()` | Verifiable credentials (Certificates packaged so a third party can check who issued them) |

</BlueTable>

Every module reaches the wallet through `getClient()`, which returns the BRC-100 interface of the wallet underneath. That is why the same methods work in the browser and on the server. The DID module is the exception: it works from the identity key alone.

Some modules also call a service over HTTP:

- Message box: `pay()`, the MessageBox methods and tokens sent to a recipient use `https://messagebox.babbage.systems` unless you set another host.
- Identity registry: `lookupIdentityByTag()` and `registerIdentityTag()` need a `registryUrl`, which has no default. If you run the registry yourself with `IdentityRegistry`, put it behind a login: it has no authentication of its own.
- Certifier and issuer: `acquireCertificateFrom()` and `acquireCredential()` call the server URL you pass to them.
- Overlay hosts: `broadcastAction()` sends to the hosts of the overlay preset you choose.
- Wallet storage: a server wallet keeps its records on `https://storage.babbage.systems` unless you set `storageUrl`.

## What happens when you send

The `send()` method takes a list of outputs and makes one `createAction()` call to the wallet, so they all go in one transaction, in the order you list them. Each output becomes a script from the fields you give it:

<BlueTable>

| Fields in the output | Script it becomes |
| --- | --- |
| `to` only | P2PKH (Pay to Public Key Hash, the standard script that locks coins to an address) to the address of the public key in `to` |
| `data` only | An OP_RETURN (A script that stores data in a transaction and can never be spent) output with 0 satoshis (The smallest unit of BitcoinSV (BSV): 1 BSV is 100,000,000 satoshis) |
| `to` and `data` | A PushDrop (A script that stores data fields and locks them to a public key, used for tokens) token for the key in `to`, kept in the `tokens` basket (A named group of outputs that a wallet tracks together) |

</BlueTable>

The inscription methods call `send()` with data outputs. `createToken()` builds its own transaction instead. It encrypts the data with the wallet first and then locks it in a PushDrop token, so only the wallet can read it.

To pay someone, there are two options:

- `pay()` delivers the transaction to the recipient's message box, and the recipient accepts it with `acceptIncomingPayment()`. With `@bsv/message-box-client` 2.7.0, the current release, `pay()` returns an empty `txid`.
- `createPaymentRequest()`, `sendDirectPayment()` and `receiveDirectPayment()` work without a message box. Like `pay()`, they derive the recipient's key with BRC-29 (BSV Request for Comments 29, payments to a key derived for each payment). The recipient creates a request, the sender's wallet builds the transaction, and the recipient's wallet adds the output to its balance.

## When to use `WalletClient` instead

`WalletClient` from `@bsv/sdk` is the standard way for an app to talk to the user's wallet, and `@bsv/simple` adds shortcuts on top of it. The shortcuts fit apps that work with tokens, inscriptions or message box payments, and servers that need a wallet with sensible defaults.

Call `WalletClient` yourself when you need:

- Your own `createAction()` arguments, such as inputs or labels. `send()` does not take them, and it fixes the broadcast options.
- The transaction ID of a payment, which `pay()` does not return.
- Fewer packages. `@bsv/simple` also installs `@bsv/wallet-toolbox` and `@bsv/message-box-client`, even in an app that only runs in the browser. It needs `@bsv/sdk` as a peer, 2.4.1 or later in 2.x, any 3.x, or 4.0.1 or later in 4.x.

You can also mix both. `getClient()` returns the same wallet as a BRC-100 interface, so your app can use the shortcuts for most calls and the wallet methods for the rest.

## Other parts of the package

These parts matter once you build a backend or work with identity:

### Server helpers for HTTP routes

`@bsv/simple/server` can serve a server wallet over HTTP. `createServerWalletHandler()` returns Next.js route handlers. Each action answers with HTTP 403 until your `authorize` callback returns `true` for it, so a route stays closed until you decide who may call it.

`ServerWalletManager` creates the server wallet once and keeps its key. It reads the key from `SERVER_PRIVATE_KEY`. Without it, the manager reads `.server-wallet.json` in the working folder, or generates a key and saves it there. Add that file to `.gitignore`, because it holds the private key.

`IdentityRegistry` stores handles for identity keys, with no authentication. Anyone who reaches it can register or revoke a handle for another key. Put it behind your own login before you expose it.

### Classes that work without a wallet object

- `DID` turns an identity key into a `did:key` identifier and resolves it offline. Version 0.7.0 replaced the earlier DID and credential tooling with these classes, so older material that uses `registerDID()` or `did:bsv` identifiers no longer applies.
- `Certifier`, `CredentialSchema` and `CredentialIssuer` issue and verify certificates and credentials. `MemoryRevocationStore` keeps revocation records in memory, and `FileRevocationStore` keeps them in a file on the server.
- `Overlay` creates a topic broadcaster (A client that sends a transaction to the overlay hosts that accept its topic) and a lookup resolver (A client that asks overlay hosts for data they track) for the `mainnet`, `testnet`, `teratestnet` or `local` preset, and uses `mainnet` when you set none.

### Defaults you can set

The `createWallet()` options set the values the methods fall back on: the network, the transaction and output descriptions, the token basket and protocol, and the message box host, `https://messagebox.babbage.systems` by default. `ServerWallet.create()` sets only the network, so on the server the other defaults stay as they are.

### Packages it depends on

- `@bsv/sdk`, a peer dependency: `WalletClient`, scripts, keys, certificates and the overlay clients.
- `@bsv/wallet-toolbox`: the wallet inside `ServerWallet`.
- `@bsv/message-box-client`: `pay()`, the MessageBox methods and tokens sent through a message box.
- `@bsv/did`: DIDs and credentials.

## Related articles

To learn more about how wallets and packages fit together on the BSV blockchain, review these articles:

- [How the BSV blockchain stack fits together](https://bsvblockchain.com/docs/concepts/architecture/)
- [BRC-100 Wallet Interface](https://bsvblockchain.com/docs/concepts/wallet-model/)