Skip to content
Bitcoin Roots

v29.4-roots.3 · Commit 27: [PATCH 27/30] docs(wallet): document advanced privacy tools

doc/wallet-privacy.md

Before: /dev/null · After: doc/wallet-privacy.md

File metadata
new file mode 100644
index 0000000000000000000000000000000000000000..b0d8d59f10bfd34b347b6510b1526d0f4dc9f591

Download original patch · Release notes

Diff rows 1–77 of 77. Line numbers refer to the original before/after files.

+ Added− RemovedUnmarked lines are context.

Scroll the code area horizontally to read long lines. Before is on the left; after is on the right. Unified view fits narrow screens more easily.

doc/wallet-privacy.md ADDED
@@ -0,0 +1,77 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Advanced wallet privacy tools (unreleased)
2
+
3
+ This guide describes the advanced wallet tools in this unreleased
4
+ post-`v29.4-roots.2` topic. They are not part of the published
5
+ `v29.4-roots.2` release. Bitcoin Core v29.4 remains the direct upstream base;
6
+ selected Bitcoin Knots history is lineage only, not an upstream dependency or
7
+ product specification.
8
+
9
+ ## Sweep an external private key
10
+
11
+ `sweepprivkeys` scans confirmed UTXOs controlled by supplied Base58 WIF private
12
+ keys and creates one signed transaction paying a destination in the selected
13
+ wallet. It is intended for an explicit, operator-controlled recovery of an
14
+ external key, not routine wallet import or consolidation.
15
+
16
+ - P2PKH is supported for valid compressed and uncompressed WIF keys. For a
17
+ compressed WIF, native P2WPKH and wrapped P2SH-P2WPKH are also supported.
18
+ Taproot and any other script form are not scanned by this command.
19
+ - The destination must be a spendable address controlled by the wallet handling
20
+ the RPC request. A destination in another loaded wallet is rejected. The
21
+ supported configuration is a descriptor wallet with local private keys;
22
+ watch-only, private-key-disabled, and external-signer configurations are not
23
+ eligible destinations. Legacy-wallet behavior is not part of this topic's
24
+ verified matrix and requires a compatible Berkeley DB build.
25
+ - `broadcast=false` is the default and returns a signed preview with its input
26
+ total, fee, input count, transaction ID, and hex. It does not submit a
27
+ transaction. Review the destination, net amount, and fee; decode the preview
28
+ when inspecting its fee rate and RBF state before using `broadcast=true`.
29
+ - Fees use the current wallet fee settings and chain state. A fresh broadcast
30
+ can fail because an input was spent, relay or mempool policy changed, or the
31
+ fee is no longer sufficient. Recreate and review a preview after such a
32
+ failure; do not assume a previous preview is still valid.
33
+ - Supplied keys are used transiently for scanning and signing. They are not
34
+ imported as wallet keys, descriptors, labels, or settings, and are redacted
35
+ from the RPC console and normal logs. This is not key backup or recovery:
36
+ retain an independent, secure backup until the sweep confirms.
37
+
38
+ The Qt **Sweep Private Key** dialog applies the same contract. Its key field is
39
+ masked and disables copy, cut, and context-menu actions. It clears the entered
40
+ key after a preview request, when dismissed, or when the wallet unloads.
41
+ Showing the key still exposes it on screen; use that control only when the
42
+ display is safe. Broadcasting is irreversible and may fail after a chain or fee
43
+ change.
44
+
45
+ ## Inspect and select wallet inputs
46
+
47
+ The Send Coins coin-control dialog exposes wallet-reported facts about UTXOs:
48
+ amount and effective value, confirmations, lock and spendability state,
49
+ watch-only status, reuse, grouping, input-size estimates, and fee/change/RBF
50
+ consequences. It does not infer identity, rate privacy, or make a transaction
51
+ anonymous.
52
+
53
+ - A **Reused address** indicator and grouping describe observable wallet facts.
54
+ Selecting a group combines its inputs and can reveal an on-chain relationship;
55
+ neither label is a privacy recommendation or score.
56
+ - Explicit input selections are honored for the prepared send. Locked, unsafe,
57
+ immature, or unavailable inputs are reported by the wallet. A material wallet
58
+ change, including a competing spend or reorganization, clears the selection
59
+ so the operator must review current inputs again.
60
+ - The confirmation shows the effective inputs, fee, change, and whether the
61
+ transaction signals Replace-By-Fee. These are transaction facts, not a
62
+ promise that a replacement will be accepted by every peer or policy.
63
+ - A custom change destination is conspicuous and validated. If it is empty or
64
+ invalid, the wallet uses a newly generated change address. Review custom
65
+ change carefully because it can affect address linkage.
66
+
67
+ These tools do not add CoinJoin, payjoin, silent automatic consolidation,
68
+ private-key export, a transaction-history product, or any anonymity guarantee.
69
+
70
+ ## Verification references
71
+
72
+ The reviewed behavior is exercised by
73
+ [`wallet_sweepprivkeys.py`](/test/functional/wallet_sweepprivkeys.py),
74
+ [`wallet_send.py`](/test/functional/wallet_send.py), wallet unit tests, and
75
+ [`src/qt/test/wallettests.cpp`](/src/qt/test/wallettests.cpp). Use
76
+ `bitcoin-cli help sweepprivkeys` and the final transaction preview as the
77
+ authority for a particular binary and transaction.