Bitcoin ABC  0.22.13
P2P Digital Currency
wallet.h
Go to the documentation of this file.
1 // Copyright (c) 2018 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 Amount
9 #include <primitives/transaction.h> // For CTxOut
10 #include <pubkey.h> // For CKeyID and CScriptID (definitions needed in CTxDestination instantiation)
11 #include <script/sighashtype.h>
12 #include <script/standard.h> // For CTxDestination
13 #include <support/allocators/secure.h> // For SecureString
14 #include <util/message.h>
15 #include <util/ui_change_type.h>
16 
17 #include <cstdint>
18 #include <functional>
19 #include <map>
20 #include <memory>
21 #include <string>
22 #include <tuple>
23 #include <utility>
24 #include <vector>
25 
26 class CChainParams;
27 class CCoinControl;
28 class CKey;
30 class COutPoint;
31 class CTransaction;
32 class CWallet;
33 enum class FeeReason;
34 enum class OutputType;
35 enum class TransactionError;
36 enum isminetype : unsigned int;
37 struct CRecipient;
39 typedef uint8_t isminefilter;
40 struct TxId;
41 struct bilingual_str;
42 
43 namespace interfaces {
44 
45 class Handler;
46 struct WalletAddress;
47 struct WalletBalances;
48 struct WalletTx;
49 struct WalletTxOut;
50 struct WalletTxStatus;
51 
52 using WalletOrderForm = std::vector<std::pair<std::string, std::string>>;
53 using WalletValueMap = std::map<std::string, std::string>;
54 
56 class Wallet {
57 public:
58  virtual ~Wallet() {}
59 
61  virtual bool encryptWallet(const SecureString &wallet_passphrase) = 0;
62 
64  virtual bool isCrypted() = 0;
65 
67  virtual bool lock() = 0;
68 
70  virtual bool unlock(const SecureString &wallet_passphrase) = 0;
71 
73  virtual bool isLocked() = 0;
74 
76  virtual bool
77  changeWalletPassphrase(const SecureString &old_wallet_passphrase,
78  const SecureString &new_wallet_passphrase) = 0;
79 
81  virtual void abortRescan() = 0;
82 
84  virtual bool backupWallet(const std::string &filename) = 0;
85 
87  virtual std::string getWalletName() = 0;
88 
90  virtual const CChainParams &getChainParams() = 0;
91 
93  virtual std::set<CTxDestination>
94  getLabelAddresses(const std::string &label) = 0;
95 
96  // Get a new address.
97  virtual bool getNewDestination(const OutputType type,
98  const std::string label,
99  CTxDestination &dest) = 0;
100 
102  virtual bool getPubKey(const CScript &script, const CKeyID &address,
103  CPubKey &pub_key) = 0;
104 
106  virtual SigningResult signMessage(const std::string &message,
107  const PKHash &pkhash,
108  std::string &str_sig) = 0;
109 
111  virtual bool isSpendable(const CTxDestination &dest) = 0;
112 
114  virtual bool haveWatchOnly() = 0;
115 
117  virtual bool setAddressBook(const CTxDestination &dest,
118  const std::string &name,
119  const std::string &purpose) = 0;
120 
121  // Remove address.
122  virtual bool delAddressBook(const CTxDestination &dest) = 0;
123 
125  virtual bool getAddress(const CTxDestination &dest, std::string *name,
126  isminetype *is_mine, std::string *purpose) = 0;
127 
129  virtual std::vector<WalletAddress> getAddresses() = 0;
130 
132  virtual bool addDestData(const CTxDestination &dest, const std::string &key,
133  const std::string &value) = 0;
134 
136  virtual bool eraseDestData(const CTxDestination &dest,
137  const std::string &key) = 0;
138 
140  virtual std::vector<std::string>
141  getDestValues(const std::string &prefix) = 0;
142 
144  virtual void lockCoin(const COutPoint &output) = 0;
145 
147  virtual void unlockCoin(const COutPoint &output) = 0;
148 
150  virtual bool isLockedCoin(const COutPoint &output) = 0;
151 
153  virtual void listLockedCoins(std::vector<COutPoint> &outputs) = 0;
154 
156  virtual CTransactionRef
157  createTransaction(const std::vector<CRecipient> &recipients,
158  const CCoinControl &coin_control, bool sign,
159  int &change_pos, Amount &fee,
160  bilingual_str &fail_reason) = 0;
161 
163  virtual void commitTransaction(CTransactionRef tx, WalletValueMap value_map,
164  WalletOrderForm order_form) = 0;
165 
167  virtual bool transactionCanBeAbandoned(const TxId &txid) = 0;
168 
170  virtual bool abandonTransaction(const TxId &txid) = 0;
171 
173  virtual CTransactionRef getTx(const TxId &txid) = 0;
174 
176  virtual WalletTx getWalletTx(const TxId &txid) = 0;
177 
179  virtual std::vector<WalletTx> getWalletTxs() = 0;
180 
183  virtual bool tryGetTxStatus(const TxId &txid, WalletTxStatus &tx_status,
184  int &num_blocks, int64_t &block_time) = 0;
185 
187  virtual WalletTx getWalletTxDetails(const TxId &txid,
188  WalletTxStatus &tx_status,
189  WalletOrderForm &order_form,
190  bool &in_mempool, int &num_blocks) = 0;
191 
193  virtual TransactionError fillPSBT(SigHashType sighash_type, bool sign,
194  bool bip32derivs,
196  bool &complete) const = 0;
197 
199  virtual WalletBalances getBalances() = 0;
200 
202  virtual bool tryGetBalances(WalletBalances &balances, int &num_blocks,
203  bool force, int cached_num_blocks) = 0;
204 
206  virtual Amount getBalance() = 0;
207 
209  virtual Amount getAvailableBalance(const CCoinControl &coin_control) = 0;
210 
212  virtual isminetype txinIsMine(const CTxIn &txin) = 0;
213 
215  virtual isminetype txoutIsMine(const CTxOut &txout) = 0;
216 
218  virtual Amount getDebit(const CTxIn &txin, isminefilter filter) = 0;
219 
221  virtual Amount getCredit(const CTxOut &txout, isminefilter filter) = 0;
222 
225  using CoinsList = std::map<CTxDestination,
226  std::vector<std::tuple<COutPoint, WalletTxOut>>>;
227  virtual CoinsList listCoins() = 0;
228 
230  virtual std::vector<WalletTxOut>
231  getCoins(const std::vector<COutPoint> &outputs) = 0;
232 
234  virtual Amount getRequiredFee(unsigned int tx_bytes) = 0;
235 
237  virtual Amount getMinimumFee(unsigned int tx_bytes,
238  const CCoinControl &coin_control) = 0;
239 
240  // Return whether HD enabled.
241  virtual bool hdEnabled() = 0;
242 
243  // Return whether the wallet is blank.
244  virtual bool canGetAddresses() const = 0;
245 
246  // Return whether private keys enabled.
247  virtual bool privateKeysDisabled() = 0;
248 
249  // Get default address type.
250  virtual OutputType getDefaultAddressType() = 0;
251 
252  // Get default change type.
253  virtual OutputType getDefaultChangeType() = 0;
254 
256  virtual Amount getDefaultMaxTxFee() = 0;
257 
258  // Remove wallet.
259  virtual void remove() = 0;
260 
262  virtual bool isLegacy() = 0;
263 
265  using UnloadFn = std::function<void()>;
266  virtual std::unique_ptr<Handler> handleUnload(UnloadFn fn) = 0;
267 
269  using ShowProgressFn =
270  std::function<void(const std::string &title, int progress)>;
271  virtual std::unique_ptr<Handler> handleShowProgress(ShowProgressFn fn) = 0;
272 
274  using StatusChangedFn = std::function<void()>;
275  virtual std::unique_ptr<Handler>
277 
279  using AddressBookChangedFn = std::function<void(
280  const CTxDestination &address, const std::string &label, bool is_mine,
281  const std::string &purpose, ChangeType status)>;
282  virtual std::unique_ptr<Handler>
284 
286  using TransactionChangedFn =
287  std::function<void(const TxId &txid, ChangeType status)>;
288  virtual std::unique_ptr<Handler>
290 
292  using WatchOnlyChangedFn = std::function<void(bool have_watch_only)>;
293  virtual std::unique_ptr<Handler>
295 
297  using CanGetAddressesChangedFn = std::function<void()>;
298  virtual std::unique_ptr<Handler>
300 
302  virtual CWallet *wallet() { return nullptr; }
303 };
304 
309  std::string name;
310  std::string purpose;
311 
313  std::string nameIn, std::string purposeIn)
314  : dest(std::move(destIn)), is_mine(isMineIn), name(std::move(nameIn)),
315  purpose(std::move(purposeIn)) {}
316 };
317 
321  Amount unconfirmed_balance = Amount::zero();
322  Amount immature_balance = Amount::zero();
323  bool have_watch_only = false;
324  Amount watch_only_balance = Amount::zero();
325  Amount unconfirmed_watch_only_balance = Amount::zero();
326  Amount immature_watch_only_balance = Amount::zero();
327 
328  bool balanceChanged(const WalletBalances &prev) const {
329  return balance != prev.balance ||
330  unconfirmed_balance != prev.unconfirmed_balance ||
331  immature_balance != prev.immature_balance ||
332  watch_only_balance != prev.watch_only_balance ||
333  unconfirmed_watch_only_balance !=
335  immature_watch_only_balance != prev.immature_watch_only_balance;
336  }
337 };
338 
339 // Wallet transaction information.
340 struct WalletTx {
342  std::vector<isminetype> txin_is_mine;
343  std::vector<isminetype> txout_is_mine;
344  std::vector<CTxDestination> txout_address;
345  std::vector<isminetype> txout_address_is_mine;
349  int64_t time;
350  std::map<std::string, std::string> value_map;
352 };
353 
359  unsigned int time_received;
360  uint32_t lock_time;
361  bool is_final;
366 };
367 
369 struct WalletTxOut {
371  int64_t time;
372  int depth_in_main_chain = -1;
373  bool is_spent = false;
374 };
375 
378 std::unique_ptr<Wallet> MakeWallet(const std::shared_ptr<CWallet> &wallet);
379 
380 } // namespace interfaces
381 
382 #endif // BITCOIN_INTERFACES_WALLET_H
std::shared_ptr< const CTransaction > CTransactionRef
Definition: transaction.h:336
virtual bool isCrypted()=0
Return whether wallet is encrypted.
virtual bool privateKeysDisabled()=0
virtual Amount getRequiredFee(unsigned int tx_bytes)=0
Get required fee.
std::function< void(const std::string &title, int progress)> ShowProgressFn
Register handler for show progress messages.
Definition: wallet.h:270
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
static constexpr Amount zero()
Definition: amount.h:35
std::vector< CTxDestination > txout_address
Definition: wallet.h:344
virtual bool isLocked()=0
Return whether wallet is locked.
virtual OutputType getDefaultAddressType()=0
unsigned int time_received
Definition: wallet.h:359
Bilingual messages:
Definition: translation.h:17
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:292
virtual CWallet * wallet()
Return pointer to internal wallet class, useful for testing.
Definition: wallet.h:302
Amount unconfirmed_watch_only_balance
Definition: wallet.h:325
std::vector< isminetype > txin_is_mine
Definition: wallet.h:342
SigningResult
Definition: message.h:47
virtual std::unique_ptr< Handler > handleAddressBookChanged(AddressBookChangedFn fn)=0
std::vector< isminetype > txout_is_mine
Definition: wallet.h:343
const char * prefix
Definition: rest.cpp:755
virtual bool getPubKey(const CScript &script, const CKeyID &address, CPubKey &pub_key)=0
Get public key.
std::function< void()> UnloadFn
Register handler for unload message.
Definition: wallet.h:265
std::basic_string< char, std::char_traits< char >, secure_allocator< char > > SecureString
Definition: secure.h:56
Definition: amount.h:17
virtual CTransactionRef createTransaction(const std::vector< CRecipient > &recipients, const CCoinControl &coin_control, bool sign, int &change_pos, Amount &fee, bilingual_str &fail_reason)=0
Create transaction.
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:297
virtual void lockCoin(const COutPoint &output)=0
Lock coin.
CChainParams defines various tweakable parameters of a given instance of the Bitcoin system...
Definition: chainparams.h:47
CTransactionRef tx
Definition: wallet.h:341
A version of CTransaction with the PSBT format.
Definition: psbt.h:335
virtual Amount getAvailableBalance(const CCoinControl &coin_control)=0
Get available balance.
virtual bool transactionCanBeAbandoned(const TxId &txid)=0
Return whether transaction can be abandoned.
std::map< std::string, std::string > WalletValueMap
Definition: wallet.h:53
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:19
std::function< void()> StatusChangedFn
Register handler for status changed messages.
Definition: wallet.h:274
virtual Amount getDebit(const CTxIn &txin, isminefilter filter)=0
Return debit amount if transaction input belongs to wallet.
virtual isminetype txinIsMine(const CTxIn &txin)=0
Return whether transaction input belongs to wallet.
std::map< CTxDestination, std::vector< std::tuple< COutPoint, WalletTxOut > >> CoinsList
Return AvailableCoins + LockedCoins grouped by wallet address.
Definition: wallet.h:226
virtual std::unique_ptr< Handler > handleUnload(UnloadFn fn)=0
CTxDestination dest
Definition: wallet.h:307
std::string purpose
Definition: wallet.h:310
virtual std::set< CTxDestination > getLabelAddresses(const std::string &label)=0
Get set of addresses corresponding to a given label.
virtual std::unique_ptr< Handler > handleTransactionChanged(TransactionChangedFn fn)=0
virtual bool hdEnabled()=0
virtual bool tryGetBalances(WalletBalances &balances, int &num_blocks, bool force, int cached_num_blocks)=0
Get balances if possible without waiting for chain and wallet locks.
virtual std::unique_ptr< Handler > handleShowProgress(ShowProgressFn fn)=0
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.
virtual bool abandonTransaction(const TxId &txid)=0
Abandon transaction.
Collection of wallet balances.
Definition: wallet.h:319
An input of a transaction.
Definition: transaction.h:67
const char * name
Definition: rest.cpp:43
virtual Amount getMinimumFee(unsigned int tx_bytes, const CCoinControl &coin_control)=0
Get minimum fee.
virtual CTransactionRef getTx(const TxId &txid)=0
Get a transaction.
An encapsulated public key.
Definition: pubkey.h:31
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:281
Interface for accessing a wallet.
Definition: wallet.h:56
virtual bool encryptWallet(const SecureString &wallet_passphrase)=0
Encrypt wallet.
uint8_t isminefilter
Definition: wallet.h:38
virtual Amount getCredit(const CTxOut &txout, isminefilter filter)=0
Return credit amount if transaction input belongs to wallet.
isminetype
IsMine() return codes.
Definition: ismine.h:18
virtual bool tryGetTxStatus(const TxId &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.
An output of a transaction.
Definition: transaction.h:141
virtual WalletTx getWalletTxDetails(const TxId &txid, WalletTxStatus &tx_status, WalletOrderForm &order_form, bool &in_mempool, int &num_blocks)=0
Get transaction details.
An outpoint - a combination of a transaction hash and an index n into its vout.
Definition: transaction.h:22
virtual WalletTx getWalletTx(const TxId &txid)=0
Get transaction information.
std::unique_ptr< Wallet > MakeWallet(const std::shared_ptr< CWallet > &wallet)
Return implementation of Wallet interface.
Definition: dummywallet.cpp:84
static Amount balance
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 ~Wallet()
Definition: wallet.h:58
virtual bool getNewDestination(const OutputType type, const std::string label, CTxDestination &dest)=0
virtual const CChainParams & getChainParams()=0
Get chainparams.
std::vector< isminetype > txout_address_is_mine
Definition: wallet.h:345
virtual std::vector< WalletTx > getWalletTxs()=0
Get list of all wallet transactions.
virtual bool delAddressBook(const CTxDestination &dest)=0
virtual void listLockedCoins(std::vector< COutPoint > &outputs)=0
List locked coins.
virtual TransactionError fillPSBT(SigHashType sighash_type, bool sign, bool bip32derivs, PartiallySignedTransaction &psbtx, bool &complete) const =0
Fill PSBT.
Serialized script, used inside transaction inputs and outputs.
Definition: script.h:430
A TxId is the identifier of a transaction.
Definition: txid.h:14
Amount immature_watch_only_balance
Definition: wallet.h:326
virtual bool setAddressBook(const CTxDestination &dest, const std::string &name, const std::string &purpose)=0
Add or update address.
A mutable version of CTransaction.
Definition: transaction.h:295
A reference to a CKey: the Hash160 of its serialized public key.
Definition: pubkey.h:22
virtual bool haveWatchOnly()=0
Return whether wallet has watch only keys.
WalletAddress(CTxDestination destIn, isminetype isMineIn, std::string nameIn, std::string purposeIn)
Definition: wallet.h:312
A CWallet maintains a set of transactions and balances, and provides the ability to create new transa...
Definition: wallet.h:679
TransactionError
Definition: error.h:22
virtual bool isLockedCoin(const COutPoint &output)=0
Return whether coin is locked.
virtual Amount getDefaultMaxTxFee()=0
Get max tx fee.
std::vector< std::pair< std::string, std::string > > WalletOrderForm
Definition: wallet.h:52
Information about one wallet address.
Definition: wallet.h:306
virtual bool lock()=0
Lock wallet.
std::map< std::string, std::string > value_map
Definition: wallet.h:350
An encapsulated secp256k1 private key.
Definition: key.h:25
virtual void abortRescan()=0
Abort a rescan.
The basic transaction that is broadcasted on the network and contained in blocks. ...
Definition: transaction.h:211
virtual void commitTransaction(CTransactionRef tx, WalletValueMap value_map, WalletOrderForm order_form)=0
Commit transaction.
virtual WalletBalances getBalances()=0
Get balances.
ChangeType
General change type (added, updated, removed).
Definition: ui_change_type.h:9
virtual Amount getBalance()=0
Get balance.
Wallet transaction output.
Definition: wallet.h:369
bool balanceChanged(const WalletBalances &prev) const
Definition: wallet.h:328
std::function< void(const TxId &txid, ChangeType status)> TransactionChangedFn
Register handler for transaction changed messages.
Definition: wallet.h:287
virtual std::string getWalletName()=0
Get wallet name.
Updated transaction status.
Definition: wallet.h:355
boost::variant< CNoDestination, PKHash, ScriptHash > CTxDestination
A txout script template with a specific destination.
Definition: standard.h:87
virtual bool canGetAddresses() const =0
virtual std::vector< std::string > getDestValues(const std::string &prefix)=0
Get dest values with prefix.
Signature hash type wrapper class.
Definition: sighashtype.h:37
virtual bool unlock(const SecureString &wallet_passphrase)=0
Unlock wallet.
virtual std::vector< WalletAddress > getAddresses()=0
Get wallet address list.