1// Copyright (c) 2017-present 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_WALLET_WALLETUTIL_H
6#define BITCOIN_WALLET_WALLETUTIL_H
7
8#include <script/descriptor.h>
9#include <util/fs.h>
10
11#include <vector>
12
13namespace wallet {
14
15enum WalletFlags : uint64_t {
16    // wallet flags in the upper section (> 1 << 31) will lead to not opening the wallet if flag is unknown
17    // unknown wallet flags in the lower section <= (1 << 31) will be tolerated
18
19    // will categorize coins as clean (not reused) and dirty (reused), and handle
20    // them with privacy considerations in mind
21    WALLET_FLAG_AVOID_REUSE = (1ULL << 0),
22
23    // Indicates that the metadata has already been upgraded to contain key origins
24    WALLET_FLAG_KEY_ORIGIN_METADATA = (1ULL << 1),
25
26    // Indicates that the descriptor cache has been upgraded to cache last hardened xpubs
27    WALLET_FLAG_LAST_HARDENED_XPUB_CACHED = (1ULL << 2),
28
29    // will enforce the rule that the wallet can't contain any private keys (only watch-only/pubkeys)
30    WALLET_FLAG_DISABLE_PRIVATE_KEYS = (1ULL << 32),
31
32    //! Flag set when a wallet contains no HD seed and no private keys, scripts,
33    //! addresses, and other watch only things, and is therefore "blank."
34    //!
35    //! The main function this flag serves is to distinguish a blank wallet from
36    //! a newly created wallet when the wallet database is loaded, to avoid
37    //! initialization that should only happen on first run.
38    //!
39    //! A secondary function of this flag, which applies to descriptor wallets
40    //! only, is to serve as an ongoing indication that descriptors in the
41    //! wallet should be created manually, and that the wallet should not
42    //! generate automatically generate new descriptors if it is later
43    //! encrypted. To support this behavior, descriptor wallets unlike legacy
44    //! wallets do not automatically unset the BLANK flag when things are
45    //! imported.
46    //!
47    //! This flag is also a mandatory flag to prevent previous versions of
48    //! bitcoin from opening the wallet, thinking it was newly created, and
49    //! then improperly reinitializing it.
50    WALLET_FLAG_BLANK_WALLET = (1ULL << 33),
51
52    //! Indicate that this wallet supports DescriptorScriptPubKeyMan
53    WALLET_FLAG_DESCRIPTORS = (1ULL << 34),
54
55    //! Indicates that the wallet needs an external signer
56    WALLET_FLAG_EXTERNAL_SIGNER = (1ULL << 35),
57};
58
59//! Get the path of the wallet directory.
60fs::path GetWalletDir();
61
62/** Descriptor with some wallet metadata */
63class WalletDescriptor
64{
65private:
66    int32_t range_start = 0; // First item in range; start of range, inclusive, i.e. [range_start, range_end). This never changes.
67    int32_t next_index = 0; // Position of the next item to generate
68    int32_t range_end = 0; // Item after the last; end of range, exclusive, i.e. [range_start, range_end). This will increment with each TopUp()
69
70    mutable std::optional<uint256> m_canonical_hash; // Hash of the canonical string, used as a shortcut for comparing canonical strings
71
72    uint256 GetCanonicalHash() const;
73
74public:
75    const std::shared_ptr<const Descriptor> descriptor;
76    uint64_t creation_time = 0;
77    DescriptorCache cache;
78
79    int32_t GetStart() const { return range_start; }
80    int32_t GetNext() const { return next_index; }
81    int32_t GetEnd() const { return range_end; }
82
83    //! Increments the next_index of the descriptor.
84    void IncNext()
85    {
86        next_index++;
87    }
88
89    //! Increments the next_index of the descriptor.
90    void DecNext()
91    {
92        next_index--;
93    }
94
95    //! Sets the range_end of the descriptor.
96    void SetEnd(int32_t end)
97    {
98        if (!descriptor->IsRange()) {
99            CHECK_NONFATAL(end == 1);
100        }
101        range_end = end;
102    }
103
104    template <typename Stream>
105    void Serialize(Stream& s) const
106    {
107        std::string descriptor_str = descriptor->ToString();
108        s << descriptor_str << creation_time << next_index << range_start << range_end;
109    }
110
111    template <typename Stream>
112    static WalletDescriptor FromStream(deserialize_type, Stream& s)
113    {
114        std::string descriptor_str;
115        uint64_t creation_time;
116        int32_t next_index, range_start, range_end;
117        s >> descriptor_str >> creation_time >> next_index >> range_start >> range_end;
118
119        std::string error;
120        FlatSigningProvider keys;
121        auto descs = Parse(descriptor_str, keys, error, true);
122        if (descs.empty()) {
123            throw std::ios_base::failure("Invalid descriptor: " + error);
124        }
125        if (descs.size() > 1) {
126            throw std::ios_base::failure("Can't load a multipath descriptor from databases");
127        }
128        return WalletDescriptor(std::move(descs.at(0)), creation_time, range_start, range_end, next_index);
129    }
130
131    WalletDescriptor() = delete;
132    WalletDescriptor(std::shared_ptr<Descriptor> descriptor, uint64_t creation_time, int32_t range_start, int32_t range_end, int32_t next_index)
133    : range_start(descriptor->IsRange() ? range_start : 0),
134      next_index(next_index),
135      range_end(descriptor->IsRange() ? range_end : 1),
136      descriptor(descriptor),
137      creation_time(creation_time)
138    {}
139
140    /** Replaces all metadata (range, start, end, creation time), and cache from another WalletDescriptor if it has the same canonical descriptor string.
141     *  The descriptor itself is not replaced to preserve existing serialization to maintain compatibility with previous software versions that expect
142     *  specific serialization.
143     */
144    void UpdateFrom(const WalletDescriptor& other);
145
146    // Compare by using the canonical string to make the hardened indicators consistent for comparison
147    bool IsCanonicallyEquivalent(const WalletDescriptor& other) const;
148};
149
150WalletDescriptor GenerateWalletDescriptor(const CExtPubKey& master_key, const OutputType& output_type, bool internal);
151} // namespace wallet
152
153#endif // BITCOIN_WALLET_WALLETUTIL_H
154