1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
//! [`confirm_spendable_by_name`] — the second, disagreeing question every spend builder must ask
//! about every coin it is about to spend.
//!
//! # Why a by-puzzle-hash listing is not enough
//!
//! Selecting inputs asks the chain "what coins does this puzzle hash own?". Consensus asks a
//! different question when the bundle arrives: "is coin X, by name, still unspent?". The two are
//! answered by different indexes and, on this ecosystem's aggregating mainnet source, frequently by
//! DIFFERENT PEERS — the source routes each read to a peer it picks per call, and twelve consecutive
//! listings of one funded address have been observed returning `2,2,2,2,2,2,0,2,2,2,2,0` coins.
//!
//! A listing that is stale by one spend offers a coin the network already considers gone, and
//! nothing downstream notices: the bundle builds, passes the signing gate, is broadcast, and the
//! mempool answers `DOUBLE_SPEND` — because a removal whose coin record says spent is the only
//! condition that produces that verdict. This is not hypothetical. It produced a real mainnet
//! `DOUBLE_SPEND` on the mint path.
//!
//! So every coin a builder selects is re-read BY NAME, and the build is abandoned unless that answer
//! also calls the coin confirmed and unspent, before a single mojo is committed to a bundle.
//!
//! # Two answers that cannot both be true make the state UNKNOWN
//!
//! A disagreement is never a shortfall and never a refusal. The wallet may be perfectly funded and
//! the next read may be answered by a node that is caught up, so the honest report is "we could not
//! establish this coin's state" — which every caller maps onto its own `ChainUnreachable`-shaped
//! variant. See [`UnconfirmedInput`].
//!
//! # Where this lives, and why it is not in `wallet` or in `mint`
//!
//! Both the transfer builders ([`crate::wallet::transfer`], [`crate::wallet::cat_transfer`]) and the
//! mint select coins and must ask this question identically. A helper owned by either module would
//! make the other depend on its neighbour's error type for a fact about the chain that belongs to
//! neither. It therefore sits at the crate root, depends only on [`ChainSource`], and returns a
//! NEUTRAL error each caller translates.
use ;
use ChainSource;
/// Why a selected input could not be confirmed spendable by name.
///
/// Deliberately not any module's error type. Each caller maps this onto its own
/// `ChainUnreachable`-shaped variant, so a builder's public error surface stays that builder's own
/// while the fact being reported stays one fact.
///
/// Every variant means the SAME thing to a caller: the coin's state is UNKNOWN. None of them means
/// "the user is short" and none of them means "refused".
/// Re-read `coin` BY NAME and succeed only if that answer also calls it confirmed and unspent.
///
/// This is the guard described in the module docs. Call it on EVERY selected input, before building
/// anything.
///
/// # Errors
///
/// [`UnconfirmedInput`] — always meaning the coin's state is UNKNOWN, never a shortfall.
/// Confirm every coin in `coins`, all-or-nothing.
///
/// # Why one disagreeing input fails the WHOLE attempt
///
/// A multi-input transfer is a plan the user has already been shown: these coins, this amount, this
/// change. Dropping a stale input and proceeding on the survivors silently changes that plan and can
/// change the change coin, the fee, or whether the send is affordable at all. Re-selecting from the
/// same listing is no better — the listing is the thing that was stale, so it can hand back another
/// coin in the same condition.
///
/// So the attempt is abandoned and the caller retries from a fresh read. Never proceed on the
/// survivors, never silently substitute a different coin, never report the disagreement as a
/// shortfall and never as a refusal.
///
/// # Errors
///
/// The FIRST [`UnconfirmedInput`] encountered. Short-circuiting is deliberate: the attempt is over
/// at the first disagreement, and further reads would only spend more time on a plan already being
/// discarded.