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 
95  // Get a new address.
96  virtual bool getNewDestination(const OutputType type,
97  const std::string label,
98  CTxDestination &dest) = 0;
99 
101  virtual bool getPubKey(const CScript &script, const CKeyID &address,
102  CPubKey &pub_key) = 0;
103 
105  virtual SigningResult signMessage(const std::string &message,
106  const PKHash &pkhash,
107  std::string &str_sig) = 0;
108 
110  virtual bool isSpendable(const CTxDestination &dest) = 0;
111 
113  virtual bool haveWatchOnly() = 0;
114 
116  virtual bool setAddressBook(const CTxDestination &dest,
117  const std::string &name,
118  const std::string &purpose) = 0;
119 
120  // Remove address.
121  virtual bool delAddressBook(const CTxDestination &dest) = 0;
122 
124  virtual bool getAddress(const CTxDestination &dest, std::string *name,
125  isminetype *is_mine, std::string *purpose) = 0;
126 
128  virtual std::vector<WalletAddress> getAddresses() = 0;
129 
131  virtual bool addDestData(const CTxDestination &dest, const std::string &key,
132  const std::string &value) = 0;
133 
135  virtual bool eraseDestData(const CTxDestination &dest,
136  const std::string &key) = 0;
137 
139  virtual std::vector<std::string>
140  getDestValues(const std::string &prefix) = 0;
141 
143  virtual void lockCoin(const COutPoint &output) = 0;
144 
146  virtual void unlockCoin(const COutPoint &output) = 0;
147 
149  virtual bool isLockedCoin(const COutPoint &output) = 0;
150 
152  virtual void listLockedCoins(std::vector<COutPoint> &outputs) = 0;
153 
155  virtual CTransactionRef
156  createTransaction(const std::vector<CRecipient> &recipients,
157  const CCoinControl &coin_control, bool sign,
158  int &change_pos, Amount &fee,
159  bilingual_str &fail_reason) = 0;
160 
163  WalletOrderForm order_form) = 0;
164 
166  virtual bool transactionCanBeAbandoned(const TxId &txid) = 0;
167 
169  virtual bool abandonTransaction(const TxId &txid) = 0;
170 
172  virtual CTransactionRef getTx(const TxId &txid) = 0;
173 
175  virtual WalletTx getWalletTx(const TxId &txid) = 0;
176 
178  virtual std::vector<WalletTx> getWalletTxs() = 0;
179 
182  virtual bool tryGetTxStatus(const TxId &txid, WalletTxStatus &tx_status,
183  int &num_blocks, int64_t &block_time) = 0;
184 
186  virtual WalletTx getWalletTxDetails(const TxId &txid,
187  WalletTxStatus &tx_status,
188  WalletOrderForm &order_form,
189  bool &in_mempool, int &num_blocks) = 0;
190 
192  virtual TransactionError fillPSBT(SigHashType sighash_type, bool sign,
193  bool bip32derivs,
195  bool &complete) const = 0;
196 
199 
201  virtual bool tryGetBalances(WalletBalances &balances,
202  BlockHash &block_hash) = 0;
203 
205  virtual Amount getBalance() = 0;
206 
208  virtual Amount getAvailableBalance(const CCoinControl &coin_control) = 0;
209 
211  virtual isminetype txinIsMine(const CTxIn &txin) = 0;
212 
214  virtual isminetype txoutIsMine(const CTxOut &txout) = 0;
215 
217  virtual Amount getDebit(const CTxIn &txin, isminefilter filter) = 0;
218 
220  virtual Amount getCredit(const CTxOut &txout, isminefilter filter) = 0;
221 
224  using CoinsList = std::map<CTxDestination,
225  std::vector<std::tuple<COutPoint, WalletTxOut>>>;
226  virtual CoinsList listCoins() = 0;
227 
229  virtual std::vector<WalletTxOut>
230  getCoins(const std::vector<COutPoint> &outputs) = 0;
231 
233  virtual Amount getRequiredFee(unsigned int tx_bytes) = 0;
234 
236  virtual Amount getMinimumFee(unsigned int tx_bytes,
237  const CCoinControl &coin_control) = 0;
238 
239  // Return whether HD enabled.
240  virtual bool hdEnabled() = 0;
241 
242  // Return whether the wallet is blank.
243  virtual bool canGetAddresses() const = 0;
244 
245  // Return whether private keys enabled.
246  virtual bool privateKeysDisabled() = 0;
247 
248  // Get default address type.
250 
252  virtual Amount getDefaultMaxTxFee() = 0;
253 
254  // Remove wallet.
255  virtual void remove() = 0;
256 
258  virtual bool isLegacy() = 0;
259 
261  using UnloadFn = std::function<void()>;
262  virtual std::unique_ptr<Handler> handleUnload(UnloadFn fn) = 0;
263 
266  std::function<void(const std::string &title, int progress)>;
267  virtual std::unique_ptr<Handler> handleShowProgress(ShowProgressFn fn) = 0;
268 
270  using StatusChangedFn = std::function<void()>;
271  virtual std::unique_ptr<Handler>
273 
275  using AddressBookChangedFn = std::function<void(
276  const CTxDestination &address, const std::string &label, bool is_mine,
277  const std::string &purpose, ChangeType status)>;
278  virtual std::unique_ptr<Handler>
280 
283  std::function<void(const TxId &txid, ChangeType status)>;
284  virtual std::unique_ptr<Handler>
286 
288  using WatchOnlyChangedFn = std::function<void(bool have_watch_only)>;
289  virtual std::unique_ptr<Handler>
291 
293  using CanGetAddressesChangedFn = std::function<void()>;
294  virtual std::unique_ptr<Handler>
296 
298  virtual CWallet *wallet() { return nullptr; }
299 };
300 
304 class WalletClient : public ChainClient {
305 public:
307  virtual std::unique_ptr<Wallet>
308  createWallet(const std::string &name, const SecureString &passphrase,
309  uint64_t wallet_creation_flags, bilingual_str &error,
310  std::vector<bilingual_str> &warnings) = 0;
311 
313  virtual std::unique_ptr<Wallet>
314  loadWallet(const std::string &name, bilingual_str &error,
315  std::vector<bilingual_str> &warnings) = 0;
316 
318  virtual std::string getWalletDir() = 0;
319 
321  virtual std::vector<std::string> listWalletDir() = 0;
322 
324  virtual std::vector<std::unique_ptr<Wallet>> getWallets() = 0;
325 
329  using LoadWalletFn = std::function<void(std::unique_ptr<Wallet> wallet)>;
330  virtual std::unique_ptr<Handler> handleLoadWallet(LoadWalletFn fn) = 0;
331 };
332 
337  std::string name;
338  std::string purpose;
339 
341  std::string nameIn, std::string purposeIn)
342  : dest(std::move(destIn)), is_mine(isMineIn), name(std::move(nameIn)),
343  purpose(std::move(purposeIn)) {}
344 };
345 
351  bool have_watch_only = false;
355 
356  bool balanceChanged(const WalletBalances &prev) const {
357  return balance != prev.balance ||
364  }
365 };
366 
367 // Wallet transaction information.
368 struct WalletTx {
370  std::vector<isminetype> txin_is_mine;
371  std::vector<isminetype> txout_is_mine;
372  std::vector<CTxDestination> txout_address;
373  std::vector<isminetype> txout_address_is_mine;
377  int64_t time;
378  std::map<std::string, std::string> value_map;
380 };
381 
387  unsigned int time_received;
388  uint32_t lock_time;
393 };
394 
396 struct WalletTxOut {
398  int64_t time;
400  bool is_spent = false;
401 };
402 
405 std::unique_ptr<Wallet> MakeWallet(const std::shared_ptr<CWallet> &wallet);
406 
409 std::unique_ptr<WalletClient> MakeWalletClient(Chain &chain, ArgsManager &args);
410 
411 } // namespace interfaces
412 
413 #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:274
An outpoint - a combination of a transaction hash and an index n into its vout.
Definition: transaction.h:20
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:192
An input of a transaction.
Definition: transaction.h:59
An output of a transaction.
Definition: transaction.h:128
A CWallet maintains a set of transactions and balances, and provides the ability to create new transa...
Definition: wallet.h:253
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:310
Interface giving clients (wallet processes, maybe other analysis tools in the future) ability to acce...
Definition: chain.h:123
Wallet chain client that in addition to having chain client methods for starting up,...
Definition: wallet.h:304
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:329
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:283
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:288
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:261
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:298
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:277
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:266
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:225
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:270
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 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:293
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: interfaces.cpp:581
std::map< std::string, std::string > WalletValueMap
Definition: wallet.h:56
Implement std::hash so RCUPtr can be used as a key for maps or sets.
Definition: rcu.h:257
OutputType
Definition: outputtype.h:16
std::shared_ptr< const CTransaction > CTransactionRef
Definition: transaction.h:315
const char * prefix
Definition: rest.cpp:818
const char * name
Definition: rest.cpp:47
std::basic_string< char, std::char_traits< char >, secure_allocator< char > > SecureString
Definition: secure.h:55
std::variant< CNoDestination, PKHash, ScriptHash > CTxDestination
A txout script template with a specific destination.
Definition: standard.h:92
Definition: amount.h:19
static constexpr Amount zero() noexcept
Definition: amount.h:32
A BlockHash is a unqiue identifier for a block.
Definition: blockhash.h:13
A version of CTransaction with the PSBT format.
Definition: psbt.h:334
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:334
CTxDestination dest
Definition: wallet.h:335
std::string purpose
Definition: wallet.h:338
WalletAddress(CTxDestination destIn, isminetype isMineIn, std::string nameIn, std::string purposeIn)
Definition: wallet.h:340
Collection of wallet balances.
Definition: wallet.h:347
Amount immature_watch_only_balance
Definition: wallet.h:354
Amount unconfirmed_watch_only_balance
Definition: wallet.h:353
bool balanceChanged(const WalletBalances &prev) const
Definition: wallet.h:356
std::vector< CTxDestination > txout_address
Definition: wallet.h:372
std::vector< isminetype > txout_is_mine
Definition: wallet.h:371
CTransactionRef tx
Definition: wallet.h:369
std::map< std::string, std::string > value_map
Definition: wallet.h:378
std::vector< isminetype > txout_address_is_mine
Definition: wallet.h:373
std::vector< isminetype > txin_is_mine
Definition: wallet.h:370
Wallet transaction output.
Definition: wallet.h:396
Updated transaction status.
Definition: wallet.h:383
unsigned int time_received
Definition: wallet.h:387
bool error(const char *fmt, const Args &...args)
Definition: system.h:45
ChangeType
General change type (added, updated, removed).
Definition: ui_change_type.h:9