From fca71bc4f98d14d614368544ea931c5527097153 Mon Sep 17 00:00:00 2001 From: migberto <146127140+migberto@users.noreply.github.com> Date: Fri, 18 Sep 2026 06:21:54 +0000 Subject: [PATCH 1/4] docs: clarify payment recovery and development-only mobile state --- .../docs/concepts/backup-and-recovery.mdx | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/src/content/docs/concepts/backup-and-recovery.mdx b/src/content/docs/concepts/backup-and-recovery.mdx index 643d0b1..302f81d 100644 --- a/src/content/docs/concepts/backup-and-recovery.mdx +++ b/src/content/docs/concepts/backup-and-recovery.mdx @@ -24,12 +24,9 @@ authorize moving them, and the recovery phrase reproduces those keys anywhere. ## 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 @@ -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 @@ -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 atomic mobile metadata receipts 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. From a364a0088343a3b2d907d5cd1b2d8ad6ad4a94de Mon Sep 17 00:00:00 2001 From: migberto <146127140+migberto@users.noreply.github.com> Date: Fri, 18 Sep 2026 06:46:06 +0000 Subject: [PATCH 2/4] docs: scope the recovery diagram and verify source metadata --- src/content/docs/concepts/backup-and-recovery.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/concepts/backup-and-recovery.mdx b/src/content/docs/concepts/backup-and-recovery.mdx index 302f81d..fe41d21 100644 --- a/src/content/docs/concepts/backup-and-recovery.mdx +++ b/src/content/docs/concepts/backup-and-recovery.mdx @@ -2,9 +2,9 @@ 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'; @@ -17,8 +17,8 @@ authorize moving them, and the recovery phrase reproduces those keys anywhere. - 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. From 7e8d33c7f5bc846b0e1608e7b14ecfd9abfcdc7a Mon Sep 17 00:00:00 2001 From: migberto <146127140+migberto@users.noreply.github.com> Date: Fri, 18 Sep 2026 12:39:45 +0000 Subject: [PATCH 3/4] docs: align wallet recovery boundaries and verification --- src/content/docs/concepts/backup-and-recovery.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/concepts/backup-and-recovery.mdx b/src/content/docs/concepts/backup-and-recovery.mdx index fe41d21..91bf378 100644 --- a/src/content/docs/concepts/backup-and-recovery.mdx +++ b/src/content/docs/concepts/backup-and-recovery.mdx @@ -12,7 +12,7 @@ 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. @@ -89,4 +89,4 @@ The window closes the moment anything happens to that browser profile. 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 atomic mobile metadata receipts 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. +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. From 85865742c357350259ca53e0b4aded06c6f74be4 Mon Sep 17 00:00:00 2001 From: migberto <146127140+migberto@users.noreply.github.com> Date: Fri, 18 Sep 2026 14:22:49 +0000 Subject: [PATCH 4/4] docs: explain network-scoped account reload and recovery --- .../docs/tasks/switch-chain-and-network.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/src/content/docs/tasks/switch-chain-and-network.md b/src/content/docs/tasks/switch-chain-and-network.md index 826ac30..4529c88 100644 --- a/src/content/docs/tasks/switch-chain-and-network.md +++ b/src/content/docs/tasks/switch-chain-and-network.md @@ -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. @@ -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 @@ -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. @@ -52,7 +52,7 @@ 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. @@ -60,10 +60,11 @@ The wallet header shows the network you chose, and the balance and assets are th | 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