---
name: bsv-backup-and-recovery
description: "Design the backup and recovery flow for a BSV wallet: why a complete backup has two parts, setting up the records backup silently, asking for recovery words or shares when there is something worth protecting, showing both halves' state, and restoring honestly. Use when asked to 'design the backup flow', 'add recovery words', 'write the recovery screens', 'what do we back up', 'restore a wallet', or anything about a BSV user not losing access to their money."
---

> Start from [bitcoinsv-design](../bitcoinsv-design/SKILL.md). Shared states, labels, errors, amounts and fees: [shared patterns](../bitcoinsv-design/references/shared-patterns.md).

# Design BSV wallet backup and recovery

**Scope:** Backup and recovery for a wallet: what each half contains, when to ask, how to show it, and how to restore.

**Does NOT cover:**

- Multi-key and time-based arrangements: see [bsv-script-conditions](../bsv-script-conditions/SKILL.md)

**Cross-references:** [bsv-script-conditions](../bsv-script-conditions/SKILL.md), [bsv-payments](../bsv-payments/SKILL.md), [shared patterns](../bitcoinsv-design/references/shared-patterns.md).

For a modern BSV wallet a complete backup has two parts: key recovery material (recovery words, a recovery key or shares) that restores signing authority, and wallet records that say which outputs are the user's and what is needed to spend them. A BSV wallet derives a fresh key for each payment from both parties' keys plus payment details, and those details live in the records, not on the chain. Words alone can restore a wallet that holds the right key and cannot find the money. Never tell users "these words are your wallet" unless that is true of yours.

## ALWAYS

- Encrypt on the device, before anything is sent. The service should only ever hold a blob it cannot read. _([costs money](https://www.bitcoinsv.design/guide/rule/78bc2950f3/))_
- Walk the recovery path assuming the device is gone, not locked, and remove every step that needs something only that device had. _([costs money](https://www.bitcoinsv.design/guide/rule/c22b55aa20/))_
- Show when the last backup ran, on a screen the user sees often. A backup that silently stopped three months ago fails exactly when it is needed. _([costs money](https://www.bitcoinsv.design/guide/rule/0994527ea9/))_
- Explain first, in two sentences: what the words do, and that a photograph of them is a copy of the money. Then show them. _([costs money](https://www.bitcoinsv.design/guide/rule/55c4347112/))_
- Disable screenshots on this screen where the platform allows it, and say why rather than failing silently. _([costs money](https://www.bitcoinsv.design/guide/rule/5836d4dc2f/))_
- Offer shares as an alternative, not an addition. Words and shares are two encodings of the same secret, so holding both makes two complete copies to protect rather than a safer arrangement. _([costs money](https://www.bitcoinsv.design/guide/rule/805502c7da/))_

## NEVER

- 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. _([costs money](https://www.bitcoinsv.design/guide/rule/1dcc7454f0/))_
- Let the master identity key sign payments or messages directly, and never expose a child private key derived against anyone. _([costs money](https://www.bitcoinsv.design/guide/rule/bd0e68876f/))_
- Imply that recovery words move between wallet families. "Compatible with any bitcoin wallet" is false here, and a user who believes it will conclude their money is gone. _([costs money](https://www.bitcoinsv.design/guide/rule/2377e802d8/))_
- Let the words reach a screenshot, a cloud note, a password manager on the same device, or a chat message. Disable screenshots on that screen where the platform allows it, and say why. _([costs money](https://www.bitcoinsv.design/guide/rule/fd2bd65519/))_
- Store the root private key on a remote service in a form the service can decrypt. That is custody, and it should be described as custody. _([costs money](https://www.bitcoinsv.design/guide/rule/f728c8f93c/))_
- Derive the encryption key from something the provider also holds. If the provider can decrypt it, the user is not self-custodying and the screen should not say they are. _([costs money](https://www.bitcoinsv.design/guide/rule/fa511c9f66/))_

## Patterns

### 1. Back up the records silently

**When:** During onboarding, before there is money.

**How:**

1. Set up the records backup automatically and explain it in one line: "Your wallet keeps an encrypted backup so a new phone can find your money. Only you can open it."
2. Encrypt on the device before anything is sent; the service holds a blob it cannot read. Use the documented wallet data format (BRC-38, encrypted with BRC-39).
3. Let the user choose a provider or run their own, support more than one destination, and never turn remote storage on without saying so.
4. Show the last success as a time, not a tick, somewhere the user passes regularly, and say when it has stopped running.

_Source: [Automatic cloud backup](https://www.bitcoinsv.design/guide/daily-spending-wallet/backup-and-recovery/cloud-backup/)_

### 2. Ask for the key backup when it matters

**When:** The balance first crosses something the user would mind losing.

**How:**

1. Prompt then, in terms of the balance: "Back up your wallet to protect the 4,200 sats you're holding." Never show recovery words to somebody with nothing to lose.
2. Explain first in two sentences: what the words do, and that a photograph of them is a copy of the money. Then show them numbered in a fixed grid, with screenshots disabled and no copy button.
3. Say which kind of words these are; recovery words do not move between wallet families. Confirm a few words at positions the user must read, then ask where the paper will live.
4. Offer shares (BRC-140) as an alternative, not an addition: two encodings of the same secret are two complete copies to protect.

_Source: [Manual backup](https://www.bitcoinsv.design/guide/daily-spending-wallet/backup-and-recovery/manual-backup/)_

### 3. Show both halves, separately

**When:** Settings, the backup screen, and anywhere "backed up" is shown.

**How:**

1. Put both on one screen, each with its own state: when the records were last backed up, and whether the recovery words have been written down.
2. Never call the whole thing "backup" with one tick. Say on the records screen that it does not back up the keys.
3. Offer a recovery check at any time that asks for the words and confirms they match without moving money.

_Source: [Backup and recovery](https://www.bitcoinsv.design/guide/daily-spending-wallet/backup-and-recovery/landing-page/)_

### 4. Recover, and say what came back

**When:** A new device, a lost phone, a reinstall.

**How:**

1. Put "I already have a wallet" on the first screen, as prominent as creating one. Do not call it "import".
2. Restore keys, then find the records, then check payments, saying each step in words. Make it interruptible and resumable.
3. Show what came back: balance, recent activity, contacts, tokens. Name anything that did not and what it means. Never report a zero balance as a fact; it is what the wallet currently knows about.
4. Re-establish the backup on the new device, and say so. If the old device was stolen rather than lost, prompt about moving to fresh keys.

**Error states:**

- **The words do not validate:** Say what is wrong: a word not in the list, a word in the wrong position, or a checksum failure meaning one word is wrong. Never clear the field.

_Source: [Recovery](https://www.bitcoinsv.design/guide/daily-spending-wallet/backup-and-recovery/recovery/)_

## All the rules

`references/rules.md`: 85 rules from 8 pages, 40 of them costly, most costly first.
Every rule in the guide, most costly first: https://www.bitcoinsv.design/api/rules.json

## Implementation resources

- **[Wallet Toolbox storage](https://github.com/bsv-blockchain/wallet-toolbox)**: Where a wallet's records live, and therefore what the records half of the backup has to capture.
- **[@bsv/sdk](https://bsv-blockchain.github.io/ts-sdk/)**: The TypeScript SDK: `WalletClient` for every BRC-100 call, `AuthFetch` for HTTP 402, transactions, scripts and BEEF. Source at github.com/bsv-blockchain/ts-sdk.
- **[Wallet Toolbox](https://github.com/bsv-blockchain/wallet-toolbox)**: The wallet side of the interface: storage, signing and `WalletPermissionsManager`. Start here if you are building a wallet rather than an app.
- **[BRCs](https://github.com/bsv-blockchain/BRCs)**: Every proposal the skills cite, by number.

---

_Generated from https://www.bitcoinsv.design/, Open BSV License Version 6. Rules are extracted from the guide's pages and cannot be out of date about what it says; the patterns may still need updating._