BSV blockchainBSV blockchain

How @bsv/simple is built

@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-100BSV 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.

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:

Where your code runsHow you create itWallet underneathWho holds the key
BrowsercreateWallet() from @bsv/simpleWalletClient from @bsv/sdk, connected to the user’s walletThe user’s wallet app
ServerServerWallet.create() from @bsv/simple/serverWallet from @bsv/wallet-toolboxYour server

In the browser, createWallet() connects to the wallet app the user has, such as BSV Desktop on a computer or 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:

LayerExamples of methodsWhat it is for
Base classsend(), pay(), getBalance()Sending transactions and reading the balance
TokenscreateToken(), sendToken()Tokens that carry your own data
InscriptionsinscribeText(), inscribeJSON()Data written on chain
MessageBoxsendMessageBoxPayment(), lookupIdentityByTag()Payments and messages through a message boxA server that holds messages and payments for a recipient until the recipient collects them
CertificationacquireCertificateFrom()Certificates from a certifierA server that checks a claim about a user and signs a certificate for their identity key
OverlayadvertiseSHIP(), broadcastAction()Publishing to overlayServices that track selected transactions and answer queries about them services
DIDgetDID(), resolveDID()DIDsDecentralized identifier, a W3C identifier that the holder controls for an identity keyThe public key that identifies a wallet to apps and other users
CredentialsacquireCredential()Verifiable credentialsCertificates packaged so a third party can check who issued them

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:

Fields in the outputScript it becomes
to onlyP2PKHPay to Public Key Hash, the standard script that locks coins to an address to the address of the public key in to
data onlyAn OP_RETURNA script that stores data in a transaction and can never be spent output with 0 satoshisThe smallest unit of BitcoinSV (BSV): 1 BSV is 100,000,000 satoshis
to and dataA PushDropA 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 basketA named group of outputs that a wallet tracks together

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-29BSV 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 broadcasterA client that sends a transaction to the overlay hosts that accept its topic and a lookup resolverA 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.

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