# Plug in your own storage

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

WalletStorageManager in @bsv/wallet-toolbox keeps a wallet's records in an active store and copies them to backup stores: a database you open, a storage server you run, or a provider you write.

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

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-100 (BSV 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:

<StorageStoresFlow />

How WalletStorageManager uses its stores. Use: the Wallet runs a BRC-100 method such as createAction or listOutputs, WalletStorageManager sends every read and write to the active store, and the active store holds the records the wallet works on. Back up: the active store holds the current state of the wallet, WalletStorageManager copies the changes with updateBackups or setActive, and the 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:

<BlueTable>

| Provider | Where the records live | Use it for |
| --- | --- | --- |
| `StorageKnex` | A SQL database reached through [Knex](https://knexjs.org/): 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-RPC (A remote procedure call protocol that sends JSON over HTTP), with BRC-103 (Mutual 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 |

</BlueTable>

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:

**1. Install the packages**

Run this in an empty project folder:

```bash
npm init -y
npm install @bsv/wallet-toolbox @bsv/sdk knex better-sqlite3
```

`knex` and `better-sqlite3` are the driver of the SQLite stores.

**2. Keep secrets out of git**

Create `.gitignore` in the project folder before any key exists:

```text .gitignore
.env
*.sqlite
node_modules
```

The `.sqlite` files hold the wallet's records, so they stay out of git like the keys.

**3. 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`:

```javascript 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.')
}
```

```text
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:

**1. Write the store factory**

Create `storage.mjs`. It opens a SQLite file through Knex, creates the toolbox tables, and returns a ready store:

```javascript storage.mjs
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
}
```

- `knex` is the Knex instance the store works on, here a SQLite file opened with `better-sqlite3`.
- `StorageKnex.defaultOptions()` sets the fee model and turns commission fees off.
- `migrate` creates 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.

**2. 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:

```javascript wallet.mjs
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.loadEnvFile` loads `.env`, and `Setup.getEnv('test')` picks the testnet identities and their keys.
- The second argument of `WalletStorageManager` is 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 `backup` is one, so `setActive` on the current active store merges it and turns it into a backup.

**3. Check the stores**

Print the stores the wallet opened with `check.mjs`, then run it with `node check.mjs`:

```javascript check.mjs
import { openWallet, showStores } from './wallet.mjs'

const { wallet, storage } = await openWallet()
showStores(storage)
await wallet.destroy()
```

```text
main: active
backup: backup
```

The 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:

**1. 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:

```javascript add-certificate.mjs
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 `type` must be 32 bytes in base64, so the script hashes a label. The last argument of `issueCertificateForSubject` returns a placeholder revocation outpoint, so the certificate needs no transaction on chain.
- `keyringRevealer: 'certifier'` tells the wallet that the certifier encrypted `keyringForSubject`, the keys that open the certificate fields.

Run it with `node add-certificate.mjs`:

```text
Certificates in the active store: 1
```

The 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.

**2. Copy the changes to the backup**

Create `backup.mjs`, which calls `updateBackups` to push what changed in the active store to every backup:

```javascript backup.mjs
import { openWallet, printSync } from './wallet.mjs'

const { wallet, storage } = await openWallet()
printSync(await storage.updateBackups())
await wallet.destroy()
```

Run it with `node backup.mjs`:

```text
syncToWriter from main to backup
syncToWriter complete: 2 inserts, 0 updates
```

The 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.

**3. 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:

```javascript switch.mjs
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`:

```text
backup: active
main: backup
Certificates in the active store: 1
```

`setActive` 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`:

**1. 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:

```javascript server.mjs
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:

```text
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: false` lets 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.

**2. 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:

```javascript remote-backup.mjs
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()
```

- `StorageClient` signs each request with the wallet's identity key, so the wallet must exist before the client.
- `addWalletStorageProvider` adds a store to a manager that is already open. In your own wallet, add the client in `openWallet` to keep the server on every run.

Run `node remote-backup.mjs`:

```text
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: backup
```

`setActive` 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:

<BlueTable>

| 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` |

</BlueTable>

The methods to implement are in [`WalletStorage.interfaces.ts`](https://github.com/bsv-blockchain/ts-stack/blob/main/packages/wallet/wallet-toolbox/src/sdk/WalletStorage.interfaces.ts) and, for the first route, in [`StorageProvider.ts`](https://github.com/bsv-blockchain/ts-stack/blob/main/packages/wallet/wallet-toolbox/src/storage/StorageProvider.ts) and the classes it extends. [`StorageIdb.ts`](https://github.com/bsv-blockchain/ts-stack/blob/main/packages/wallet/wallet-toolbox/src/storage/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](https://bsvblockchain.com/docs/wallet-dev/wallet-toolbox/utxo-lifecycle/#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:

- [How the toolbox tracks UTXOs](https://bsvblockchain.com/docs/wallet-dev/wallet-toolbox/utxo-lifecycle/)
- [Build a wallet](https://bsvblockchain.com/docs/wallet-dev/)
- [BRC-100 Wallet Interface](https://bsvblockchain.com/docs/concepts/wallet-model/)