Skip to content

Commit ad2f234

Browse files
committed
docs: Compress the descriptor QR
The watch-only wallet file from exportwatchonlywallet does not fit in a QR even compressed (12,288 bytes; 2,365 gzipped against qr's 2,331-byte limit), so the guide sends the public descriptors. gzip shrinks them from 1,975 to 619 bytes, which takes qr's code from version 37 to 19, about half the width, and makes the scan more reliable. The online side reads the QR with zbarcam -Sbinary and pipes it through gunzip. Without -Sbinary, ZBar rewrites the bytes as text and gunzip fails. qrencode needs -8 for the same data; without it the input stops at the first zero byte. Validation: on two separate Bitcoin Core 32.0rc2 regtest nodes with the BIP-93 test vector, the gzipped listdescriptors output went through qr and back through zbarimg with the guide's flags and gunzip, all 8 descriptors imported with success, and both wallets gave the same first address. qrencode -8 round-tripped the same bytes. Docs-only change. Refs #92 Claude-Session: https://claude.ai/code/session_01T233rKgZqE5wzDm3EVTHL1
1 parent d4641c4 commit ad2f234

1 file changed

Lines changed: 13 additions & 11 deletions

File tree

‎docs/user/guide.md‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -216,24 +216,24 @@ are present.
216216
### 2. Create the online watch-only wallet
217217

218218
The tutorial moves a watch-only wallet file made by `exportwatchonlywallet`.
219-
That file is far too large for a QR, so send the public descriptors instead.
220-
On the offline computer:
219+
That file does not fit in a QR even compressed, so send the public descriptors
220+
instead, compressed with `gzip`. On the offline computer:
221221

222222
```bash
223-
bitcoin-cli -rpcwallet=offline_wallet listdescriptors | jq -cj '[.descriptors[] | {desc,timestamp,active,internal,range,next_index}]' | qr
223+
bitcoin-cli -rpcwallet=offline_wallet listdescriptors | jq -cj '[.descriptors[] | {desc,timestamp,active,internal,range,next_index}]' | gzip -9 | qr
224224
```
225225

226-
The QR holds about 2,000 characters; see [QR troubleshooting](#qr-troubleshooting)
227-
if it does not fit. Public descriptors cannot spend, but they reveal wallet
228-
activity. Do not use a website, cloud scanner, chat service, or synced
229-
clipboard.
226+
The compressed descriptors take about 620 bytes; see
227+
[QR troubleshooting](#qr-troubleshooting) if the QR does not fit. Public
228+
descriptors cannot spend, but they reveal wallet activity. Do not use a
229+
website, cloud scanner, chat service, or synced clipboard.
230230

231-
On the online computer, create a blank watch-only wallet and scan the QR into
232-
it:
231+
On the online computer, create a blank watch-only wallet, then scan and
232+
decompress the QR into it:
233233

234234
```bash
235235
bitcoin-cli -named createwallet wallet_name=watch_only_wallet disable_private_keys=true blank=true
236-
zbarcam --raw --oneshot -Sdisable -Sqrcode.enable |
236+
zbarcam --raw --oneshot -Sdisable -Sqrcode.enable -Sbinary | gunzip |
237237
bitcoin-cli -rpcwallet=watch_only_wallet -stdin importdescriptors
238238
```
239239

@@ -372,7 +372,9 @@ arbitrary-HRP format direction is not yet merged into that specification.
372372

373373
Maximize the terminal and reduce its font size if a QR does not fit. Keep `qr`
374374
connected to the terminal; redirecting its output creates an image file. If `qr`
375-
is unavailable, `qrencode -t ANSIUTF8` shows the same QR. Only public
375+
is unavailable, `qrencode -8 -t ANSIUTF8` shows the same QR. Reading the
376+
compressed descriptors needs ZBar 0.23.1 or newer for `-Sbinary`; without it,
377+
ZBar rewrites the bytes as text and `gunzip` fails. Only public
376378
descriptors, xpubs, PSBTs, and signed transactions may cross the offline
377379
boundary by QR.
378380

0 commit comments

Comments
 (0)