Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 14 additions & 12 deletions src/content/docs/concepts/backup-and-recovery.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,34 +2,31 @@
title: Backup and recovery
description: What the recovery phrase restores, what it does not, and which of the five ways to lose a wallet has no way back.
sourceRepo: bitcoinuniverseio/wallet
sourcePath: backend/service/keyring, frontend/ui/pages/Settings/ExportMnemonicsScreen.tsx
sourcePath: backend/background/service/keyring.ts, frontend/ui/pages/Settings/ExportMnemonicsScreen.tsx
lifecycle: experimental
lastVerified: 2026-09-01
lastVerified: 2026-09-18
---

import Diagram from '../../../components/Diagram.astro';
import BackupRecovery from '../../../components/diagrams/BackupRecovery.astro';
import { Aside } from '@astrojs/starlight/components';

Your coins are not in the extension. They are on the chain. The extension holds the keys that
authorize moving them, and the recovery phrase reproduces those keys anywhere.
authorize moving them. A compatible wallet can reproduce phrase-derived keys from the same recovery details.

<Diagram title="Which loss the recovery phrase covers, and the one it does not">
<BackupRecovery />
<span slot="caption">
Four of these five situations are recoverable from paper alone. The fifth has no path back, for
anyone.
This diagram concerns keys derived from the recovery phrase. Separate device keys, channel
state and product backups have additional recovery requirements.
</span>
</Diagram>

## What the phrase restores

Everything that is money:
The phrase restores keys derived from that phrase when the receiving wallet uses the same passphrase, derivation paths, network and address formats. BIP-39 compatibility alone does not establish support for every account or product.

- every account in the wallet,
- every network,
- every address type,
- on any device, in any BIP-39 compatible wallet, not only this one.
Separately imported keys and hardware-wallet keys require their own backups. This page does not promise seed-only recovery of Lightning channel state, Taproot Assets proofs and databases, Spark recovery data or mobile pairing state.

## What the phrase does not restore

Expand All @@ -41,8 +38,7 @@ Everything that is a setting:
- coins you locked yourself,
- spending limits.

These live on the device. After a restore, your funds and assets are all there, and your preferences
are not. Expect to set them up again. Nothing about that indicates a failed restore.
These settings live on the device. After restoring keys, check known addresses, the selected network and authoritative balances before using the wallet. Restore separate product backups where required. Missing history or preferences does not by itself prove that funds were lost.

## The five situations

Expand Down Expand Up @@ -88,3 +84,9 @@ The window closes the moment anything happens to that browser profile.
- [Back up your recovery phrase](/docs-wallet/start/back-up)
- [Import an existing wallet](/docs-wallet/start/import-a-wallet)
- [Locking and passwords](/docs-wallet/tasks/lock-and-password)

## Interrupted operations and device pairing

A storage error or missing reply does not prove that a payment failed. Keep the original operation reference and check that operation instead of creating another payment. Do not erase unresolved history to clear an error.

Development work on authenticated mobile metadata receipts and interrupted-pairing recovery does not mean mobile pairing is publicly released. Pairing keys, replay counters and metadata history are not recreated by the recovery phrase. Do not copy an old counter backward or reuse an old pairing key after a reset. Public capabilities remain those listed by the current release, not those present only in source.
19 changes: 10 additions & 9 deletions src/content/docs/tasks/switch-chain-and-network.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
title: Switch chain and network
description: Change which chain and network the wallet is showing, and understand what that does to connected sites and to your addresses.
sourceRepo: bitcoinuniverseio/wallet
sourcePath: frontend/ui/pages/Settings/NetworkTypeScreen.tsx
sourcePath: frontend/ui/pages/Settings/SwitchChainModal.tsx, frontend/ui/state/accounts/hooks.ts
lifecycle: experimental
lastVerified: 2026-09-01
lastVerified: 2026-09-18
---

**Intended reader:** anyone using more than one chain, or testing on a test network.
Expand All @@ -15,10 +15,10 @@ an address.

## Steps

1. Open **Settings**, then **Network**.
1. Open the network selector in the wallet header.
2. The screen lists every network the build knows about, and states how many are selectable.
3. Choose one. Entries a build has not enabled are marked **Coming soon** and cannot be selected.
4. Confirm the network name now shown at the top of the wallet.
3. Choose one. Unavailable entries cannot be selected.
4. Confirm both the network name and the selected account before copying an address or reviewing a request.

## The list

Expand All @@ -35,7 +35,7 @@ Dogecoin Testnet, Zcash, Zcash Testnet, Fractal Bitcoin, and Fractal Bitcoin Tes

## What does not change

- Your recovery phrase. One phrase covers every network.
- Your saved recovery phrase or separately imported keys. Switching does not replace them.
- Anything on any chain. Switching is a view change, not a transaction.
- Existing connections. A connection is granted for one address on one network, and switching does
not extend it to another. A site that needs the other network has to request it.
Expand All @@ -52,18 +52,19 @@ The wallet header shows the network you chose, and the balance and assets are th
## How to verify

- The network name in the wallet header is the one you selected.
- The receiving address has the prefix you expect for that network.
- The receiving address matches the selected account. A prefix alone does not distinguish Bitcoin Signet from Testnet or Testnet4.
- The balance matches what you expect for that network, which for a test network is usually zero until
you use a faucet.

## Common failures

| What you see | What it means | What to do |
| --- | --- | --- |
| Balance is zero after switching | Correct. That network holds nothing yet. | Switch back, or fund it |
| An entry is marked Coming soon | The build did not enable that network | Nothing you can change locally |
| Balance is missing or zero after switching | The account may be unfunded, or its data may still be loading or unavailable | Check the account and network, then wait for the balance read to finish |
| An entry is unavailable | The build did not enable that network | Use an enabled network; do not try to override the restriction |
| A connected site stops working | Its grant was for the other network | Reconnect on the network you are using |
| A switch prompt appeared unexpectedly | A page requested it | Read the network being requested. Reject if unclear. |
| A request reports an account or network mismatch | Its response does not match the selected wallet context | Reopen it for the selected account; check an existing operation before starting another payment |

## Related

Expand Down
Loading