Plug in your own storage
Choose where a @bsv/wallet-toolbox wallet keeps its records, then copy them to a backup database and to a storage server you run. At the end, a testnet wallet works on a SQLite database you open yourself, keeps a copy in a second database and on a local server, and can switch its active store from one to another. Plug in your own storage when the records must live in your database or on your servers, when a wallet needs a backup, or when you move a wallet from one store to another. The example runs standalone, with a test wallet that holds no coins.
Before you begin
You need Node.js 22 or newer. This page was written against @bsv/wallet-toolbox 2.15.1, @bsv/sdk 4.0.1, knex 3.3.0 and better-sqlite3 13.0.3.
How it works
A BRC-100BSV Request for Comments 100, the standard interface between apps and wallets wallet built with the toolbox never talks to a database directly. It passes every read and write to WalletStorageManager, which holds one active store and any number of backup stores:
- Wallet
Runs a BRC-100 method such as createAction or listOutputs
- WalletStorageManager
Sends every read and write to the active store
- Active store
Holds the records the wallet works on
- Active store
Holds the current state of the wallet
- WalletStorageManager
Copies the changes with updateBackups or setActive
- Backup stores
Hold a copy, on the same machine or on your own server
A store is any object that implements the WalletStorageProvider interface, and the toolbox ships three:
| Provider | Where the records live | Use it for |
|---|---|---|
StorageKnex | A SQL database reached through Knex: SQLite, MySQL or Postgres | A wallet in Node.js, on your own database |
StorageIdb | IndexedDB in the browser, from the @bsv/wallet-toolbox-client package | A wallet that keeps its records on the user’s device |
StorageClient | A StorageServer reached over JSON-RPCA remote procedure call protocol that sends JSON over HTTP, with BRC-103Mutual authentication, where the wallet and the server prove their identity keys to each other mutual authentication | A wallet whose records live on a server you run |
Only the active store takes writes. StorageKnex supports SQLite, MySQL and Postgres through Knex, and the example on this page uses SQLite for every store.
Set up the project
The first step is to set up a Node.js project folder with the packages and a test wallet:
Install the packages
Run this in an empty project folder:
npm init -y
npm install @bsv/wallet-toolbox @bsv/sdk knex better-sqlite3knex and better-sqlite3 are the driver of the SQLite stores.
Keep secrets out of git
Create .gitignore in the project folder before any key exists:
.env
*.sqlite
node_modulesThe .sqlite files hold the wallet’s records, so they stay out of git like the keys.
Generate the keys
The .env file holds the private keys of the test wallet. Keep it out of git, never print it or paste it into code, and use this wallet only on testnet.
Write the keys of a test wallet to .env with Setup.makeEnv(). Save this script as create-env.mjs and run it once with node create-env.mjs:
import { existsSync, writeFileSync } from 'node:fs'
import { Setup } from '@bsv/wallet-toolbox'
if (existsSync('.env')) {
console.log('.env already exists, nothing was written.')
} else {
writeFileSync('.env', Setup.makeEnv(), { mode: 0o600 })
console.log('Wrote the test wallet keys to .env.')
}Wrote the test wallet keys to .env.The script does not replace an existing .env. The file holds two test identities, one for the wallet and one for the storage server later on this page. Setup.makeEnv() also writes two Mainnet identities and placeholder API keys, which this page does not use.
Open the wallet on your own database
With the keys in place, build the wallet by hand, so you choose each store instead of letting Setup choose one:
Write the store factory
Create storage.mjs. It opens a SQLite file through Knex, creates the toolbox tables, and returns a ready store:
import knex from 'knex'
import { StorageKnex, randomBytesHex } from '@bsv/wallet-toolbox'
export async function openSQLiteStorage (filename, storageName) {
const db = knex({
client: 'better-sqlite3',
connection: { filename },
useNullAsDefault: true
})
const storage = new StorageKnex({
...StorageKnex.defaultOptions(),
chain: 'test',
knex: db
})
await storage.migrate(storageName, randomBytesHex(33))
await storage.makeAvailable()
return storage
}knexis the Knex instance the store works on, here a SQLite file opened withbetter-sqlite3.StorageKnex.defaultOptions()sets the fee model and turns commission fees off.migratecreates or updates the tables. It writes the storage name and the random storage identity key on the first run only, and later runs keep them.
Build the wallet
Add wallet.mjs to the same folder. It opens two stores, gives them to WalletStorageManager with main as the active store, and builds the wallet on top:
import { PrivateKey, CachedKeyDeriver } from '@bsv/sdk'
import { Setup, Services, Wallet, WalletStorageManager } from '@bsv/wallet-toolbox'
import { openSQLiteStorage } from './storage.mjs'
process.loadEnvFile('.env')
const env = Setup.getEnv('test')
export async function openWallet () {
const rootKey = PrivateKey.fromHex(env.devKeys[env.identityKey])
const identityKey = rootKey.toPublicKey().toString()
const main = await openSQLiteStorage('./main.sqlite', 'main')
const backup = await openSQLiteStorage('./backup.sqlite', 'backup')
const services = new Services('test')
const storage = new WalletStorageManager(identityKey, main, [backup])
storage.setServices(services)
await storage.makeAvailable()
if (storage.getConflictingStores().length > 0) {
await storage.setActive(storage.getActiveStore())
}
const wallet = new Wallet({
chain: 'test',
keyDeriver: new CachedKeyDeriver(rootKey),
storage,
services
})
return { wallet, storage }
}
export function showStores (storage) {
for (const s of storage.getStores()) {
console.log(`${s.storageName}: ${s.isActive ? 'active' : 'backup'}`)
}
}
export function printSync (log) {
console.log(log.split('\n').filter(line => line.startsWith('syncToWriter')).join('\n'))
}process.loadEnvFileloads.env, andSetup.getEnv('test')picks the testnet identities and their keys.- The second argument of
WalletStorageManageris the active store, and the third is the list of backups. - A store that was never synced starts as a conflicting store, and the manager refuses writes until the conflict is resolved. On the first run
backupis one, sosetActiveon the current active store merges it and turns it into a backup.
Check the stores
Print the stores the wallet opened with check.mjs, then run it with node check.mjs:
import { openWallet, showStores } from './wallet.mjs'
const { wallet, storage } = await openWallet()
showStores(storage)
await wallet.destroy()main: active
backup: backupThe project folder now has main.sqlite and backup.sqlite, each with the toolbox tables.
Back up and switch the active store
A new wallet has nothing to copy yet, so the first step adds one record to the active store, and the next ones copy it:
Add a record to the wallet
Save this as add-certificate.mjs. It issues a test identity certificate from a throwaway certifier and stores it in the wallet, which needs no coins:
import { Hash, MasterCertificate, PrivateKey, ProtoWallet, Utils } from '@bsv/sdk'
import { openWallet } from './wallet.mjs'
const { wallet } = await openWallet()
const { publicKey: subject } = await wallet.getPublicKey({ identityKey: true })
const certifier = new ProtoWallet(PrivateKey.fromRandom())
const type = Utils.toBase64(Hash.sha256('storage test', 'utf8'))
const cert = await MasterCertificate.issueCertificateForSubject(certifier, subject, { name: 'Alice' }, type, async () => '00'.repeat(32) + '.0')
await wallet.acquireCertificate({
acquisitionProtocol: 'direct',
type: cert.type,
certifier: cert.certifier,
serialNumber: cert.serialNumber,
revocationOutpoint: cert.revocationOutpoint,
signature: cert.signature,
fields: cert.fields,
keyringRevealer: 'certifier',
keyringForSubject: cert.masterKeyring
})
const { totalCertificates } = await wallet.listCertificates({ certifiers: [cert.certifier], types: [type] })
console.log('Certificates in the active store:', totalCertificates)
await wallet.destroy()- The certificate
typemust be 32 bytes in base64, so the script hashes a label. The last argument ofissueCertificateForSubjectreturns a placeholder revocation outpoint, so the certificate needs no transaction on chain. keyringRevealer: 'certifier'tells the wallet that the certifier encryptedkeyringForSubject, the keys that open the certificate fields.
Run it with node add-certificate.mjs:
Certificates in the active store: 1The wallet wrote the certificate to main only. Every other wallet write, such as a transaction from createAction, goes to the active store the same way.
Copy the changes to the backup
Create backup.mjs, which calls updateBackups to push what changed in the active store to every backup:
import { openWallet, printSync } from './wallet.mjs'
const { wallet, storage } = await openWallet()
printSync(await storage.updateBackups())
await wallet.destroy()Run it with node backup.mjs:
syncToWriter from main to backup
syncToWriter complete: 2 inserts, 0 updatesThe two inserts are the certificate and its field. A second run prints 0 inserts, 0 updates, because each store keeps a sync state that records what it already has.
Switch the active store
Write switch.mjs, which makes the store named on the command line the active one and reads the certificates from it:
import { openWallet, showStores } from './wallet.mjs'
const target = process.argv[2]
const { wallet, storage } = await openWallet()
const store = storage.getStores().find(s => s.storageName === target)
if (!store) {
console.log('Use main or backup, for example: node switch.mjs main')
await wallet.destroy()
process.exit(1)
}
await storage.setActive(store.storageIdentityKey)
showStores(storage)
const { totalCertificates } = await wallet.listCertificates({ certifiers: [], types: [] })
console.log('Certificates in the active store:', totalCertificates)
await wallet.destroy()Run it with node switch.mjs backup:
backup: active
main: backup
Certificates in the active store: 1setActive first copies the current active store to the others, then records the new choice in every store. The choice persists, so node check.mjs now also prints backup: active. The next section expects main to be the active store, so switch back now with node switch.mjs main. The first two lines list main as active and backup as backup, and the certificate count stays the same.
Keep a backup on your own server
The same wallet can also keep a copy on a server you run. StorageServer puts a StorageKnex store behind an authenticated endpoint, and the wallet reaches it with StorageClient:
Start the storage server
Create server.mjs. It opens a third SQLite file and serves it on port 8100, with the second test identity from .env as the server’s own key:
import { PrivateKey, CachedKeyDeriver } from '@bsv/sdk'
import { Setup, Services, StorageServer, Wallet, WalletStorageManager } from '@bsv/wallet-toolbox'
import { openSQLiteStorage } from './storage.mjs'
process.loadEnvFile('.env')
const env = Setup.getEnv('test')
const serverKey = PrivateKey.fromHex(env.devKeys[env.identityKey2])
const storage = await openSQLiteStorage('./server.sqlite', 'server')
const services = new Services('test')
storage.setServices(services)
const wallet = new Wallet({
chain: 'test',
keyDeriver: new CachedKeyDeriver(serverKey),
storage: new WalletStorageManager(serverKey.toPublicKey().toString(), storage),
services
})
const server = new StorageServer(storage, { host: 'localhost', port: 8100, wallet, monetize: false })
server.start()Run it in a second terminal with node server.mjs and leave it running:
WalletStorageServer listening at http://localhost:8100- The server’s own wallet answers the BRC-103 handshake. Each client proves its identity key, and the server checks that every request asks only for that client’s records.
monetize: falselets clients call the server without paying per request.host: 'localhost'keeps the server off the network, and without it the server listens on every interface. The example serves plain HTTP, so put the server behind HTTPS before another machine reaches it.
Add the server as a backup
Back in the first terminal, create remote-backup.mjs. It adds a StorageClient for the server to the wallet’s stores and merges it the same way as the local backup:
import { StorageClient } from '@bsv/wallet-toolbox'
import { openWallet, showStores, printSync } from './wallet.mjs'
const { wallet, storage } = await openWallet()
const remote = new StorageClient(wallet, 'http://localhost:8100')
await storage.addWalletStorageProvider(remote)
if (storage.getConflictingStores().length > 0) {
printSync(await storage.setActive(storage.getActiveStore()))
}
showStores(storage)
await wallet.destroy()StorageClientsigns each request with the wallet’s identity key, so the wallet must exist before the client.addWalletStorageProvideradds a store to a manager that is already open. In your own wallet, add the client inopenWalletto keep the server on every run.
Run node remote-backup.mjs:
syncToWriter from server to main
syncToWriter complete: 0 inserts, 0 updates
syncToWriter from main to backup
syncToWriter complete: 0 inserts, 1 updates
syncToWriter from main to server
syncToWriter complete: 2 inserts, 1 updates
main: active
backup: backup
server: backupsetActive first merges the new store into the active one, from server to main, and then pushes the active state to every other store. The certificate reaches the server as the two inserts.
The wallet now works on main, keeps copies in backup.sqlite and on your storage server, and can make any of the three its active store with setActive. The server keeps running until you stop it with Ctrl+C.
Write your own provider
When none of the built-in providers fits, such as a database that Knex does not support, write a provider of your own. There are two routes, and the toolbox’s own providers show both:
| Route | What you implement | Example in the toolbox |
|---|---|---|
Extend StorageProvider | Table level methods such as find, insert and update, and the toolbox runs the wallet logic on top | StorageKnex, StorageIdb |
Implement WalletStorageProvider | Every wallet level method, with isStorageProvider() returning false | StorageClient |
The methods to implement are in WalletStorage.interfaces.ts and, for the first route, in StorageProvider.ts and the classes it extends. StorageIdb.ts shows a store that is not SQL. Either kind of provider plugs into WalletStorageManager like the SQLite stores above.
The route also decides whether the Monitor can run. Its tasks run only when the active store is a full StorageProvider, and they fail when isStorageProvider() returns false. For what those tasks do, see What the Monitor settles in the background.
Troubleshooting
Wallet refuses to write after a new store is added #
The wallet throws WERR_NOT_ACTIVE: WalletStorageManager is not accessing user's active storage or there are conflicting active stores configured. A store that was never synced starts as a conflicting store, and the manager allows reads but refuses writes until the conflict is resolved. Before the first write, call setActive with the identity key of the store you want active, as openWallet does with storage.getActiveStore().
Related articles
To learn more about how a BSV blockchain wallet keeps its records, review these articles: