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; 34 struct PartiallySignedTransaction; 35 struct WalletContext; 36 struct bilingual_str; 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 51 //! Interface for accessing a wallet. 52 class Wallet 53 { 54 public: ~Wallet()55 virtual ~Wallet() {} 56 57 //! Encrypt wallet. 58 virtual bool encryptWallet(const SecureString& wallet_passphrase) = 0; 59 60 //! Return whether wallet is encrypted. 61 virtual bool isCrypted() = 0; 62 63 //! Lock wallet. 64 virtual bool lock() = 0; 65 66 //! Unlock wallet. 67 virtual bool unlock(const SecureString& wallet_passphrase) = 0; 68 69 //! Return whether wallet is locked. 70 virtual bool isLocked() = 0; 71 72 //! Change wallet passphrase. 73 virtual bool changeWalletPassphrase(const SecureString& old_wallet_passphrase, 74 const SecureString& new_wallet_passphrase) = 0; 75 76 //! Abort a rescan. 77 virtual void abortRescan() = 0; 78 79 //! Back up wallet. 80 virtual bool backupWallet(const std::string& filename) = 0; 81 82 //! Get wallet name. 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 88 //! Get public key. 89 virtual bool getPubKey(const CScript& script, const CKeyID& address, CPubKey& pub_key) = 0; 90 91 //! Sign message 92 virtual SigningResult signMessage(const std::string& message, const PKHash& pkhash, std::string& str_sig) = 0; 93 94 //! Return whether wallet has private key. 95 virtual bool isSpendable(const CTxDestination& dest) = 0; 96 97 //! Return whether wallet has watch only keys. 98 virtual bool haveWatchOnly() = 0; 99 100 //! Add or update address. 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 106 //! Look up address in wallet, return whether exists. 107 virtual bool getAddress(const CTxDestination& dest, 108 std::string* name, 109 isminetype* is_mine, 110 std::string* purpose) = 0; 111 112 //! Get wallet address list. 113 virtual std::vector<WalletAddress> getAddresses() = 0; 114 115 //! Add dest data. 116 virtual bool addDestData(const CTxDestination& dest, const std::string& key, const std::string& value) = 0; 117 118 //! Erase dest data. 119 virtual bool eraseDestData(const CTxDestination& dest, const std::string& key) = 0; 120 121 //! Get dest values with prefix. 122 virtual std::vector<std::string> getDestValues(const std::string& prefix) = 0; 123 124 //! Lock coin. 125 virtual void lockCoin(const COutPoint& output) = 0; 126 127 //! Unlock coin. 128 virtual void unlockCoin(const COutPoint& output) = 0; 129 130 //! Return whether coin is locked. 131 virtual bool isLockedCoin(const COutPoint& output) = 0; 132 133 //! List locked coins. 134 virtual void listLockedCoins(std::vector<COutPoint>& outputs) = 0; 135 136 //! Create transaction. 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 144 //! Commit transaction. 145 virtual void commitTransaction(CTransactionRef tx, 146 WalletValueMap value_map, 147 WalletOrderForm order_form) = 0; 148 149 //! Return whether transaction can be abandoned. 150 virtual bool transactionCanBeAbandoned(const uint256& txid) = 0; 151 152 //! Abandon transaction. 153 virtual bool abandonTransaction(const uint256& txid) = 0; 154 155 //! Return whether transaction can be bumped. 156 virtual bool transactionCanBeBumped(const uint256& txid) = 0; 157 158 //! Create bump transaction. 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 166 //! Sign bump transaction. 167 virtual bool signBumpTransaction(CMutableTransaction& mtx) = 0; 168 169 //! Commit bump transaction. 170 virtual bool commitBumpTransaction(const uint256& txid, 171 CMutableTransaction&& mtx, 172 std::vector<bilingual_str>& errors, 173 uint256& bumped_txid) = 0; 174 175 //! Get a transaction. 176 virtual CTransactionRef getTx(const uint256& txid) = 0; 177 178 //! Get transaction information. 179 virtual WalletTx getWalletTx(const uint256& txid) = 0; 180 181 //! Get list of all wallet transactions. 182 virtual std::vector<WalletTx> getWalletTxs() = 0; 183 184 //! Try to get updated status for a particular transaction, if possible without blocking. 185 virtual bool tryGetTxStatus(const uint256& txid, 186 WalletTxStatus& tx_status, 187 int& num_blocks, 188 int64_t& block_time) = 0; 189 190 //! Get transaction details. 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 197 //! Fill PSBT. 198 virtual TransactionError fillPSBT(int sighash_type, 199 bool sign, 200 bool bip32derivs, 201 PartiallySignedTransaction& psbtx, 202 bool& complete, 203 size_t* n_signed) = 0; 204 205 //! Get balances. 206 virtual WalletBalances getBalances() = 0; 207 208 //! Get balances if possible without blocking. 209 virtual bool tryGetBalances(WalletBalances& balances, uint256& block_hash) = 0; 210 211 //! Get balance. 212 virtual CAmount getBalance() = 0; 213 214 //! Get available balance. 215 virtual CAmount getAvailableBalance(const CCoinControl& coin_control) = 0; 216 217 //! Return whether transaction input belongs to wallet. 218 virtual isminetype txinIsMine(const CTxIn& txin) = 0; 219 220 //! Return whether transaction output belongs to wallet. 221 virtual isminetype txoutIsMine(const CTxOut& txout) = 0; 222 223 //! Return debit amount if transaction input belongs to wallet. 224 virtual CAmount getDebit(const CTxIn& txin, isminefilter filter) = 0; 225 226 //! Return credit amount if transaction input belongs to wallet. 227 virtual CAmount getCredit(const CTxOut& txout, isminefilter filter) = 0; 228 229 //! Return AvailableCoins + LockedCoins grouped by wallet address. 230 //! (put change in one group with wallet address) 231 using CoinsList = std::map<CTxDestination, std::vector<std::tuple<COutPoint, WalletTxOut>>>; 232 virtual CoinsList listCoins() = 0; 233 234 //! Return wallet transaction output information. 235 virtual std::vector<WalletTxOut> getCoins(const std::vector<COutPoint>& outputs) = 0; 236 237 //! Get required fee. 238 virtual CAmount getRequiredFee(unsigned int tx_bytes) = 0; 239 240 //! Get minimum fee. 241 virtual CAmount getMinimumFee(unsigned int tx_bytes, 242 const CCoinControl& coin_control, 243 int* returned_target, 244 FeeReason* reason) = 0; 245 246 //! Get tx confirm target. 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 261 //! Get max tx fee. 262 virtual CAmount getDefaultMaxTxFee() = 0; 263 264 // Remove wallet. 265 virtual void remove() = 0; 266 267 //! Return whether is a legacy wallet 268 virtual bool isLegacy() = 0; 269 270 //! Register handler for unload message. 271 using UnloadFn = std::function<void()>; 272 virtual std::unique_ptr<Handler> handleUnload(UnloadFn fn) = 0; 273 274 //! Register handler for show progress messages. 275 using ShowProgressFn = std::function<void(const std::string& title, int progress)>; 276 virtual std::unique_ptr<Handler> handleShowProgress(ShowProgressFn fn) = 0; 277 278 //! Register handler for status changed messages. 279 using StatusChangedFn = std::function<void()>; 280 virtual std::unique_ptr<Handler> handleStatusChanged(StatusChangedFn fn) = 0; 281 282 //! Register handler for address book changed messages. 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 290 //! Register handler for transaction changed messages. 291 using TransactionChangedFn = std::function<void(const uint256& txid, ChangeType status)>; 292 virtual std::unique_ptr<Handler> handleTransactionChanged(TransactionChangedFn fn) = 0; 293 294 //! Register handler for watchonly changed messages. 295 using WatchOnlyChangedFn = std::function<void(bool have_watch_only)>; 296 virtual std::unique_ptr<Handler> handleWatchOnlyChanged(WatchOnlyChangedFn fn) = 0; 297 298 //! Register handler for keypool changed messages. 299 using CanGetAddressesChangedFn = std::function<void()>; 300 virtual std::unique_ptr<Handler> handleCanGetAddressesChanged(CanGetAddressesChangedFn fn) = 0; 301 302 //! Return pointer to internal wallet class, useful for testing. wallet()303 virtual CWallet* wallet() { return nullptr; } 304 }; 305 306 //! Wallet chain client that in addition to having chain client methods for 307 //! starting up, shutting down, and registering RPCs, also has additional 308 //! methods (called by the GUI) to load and create wallets. 309 class WalletClient : public ChainClient 310 { 311 public: 312 //! Create new wallet. 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 315 //! Load existing wallet. 316 virtual std::unique_ptr<Wallet> loadWallet(const std::string& name, bilingual_str& error, std::vector<bilingual_str>& warnings) = 0; 317 318 //! Return default wallet directory. 319 virtual std::string getWalletDir() = 0; 320 321 //! Return available wallets in wallet directory. 322 virtual std::vector<std::string> listWalletDir() = 0; 323 324 //! Return interfaces for accessing wallets (if any). 325 virtual std::vector<std::unique_ptr<Wallet>> getWallets() = 0; 326 327 //! Register handler for load wallet messages. This callback is triggered by 328 //! createWallet and loadWallet above, and also triggered when wallets are 329 //! loaded at startup or by RPC. 330 using LoadWalletFn = std::function<void(std::unique_ptr<Wallet> wallet)>; 331 virtual std::unique_ptr<Handler> handleLoadWallet(LoadWalletFn fn) = 0; 332 }; 333 334 //! Information about one wallet address. 335 struct WalletAddress 336 { 337 CTxDestination dest; 338 isminetype is_mine; 339 std::string name; 340 std::string purpose; 341 WalletAddressWalletAddress342 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 348 //! Collection of wallet balances. 349 struct WalletBalances 350 { 351 CAmount balance = 0; 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 balanceChangedWalletBalances359 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 { 371 CTransactionRef tx; 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; 376 CAmount credit; 377 CAmount debit; 378 CAmount change; 379 int64_t time; 380 std::map<std::string, std::string> value_map; 381 bool is_coinbase; 382 }; 383 384 //! Updated transaction status. 385 struct WalletTxStatus 386 { 387 int block_height; 388 int blocks_to_maturity; 389 int depth_in_main_chain; 390 unsigned int time_received; 391 uint32_t lock_time; 392 bool is_final; 393 bool is_trusted; 394 bool is_abandoned; 395 bool is_coinbase; 396 bool is_in_main_chain; 397 }; 398 399 //! Wallet transaction output. 400 struct WalletTxOut 401 { 402 CTxOut txout; 403 int64_t time; 404 int depth_in_main_chain = -1; 405 bool is_spent = false; 406 }; 407 408 //! Return implementation of Wallet interface. This function is defined in 409 //! dummywallet.cpp and throws if the wallet component is not compiled. 410 std::unique_ptr<Wallet> MakeWallet(const std::shared_ptr<CWallet>& wallet); 411 412 //! Return implementation of ChainClient interface for a wallet client. This 413 //! function will be undefined in builds where ENABLE_WALLET is false. 414 std::unique_ptr<WalletClient> MakeWalletClient(Chain& chain, ArgsManager& args); 415 416 } // namespace interfaces 417 418 #endif // BITCOIN_INTERFACES_WALLET_H 419