From 53a82b3b66855e8b6809bf5674a3e36c23c7eb77 Mon Sep 17 00:00:00 2001 From: Ben Westgate Date: Tue, 6 Oct 2026 22:03:41 +0000 Subject: [PATCH 1/2] 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 b875ab04..a91614cd 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, From ba1aad6b89eb1489d1aad268fd4a37bf00a686f3 Mon Sep 17 00:00:00 2001 From: Ben Westgate Date: Fri, 23 Oct 2026 14:05:11 -0500 Subject: [PATCH 2/2] docs: explain network and power preparation Keep the preparation advice in the user guide rather than adding runtime prompts or host controls. Recommend charging a low laptop battery before disconnecting its cable for recovery-secret handling or offline signing, and explain that neither temporary network disconnection nor battery operation makes a compromised host safe. Signed-off-by: Ben Westgate --- docs/user/guide.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/user/guide.md b/docs/user/guide.md index a91614cd..5311f9d6 100644 --- a/docs/user/guide.md +++ b/docs/user/guide.md @@ -89,7 +89,16 @@ 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. +initialization, or signing. Temporarily disconnecting does not make a +compromised computer safe: malware can save secrets and send them after you +reconnect. + +On a laptop, consider disconnecting the charging cable while handling recovery +secrets. If the battery is low, charge it first, then unplug before starting. +A power connection is a potential physical side channel. Battery operation +removes that connection, not every side channel, and is a recommendation rather +than a requirement. You can also keep the cable disconnected during offline +signing. codex32 does not change networking or power settings for you. Bitcoin Core wallet encryption is strongly recommended. Bitcoin Core owns the passphrase and its prompts; codex32 never asks for, reads, or forwards it.