Skip to content
Bitcoin Roots

v31.1-roots.1 · Commit 1: [PATCH 01/17] build(roots): establish v31 portability foundation

doc/wallet-privacy.md

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

File metadata
new file mode 100644
index 0000000000000000000000000000000000000000..9af45bffb31d1d1c57d6df4b005fbbed903fcb2d

Download original patch · Release notes

Diff rows 1–102 of 102. 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,102 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Advanced wallet privacy preservation contract
2
+ **v31 candidate status: deferred to the wallet theme.** The sweep and enhanced
3
+ coin-control behavior below is the accepted 30.3 source contract, not an
4
+ available v31 feature. Code/test references and example verification commands
5
+ refer to pinned source `10d772eb7f4b00b5193428a0dde4c06558d6c297`.
6
+ [The port review](roots-v31-port-review.md) records implementation ownership.
7
+
8
+ This guide describes the advanced wallet tools intended for the
9
+ `v30.3-roots.1` candidate. This is candidate documentation, not a release
10
+ announcement; the tools are not part of the published `v29.4-roots.2` release.
11
+ Bitcoin Core v30.3 is the direct upstream base; selected Bitcoin Knots
12
+ history is lineage only, not an upstream dependency or product specification.
13
+
14
+ ## Sweep an external private key
15
+
16
+ `sweepprivkeys` scans confirmed UTXOs controlled by supplied Base58 WIF private
17
+ keys and creates one signed transaction paying a destination in the selected
18
+ wallet. It is intended for an explicit, operator-controlled recovery of an
19
+ external key, not routine wallet import or consolidation.
20
+
21
+ - P2PKH is supported for valid compressed and uncompressed WIF keys. For a
22
+ compressed WIF, native P2WPKH and wrapped P2SH-P2WPKH are also supported.
23
+ Taproot and any other script form are not scanned by this command.
24
+ - The destination must be a spendable address controlled by the wallet handling
25
+ the RPC request. A destination in another loaded wallet is rejected. The
26
+ supported configuration is a descriptor wallet with local private keys;
27
+ watch-only, private-key-disabled, and external-signer configurations are not
28
+ eligible destinations. Legacy wallets must be migrated to descriptor wallets;
29
+ this port does not restore a Berkeley DB build option.
30
+ - `broadcast=false` is the default and returns a signed preview with its input
31
+ total, fee, input count, transaction ID, and hex. It does not submit a
32
+ transaction. Review the destination, net amount, and fee; decode the preview
33
+ when inspecting its fee rate and RBF state before using `broadcast=true`.
34
+ - Fees use the current wallet fee settings and chain state. A fresh broadcast
35
+ can fail because an input was spent, relay or mempool policy changed, or the
36
+ fee is no longer sufficient. Recreate and review a preview after such a
37
+ failure; do not assume a previous preview is still valid.
38
+ - Supplied keys are used transiently for scanning and signing. They are not
39
+ imported as wallet keys, descriptors, labels, or settings, and are redacted
40
+ from the RPC console and normal logs. This is not key backup or recovery:
41
+ retain an independent, secure backup until the sweep confirms.
42
+
43
+ The Qt **Sweep Private Key** dialog applies the same contract. Its key field is
44
+ masked and disables copy, cut, and context-menu actions. The dialog uses a
45
+ transient secure key cache, cleans its temporary encoded input, and overwrites
46
+ then clears its input control when it can invalidate a request. A cancellation
47
+ can stop an outstanding scan or preview; once broadcast submission passes its
48
+ final authorization boundary, it cannot be cancelled and the dialog waits for
49
+ the result. These measures reduce the lifetime of the entered secret, but do
50
+ not promise to erase every copy retained by the GUI toolkit or host. Showing
51
+ the key still exposes it on screen; use that control only when the display is
52
+ safe. Broadcasting is irreversible and may fail after a chain or fee change.
53
+
54
+ ## Inspect and select wallet inputs
55
+
56
+ The Send Coins coin-control dialog exposes wallet-reported facts about UTXOs:
57
+ amount and effective value, confirmations, lock and spendability state,
58
+ watch-only status, reuse, grouping, input-size estimates, and fee/change/RBF
59
+ consequences. It does not infer identity, rate privacy, or make a transaction
60
+ anonymous.
61
+
62
+ - A **Reused address** indicator and grouping describe observable wallet facts.
63
+ Selecting a group combines its inputs and can reveal an on-chain relationship;
64
+ neither label is a privacy recommendation or score.
65
+ - The dialog starts with the wallet's normal available-output list. Locked
66
+ outputs remain visible so their lock state can be inspected, but cannot be
67
+ selected. Unsafe and immature outputs are not added merely to show a status;
68
+ outputs excluded by those normal availability filters are absent until their
69
+ state changes. “Not spendable” is metadata for a displayed output, not an
70
+ inventory of unavailable outputs.
71
+ - Explicit input selections are honored for the prepared send. A material wallet
72
+ change, including a competing spend or reorganization, clears the selection
73
+ so the operator must review current inputs again.
74
+ - The confirmation shows the effective inputs, fee, change, and whether the
75
+ transaction signals Replace-By-Fee. These are transaction facts, not a
76
+ promise that a replacement will be accepted by every peer or policy.
77
+ - A custom change destination is conspicuous and validated. If it is empty or
78
+ invalid, the wallet uses a newly generated change address. Review custom
79
+ change carefully because it can affect address linkage.
80
+
81
+ These tools do not add CoinJoin, payjoin, silent automatic consolidation,
82
+ private-key export, a transaction-history product, or any anonymity guarantee.
83
+
84
+ ## Candidate verification
85
+
86
+ The candidate behavior is exercised by
87
+ `wallet_sweepprivkeys.py` (`test/functional/wallet_sweepprivkeys.py`, source reference),
88
+ `wallet_send.py` (`test/functional/wallet_send.py`, source reference), wallet unit tests, and
89
+ `src/qt/test/wallettests.cpp` (`src/qt/test/wallettests.cpp`, source reference). Before operating
90
+ on funds, compare the intended command with the built binary and inspect a
91
+ non-broadcast preview:
92
+
93
+ ```sh
94
+ bitcoin-cli help sweepprivkeys
95
+ build/test/functional/test_runner.py wallet_sweepprivkeys.py
96
+ python3 ci/test/test_wallet_privacy_contract.py
97
+ ```
98
+
99
+ `bitcoin-cli help sweepprivkeys` and the final transaction preview are the
100
+ authority for a particular binary and transaction. Verify the executable's
101
+ identity separately with `bitcoin-cli --version`; the intended
102
+ `v30.3-roots.1` candidate label in this guide does not replace that check.