Bitcoin ABC  0.26.3
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 <consensus/amount.h>
9 #include <interfaces/chain.h> // For ChainClient
10 #include <primitives/blockhash.h>
11 #include <primitives/transaction.h> // For CTxOut
12 #include <pubkey.h> // For CKeyID and CScriptID (definitions needed in CTxDestination instantiation)
13 #include <script/sighashtype.h>
14 #include <script/standard.h> // For CTxDestination
15 #include <support/allocators/secure.h> // For SecureString
16 #include <util/message.h>
17 #include <util/ui_change_type.h>
18 
19 #include <cstdint>
20 #include <functional>
21 #include <map>
22 #include <memory>
23 #include <string>
24 #include <tuple>
25 #include <utility>
26 #include <vector>
27 
28 class CChainParams;
29 class CCoinControl;
30 class CKey;
32 class COutPoint;
33 class CTransaction;
34 class CWallet;
35 enum class FeeReason;
36 enum class OutputType;
37 enum class TransactionError;
38 enum isminetype : unsigned int;
39 struct CRecipient;
41 struct WalletContext;
42 typedef uint8_t isminefilter;
43 struct TxId;
44 struct bilingual_str;
45 
46 namespace interfaces {
47 
48 class Handler;
49 struct WalletAddress;
50 struct WalletBalances;
51 struct WalletTx;
52 struct WalletTxOut;
53 struct WalletTxStatus;
54 
55 using WalletOrderForm = std::vector<std::pair<std::string, std::string>>;
56 using WalletValueMap = std::map<std::string, std::string>;
57 
59 class Wallet {
60 public:
61  virtual ~Wallet() {}
62 
64  virtual bool encryptWallet(const SecureString &wallet_passphrase) = 0;
65 
67  virtual bool isCrypted() = 0;
68 
70  virtual bool lock() = 0;
71 
73  virtual bool unlock(const SecureString &wallet_passphrase) = 0;
74 
76  virtual bool isLocked() = 0;
77 
79  virtual bool
80  changeWalletPassphrase(const SecureString &old_wallet_passphrase,
81  const SecureString &new_wallet_passphrase) = 0;
82 
84  virtual void abortRescan() = 0;
85 
87  virtual bool backupWallet(const std::string &filename) = 0;
88 
90  virtual std::string getWalletName() = 0;
91 
93  virtual const CChainParams &getChainParams() = 0;
94 
96  virtual std::set<CTxDestination>
97  getLabelAddresses(const std::string &label) = 0;
98 
99  // Get a new address.
100  virtual bool getNewDestination(const OutputType type,
101  const std::string label,
102  CTxDestination &dest) = 0;
103 
105  virtual bool getPubKey(const CScript &script, const CKeyID &address,
106  CPubKey &pub_key) = 0;
107 
109  virtual SigningResult signMessage(const std::string &message,
110  const PKHash &pkhash,
111  std::string &str_sig) = 0;
112 
114  virtual bool isSpendable(const CTxDestination &dest) = 0;
115 
117  virtual bool haveWatchOnly() = 0;
118 
120  virtual bool setAddressBook(const CTxDestination &dest,
121  const std::string &name,
122  const std::string &purpose) = 0;
123 
124  // Remove address.
125  virtual bool delAddressBook(const CTxDestination &dest) = 0;
126 
128  virtual bool getAddress(const CTxDestination &dest, std::string *name,
129  isminetype *is_mine, std::string *purpose) = 0;
130 
132  virtual std::vector<WalletAddress> getAddresses() = 0;
133 
135  virtual bool addDestData(const CTxDestination &dest, const std::string &key,
136  const std::string &value) = 0;
137 
139  virtual bool eraseDestData(const CTxDestination &dest,
140  const std::string &key) = 0;
141 
143  virtual std::vector<std::string>
144  getDestValues(const std::string &prefix) = 0;
145 
147  virtual void lockCoin(const COutPoint &output) = 0;
148 
150  virtual void unlockCoin(const COutPoint &output) = 0;
151 
153  virtual bool isLockedCoin(const COutPoint &output) = 0;
154 
156  virtual void listLockedCoins(std::vector<COutPoint> &outputs) = 0;
157 
159  virtual CTransactionRef
160  createTransaction(const std::vector<CRecipient> &recipients,
161  const CCoinControl &coin_control, bool sign,
162  int &change_pos, Amount &fee,
163  bilingual_str &fail_reason) = 0;
164 
167  WalletOrderForm order_form) = 0;
168 
170  virtual bool transactionCanBeAbandoned(const TxId &txid) = 0;
171 
173  virtual bool abandonTransaction(const TxId &txid) = 0;
174 
176  virtual CTransactionRef getTx(const TxId &txid) = 0;
177 
179  virtual WalletTx getWalletTx(const TxId &txid) = 0;
180 
182  virtual std::vector<WalletTx> getWalletTxs() = 0;
183 
186  virtual bool tryGetTxStatus(const TxId &txid, WalletTxStatus &tx_status,
187  int &num_blocks, int64_t &block_time) = 0;
188 
190  virtual WalletTx getWalletTxDetails(const TxId &txid,
191  WalletTxStatus &tx_status,
192  WalletOrderForm &order_form,
193  bool &in_mempool, int &num_blocks) = 0;
194 
196  virtual TransactionError fillPSBT(SigHashType sighash_type, bool sign,
197  bool bip32derivs,
199  bool &complete) const = 0;
200 
203 
205  virtual bool tryGetBalances(WalletBalances &balances,
206  BlockHash &block_hash) = 0;
207 
209  virtual Amount getBalance() = 0;
210 
212  virtual Amount getAvailableBalance(const CCoinControl &coin_control) = 0;
213 
215  virtual isminetype txinIsMine(const CTxIn &txin) = 0;
216 
218  virtual isminetype txoutIsMine(const CTxOut &txout) = 0;
219 
221  virtual Amount getDebit(const CTxIn &txin, isminefilter filter) = 0;
222 
224  virtual Amount getCredit(const CTxOut &txout, isminefilter filter) = 0;
225 
228  using CoinsList = std::map<CTxDestination,
229  std::vector<std::tuple<COutPoint, WalletTxOut>>>;
230  virtual CoinsList listCoins() = 0;
231 
233  virtual std::vector<WalletTxOut>
234  getCoins(const std::vector<COutPoint> &outputs) = 0;
235 
237  virtual Amount getRequiredFee(unsigned int tx_bytes) = 0;
238 
240  virtual Amount getMinimumFee(unsigned int tx_bytes,
241  const CCoinControl &coin_control) = 0;
242 
243  // Return whether HD enabled.
244  virtual bool hdEnabled() = 0;
245 
246  // Return whether the wallet is blank.
247  virtual bool canGetAddresses() const = 0;
248 
249  // Return whether private keys enabled.
250  virtual bool privateKeysDisabled() = 0;
251 
252  // Get default address type.
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 
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 
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 
308 class WalletClient : public ChainClient {
309 public:
311  virtual std::unique_ptr<Wallet>
312  createWallet(const std::string &name, const SecureString &passphrase,
313  uint64_t wallet_creation_flags, bilingual_str &error,
314  std::vector<bilingual_str> &warnings) = 0;
315 
317  virtual std::unique_ptr<Wallet>
318  loadWallet(const std::string &name, bilingual_str &error,
319  std::vector<bilingual_str> &warnings) = 0;
320 
322  virtual std::string getWalletDir() = 0;
323 
325  virtual std::vector<std::string> listWalletDir() = 0;
326 
328  virtual std::vector<std::unique_ptr<Wallet>> getWallets() = 0;
329 
333  using LoadWalletFn = std::function<void(std::unique_ptr<Wallet> wallet)>;
334  virtual std::unique_ptr<Handler> handleLoadWallet(LoadWalletFn fn) = 0;
335 };
336 
341  std::string name;
342  std::string purpose;
343 
345  std::string nameIn, std::string purposeIn)
346  : dest(std::move(destIn)), is_mine(isMineIn), name(std::move(nameIn)),
347  purpose(std::move(purposeIn)) {}
348 };
349 
355  bool have_watch_only = false;
359 
360  bool balanceChanged(const WalletBalances &prev) const {
361  return balance != prev.balance ||
368  }
369 };
370 
371 // Wallet transaction information.
372 struct WalletTx {
374  std::vector<isminetype> txin_is_mine;
375  std::vector<isminetype> txout_is_mine;
376  std::vector<CTxDestination> txout_address;
377  std::vector<isminetype> txout_address_is_mine;
381  int64_t time;
382  std::map<std::string, std::string> value_map;
384 };
385 
391  unsigned int time_received;
392  uint32_t lock_time;
393  bool is_final;
398 };
399 
401 struct WalletTxOut {
403  int64_t time;
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
CChainParams defines various tweakable parameters of a given instance of the Bitcoin system.
Definition: chainparams.h:74
Coin Control Features.
Definition: coincontrol.h:21
An encapsulated secp256k1 private key.
Definition: key.h:28
A reference to a CKey: the Hash160 of its serialized public key.
Definition: pubkey.h:22
A mutable version of CTransaction.
Definition: transaction.h:278
An outpoint - a combination of a transaction hash and an index n into its vout.
Definition: transaction.h:22
An encapsulated public key.
Definition: pubkey.h:31
Serialized script, used inside transaction inputs and outputs.
Definition: script.h:431
The basic transaction that is broadcasted on the network and contained in blocks.
Definition: transaction.h:194
An input of a transaction.
Definition: transaction.h:61
An output of a transaction.
Definition: transaction.h:130
A CWallet maintains a set of transactions and balances, and provides the ability to create new transa...
Definition: wallet.h:679
Signature hash type wrapper class.
Definition: sighashtype.h:37
Interface to let node manage chain clients (wallets, or maybe tools for monitoring and analysis in th...
Definition: chain.h:326
Interface giving clients (wallet processes, maybe other analysis tools in the future) ability to acce...
Definition: chain.h:121
Wallet chain client that in addition to having chain client methods for starting up,...
Definition: wallet.h:308
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
Create new wallet.
virtual std::vector< std::unique_ptr< Wallet > > getWallets()=0
Return interfaces for accessing wallets (if any).
virtual std::unique_ptr< Wallet > loadWallet(const std::string &name, bilingual_str &error, std::vector< bilingual_str > &warnings)=0
Load existing wallet.
virtual std::string getWalletDir()=0
Return default wallet directory.
virtual std::vector< std::string > listWalletDir()=0
Return available wallets in wallet directory.
std::function< void(std::unique_ptr< Wallet > wallet)> LoadWalletFn
Register handler for load wallet messages.
Definition: wallet.h:333
virtual std::unique_ptr< Handler > handleLoadWallet(LoadWalletFn fn)=0
Interface for accessing a wallet.
Definition: wallet.h:59
std::function< void(const TxId &txid, ChangeType status)> TransactionChangedFn
Register handler for transaction changed messages.
Definition: wallet.h:287
virtual bool getNewDestination(const OutputType type, const std::string label, CTxDestination &dest)=0
virtual CoinsList listCoins()=0
virtual bool getPubKey(const CScript &script, const CKeyID &address, CPubKey &pub_key)=0
Get public key.
virtual std::vector< WalletAddress > getAddresses()=0
Get wallet address list.
virtual bool encryptWallet(const SecureString &wallet_passphrase)=0
Encrypt wallet.
std::function< void(bool have_watch_only)> WatchOnlyChangedFn
Register handler for watchonly changed messages.
Definition: wallet.h:292
virtual bool isLegacy()=0
Return whether is a legacy wallet.
virtual bool canGetAddresses() const =0
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::function< void()> UnloadFn
Register handler for unload message.
Definition: wallet.h:265
virtual bool isLocked()=0
Return whether wallet is locked.
virtual std::unique_ptr< Handler > handleCanGetAddressesChanged(CanGetAddressesChangedFn fn)=0
virtual WalletTx getWalletTxDetails(const TxId &txid, WalletTxStatus &tx_status, WalletOrderForm &order_form, bool &in_mempool, int &num_blocks)=0
Get transaction details.
virtual WalletTx getWalletTx(const TxId &txid)=0
Get transaction information.
virtual void unlockCoin(const COutPoint &output)=0
Unlock coin.
virtual CWallet * wallet()
Return pointer to internal wallet class, useful for testing.
Definition: wallet.h:302
virtual std::unique_ptr< Handler > handleWatchOnlyChanged(WatchOnlyChangedFn fn)=0
virtual isminetype txinIsMine(const CTxIn &txin)=0
Return whether transaction input belongs to wallet.
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 void abortRescan()=0
Abort a rescan.
virtual ~Wallet()
Definition: wallet.h:61
virtual bool unlock(const SecureString &wallet_passphrase)=0
Unlock wallet.
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
virtual bool changeWalletPassphrase(const SecureString &old_wallet_passphrase, const SecureString &new_wallet_passphrase)=0
Change wallet passphrase.
virtual std::string getWalletName()=0
Get wallet name.
virtual bool setAddressBook(const CTxDestination &dest, const std::string &name, const std::string &purpose)=0
Add or update address.
std::function< void(const std::string &title, int progress)> ShowProgressFn
Register handler for show progress messages.
Definition: wallet.h:270
virtual bool isSpendable(const CTxDestination &dest)=0
Return whether wallet has private key.
virtual bool hdEnabled()=0
virtual std::unique_ptr< Handler > handleShowProgress(ShowProgressFn fn)=0
virtual bool isLockedCoin(const COutPoint &output)=0
Return whether coin is locked.
std::map< CTxDestination, std::vector< std::tuple< COutPoint, WalletTxOut > >> CoinsList
Return AvailableCoins + LockedCoins grouped by wallet address.
Definition: wallet.h:229
virtual WalletBalances getBalances()=0
Get balances.
virtual OutputType getDefaultAddressType()=0
virtual std::vector< std::string > getDestValues(const std::string &prefix)=0
Get dest values with prefix.
virtual bool tryGetBalances(WalletBalances &balances, BlockHash &block_hash)=0
Get balances if possible without blocking.
virtual std::unique_ptr< Handler > handleUnload(UnloadFn fn)=0
virtual Amount getDebit(const CTxIn &txin, isminefilter filter)=0
Return debit amount if transaction input belongs to wallet.
virtual bool backupWallet(const std::string &filename)=0
Back up wallet.
virtual void commitTransaction(CTransactionRef tx, WalletValueMap value_map, WalletOrderForm order_form)=0
Commit transaction.
virtual void listLockedCoins(std::vector< COutPoint > &outputs)=0
List locked coins.
virtual CTransactionRef getTx(const TxId &txid)=0
Get a transaction.
virtual bool abandonTransaction(const TxId &txid)=0
Abandon transaction.
virtual Amount getBalance()=0
Get balance.
virtual std::vector< WalletTx > getWalletTxs()=0
Get list of all wallet transactions.
virtual bool eraseDestData(const CTxDestination &dest, const std::string &key)=0
Erase dest data.
virtual bool delAddressBook(const CTxDestination &dest)=0
virtual void remove()=0
virtual TransactionError fillPSBT(SigHashType sighash_type, bool sign, bool bip32derivs, PartiallySignedTransaction &psbtx, bool &complete) const =0
Fill PSBT.
std::function< void()> StatusChangedFn
Register handler for status changed messages.
Definition: wallet.h:274
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 > handleStatusChanged(StatusChangedFn fn)=0
virtual bool haveWatchOnly()=0
Return whether wallet has watch only keys.
virtual isminetype txoutIsMine(const CTxOut &txout)=0
Return whether transaction output belongs to wallet.
virtual std::unique_ptr< Handler > handleAddressBookChanged(AddressBookChangedFn fn)=0
virtual std::set< CTxDestination > getLabelAddresses(const std::string &label)=0
Get set of addresses corresponding to a given label.
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.
virtual SigningResult signMessage(const std::string &message, const PKHash &pkhash, std::string &str_sig)=0
Sign message.
virtual const CChainParams & getChainParams()=0
Get chainparams.
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 Amount getCredit(const CTxOut &txout, isminefilter filter)=0
Return credit amount if transaction input belongs to wallet.
virtual bool lock()=0
Lock wallet.
virtual void lockCoin(const COutPoint &output)=0
Lock coin.
virtual Amount getMinimumFee(unsigned int tx_bytes, const CCoinControl &coin_control)=0
Get minimum fee.
std::function< void()> CanGetAddressesChangedFn
Register handler for keypool changed messages.
Definition: wallet.h:297
virtual bool isCrypted()=0
Return whether wallet is encrypted.
virtual std::unique_ptr< Handler > handleTransactionChanged(TransactionChangedFn fn)=0
virtual Amount getDefaultMaxTxFee()=0
Get max tx fee.
virtual Amount getRequiredFee(unsigned int tx_bytes)=0
Get required fee.
TransactionError
Definition: error.h:22
uint8_t isminefilter
Definition: wallet.h:41
isminetype
IsMine() return codes.
Definition: ismine.h:18
SigningResult
Definition: message.h:47
std::unique_ptr< Wallet > MakeWallet(const std::shared_ptr< CWallet > &wallet)
Return implementation of Wallet interface.
Definition: dummywallet.cpp:44
std::vector< std::pair< std::string, std::string > > WalletOrderForm
Definition: wallet.h:55
std::unique_ptr< WalletClient > MakeWalletClient(Chain &chain, ArgsManager &args)
Return implementation of ChainClient interface for a wallet client.
Definition: wallet.cpp:566
std::map< std::string, std::string > WalletValueMap
Definition: wallet.h:56
OutputType
Definition: outputtype.h:17
std::shared_ptr< const CTransaction > CTransactionRef
Definition: transaction.h:319
const char * prefix
Definition: rest.cpp:818
const char * name
Definition: rest.cpp:45
std::basic_string< char, std::char_traits< char >, secure_allocator< char > > SecureString
Definition: secure.h:56
boost::variant< CNoDestination, PKHash, ScriptHash > CTxDestination
A txout script template with a specific destination.
Definition: standard.h:93
Definition: amount.h:19
static constexpr Amount zero()
Definition: amount.h:42
A BlockHash is a unqiue identifier for a block.
Definition: blockhash.h:13
A version of CTransaction with the PSBT format.
Definition: psbt.h:335
A TxId is the identifier of a transaction.
Definition: txid.h:14
WalletContext struct containing references to state shared between CWallet instances,...
Definition: context.h:23
Bilingual messages:
Definition: translation.h:17
Information about one wallet address.
Definition: wallet.h:338
CTxDestination dest
Definition: wallet.h:339
std::string purpose
Definition: wallet.h:342
WalletAddress(CTxDestination destIn, isminetype isMineIn, std::string nameIn, std::string purposeIn)
Definition: wallet.h:344
Collection of wallet balances.
Definition: wallet.h:351
Amount immature_watch_only_balance
Definition: wallet.h:358
Amount unconfirmed_watch_only_balance
Definition: wallet.h:357
bool balanceChanged(const WalletBalances &prev) const
Definition: wallet.h:360
std::vector< CTxDestination > txout_address
Definition: wallet.h:376
std::vector< isminetype > txout_is_mine
Definition: wallet.h:375
CTransactionRef tx
Definition: wallet.h:373
std::map< std::string, std::string > value_map
Definition: wallet.h:382
std::vector< isminetype > txout_address_is_mine
Definition: wallet.h:377
std::vector< isminetype > txin_is_mine
Definition: wallet.h:374
Wallet transaction output.
Definition: wallet.h:401
Updated transaction status.
Definition: wallet.h:387
unsigned int time_received
Definition: wallet.h:391
bool error(const char *fmt, const Args &...args)
Definition: system.h:46
ChangeType
General change type (added, updated, removed).
Definition: ui_change_type.h:9