Backups
What a complete BSV wallet backup contains, why recovery words alone may not be enough, and how to design backup and recovery honestly.
Owning BSV yourself means being able to get it back when a phone is lost, broken or replaced, and that depends on the backup. This page explains what a complete backup contains, and how to design backup flows that tell users the truth about it.
The short version
For a modern BSV wallet, a complete backup has two parts:
- Key recovery material. Something that restores the user's signing authority, such as recovery words, a recovery key, or key shares held in different places.
- Wallet records. The wallet's own data: which outputs belong to the user, and the details needed to spend them.
Your recovery words restore your keys. Your wallet backup restores your records: which money is yours and how to spend it. Keep both. Losing either one can lose money: words without the records may not find all of it, and records without the keys cannot spend any of it.
Recommendation
Never tell users "these words are your wallet" unless that is true for your wallet. Say plainly what the backup covers and what it doesn't.
Why words alone may not be enough
Seed-only wallets derive every address from the words in a fixed sequence, so the words alone can find everything (see Legacy compatibility).
A modern BSV wallet derives a fresh key for each payment from both parties' keys plus payment-specific details (BRC-42), as described in Payments. Those details, such as who sent the payment and the derivation values that came with it, live in the wallet's records, not on the blockchain. Without them, a recovered wallet may not know which outputs are the user's, even though it holds the right root key.
Two more things follow:
- Words restore only in wallets that use the same scheme. Wallets using BSV recovery words (BRC-75) derive keys differently from seed-only wallets (BIP-39/BIP-44). The same words entered into a different kind of wallet may show a different, often empty, balance.
- Tokens and app assets need more again. Their value can depend on scripts, baskets and overlay services that a plain key restore will not bring back.
What to back up
Help users, or your backend, keep each of these:
| Part | Contains | Who usually holds it |
|---|---|---|
| Key recovery material | Recovery words, recovery key or key shares | The user, offline |
| Wallet records | Outputs, payment derivation details, baskets, labels, Passes, pending work | The wallet: local file, encrypted export, or a storage service |
| App-specific data | Contacts, settings, token state the wallet doesn't hold | The app |
Don't
Protect a backup with a password manager or account that lived only on the lost phone. That is not a backup. See Cloud backup › The circular-dependency trap.
Designing the backup flow
Make storage local by default
Wallet records live on the device unless the user chooses otherwise. Remote storage and sync are an opt-in the user makes knowingly, never switched on silently.
Do
Keep wallet records on the device by default, and make remote storage a separate, explained opt-in.
Do
Encrypt records on the device before they are sent anywhere.
When remote storage is used, never store the root private key remotely in a form the service can decrypt. Let users choose, or host, their storage provider, and support more than one backup location.
Offer an encrypted export
Give users an export they hold themselves, such as an encrypted file, that contains everything needed to rebuild the wallet records. A user should be able to recover without the original wallet vendor or storage provider. The wallet data format (BRC-38 and BRC-39) is the portable form of this.
Back up records continuously
Every incoming payment adds records. A backup from last week will not include this week's payments.
Do
Back up records automatically and show when the last backup ran.
Explain it in two lines
Users do not need the cryptography. A backup screen can say:
Your recovery words restore your keys. Your wallet backup restores your records: which money is yours and how to spend it. Keep both.
Recovery
A recovery flow restores both parts and shows the user what came back:
- Restore signing authority from the key recovery material.
- Restore wallet records from the export or storage service.
- Show the restored balance, recent activity and any tokens.
- Point out anything that could not be restored, such as token types the wallet does not support.
Always provide an exit
Every consumer wallet needs a way to send to a plain address that works without the vendor. See Legacy compatibility.
Test recovery before launch
A backup that has never been restored is an assumption. Before a wallet holds real money, run a full recovery drill. Cloud backup has the shorter version for one backup path.
- Fund a test wallet with ordinary BSV and every supported token type.
- Make payments across several apps and counterparties.
- Export the full user backup.
- Delete the original installation and its local data.
- Remove the original vendor and storage provider from the recovery path.
- Restore on a clean install, ideally with a different compatible wallet or an open recovery tool.
- Confirm all BSV and supported assets appear.
- Send the BSV to a plain address.
- Move each token to another compatible wallet without losing its status.
If a wallet cannot pass this drill, keep it experimental and limit it to small balances.
Related
- Wallet setups: keep savings outside the app-connected wallet
- Private key management
- Daily spending wallet: backup and recovery
Written from: ts-stack wallet backup and recovery guide, ts-stack recovery drill, BRC-151 §5, BRC-38/39, BRC-75.
Checklist
The rules on this page, in a form you can work through.
5 rules