Bitcoin Core  0.20.99
P2P Digital Currency
wallet.h
Go to the documentation of this file.
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;
35 struct WalletContext;
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 
52 class Wallet
53 {
54 public:
55  virtual ~Wallet() {}
56 
58  virtual bool encryptWallet(const SecureString& wallet_passphrase) = 0;
59 
61  virtual bool isCrypted() = 0;
62 
64  virtual bool lock() = 0;
65 
67  virtual bool unlock(const SecureString& wallet_passphrase) = 0;
68 
70  virtual bool isLocked() = 0;
71 
73  virtual bool changeWalletPassphrase(const SecureString& old_wallet_passphrase,
74  const SecureString& new_wallet_passphrase) = 0;
75 
77  virtual void abortRescan() = 0;
78 
80  virtual bool backupWallet(const std::string& filename) = 0;
81 
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 
89  virtual bool getPubKey(const CScript& script, const CKeyID& address, CPubKey& pub_key) = 0;
90 
92  virtual SigningResult signMessage(const std::string& message, const PKHash& pkhash, std::string& str_sig) = 0;
93 
95  virtual bool isSpendable(const CTxDestination& dest) = 0;
96 
98  virtual bool haveWatchOnly() = 0;
99 
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 
107  virtual bool getAddress(const CTxDestination& dest,
108  std::string* name,
109  isminetype* is_mine,
110  std::string* purpose) = 0;
111 
113  virtual std::vector<WalletAddress> getAddresses() = 0;
114 
116  virtual bool addDestData(const CTxDestination& dest, const std::string& key, const std::string& value) = 0;
117 
119  virtual bool eraseDestData(const CTxDestination& dest, const std::string& key) = 0;
120 
122  virtual std::vector<std::string> getDestValues(const std::string& prefix) = 0;
123 
125  virtual void lockCoin(const COutPoint& output) = 0;
126 
128  virtual void unlockCoin(const COutPoint& output) = 0;
129 
131  virtual bool isLockedCoin(const COutPoint& output) = 0;
132 
134  virtual void listLockedCoins(std::vector<COutPoint>& outputs) = 0;
135 
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 
145  virtual void commitTransaction(CTransactionRef tx,
146  WalletValueMap value_map,
147  WalletOrderForm order_form) = 0;
148 
150  virtual bool transactionCanBeAbandoned(const uint256& txid) = 0;
151 
153  virtual bool abandonTransaction(const uint256& txid) = 0;
154 
156  virtual bool transactionCanBeBumped(const uint256& txid) = 0;
157 
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 
167  virtual bool signBumpTransaction(CMutableTransaction& mtx) = 0;
168 
170  virtual bool commitBumpTransaction(const uint256& txid,
171  CMutableTransaction&& mtx,
172  std::vector<bilingual_str>& errors,
173  uint256& bumped_txid) = 0;
174 
176  virtual CTransactionRef getTx(const uint256& txid) = 0;
177 
179  virtual WalletTx getWalletTx(const uint256& txid) = 0;
180 
182  virtual std::vector<WalletTx> getWalletTxs() = 0;
183 
185  virtual bool tryGetTxStatus(const uint256& txid,
186  WalletTxStatus& tx_status,
187  int& num_blocks,
188  int64_t& block_time) = 0;
189 
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 
198  virtual TransactionError fillPSBT(int sighash_type,
199  bool sign,
200  bool bip32derivs,
202  bool& complete,
203  size_t* n_signed) = 0;
204 
206  virtual WalletBalances getBalances() = 0;
207 
209  virtual bool tryGetBalances(WalletBalances& balances, uint256& block_hash) = 0;
210 
212  virtual CAmount getBalance() = 0;
213 
215  virtual CAmount getAvailableBalance(const CCoinControl& coin_control) = 0;
216 
218  virtual isminetype txinIsMine(const CTxIn& txin) = 0;
219 
221  virtual isminetype txoutIsMine(const CTxOut& txout) = 0;
222 
224  virtual CAmount getDebit(const CTxIn& txin, isminefilter filter) = 0;
225 
227  virtual CAmount getCredit(const CTxOut& txout, isminefilter filter) = 0;
228 
231  using CoinsList = std::map<CTxDestination, std::vector<std::tuple<COutPoint, WalletTxOut>>>;
232  virtual CoinsList listCoins() = 0;
233 
235  virtual std::vector<WalletTxOut> getCoins(const std::vector<COutPoint>& outputs) = 0;
236 
238  virtual CAmount getRequiredFee(unsigned int tx_bytes) = 0;
239 
241  virtual CAmount getMinimumFee(unsigned int tx_bytes,
242  const CCoinControl& coin_control,
243  int* returned_target,
244  FeeReason* reason) = 0;
245 
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 
262  virtual CAmount getDefaultMaxTxFee() = 0;
263 
264  // Remove wallet.
265  virtual void remove() = 0;
266 
268  virtual bool isLegacy() = 0;
269 
271  using UnloadFn = std::function<void()>;
272  virtual std::unique_ptr<Handler> handleUnload(UnloadFn fn) = 0;
273 
275  using ShowProgressFn = std::function<void(const std::string& title, int progress)>;
276  virtual std::unique_ptr<Handler> handleShowProgress(ShowProgressFn fn) = 0;
277 
279  using StatusChangedFn = std::function<void()>;
280  virtual std::unique_ptr<Handler> handleStatusChanged(StatusChangedFn fn) = 0;
281 
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 
291  using TransactionChangedFn = std::function<void(const uint256& txid, ChangeType status)>;
292  virtual std::unique_ptr<Handler> handleTransactionChanged(TransactionChangedFn fn) = 0;
293 
295  using WatchOnlyChangedFn = std::function<void(bool have_watch_only)>;
296  virtual std::unique_ptr<Handler> handleWatchOnlyChanged(WatchOnlyChangedFn fn) = 0;
297 
299  using CanGetAddressesChangedFn = std::function<void()>;
300  virtual std::unique_ptr<Handler> handleCanGetAddressesChanged(CanGetAddressesChangedFn fn) = 0;
301 
303  virtual CWallet* wallet() { return nullptr; }
304 };
305 
309 class WalletClient : public ChainClient
310 {
311 public:
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 
316  virtual std::unique_ptr<Wallet> loadWallet(const std::string& name, bilingual_str& error, std::vector<bilingual_str>& warnings) = 0;
317 
319  virtual std::string getWalletDir() = 0;
320 
322  virtual std::vector<std::string> listWalletDir() = 0;
323 
325  virtual std::vector<std::unique_ptr<Wallet>> getWallets() = 0;
326 
330  using LoadWalletFn = std::function<void(std::unique_ptr<Wallet> wallet)>;
331  virtual std::unique_ptr<Handler> handleLoadWallet(LoadWalletFn fn) = 0;
332 };
333 
336 {
339  std::string name;
340  std::string purpose;
341 
342  WalletAddress(CTxDestination dest, isminetype is_mine, std::string name, std::string purpose)
343  : dest(std::move(dest)), is_mine(is_mine), name(std::move(name)), purpose(std::move(purpose))
344  {
345  }
346 };
347 
350 {
352  CAmount unconfirmed_balance = 0;
353  CAmount immature_balance = 0;
354  bool have_watch_only = false;
355  CAmount watch_only_balance = 0;
356  CAmount unconfirmed_watch_only_balance = 0;
357  CAmount immature_watch_only_balance = 0;
358 
359  bool balanceChanged(const WalletBalances& prev) const
360  {
361  return balance != prev.balance || unconfirmed_balance != prev.unconfirmed_balance ||
362  immature_balance != prev.immature_balance || watch_only_balance != prev.watch_only_balance ||
363  unconfirmed_watch_only_balance != prev.unconfirmed_watch_only_balance ||
364  immature_watch_only_balance != prev.immature_watch_only_balance;
365  }
366 };
367 
368 // Wallet transaction information.
369 struct WalletTx
370 {
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;
379  int64_t time;
380  std::map<std::string, std::string> value_map;
382 };
383 
386 {
390  unsigned int time_received;
391  uint32_t lock_time;
392  bool is_final;
397 };
398 
401 {
403  int64_t time;
404  int depth_in_main_chain = -1;
405  bool is_spent = false;
406 };
407 
410 std::unique_ptr<Wallet> MakeWallet(const std::shared_ptr<CWallet>& wallet);
411 
414 std::unique_ptr<WalletClient> MakeWalletClient(Chain& chain, ArgsManager& args);
415 
416 } // namespace interfaces
417 
418 #endif // BITCOIN_INTERFACES_WALLET_H
std::shared_ptr< const CTransaction > CTransactionRef
Definition: transaction.h:395
virtual bool isCrypted()=0
Return whether wallet is encrypted.
virtual bool privateKeysDisabled()=0
virtual bool getAddress(const CTxDestination &dest, std::string *name, isminetype *is_mine, std::string *purpose)=0
Look up address in wallet, return whether exists.
virtual CoinsList listCoins()=0
virtual bool canGetAddresses()=0
WalletAddress(CTxDestination dest, isminetype is_mine, std::string name, std::string purpose)
Definition: wallet.h:342
std::vector< CTxDestination > txout_address
Definition: wallet.h:374
virtual WalletTx getWalletTxDetails(const uint256 &txid, WalletTxStatus &tx_status, WalletOrderForm &order_form, bool &in_mempool, int &num_blocks)=0
Get transaction details.
virtual bool isLocked()=0
Return whether wallet is locked.
virtual OutputType getDefaultAddressType()=0
unsigned int time_received
Definition: wallet.h:390
Bilingual messages:
Definition: translation.h:16
virtual isminetype txoutIsMine(const CTxOut &txout)=0
Return whether transaction output belongs to wallet.
std::function< void(bool have_watch_only)> WatchOnlyChangedFn
Register handler for watchonly changed messages.
Definition: wallet.h:295
virtual CWallet * wallet()
Return pointer to internal wallet class, useful for testing.
Definition: wallet.h:303
std::vector< isminetype > txin_is_mine
Definition: wallet.h:372
SigningResult
Definition: message.h:42
virtual std::unique_ptr< Handler > handleAddressBookChanged(AddressBookChangedFn fn)=0
std::vector< isminetype > txout_is_mine
Definition: wallet.h:373
virtual CTransactionRef getTx(const uint256 &txid)=0
Get a transaction.
const char * prefix
Definition: rest.cpp:670
virtual bool getPubKey(const CScript &script, const CKeyID &address, CPubKey &pub_key)=0
Get public key.
virtual CAmount getDefaultMaxTxFee()=0
Get max tx fee.
std::function< void()> UnloadFn
Register handler for unload message.
Definition: wallet.h:271
std::basic_string< char, std::char_traits< char >, secure_allocator< char > > SecureString
Definition: secure.h:60
virtual std::unique_ptr< Handler > handleWatchOnlyChanged(WatchOnlyChangedFn fn)=0
virtual bool backupWallet(const std::string &filename)=0
Back up wallet.
std::function< void()> CanGetAddressesChangedFn
Register handler for keypool changed messages.
Definition: wallet.h:299
virtual void lockCoin(const COutPoint &output)=0
Lock coin.
CTransactionRef tx
Definition: wallet.h:371
A version of CTransaction with the PSBT format.
Definition: psbt.h:390
std::map< std::string, std::string > WalletValueMap
Definition: wallet.h:49
virtual bool isLegacy()=0
Return whether is a legacy wallet.
virtual SigningResult signMessage(const std::string &message, const PKHash &pkhash, std::string &str_sig)=0
Sign message.
Wallet chain client that in addition to having chain client methods for starting up, shutting down, and registering RPCs, also has additional methods (called by the GUI) to load and create wallets.
Definition: wallet.h:309
virtual bool eraseDestData(const CTxDestination &dest, const std::string &key)=0
Erase dest data.
virtual bool changeWalletPassphrase(const SecureString &old_wallet_passphrase, const SecureString &new_wallet_passphrase)=0
Change wallet passphrase.
virtual bool isSpendable(const CTxDestination &dest)=0
Return whether wallet has private key.
OutputType
Definition: outputtype.h:17
Coin Control Features.
Definition: coincontrol.h:22
std::function< void()> StatusChangedFn
Register handler for status changed messages.
Definition: wallet.h:279
virtual WalletTx getWalletTx(const uint256 &txid)=0
Get transaction information.
virtual isminetype txinIsMine(const CTxIn &txin)=0
Return whether transaction input belongs to wallet.
int64_t CAmount
Amount in satoshis (Can be negative)
Definition: amount.h:12
std::map< CTxDestination, std::vector< std::tuple< COutPoint, WalletTxOut > >> CoinsList
Return AvailableCoins + LockedCoins grouped by wallet address.
Definition: wallet.h:231
virtual std::unique_ptr< Handler > handleUnload(UnloadFn fn)=0
CTxDestination dest
Definition: wallet.h:337
std::string purpose
Definition: wallet.h:340
virtual std::unique_ptr< Handler > handleTransactionChanged(TransactionChangedFn fn)=0
virtual bool hdEnabled()=0
std::function< void(const CTxDestination &address, const std::string &label, bool is_mine, const std::string &purpose, ChangeType status)> AddressBookChangedFn
Register handler for address book changed messages.
Definition: wallet.h:287
virtual CAmount getCredit(const CTxOut &txout, isminefilter filter)=0
Return credit amount if transaction input belongs to wallet.
virtual std::unique_ptr< Handler > handleShowProgress(ShowProgressFn fn)=0
static CAmount balance
virtual std::unique_ptr< Handler > handleCanGetAddressesChanged(CanGetAddressesChangedFn fn)=0
virtual std::unique_ptr< Handler > handleStatusChanged(StatusChangedFn fn)=0
virtual void unlockCoin(const COutPoint &output)=0
Unlock coin.
Collection of wallet balances.
Definition: wallet.h:349
virtual bool commitBumpTransaction(const uint256 &txid, CMutableTransaction &&mtx, std::vector< bilingual_str > &errors, uint256 &bumped_txid)=0
Commit bump transaction.
An input of a transaction.
Definition: transaction.h:65
const char * name
Definition: rest.cpp:41
An encapsulated public key.
Definition: pubkey.h:31
virtual bool createBumpTransaction(const uint256 &txid, const CCoinControl &coin_control, std::vector< bilingual_str > &errors, CAmount &old_fee, CAmount &new_fee, CMutableTransaction &mtx)=0
Create bump transaction.
virtual bool transactionCanBeAbandoned(const uint256 &txid)=0
Return whether transaction can be abandoned.
Interface for accessing a wallet.
Definition: wallet.h:52
virtual bool encryptWallet(const SecureString &wallet_passphrase)=0
Encrypt wallet.
uint8_t isminefilter
Definition: wallet.h:36
virtual CAmount getMinimumFee(unsigned int tx_bytes, const CCoinControl &coin_control, int *returned_target, FeeReason *reason)=0
Get minimum fee.
virtual bool tryGetTxStatus(const uint256 &txid, WalletTxStatus &tx_status, int &num_blocks, int64_t &block_time)=0
Try to get updated status for a particular transaction, if possible without blocking.
isminetype
IsMine() return codes.
Definition: ismine.h:18
An output of a transaction.
Definition: transaction.h:128
CAmount immature_watch_only_balance
Definition: wallet.h:357
FeeReason
Definition: fees.h:36
std::function< void(std::unique_ptr< Wallet > wallet)> LoadWalletFn
Register handler for load wallet messages.
Definition: wallet.h:330
virtual bool transactionCanBeBumped(const uint256 &txid)=0
Return whether transaction can be bumped.
An outpoint - a combination of a transaction hash and an index n into its vout.
Definition: transaction.h:26
std::unique_ptr< Wallet > MakeWallet(const std::shared_ptr< CWallet > &wallet)
Return implementation of Wallet interface.
Definition: dummywallet.cpp:60
virtual TransactionError fillPSBT(int sighash_type, bool sign, bool bip32derivs, PartiallySignedTransaction &psbtx, bool &complete, size_t *n_signed)=0
Fill PSBT.
std::function< void(const uint256 &txid, ChangeType status)> TransactionChangedFn
Register handler for transaction changed messages.
Definition: wallet.h:291
virtual std::vector< WalletTxOut > getCoins(const std::vector< COutPoint > &outputs)=0
Return wallet transaction output information.
virtual bool addDestData(const CTxDestination &dest, const std::string &key, const std::string &value)=0
Add dest data.
virtual CAmount getDebit(const CTxIn &txin, isminefilter filter)=0
Return debit amount if transaction input belongs to wallet.
virtual ~Wallet()
Definition: wallet.h:55
256-bit opaque blob.
Definition: uint256.h:124
std::unique_ptr< WalletClient > MakeWalletClient(Chain &chain, ArgsManager &args)
Return implementation of ChainClient interface for a wallet client.
Definition: wallet.cpp:569
virtual bool getNewDestination(const OutputType type, const std::string label, CTxDestination &dest)=0
virtual bool signBumpTransaction(CMutableTransaction &mtx)=0
Sign bump transaction.
std::vector< isminetype > txout_address_is_mine
Definition: wallet.h:375
virtual std::vector< WalletTx > getWalletTxs()=0
Get list of all wallet transactions.
virtual bool delAddressBook(const CTxDestination &dest)=0
CAmount unconfirmed_watch_only_balance
Definition: wallet.h:356
Interface to let node manage chain clients (wallets, or maybe tools for monitoring and analysis in th...
Definition: chain.h:292
Interface giving clients (wallet processes, maybe other analysis tools in the future) ability to acce...
Definition: chain.h:83
virtual void listLockedCoins(std::vector< COutPoint > &outputs)=0
List locked coins.
virtual CTransactionRef createTransaction(const std::vector< CRecipient > &recipients, const CCoinControl &coin_control, bool sign, int &change_pos, CAmount &fee, bilingual_str &fail_reason)=0
Create transaction.
Serialized script, used inside transaction inputs and outputs.
Definition: script.h:404
virtual bool tryGetBalances(WalletBalances &balances, uint256 &block_hash)=0
Get balances if possible without blocking.
virtual bool setAddressBook(const CTxDestination &dest, const std::string &name, const std::string &purpose)=0
Add or update address.
A reference to a CKey: the Hash160 of its serialized public key.
Definition: pubkey.h:21
virtual bool haveWatchOnly()=0
Return whether wallet has watch only keys.
std::function< void(const std::string &title, int progress)> ShowProgressFn
Register handler for show progress messages.
Definition: wallet.h:275
A CWallet maintains a set of transactions and balances, and provides the ability to create new transa...
Definition: wallet.h:622
TransactionError
Definition: error.h:22
Fee rate in satoshis per kilobyte: CAmount / kB.
Definition: feerate.h:29
virtual bool isLockedCoin(const COutPoint &output)=0
Return whether coin is locked.
std::vector< std::pair< std::string, std::string > > WalletOrderForm
Definition: wallet.h:48
Information about one wallet address.
Definition: wallet.h:335
WalletContext struct containing references to state shared between CWallet instances, like the reference to the chain interface, and the list of opened wallets.
Definition: context.h:23
virtual bool lock()=0
Lock wallet.
A mutable version of CTransaction.
Definition: transaction.h:353
virtual unsigned int getConfirmTarget()=0
Get tx confirm target.
virtual CAmount getBalance()=0
Get balance.
std::map< std::string, std::string > value_map
Definition: wallet.h:380
An encapsulated private key.
Definition: key.h:27
virtual void abortRescan()=0
Abort a rescan.
virtual CAmount getAvailableBalance(const CCoinControl &coin_control)=0
Get available balance.
virtual void commitTransaction(CTransactionRef tx, WalletValueMap value_map, WalletOrderForm order_form)=0
Commit transaction.
virtual WalletBalances getBalances()=0
Get balances.
boost::variant< CNoDestination, PKHash, ScriptHash, WitnessV0ScriptHash, WitnessV0KeyHash, WitnessUnknown > CTxDestination
A txout script template with a specific destination.
Definition: standard.h:214
ChangeType
General change type (added, updated, removed).
Definition: ui_change_type.h:9
Wallet transaction output.
Definition: wallet.h:400
virtual CAmount getRequiredFee(unsigned int tx_bytes)=0
Get required fee.
bool balanceChanged(const WalletBalances &prev) const
Definition: wallet.h:359
bool error(const char *fmt, const Args &... args)
Definition: system.h:52
virtual std::string getWalletName()=0
Get wallet name.
Updated transaction status.
Definition: wallet.h:385
virtual bool abandonTransaction(const uint256 &txid)=0
Abandon transaction.
virtual std::vector< std::string > getDestValues(const std::string &prefix)=0
Get dest values with prefix.
virtual bool unlock(const SecureString &wallet_passphrase)=0
Unlock wallet.
virtual std::vector< WalletAddress > getAddresses()=0
Get wallet address list.