From 53a82b3b66855e8b6809bf5674a3e36c23c7eb77 Mon Sep 17 00:00:00 2001 From: Ben Westgate Date: Tue, 6 Oct 2026 22:03:41 +0000 Subject: [PATCH] docs: Trim offline signing to Core's tutorial The offline-signing section pointed at Bitcoin Core's tutorial but still referred to "the QR tools below" and kept a QR troubleshooting section, with no step that used them. Carrying descriptors, PSBTs and addresses by QR is a Tails wallet workflow, so it now lives in Bails (Bails#312, Bails#320) instead of this guide. Keep only what Core's maintained tutorial does not already say for a codex32 user: create an empty encrypted descriptor wallet with private keys enabled on the offline signer and run ms32 wallet; keep that computer permanently disconnected from every network as soon as Bitcoin Core and codex32 are installed; and do not use the offline boot USB stick as the transfer drive. Signing a PSBT needs no rescan, so the signer needs no chain history. Link the tutorial on master in both places so the link follows Core's maintained copy. Keep one safety step the tutorial does not state: verify every destination, amount and fee on the offline signer against the intended payment before signing, and do not trust the online host's summary. Removing the QR steps also removes their jq dependency, which Tails does not ship. Fixes #92 Closes #111 Claude-Session: https://claude.ai/code/session_01T233rKgZqE5wzDm3EVTHL1 --- docs/user/guide.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/docs/user/guide.md b/docs/user/guide.md index b875ab0..a91614c 100644 --- a/docs/user/guide.md +++ b/docs/user/guide.md @@ -89,8 +89,7 @@ port. Use a computer you believe is malware-free and whose other software you trust. Only codex32 and Bitcoin Core should perform recovery, derivation, wallet -initialization, or signing. The QR tools below transport only public -descriptors or PSBTs. +initialization, or signing. Bitcoin Core wallet encryption is strongly recommended. Bitcoin Core owns the passphrase and its prompts; codex32 never asks for, reads, or forwards it. @@ -203,15 +202,20 @@ worth the extra steps. ## More protection: watch-only wallet and offline signer On the offline signer, create an empty encrypted descriptor wallet with private -keys enabled and run `ms32 wallet`. Keep that computer disconnected from every -network while recovery text or signing keys are present. +keys enabled and run `ms32 wallet`. Keep that computer permanently disconnected +from every network as soon as Bitcoin Core and codex32 are installed and +disconnect before recovery text or signing keys are present. -After the signer is restored, follow Bitcoin Core v32's maintained +After the signer is restored, follow Bitcoin Core's maintained [offline-signing tutorial](https://github.com/bitcoin/bitcoin/blob/master/doc/offline-signing-tutorial.md). -That workflow owns the watch-only export/import and PSBT transport steps. In +That workflow owns the watch-only export/import and PSBT transport steps. +Note: an offline bootable USB stick is not the transfer drive. In Bitcoin Core v32, `exportwatchonlywallet` creates the watch-only wallet file and `restorewallet` loads it on the online node. Do not improvise a codex32-specific descriptor-transfer procedure in place of that maintained workflow. +Before signing, inspect the decoded PSBT on the offline signer and verify every +destination, amount, and fee against your intended payment; do not trust the +online host's summary. ## Recover an existing or inherited wallet @@ -244,7 +248,7 @@ its public wallet data with the separate wallet record. It gives Core the master private key, asks Core to create the standard account-0 descriptors, scans history, and relocks an encrypted wallet. 6. If you need an online watch-only counterpart, keep the restored signer - offline and follow Bitcoin Core v32's + offline and follow Bitcoin Core's [offline-signing tutorial](https://github.com/bitcoin/bitcoin/blob/master/doc/offline-signing-tutorial.md) to export and restore the watch-only wallet. Let the online node synchronize, then compare the account, policy, addresses, balance, and transaction @@ -308,12 +312,6 @@ Keep the matching application worksheet and original wallet instructions with the inheritance plan. Published BIP-93 still defines the `ms` application; the arbitrary-HRP format direction is not yet merged into that specification. -### QR troubleshooting - -Maximize the terminal and reduce its font size if a QR does not fit. Keep `qr` -connected to the terminal; redirecting its output creates an image file. Only -public descriptors, xpubs, and PSBTs may cross the offline boundary by QR. - ## Technical references Automation, low-level private exports, parser behavior, correction mathematics,