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 <pubkey.h> // For CKeyID and CScriptID (definitions needed in CTxDestination instantiation)
10 #include <script/standard.h> // For CTxDestination
11 #include <support/allocators/secure.h> // For SecureString
12 #include <util/message.h>
13 #include <util/ui_change_type.h>
14 
15 #include <functional>
16 #include <map>
17 #include <memory>
18 #include <stdint.h>
19 #include <string>
20 #include <tuple>
21 #include <utility>
22 #include <vector>
23 
24 class CCoinControl;
25 class CFeeRate;
26 class CKey;
27 class CWallet;
28 enum class FeeReason;
29 enum class OutputType;
30 enum class TransactionError;
31 enum isminetype : unsigned int;
32 struct CRecipient;
35 typedef uint8_t isminefilter;
36 
37 namespace interfaces {
38 
39 class Handler;
40 struct WalletAddress;
41 struct WalletBalances;
42 struct WalletTx;
43 struct WalletTxOut;
44 struct WalletTxStatus;
45 
46 using WalletOrderForm = std::vector<std::pair<std::string, std::string>>;
47 using WalletValueMap = std::map<std::string, std::string>;
48 
50 class Wallet
51 {
52 public:
53  virtual ~Wallet() {}
54 
56  virtual bool encryptWallet(const SecureString& wallet_passphrase) = 0;
57 
59  virtual bool isCrypted() = 0;
60 
62  virtual bool lock() = 0;
63 
65  virtual bool unlock(const SecureString& wallet_passphrase) = 0;
66 
68  virtual bool isLocked() = 0;
69 
71  virtual bool changeWalletPassphrase(const SecureString& old_wallet_passphrase,
72  const SecureString& new_wallet_passphrase) = 0;
73 
75  virtual void abortRescan() = 0;
76 
78  virtual bool backupWallet(const std::string& filename) = 0;
79 
81  virtual std::string getWalletName() = 0;
82 
83  // Get a new address.
84  virtual bool getNewDestination(const OutputType type, const std::string label, CTxDestination& dest) = 0;
85 
87  virtual bool getPubKey(const CScript& script, const CKeyID& address, CPubKey& pub_key) = 0;
88 
90  virtual SigningResult signMessage(const std::string& message, const PKHash& pkhash, std::string& str_sig) = 0;
91 
93  virtual bool isSpendable(const CTxDestination& dest) = 0;
94 
96  virtual bool haveWatchOnly() = 0;
97 
99  virtual bool setAddressBook(const CTxDestination& dest, const std::string& name, const std::string& purpose) = 0;
100 
101  // Remove address.
102  virtual bool delAddressBook(const CTxDestination& dest) = 0;
103 
105  virtual bool getAddress(const CTxDestination& dest,
106  std::string* name,
107  isminetype* is_mine,
108  std::string* purpose) = 0;
109 
111  virtual std::vector<WalletAddress> getAddresses() = 0;
112 
114  virtual bool addDestData(const CTxDestination& dest, const std::string& key, const std::string& value) = 0;
115 
117  virtual bool eraseDestData(const CTxDestination& dest, const std::string& key) = 0;
118 
120  virtual std::vector<std::string> getDestValues(const std::string& prefix) = 0;
121 
123  virtual void lockCoin(const COutPoint& output) = 0;
124 
126  virtual void unlockCoin(const COutPoint& output) = 0;
127 
129  virtual bool isLockedCoin(const COutPoint& output) = 0;
130 
132  virtual void listLockedCoins(std::vector<COutPoint>& outputs) = 0;
133 
135  virtual CTransactionRef createTransaction(const std::vector<CRecipient>& recipients,
136  const CCoinControl& coin_control,
137  bool sign,
138  int& change_pos,
139  CAmount& fee,
140  bilingual_str& fail_reason) = 0;
141 
143  virtual void commitTransaction(CTransactionRef tx,
144  WalletValueMap value_map,
145  WalletOrderForm order_form) = 0;
146 
148  virtual bool transactionCanBeAbandoned(const uint256& txid) = 0;
149 
151  virtual bool abandonTransaction(const uint256& txid) = 0;
152 
154  virtual bool transactionCanBeBumped(const uint256& txid) = 0;
155 
157  virtual bool createBumpTransaction(const uint256& txid,
158  const CCoinControl& coin_control,
159  std::vector<bilingual_str>& errors,
160  CAmount& old_fee,
161  CAmount& new_fee,
162  CMutableTransaction& mtx) = 0;
163 
165  virtual bool signBumpTransaction(CMutableTransaction& mtx) = 0;
166 
168  virtual bool commitBumpTransaction(const uint256& txid,
169  CMutableTransaction&& mtx,
170  std::vector<bilingual_str>& errors,
171  uint256& bumped_txid) = 0;
172 
174  virtual CTransactionRef getTx(const uint256& txid) = 0;
175 
177  virtual WalletTx getWalletTx(const uint256& txid) = 0;
178 
180  virtual std::vector<WalletTx> getWalletTxs() = 0;
181 
183  virtual bool tryGetTxStatus(const uint256& txid,
184  WalletTxStatus& tx_status,
185  int& num_blocks,
186  int64_t& block_time) = 0;
187 
189  virtual WalletTx getWalletTxDetails(const uint256& txid,
190  WalletTxStatus& tx_status,
191  WalletOrderForm& order_form,
192  bool& in_mempool,
193  int& num_blocks) = 0;
194 
196  virtual TransactionError fillPSBT(int sighash_type,
197  bool sign,
198  bool bip32derivs,
200  bool& complete,
201  size_t* n_signed) = 0;
202 
204  virtual WalletBalances getBalances() = 0;
205 
207  virtual bool tryGetBalances(WalletBalances& balances, uint256& block_hash) = 0;
208 
210  virtual CAmount getBalance() = 0;
211 
213  virtual CAmount getAvailableBalance(const CCoinControl& coin_control) = 0;
214 
216  virtual isminetype txinIsMine(const CTxIn& txin) = 0;
217 
219  virtual isminetype txoutIsMine(const CTxOut& txout) = 0;
220 
222  virtual CAmount getDebit(const CTxIn& txin, isminefilter filter) = 0;
223 
225  virtual CAmount getCredit(const CTxOut& txout, isminefilter filter) = 0;
226 
229  using CoinsList = std::map<CTxDestination, std::vector<std::tuple<COutPoint, WalletTxOut>>>;
230  virtual CoinsList listCoins() = 0;
231 
233  virtual std::vector<WalletTxOut> getCoins(const std::vector<COutPoint>& outputs) = 0;
234 
236  virtual CAmount getRequiredFee(unsigned int tx_bytes) = 0;
237 
239  virtual CAmount getMinimumFee(unsigned int tx_bytes,
240  const CCoinControl& coin_control,
241  int* returned_target,
242  FeeReason* reason) = 0;
243 
245  virtual unsigned int getConfirmTarget() = 0;
246 
247  // Return whether HD enabled.
248  virtual bool hdEnabled() = 0;
249 
250  // Return whether the wallet is blank.
251  virtual bool canGetAddresses() = 0;
252 
253  // Return whether private keys enabled.
254  virtual bool privateKeysDisabled() = 0;
255 
256  // Get default address type.
257  virtual OutputType getDefaultAddressType() = 0;
258 
259  // Get default change type.
260  virtual OutputType getDefaultChangeType() = 0;
261 
263  virtual CAmount getDefaultMaxTxFee() = 0;
264 
265  // Remove wallet.
266  virtual void remove() = 0;
267 
269  virtual bool isLegacy() = 0;
270 
272  using UnloadFn = std::function<void()>;
273  virtual std::unique_ptr<Handler> handleUnload(UnloadFn fn) = 0;
274 
276  using ShowProgressFn = std::function<void(const std::string& title, int progress)>;
277  virtual std::unique_ptr<Handler> handleShowProgress(ShowProgressFn fn) = 0;
278 
280  using StatusChangedFn = std::function<void()>;
281  virtual std::unique_ptr<Handler> handleStatusChanged(StatusChangedFn fn) = 0;
282 
284  using AddressBookChangedFn = std::function<void(const CTxDestination& address,
285  const std::string& label,
286  bool is_mine,
287  const std::string& purpose,
288  ChangeType status)>;
289  virtual std::unique_ptr<Handler> handleAddressBookChanged(AddressBookChangedFn fn) = 0;
290 
292  using TransactionChangedFn = std::function<void(const uint256& txid, ChangeType status)>;
293  virtual std::unique_ptr<Handler> handleTransactionChanged(TransactionChangedFn fn) = 0;
294 
296  using WatchOnlyChangedFn = std::function<void(bool have_watch_only)>;
297  virtual std::unique_ptr<Handler> handleWatchOnlyChanged(WatchOnlyChangedFn fn) = 0;
298 
300  using CanGetAddressesChangedFn = std::function<void()>;
301  virtual std::unique_ptr<Handler> handleCanGetAddressesChanged(CanGetAddressesChangedFn fn) = 0;
302 
304  virtual CWallet* wallet() { return nullptr; }
305 };
306 
309 {
312  std::string name;
313  std::string purpose;
314 
315  WalletAddress(CTxDestination dest, isminetype is_mine, std::string name, std::string purpose)
316  : dest(std::move(dest)), is_mine(is_mine), name(std::move(name)), purpose(std::move(purpose))
317  {
318  }
319 };
320 
323 {
325  CAmount unconfirmed_balance = 0;
326  CAmount immature_balance = 0;
327  bool have_watch_only = false;
328  CAmount watch_only_balance = 0;
329  CAmount unconfirmed_watch_only_balance = 0;
330  CAmount immature_watch_only_balance = 0;
331 
332  bool balanceChanged(const WalletBalances& prev) const
333  {
334  return balance != prev.balance || unconfirmed_balance != prev.unconfirmed_balance ||
335  immature_balance != prev.immature_balance || watch_only_balance != prev.watch_only_balance ||
336  unconfirmed_watch_only_balance != prev.unconfirmed_watch_only_balance ||
337  immature_watch_only_balance != prev.immature_watch_only_balance;
338  }
339 };
340 
341 // Wallet transaction information.
342 struct WalletTx
343 {
345  std::vector<isminetype> txin_is_mine;
346  std::vector<isminetype> txout_is_mine;
347  std::vector<CTxDestination> txout_address;
348  std::vector<isminetype> txout_address_is_mine;
352  int64_t time;
353  std::map<std::string, std::string> value_map;
355 };
356 
359 {
363  unsigned int time_received;
364  uint32_t lock_time;
365  bool is_final;
370 };
371 
374 {
376  int64_t time;
377  int depth_in_main_chain = -1;
378  bool is_spent = false;
379 };
380 
383 std::unique_ptr<Wallet> MakeWallet(const std::shared_ptr<CWallet>& wallet);
384 
385 } // namespace interfaces
386 
387 #endif // BITCOIN_INTERFACES_WALLET_H
std::shared_ptr< const CTransaction > CTransactionRef
Definition: transaction.h:387
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:315
std::vector< CTxDestination > txout_address
Definition: wallet.h:347
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:363
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:296
virtual CWallet * wallet()
Return pointer to internal wallet class, useful for testing.
Definition: wallet.h:304
std::vector< isminetype > txin_is_mine
Definition: wallet.h:345
SigningResult
Definition: message.h:42
virtual std::unique_ptr< Handler > handleAddressBookChanged(AddressBookChangedFn fn)=0
std::vector< isminetype > txout_is_mine
Definition: wallet.h:346
virtual CTransactionRef getTx(const uint256 &txid)=0
Get a transaction.
const char * prefix
Definition: rest.cpp:648
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:272
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:300
virtual void lockCoin(const COutPoint &output)=0
Lock coin.
CTransactionRef tx
Definition: wallet.h:344
A version of CTransaction with the PSBT format.
Definition: psbt.h:392
std::map< std::string, std::string > WalletValueMap
Definition: wallet.h:47
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.
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.
virtual OutputType getDefaultChangeType()=0
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:280
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:229
virtual std::unique_ptr< Handler > handleUnload(UnloadFn fn)=0
CTxDestination dest
Definition: wallet.h:310
std::string purpose
Definition: wallet.h:313
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:288
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:322
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:57
const char * name
Definition: rest.cpp:41
An encapsulated public key.
Definition: pubkey.h:30
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:50
virtual bool encryptWallet(const SecureString &wallet_passphrase)=0
Encrypt wallet.
uint8_t isminefilter
Definition: wallet.h:34
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:120
CAmount immature_watch_only_balance
Definition: wallet.h:330
FeeReason
Definition: fees.h:36
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:18
std::unique_ptr< Wallet > MakeWallet(const std::shared_ptr< CWallet > &wallet)
Return implementation of Wallet interface.
Definition: dummywallet.cpp:94
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:292
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:53
256-bit opaque blob.
Definition: uint256.h:120
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:348
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:329
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:390
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:20
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:276
A CWallet maintains a set of transactions and balances, and provides the ability to create new transa...
Definition: wallet.h:621
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:46
Information about one wallet address.
Definition: wallet.h:308
virtual bool lock()=0
Lock wallet.
A mutable version of CTransaction.
Definition: transaction.h:345
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:353
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:209
ChangeType
General change type (added, updated, removed).
Definition: ui_change_type.h:9
Wallet transaction output.
Definition: wallet.h:373
virtual CAmount getRequiredFee(unsigned int tx_bytes)=0
Get required fee.
bool balanceChanged(const WalletBalances &prev) const
Definition: wallet.h:332
virtual std::string getWalletName()=0
Get wallet name.
Updated transaction status.
Definition: wallet.h:358
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.