wallet.h

Go to the documentation of this file.

// Copyright (c) 2018-present The Bitcoin Core developers
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
#ifndef BITCOIN_INTERFACES_WALLET_H
#define BITCOIN_INTERFACES_WALLET_H
 
#include <addresstype.h>
#include <common/signmessage.h>
#include <common/types.h>
#include <consensus/amount.h>
#include <interfaces/chain.h>
#include <primitives/transaction.h>
#include <pubkey.h>
#include <support/allocators/secure.h>
#include <util/expected.h>
#include <util/fs.h>
#include <util/result.h>
#include <util/ui_change_type.h>
#include <wallet/types.h>
 
#include <compare>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <map>
#include <memory>
#include <optional>
#include <set>
#include <string>
#include <tuple>
#include <utility>
#include <vector>
 
class ArgsManager;
class CScript;
class PartiallySignedTransaction;
class uint256;
enum class FeeReason;
enum class OutputType;
struct bilingual_str;
struct CExtKey;
 
namespace wallet {
class CCoinControl;
class CWallet;
struct ImportDescriptorRequest;
struct ImportResult;
struct CRecipient;
struct WalletContext;
} // namespace wallet
 
namespace interfaces {
 
class Handler;
struct WalletAddress;
struct WalletBalances;
struct WalletTx;
struct WalletTxOut;
struct WalletTxStatus;
struct WalletMigrationResult;
 
class Wallet
{
public:
    virtual ~Wallet() = default;
 
    virtual bool encryptWallet(const SecureString& wallet_passphrase) = 0;
 
    virtual bool isCrypted() = 0;
 
    virtual bool lock() = 0;
 
    virtual util::Expected<void, wallet::WalletError> unlock(const SecureString& wallet_passphrase) = 0;
 
    virtual bool isLocked() = 0;
 
    virtual util::Expected<void, wallet::WalletError> changeWalletPassphrase(const SecureString& old_wallet_passphrase,
                                                                             const SecureString& new_wallet_passphrase) = 0;
 
    virtual void abortRescan() = 0;
 
    virtual bool backupWallet(const std::string& filename) = 0;
 
    virtual std::string getWalletName() = 0;
 
    // Get a new address.
    virtual util::Result<CTxDestination> getNewDestination(OutputType type, const std::string& label) = 0;
 
    virtual bool getPubKey(const CScript& script, const CKeyID& address, CPubKey& pub_key) = 0;
 
    virtual util::Expected<CExtPubKey, wallet::WalletError> addHDKey(const std::optional<CExtKey>& key) = 0;
 
    virtual SigningResult signMessage(const std::string& message, const PKHash& pkhash, std::string& str_sig) = 0;
 
    virtual bool isSpendable(const CTxDestination& dest) = 0;
 
    virtual bool setAddressBook(const CTxDestination& dest, const std::string& name, const std::optional<wallet::AddressPurpose>& purpose) = 0;
 
    // Remove address.
    virtual bool delAddressBook(const CTxDestination& dest) = 0;
 
    virtual bool getAddress(const CTxDestination& dest,
        std::string* name,
        wallet::AddressPurpose* purpose) = 0;
 
    virtual std::vector<WalletAddress> getAddresses() = 0;
 
    virtual std::vector<std::string> getAddressReceiveRequests() = 0;
 
    virtual bool setAddressReceiveRequest(const CTxDestination& dest, const std::string& id, const std::string& value) = 0;
 
    virtual util::Result<void> displayAddress(const CTxDestination& dest) = 0;
 
    virtual bool lockCoin(const COutPoint& output, bool write_to_db) = 0;
 
    virtual bool unlockCoin(const COutPoint& output) = 0;
 
    virtual bool isLockedCoin(const COutPoint& output) = 0;
 
    virtual void listLockedCoins(std::vector<COutPoint>& outputs) = 0;
 
    virtual util::Result<wallet::CreatedTransactionResult> createTransaction(const std::vector<wallet::CRecipient>& recipients,
        const wallet::CCoinControl& coin_control,
        bool sign,
        std::optional<unsigned int> change_pos) = 0;
 
    virtual void commitTransaction(CTransactionRef tx, const std::vector<std::string>& messages) = 0;
 
    virtual bool transactionCanBeAbandoned(const Txid& txid) = 0;
 
    virtual bool abandonTransaction(const Txid& txid) = 0;
 
    virtual bool transactionCanBeBumped(const Txid& txid) = 0;
 
    virtual bool createBumpTransaction(const Txid& txid,
        const wallet::CCoinControl& coin_control,
        std::vector<bilingual_str>& errors,
        CAmount& old_fee,
        CAmount& new_fee,
        CMutableTransaction& mtx) = 0;
 
    virtual bool signBumpTransaction(CMutableTransaction& mtx) = 0;
 
    virtual bool commitBumpTransaction(const Txid& txid,
        CMutableTransaction&& mtx,
        std::vector<bilingual_str>& errors,
        Txid& bumped_txid) = 0;
 
    virtual CTransactionRef getTx(const Txid& txid) = 0;
 
    virtual WalletTx getWalletTx(const Txid& txid) = 0;
 
    virtual std::set<WalletTx> getWalletTxs() = 0;
 
    virtual bool tryGetTxStatus(const Txid& txid,
        WalletTxStatus& tx_status,
        int& num_blocks,
        int64_t& block_time) = 0;
 
    virtual WalletTx getWalletTxDetails(const Txid& txid,
        WalletTxStatus& tx_status,
        std::vector<std::string>& messages,
        std::vector<std::string>& payment_requests,
        bool& in_mempool,
        int& num_blocks) = 0;
 
    virtual std::optional<common::PSBTError> fillPSBT(const common::PSBTFillOptions& options,
        size_t* n_signed,
        PartiallySignedTransaction& psbtx,
        bool& complete) = 0;
 
    virtual std::vector<wallet::ImportResult> importDescriptors(std::vector<wallet::ImportDescriptorRequest>& requests) = 0;
 
    virtual WalletBalances getBalances() = 0;
 
    virtual bool tryGetBalances(WalletBalances& balances, uint256& block_hash) = 0;
 
    virtual CAmount getBalance() = 0;
 
    virtual CAmount getAvailableBalance(const wallet::CCoinControl& coin_control) = 0;
 
    virtual bool txinIsMine(const CTxIn& txin) = 0;
 
    virtual bool txoutIsMine(const CTxOut& txout) = 0;
 
    virtual CAmount getDebit(const CTxIn& txin) = 0;
 
    virtual CAmount getCredit(const CTxOut& txout) = 0;
 
    using CoinsList = std::map<CTxDestination, std::vector<std::tuple<COutPoint, WalletTxOut>>>;
    virtual CoinsList listCoins() = 0;
 
    virtual std::vector<WalletTxOut> getCoins(const std::vector<COutPoint>& outputs) = 0;
 
    virtual CAmount getRequiredFee(unsigned int tx_bytes) = 0;
 
    virtual CAmount getMinimumFee(unsigned int tx_bytes,
        const wallet::CCoinControl& coin_control,
        std::optional<int>* returned_target,
        FeeReason* reason) = 0;
 
    virtual unsigned int getConfirmTarget() = 0;
 
    // Return whether HD enabled.
    virtual bool hdEnabled() = 0;
 
    // Return whether the wallet is blank.
    virtual bool canGetAddresses() = 0;
 
    // Return whether private keys enabled.
    virtual bool privateKeysDisabled() = 0;
 
    // Return whether the wallet contains a Taproot scriptPubKeyMan
    virtual bool taprootEnabled() = 0;
 
    // Return whether wallet uses an external signer.
    virtual bool hasExternalSigner() = 0;
 
    // Get default address type.
    virtual OutputType getDefaultAddressType() = 0;
 
    virtual CAmount getMaxTxFee() = 0;
 
    // Remove wallet.
    virtual void remove() = 0;
 
    using UnloadFn = std::function<void()>;
    virtual std::unique_ptr<Handler> handleUnload(UnloadFn fn) = 0;
 
    using ShowProgressFn = std::function<void(const std::string& title, int progress)>;
    virtual std::unique_ptr<Handler> handleShowProgress(ShowProgressFn fn) = 0;
 
    using StatusChangedFn = std::function<void()>;
    virtual std::unique_ptr<Handler> handleStatusChanged(StatusChangedFn fn) = 0;
 
    using AddressBookChangedFn = std::function<void(const CTxDestination& address,
        const std::string& label,
        bool is_mine,
        wallet::AddressPurpose purpose,
        ChangeType status)>;
    virtual std::unique_ptr<Handler> handleAddressBookChanged(AddressBookChangedFn fn) = 0;
 
    using TransactionChangedFn = std::function<void(const Txid& txid, ChangeType status)>;
    virtual std::unique_ptr<Handler> handleTransactionChanged(TransactionChangedFn fn) = 0;
 
    using CanGetAddressesChangedFn = std::function<void()>;
    virtual std::unique_ptr<Handler> handleCanGetAddressesChanged(CanGetAddressesChangedFn fn) = 0;
 
    virtual wallet::CWallet* wallet() { return nullptr; }
 
    virtual util::Result<std::string> exportWatchOnlyWallet(const fs::path& destination) = 0;
};
 
class WalletLoader : public ChainClient
{
public:
    virtual util::Result<std::unique_ptr<Wallet>> createWallet(const std::string& name, const SecureString& passphrase, uint64_t wallet_creation_flags, std::vector<bilingual_str>& warnings) = 0;
 
    virtual util::Result<std::unique_ptr<Wallet>> loadWallet(const std::string& name, std::vector<bilingual_str>& warnings) = 0;
 
    virtual std::string getWalletDir() = 0;
 
    virtual util::Result<std::unique_ptr<Wallet>> restoreWallet(const fs::path& backup_file, const std::string& wallet_name, std::vector<bilingual_str>& warnings, bool load_after_restore) = 0;
 
    virtual util::Result<WalletMigrationResult> migrateWallet(const std::string& name, const SecureString& passphrase, bool load_wallet) = 0;
 
    virtual bool isEncrypted(const std::string& wallet_name) = 0;
 
    virtual std::vector<std::pair<std::string, std::string>> listWalletDir() = 0;
 
    virtual std::vector<std::unique_ptr<Wallet>> getWallets() = 0;
 
    using LoadWalletFn = std::function<void(std::unique_ptr<Wallet> wallet)>;
    virtual std::unique_ptr<Handler> handleLoadWallet(LoadWalletFn fn) = 0;
 
    virtual wallet::WalletContext* context() { return nullptr; }
};
 
struct WalletAddress
{
    CTxDestination dest;
    bool is_mine;
    wallet::AddressPurpose purpose;
    std::string name;
 
    WalletAddress(CTxDestination dest, bool is_mine, wallet::AddressPurpose purpose, std::string name)
        : dest(std::move(dest)), is_mine(is_mine), purpose(std::move(purpose)), name(std::move(name))
    {
    }
};
 
struct WalletBalances
{
    CAmount balance = 0;
    CAmount unconfirmed_balance = 0;
    CAmount immature_balance = 0;
    CAmount used_balance = 0;
    CAmount nonmempool_balance = 0;
 
    bool balanceChanged(const WalletBalances& prev) const
    {
        return balance != prev.balance || unconfirmed_balance != prev.unconfirmed_balance ||
               immature_balance != prev.immature_balance ||
               used_balance != prev.used_balance || nonmempool_balance != prev.nonmempool_balance;
    }
};
 
// Wallet transaction information.
struct WalletTx
{
    CTransactionRef tx;
    std::vector<bool> txin_is_mine;
    std::vector<bool> txout_is_mine;
    std::vector<bool> txout_is_change;
    std::vector<CTxDestination> txout_address;
    std::vector<bool> txout_address_is_mine;
    CAmount credit;
    CAmount debit;
    CAmount change;
    int64_t time;
    std::optional<std::string> from; // Deprecated
    std::optional<std::string> message; // Deprecated
    std::optional<std::string> comment;
    std::optional<std::string> comment_to;
    bool is_coinbase;
 
    bool operator<(const WalletTx& a) const { return tx->GetHash() < a.tx->GetHash(); }
};
 
struct WalletTxStatus
{
    int block_height;
    int blocks_to_maturity;
    int depth_in_main_chain;
    unsigned int time_received;
    uint32_t lock_time;
    bool is_trusted;
    bool is_abandoned;
    bool is_coinbase;
    bool is_in_main_chain;
};
 
struct WalletTxOut
{
    CTxOut txout;
    int64_t time;
    int depth_in_main_chain = -1;
    bool is_spent = false;
};
 
struct WalletMigrationResult
{
    std::unique_ptr<Wallet> wallet;
    std::optional<std::string> watchonly_wallet_name;
    std::optional<std::string> solvables_wallet_name;
    fs::path backup_path;
};
 
std::unique_ptr<Wallet> MakeWallet(wallet::WalletContext& context, const std::shared_ptr<wallet::CWallet>& wallet);
 
std::unique_ptr<WalletLoader> MakeWalletLoader(Chain& chain, ArgsManager& args);
 
} // namespace interfaces
 
#endif // BITCOIN_INTERFACES_WALLET_H