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. The two line-number columns refer to before and after.
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.
|