Line data Source code
1 : // Copyright (c) 2018-2020 The Bitcoin Core developers
2 : // Distributed under the MIT software license, see the accompanying
3 : // file COPYING or http://www.opensource.org/licenses/mit-license.php.
4 :
5 : #ifndef BITCOIN_INTERFACES_WALLET_H
6 : #define BITCOIN_INTERFACES_WALLET_H
7 :
8 : #include <amount.h> // For CAmount
9 : #include <interfaces/chain.h> // For ChainClient
10 : #include <pubkey.h> // For CKeyID and CScriptID (definitions needed in CTxDestination instantiation)
11 : #include <script/standard.h> // For CTxDestination
12 : #include <support/allocators/secure.h> // For SecureString
13 : #include <util/message.h>
14 : #include <util/ui_change_type.h>
15 :
16 : #include <functional>
17 : #include <map>
18 : #include <memory>
19 : #include <stdint.h>
20 : #include <string>
21 : #include <tuple>
22 : #include <utility>
23 : #include <vector>
24 :
25 : class CCoinControl;
26 : class CFeeRate;
27 : class CKey;
28 : class CWallet;
29 : enum class FeeReason;
30 : enum class OutputType;
31 : enum class TransactionError;
32 : enum isminetype : unsigned int;
33 : struct CRecipient;
34 : struct PartiallySignedTransaction;
35 : struct WalletContext;
36 : struct bilingual_str;
37 : typedef uint8_t isminefilter;
38 :
39 : namespace interfaces {
40 :
41 : class Handler;
42 : struct WalletAddress;
43 : struct WalletBalances;
44 : struct WalletTx;
45 : struct WalletTxOut;
46 : struct WalletTxStatus;
47 :
48 : using WalletOrderForm = std::vector<std::pair<std::string, std::string>>;
49 : using WalletValueMap = std::map<std::string, std::string>;
50 :
51 : //! Interface for accessing a wallet.
52 1 : class Wallet
53 : {
54 : public:
55 1 : virtual ~Wallet() {}
56 :
57 : //! Encrypt wallet.
58 : virtual bool encryptWallet(const SecureString& wallet_passphrase) = 0;
59 :
60 : //! Return whether wallet is encrypted.
61 : virtual bool isCrypted() = 0;
62 :
63 : //! Lock wallet.
64 : virtual bool lock() = 0;
65 :
66 : //! Unlock wallet.
67 : virtual bool unlock(const SecureString& wallet_passphrase) = 0;
68 :
69 : //! Return whether wallet is locked.
70 : virtual bool isLocked() = 0;
71 :
72 : //! Change wallet passphrase.
73 : virtual bool changeWalletPassphrase(const SecureString& old_wallet_passphrase,
74 : const SecureString& new_wallet_passphrase) = 0;
75 :
76 : //! Abort a rescan.
77 : virtual void abortRescan() = 0;
78 :
79 : //! Back up wallet.
80 : virtual bool backupWallet(const std::string& filename) = 0;
81 :
82 : //! Get wallet name.
83 : virtual std::string getWalletName() = 0;
84 :
85 : // Get a new address.
86 : virtual bool getNewDestination(const OutputType type, const std::string label, CTxDestination& dest) = 0;
87 :
88 : //! Get public key.
89 : virtual bool getPubKey(const CScript& script, const CKeyID& address, CPubKey& pub_key) = 0;
90 :
91 : //! Sign message
92 : virtual SigningResult signMessage(const std::string& message, const PKHash& pkhash, std::string& str_sig) = 0;
93 :
94 : //! Return whether wallet has private key.
95 : virtual bool isSpendable(const CTxDestination& dest) = 0;
96 :
97 : //! Return whether wallet has watch only keys.
98 : virtual bool haveWatchOnly() = 0;
99 :
100 : //! Add or update address.
101 : virtual bool setAddressBook(const CTxDestination& dest, const std::string& name, const std::string& purpose) = 0;
102 :
103 : // Remove address.
104 : virtual bool delAddressBook(const CTxDestination& dest) = 0;
105 :
106 : //! Look up address in wallet, return whether exists.
107 : virtual bool getAddress(const CTxDestination& dest,
108 : std::string* name,
109 : isminetype* is_mine,
110 : std::string* purpose) = 0;
111 :
112 : //! Get wallet address list.
113 : virtual std::vector<WalletAddress> getAddresses() = 0;
114 :
115 : //! Add dest data.
116 : virtual bool addDestData(const CTxDestination& dest, const std::string& key, const std::string& value) = 0;
117 :
118 : //! Erase dest data.
119 : virtual bool eraseDestData(const CTxDestination& dest, const std::string& key) = 0;
120 :
121 : //! Get dest values with prefix.
122 : virtual std::vector<std::string> getDestValues(const std::string& prefix) = 0;
123 :
124 : //! Lock coin.
125 : virtual void lockCoin(const COutPoint& output) = 0;
126 :
127 : //! Unlock coin.
128 : virtual void unlockCoin(const COutPoint& output) = 0;
129 :
130 : //! Return whether coin is locked.
131 : virtual bool isLockedCoin(const COutPoint& output) = 0;
132 :
133 : //! List locked coins.
134 : virtual void listLockedCoins(std::vector<COutPoint>& outputs) = 0;
135 :
136 : //! Create transaction.
137 : virtual CTransactionRef createTransaction(const std::vector<CRecipient>& recipients,
138 : const CCoinControl& coin_control,
139 : bool sign,
140 : int& change_pos,
141 : CAmount& fee,
142 : bilingual_str& fail_reason) = 0;
143 :
144 : //! Commit transaction.
145 : virtual void commitTransaction(CTransactionRef tx,
146 : WalletValueMap value_map,
147 : WalletOrderForm order_form) = 0;
148 :
149 : //! Return whether transaction can be abandoned.
150 : virtual bool transactionCanBeAbandoned(const uint256& txid) = 0;
151 :
152 : //! Abandon transaction.
153 : virtual bool abandonTransaction(const uint256& txid) = 0;
154 :
155 : //! Return whether transaction can be bumped.
156 : virtual bool transactionCanBeBumped(const uint256& txid) = 0;
157 :
158 : //! Create bump transaction.
159 : virtual bool createBumpTransaction(const uint256& txid,
160 : const CCoinControl& coin_control,
161 : std::vector<bilingual_str>& errors,
162 : CAmount& old_fee,
163 : CAmount& new_fee,
164 : CMutableTransaction& mtx) = 0;
165 :
166 : //! Sign bump transaction.
167 : virtual bool signBumpTransaction(CMutableTransaction& mtx) = 0;
168 :
169 : //! Commit bump transaction.
170 : virtual bool commitBumpTransaction(const uint256& txid,
171 : CMutableTransaction&& mtx,
172 : std::vector<bilingual_str>& errors,
173 : uint256& bumped_txid) = 0;
174 :
175 : //! Get a transaction.
176 : virtual CTransactionRef getTx(const uint256& txid) = 0;
177 :
178 : //! Get transaction information.
179 : virtual WalletTx getWalletTx(const uint256& txid) = 0;
180 :
181 : //! Get list of all wallet transactions.
182 : virtual std::vector<WalletTx> getWalletTxs() = 0;
183 :
184 : //! Try to get updated status for a particular transaction, if possible without blocking.
185 : virtual bool tryGetTxStatus(const uint256& txid,
186 : WalletTxStatus& tx_status,
187 : int& num_blocks,
188 : int64_t& block_time) = 0;
189 :
190 : //! Get transaction details.
191 : virtual WalletTx getWalletTxDetails(const uint256& txid,
192 : WalletTxStatus& tx_status,
193 : WalletOrderForm& order_form,
194 : bool& in_mempool,
195 : int& num_blocks) = 0;
196 :
197 : //! Fill PSBT.
198 : virtual TransactionError fillPSBT(int sighash_type,
199 : bool sign,
200 : bool bip32derivs,
201 : PartiallySignedTransaction& psbtx,
202 : bool& complete,
203 : size_t* n_signed) = 0;
204 :
205 : //! Get balances.
206 : virtual WalletBalances getBalances() = 0;
207 :
208 : //! Get balances if possible without blocking.
209 : virtual bool tryGetBalances(WalletBalances& balances, uint256& block_hash) = 0;
210 :
211 : //! Get balance.
212 : virtual CAmount getBalance() = 0;
213 :
214 : //! Get available balance.
215 : virtual CAmount getAvailableBalance(const CCoinControl& coin_control) = 0;
216 :
217 : //! Return whether transaction input belongs to wallet.
218 : virtual isminetype txinIsMine(const CTxIn& txin) = 0;
219 :
220 : //! Return whether transaction output belongs to wallet.
221 : virtual isminetype txoutIsMine(const CTxOut& txout) = 0;
222 :
223 : //! Return debit amount if transaction input belongs to wallet.
224 : virtual CAmount getDebit(const CTxIn& txin, isminefilter filter) = 0;
225 :
226 : //! Return credit amount if transaction input belongs to wallet.
227 : virtual CAmount getCredit(const CTxOut& txout, isminefilter filter) = 0;
228 :
229 : //! Return AvailableCoins + LockedCoins grouped by wallet address.
230 : //! (put change in one group with wallet address)
231 : using CoinsList = std::map<CTxDestination, std::vector<std::tuple<COutPoint, WalletTxOut>>>;
232 : virtual CoinsList listCoins() = 0;
233 :
234 : //! Return wallet transaction output information.
235 : virtual std::vector<WalletTxOut> getCoins(const std::vector<COutPoint>& outputs) = 0;
236 :
237 : //! Get required fee.
238 : virtual CAmount getRequiredFee(unsigned int tx_bytes) = 0;
239 :
240 : //! Get minimum fee.
241 : virtual CAmount getMinimumFee(unsigned int tx_bytes,
242 : const CCoinControl& coin_control,
243 : int* returned_target,
244 : FeeReason* reason) = 0;
245 :
246 : //! Get tx confirm target.
247 : virtual unsigned int getConfirmTarget() = 0;
248 :
249 : // Return whether HD enabled.
250 : virtual bool hdEnabled() = 0;
251 :
252 : // Return whether the wallet is blank.
253 : virtual bool canGetAddresses() = 0;
254 :
255 : // Return whether private keys enabled.
256 : virtual bool privateKeysDisabled() = 0;
257 :
258 : // Get default address type.
259 : virtual OutputType getDefaultAddressType() = 0;
260 :
261 : //! Get max tx fee.
262 : virtual CAmount getDefaultMaxTxFee() = 0;
263 :
264 : // Remove wallet.
265 : virtual void remove() = 0;
266 :
267 : //! Return whether is a legacy wallet
268 : virtual bool isLegacy() = 0;
269 :
270 : //! Register handler for unload message.
271 : using UnloadFn = std::function<void()>;
272 : virtual std::unique_ptr<Handler> handleUnload(UnloadFn fn) = 0;
273 :
274 : //! Register handler for show progress messages.
275 : using ShowProgressFn = std::function<void(const std::string& title, int progress)>;
276 : virtual std::unique_ptr<Handler> handleShowProgress(ShowProgressFn fn) = 0;
277 :
278 : //! Register handler for status changed messages.
279 : using StatusChangedFn = std::function<void()>;
280 : virtual std::unique_ptr<Handler> handleStatusChanged(StatusChangedFn fn) = 0;
281 :
282 : //! Register handler for address book changed messages.
283 : using AddressBookChangedFn = std::function<void(const CTxDestination& address,
284 : const std::string& label,
285 : bool is_mine,
286 : const std::string& purpose,
287 : ChangeType status)>;
288 : virtual std::unique_ptr<Handler> handleAddressBookChanged(AddressBookChangedFn fn) = 0;
289 :
290 : //! Register handler for transaction changed messages.
291 : using TransactionChangedFn = std::function<void(const uint256& txid, ChangeType status)>;
292 : virtual std::unique_ptr<Handler> handleTransactionChanged(TransactionChangedFn fn) = 0;
293 :
294 : //! Register handler for watchonly changed messages.
295 : using WatchOnlyChangedFn = std::function<void(bool have_watch_only)>;
296 : virtual std::unique_ptr<Handler> handleWatchOnlyChanged(WatchOnlyChangedFn fn) = 0;
297 :
298 : //! Register handler for keypool changed messages.
299 : using CanGetAddressesChangedFn = std::function<void()>;
300 : virtual std::unique_ptr<Handler> handleCanGetAddressesChanged(CanGetAddressesChangedFn fn) = 0;
301 :
302 : //! Return pointer to internal wallet class, useful for testing.
303 0 : virtual CWallet* wallet() { return nullptr; }
304 : };
305 :
306 : //! Wallet chain client that in addition to having chain client methods for
307 : //! starting up, shutting down, and registering RPCs, also has additional
308 : //! methods (called by the GUI) to load and create wallets.
309 2001 : class WalletClient : public ChainClient
310 : {
311 : public:
312 : //! Create new wallet.
313 : virtual std::unique_ptr<Wallet> createWallet(const std::string& name, const SecureString& passphrase, uint64_t wallet_creation_flags, bilingual_str& error, std::vector<bilingual_str>& warnings) = 0;
314 :
315 : //! Load existing wallet.
316 : virtual std::unique_ptr<Wallet> loadWallet(const std::string& name, bilingual_str& error, std::vector<bilingual_str>& warnings) = 0;
317 :
318 : //! Return default wallet directory.
319 : virtual std::string getWalletDir() = 0;
320 :
321 : //! Return available wallets in wallet directory.
322 : virtual std::vector<std::string> listWalletDir() = 0;
323 :
324 : //! Return interfaces for accessing wallets (if any).
325 : virtual std::vector<std::unique_ptr<Wallet>> getWallets() = 0;
326 :
327 : //! Register handler for load wallet messages. This callback is triggered by
328 : //! createWallet and loadWallet above, and also triggered when wallets are
329 : //! loaded at startup or by RPC.
330 : using LoadWalletFn = std::function<void(std::unique_ptr<Wallet> wallet)>;
331 : virtual std::unique_ptr<Handler> handleLoadWallet(LoadWalletFn fn) = 0;
332 : };
333 :
334 : //! Information about one wallet address.
335 0 : struct WalletAddress
336 : {
337 : CTxDestination dest;
338 : isminetype is_mine;
339 : std::string name;
340 : std::string purpose;
341 :
342 0 : WalletAddress(CTxDestination dest, isminetype is_mine, std::string name, std::string purpose)
343 0 : : dest(std::move(dest)), is_mine(is_mine), name(std::move(name)), purpose(std::move(purpose))
344 0 : {
345 0 : }
346 : };
347 :
348 : //! Collection of wallet balances.
349 0 : struct WalletBalances
350 : {
351 0 : CAmount balance = 0;
352 0 : CAmount unconfirmed_balance = 0;
353 0 : CAmount immature_balance = 0;
354 0 : bool have_watch_only = false;
355 0 : CAmount watch_only_balance = 0;
356 0 : CAmount unconfirmed_watch_only_balance = 0;
357 0 : CAmount immature_watch_only_balance = 0;
358 :
359 0 : bool balanceChanged(const WalletBalances& prev) const
360 : {
361 0 : return balance != prev.balance || unconfirmed_balance != prev.unconfirmed_balance ||
362 0 : immature_balance != prev.immature_balance || watch_only_balance != prev.watch_only_balance ||
363 0 : unconfirmed_watch_only_balance != prev.unconfirmed_watch_only_balance ||
364 0 : immature_watch_only_balance != prev.immature_watch_only_balance;
365 : }
366 : };
367 :
368 : // Wallet transaction information.
369 0 : struct WalletTx
370 : {
371 : CTransactionRef tx;
372 : std::vector<isminetype> txin_is_mine;
373 : std::vector<isminetype> txout_is_mine;
374 : std::vector<CTxDestination> txout_address;
375 : std::vector<isminetype> txout_address_is_mine;
376 : CAmount credit;
377 : CAmount debit;
378 : CAmount change;
379 : int64_t time;
380 : std::map<std::string, std::string> value_map;
381 : bool is_coinbase;
382 : };
383 :
384 : //! Updated transaction status.
385 : struct WalletTxStatus
386 : {
387 : int block_height;
388 : int blocks_to_maturity;
389 : int depth_in_main_chain;
390 : unsigned int time_received;
391 : uint32_t lock_time;
392 : bool is_final;
393 : bool is_trusted;
394 : bool is_abandoned;
395 : bool is_coinbase;
396 : bool is_in_main_chain;
397 : };
398 :
399 : //! Wallet transaction output.
400 0 : struct WalletTxOut
401 : {
402 : CTxOut txout;
403 : int64_t time;
404 0 : int depth_in_main_chain = -1;
405 0 : bool is_spent = false;
406 : };
407 :
408 : //! Return implementation of Wallet interface. This function is defined in
409 : //! dummywallet.cpp and throws if the wallet component is not compiled.
410 : std::unique_ptr<Wallet> MakeWallet(const std::shared_ptr<CWallet>& wallet);
411 :
412 : //! Return implementation of ChainClient interface for a wallet client. This
413 : //! function will be undefined in builds where ENABLE_WALLET is false.
414 : std::unique_ptr<WalletClient> MakeWalletClient(Chain& chain, ArgsManager& args, std::vector<std::string> wallet_filenames);
415 :
416 : } // namespace interfaces
417 :
418 : #endif // BITCOIN_INTERFACES_WALLET_H
|