1 // Copyright (c) 2019-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_SCRIPTPUBKEYMAN_H
6 #define BITCOIN_WALLET_SCRIPTPUBKEYMAN_H
7 8 #include <addresstype.h>
9 #include <common/messages.h>
10 #include <common/signmessage.h>
11 #include <common/types.h>
12 #include <musig.h>
13 #include <node/types.h>
14 #include <psbt.h>
15 #include <script/descriptor.h>
16 #include <script/script.h>
17 #include <script/signingprovider.h>
18 #include <util/btcsignals.h>
19 #include <util/hasher.h>
20 #include <util/log.h>
21 #include <util/result.h>
22 #include <util/time.h>
23 #include <wallet/crypter.h>
24 #include <wallet/types.h>
25 #include <wallet/walletdb.h>
26 #include <wallet/walletutil.h>
27 28 #include <functional>
29 #include <optional>
30 #include <unordered_map>
31 #include <unordered_set>
32 33 enum class OutputType;
34 35 namespace wallet {
36 struct MigrationData;
37 class ScriptPubKeyMan;
38 39 // Wallet storage things that ScriptPubKeyMans need in order to be able to store things to the wallet database.
40 // It provides access to things that are part of the entire wallet and not specific to a ScriptPubKeyMan such as
41 // wallet flags, wallet version, encryption keys, encryption status, and the database itself. This allows a
42 // ScriptPubKeyMan to have callbacks into CWallet without causing a circular dependency.
43 // WalletStorage should be the same for all ScriptPubKeyMans of a wallet.
44 class WalletStorage
45 {
46 public:
47 virtual ~WalletStorage() = default;
48 virtual std::string LogName() const = 0;
49 virtual WalletDatabase& GetDatabase() const = 0;
50 virtual bool IsWalletFlagSet(uint64_t) const = 0;
51 virtual void UnsetBlankWalletFlag(WalletBatch&) = 0;
52 //! Pass the encryption key to cb().
53 virtual bool WithEncryptionKey(std::function<bool (const CKeyingMaterial&)> cb) const = 0;
54 virtual bool HasEncryptionKeys() const = 0;
55 virtual bool IsLocked() const = 0;
56 //! Callback function for after TopUp completes containing any scripts that were added by a SPKMan
57 virtual void TopUpCallback(const std::set<CScript>&, ScriptPubKeyMan*) = 0;
58 };
59 60 //! Constant representing an unknown spkm creation time
61 static constexpr int64_t UNKNOWN_TIME = std::numeric_limits<int64_t>::max();
62 63 //! Default for -keypool
64 static const unsigned int DEFAULT_KEYPOOL_SIZE = 1000;
65 66 std::vector<CKeyID> GetAffectedKeys(const CScript& spk, const SigningProvider& provider);
67 68 struct WalletDestination
69 {
70 CTxDestination dest;
71 std::optional<bool> internal;
72 };
73 74 /*
75 * A class implementing ScriptPubKeyMan manages some (or all) scriptPubKeys used in a wallet.
76 * It contains the scripts and keys related to the scriptPubKeys it manages.
77 * A ScriptPubKeyMan will be able to give out scriptPubKeys to be used, as well as marking
78 * when a scriptPubKey has been used. It also handles when and how to store a scriptPubKey
79 * and its related scripts and keys, including encryption.
80 */
81 class ScriptPubKeyMan
82 {
83 protected:
84 WalletStorage& m_storage;
85 86 public:
87 explicit ScriptPubKeyMan(WalletStorage& storage) : m_storage(storage) {}
88 virtual ~ScriptPubKeyMan() = default;
89 virtual util::Result<CTxDestination> GetNewDestination(const OutputType type) { return util::Error{Untranslated("Not supported")}; }
90 virtual bool IsMine(const CScript& script) const { return false; }
91 92 //! Check that the given decryption key is valid for this ScriptPubKeyMan, i.e. it decrypts all of the keys handled by it.
93 virtual bool CheckDecryptionKey(const CKeyingMaterial& master_key) { return false; }
94 virtual bool Encrypt(const CKeyingMaterial& master_key, WalletBatch* batch) { return false; }
95 96 virtual util::Result<CTxDestination> GetReservedDestination(const OutputType type, bool internal, int64_t& index) { return util::Error{Untranslated("Not supported")}; }
97 virtual void KeepDestination(int64_t index, const OutputType& type) {}
98 virtual void ReturnDestination(int64_t index, bool internal, const CTxDestination& addr) {}
99 100 /** Fills internal address pool. Use within ScriptPubKeyMan implementations should be used sparingly and only
101 * when something from the address pool is removed, excluding GetNewDestination and GetReservedDestination.
102 * External wallet code is primarily responsible for topping up prior to fetching new addresses
103 */
104 virtual bool TopUp(unsigned int size = 0) { return false; }
105 106 /** Mark unused addresses as being used
107 * Affects all keys up to and including the one determined by provided script.
108 *
109 * @param script determines the last key to mark as used
110 *
111 * @return All of the addresses affected
112 */
113 virtual std::vector<WalletDestination> MarkUnusedAddresses(const CScript& script) { return {}; }
114 115 /* Returns true if HD is enabled */
116 virtual bool IsHDEnabled() const { return false; }
117 118 /* Returns true if the wallet can give out new addresses. This means it has keys in the keypool or can generate new keys */
119 virtual bool CanGetAddresses(bool internal = false) const { return false; }
120 121 virtual bool HavePrivateKeys() const { return false; }
122 virtual bool HaveCryptedKeys() const { return false; }
123 124 virtual unsigned int GetKeyPoolSize() const { return 0; }
125 126 virtual int64_t GetTimeFirstKey() const { return 0; }
127 128 virtual std::unique_ptr<CKeyMetadata> GetMetadata(const CTxDestination& dest) const { return nullptr; }
129 130 virtual std::unique_ptr<SigningProvider> GetSolvingProvider(const CScript& script) const { return nullptr; }
131 132 /** Whether this ScriptPubKeyMan can provide a SigningProvider (via GetSolvingProvider) that, combined with
133 * sigdata, can produce solving data.
134 */
135 virtual bool CanProvide(const CScript& script, SignatureData& sigdata) { return false; }
136 137 /** Creates new signatures and adds them to the transaction. Returns whether all inputs were signed */
138 virtual bool SignTransaction(CMutableTransaction& tx, const std::map<COutPoint, Coin>& coins, int sighash, std::map<int, bilingual_str>& input_errors) const { return false; }
139 /** Sign a message with the given script */
140 virtual SigningResult SignMessage(const std::string& message, const PKHash& pkhash, std::string& str_sig) const { return SigningResult::SIGNING_FAILED; };
141 /** Adds script and derivation path information to a PSBT, and optionally signs it. */
142 virtual std::optional<common::PSBTError> FillPSBT(PartiallySignedTransaction& psbt, const PrecomputedTransactionData& txdata, const common::PSBTFillOptions& options, int* n_signed = nullptr) const { return common::PSBTError::UNSUPPORTED; }
143 144 virtual uint256 GetID() const { return uint256(); }
145 146 /** Returns a set of all the scriptPubKeys that this ScriptPubKeyMan watches */
147 virtual std::unordered_set<CScript, SaltedSipHasher> GetScriptPubKeys() const { return {}; };
148 149 /** Prepends the wallet name in logging output to ease debugging in multi-wallet use cases */
150 template <typename... Params>
151 void WalletLogPrintf(util::ConstevalFormatString<sizeof...(Params)> wallet_fmt, const Params&... params) const
152 {
153 LogInfo("[%s] %s", m_storage.LogName(), tfm::format(wallet_fmt, params...));
154 };
155 156 /** Keypool has new keys */
157 btcsignals::signal<void ()> NotifyCanGetAddressesChanged;
158 159 /** Birth time changed */
160 btcsignals::signal<void (const ScriptPubKeyMan* spkm, int64_t new_birth_time)> NotifyFirstKeyTimeChanged;
161 };
162 163 /** OutputTypes supported by the LegacyScriptPubKeyMan */
164 static const std::unordered_set<OutputType> LEGACY_OUTPUT_TYPES {
165 OutputType::LEGACY,
166 OutputType::P2SH_SEGWIT,
167 OutputType::BECH32,
168 };
169 170 using KeyMap = std::map<CKeyID, CKey>;
171 using CryptedKeyMap = std::map<CKeyID, std::pair<CPubKey, std::vector<unsigned char>>>;
172 173 // Manages the data for a LegacyScriptPubKeyMan.
174 // This is the minimum necessary to load a legacy wallet so that it can be migrated.
175 class LegacyDataSPKM : public ScriptPubKeyMan, public FillableSigningProvider
176 {
177 private:
178 using WatchOnlySet = std::set<CScript>;
179 using WatchKeyMap = std::map<CKeyID, CPubKey>;
180 181 CryptedKeyMap mapCryptedKeys GUARDED_BY(cs_KeyStore);
182 WatchOnlySet setWatchOnly GUARDED_BY(cs_KeyStore);
183 WatchKeyMap mapWatchKeys GUARDED_BY(cs_KeyStore);
184 185 /* the HD chain data model (external chain counters) */
186 CHDChain m_hd_chain;
187 std::unordered_map<CKeyID, CHDChain, SaltedSipHasher> m_inactive_hd_chains;
188 189 //! keeps track of whether Unlock has run a thorough check before
190 bool fDecryptionThoroughlyChecked = true;
191 192 bool AddWatchOnlyInMem(const CScript &dest);
193 virtual bool AddKeyPubKeyInner(const CKey& key, const CPubKey &pubkey);
194 bool AddCryptedKeyInner(const CPubKey &vchPubKey, const std::vector<unsigned char> &vchCryptedSecret);
195 196 // Helper function to retrieve a conservative superset of all output scripts that may be relevant to this LegacyDataSPKM.
197 // It may include scripts that are invalid or not actually watched by this LegacyDataSPKM.
198 // Used only in migration.
199 std::unordered_set<CScript, SaltedSipHasher> GetCandidateScriptPubKeys() const;
200 201 bool IsMine(const CScript& script) const override;
202 bool CanProvide(const CScript& script, SignatureData& sigdata) override;
203 public:
204 using ScriptPubKeyMan::ScriptPubKeyMan;
205 206 // Map from Key ID to key metadata.
207 std::map<CKeyID, CKeyMetadata> mapKeyMetadata GUARDED_BY(cs_KeyStore);
208 209 // Map from Script ID to key metadata (for watch-only keys).
210 std::map<CScriptID, CKeyMetadata> m_script_metadata GUARDED_BY(cs_KeyStore);
211 212 // ScriptPubKeyMan overrides
213 bool CheckDecryptionKey(const CKeyingMaterial& master_key) override;
214 std::unordered_set<CScript, SaltedSipHasher> GetScriptPubKeys() const override;
215 std::unique_ptr<SigningProvider> GetSolvingProvider(const CScript& script) const override;
216 uint256 GetID() const override { return uint256::ONE; }
217 218 // FillableSigningProvider overrides
219 bool HaveKey(const CKeyID &address) const override;
220 bool GetKey(const CKeyID &address, CKey& keyOut) const override;
221 bool GetPubKey(const CKeyID &address, CPubKey& vchPubKeyOut) const override;
222 bool GetKeyOrigin(const CKeyID& keyid, KeyOriginInfo& info) const override;
223 224 //! Load metadata (used by LoadWallet)
225 virtual void LoadKeyMetadata(const CKeyID& keyID, const CKeyMetadata &metadata);
226 virtual void LoadScriptMetadata(const CScriptID& script_id, const CKeyMetadata &metadata);
227 228 //! Adds a watch-only address to the store, without saving it to disk (used by LoadWallet)
229 bool LoadWatchOnly(const CScript &dest);
230 //! Returns whether the watch-only script is in the wallet
231 bool HaveWatchOnly(const CScript &dest) const;
232 //! Adds a key to the store, without saving it to disk (used by LoadWallet)
233 bool LoadKey(const CKey& key, const CPubKey &pubkey);
234 //! Adds an encrypted key to the store, without saving it to disk (used by LoadWallet)
235 bool LoadCryptedKey(const CPubKey &vchPubKey, const std::vector<unsigned char> &vchCryptedSecret, bool checksum_valid);
236 //! Adds a CScript to the store
237 bool LoadCScript(const CScript& redeemScript);
238 //! Load a HD chain model (used by LoadWallet)
239 void LoadHDChain(const CHDChain& chain);
240 void AddInactiveHDChain(const CHDChain& chain);
241 const CHDChain& GetHDChain() const { return m_hd_chain; }
242 243 //! Fetches a pubkey from mapWatchKeys if it exists there
244 bool GetWatchPubKey(const CKeyID &address, CPubKey &pubkey_out) const;
245 246 /**
247 * Retrieves scripts that were imported by bugs into the legacy spkm and are
248 * simply invalid, such as a sh(sh(pkh())) script, or not watched.
249 */
250 std::unordered_set<CScript, SaltedSipHasher> GetNotMineScriptPubKeys() const;
251 252 /** Get the DescriptorScriptPubKeyMans (with private keys) that have the same scriptPubKeys as this LegacyScriptPubKeyMan.
253 * Does not modify this ScriptPubKeyMan. */
254 std::optional<MigrationData> MigrateToDescriptor();
255 /** Delete all the records of this LegacyScriptPubKeyMan from disk*/
256 bool DeleteRecordsWithDB(WalletBatch& batch);
257 };
258 259 /** Wraps a LegacyScriptPubKeyMan so that it can be returned in a new unique_ptr. Does not provide privkeys */
260 class LegacySigningProvider : public SigningProvider
261 {
262 private:
263 const LegacyDataSPKM& m_spk_man;
264 public:
265 explicit LegacySigningProvider(const LegacyDataSPKM& spk_man) : m_spk_man(spk_man) {}
266 267 bool GetCScript(const CScriptID &scriptid, CScript& script) const override { return m_spk_man.GetCScript(scriptid, script); }
268 bool HaveCScript(const CScriptID &scriptid) const override { return m_spk_man.HaveCScript(scriptid); }
269 bool GetPubKey(const CKeyID &address, CPubKey& pubkey) const override { return m_spk_man.GetPubKey(address, pubkey); }
270 bool GetKey(const CKeyID &address, CKey& key) const override { return false; }
271 bool HaveKey(const CKeyID &address) const override { return false; }
272 bool GetKeyOrigin(const CKeyID& keyid, KeyOriginInfo& info) const override { return m_spk_man.GetKeyOrigin(keyid, info); }
273 };
274 275 class DescriptorScriptPubKeyMan : public ScriptPubKeyMan
276 {
277 private:
278 using ScriptPubKeyMap = std::map<CScript, int32_t>; // Map of scripts to descriptor range index
279 using PubKeyMap = std::map<CPubKey, int32_t>; // Map of pubkeys involved in scripts to descriptor range index
280 281 ScriptPubKeyMap m_map_script_pub_keys GUARDED_BY(cs_desc_man);
282 PubKeyMap m_map_pubkeys GUARDED_BY(cs_desc_man);
283 int32_t m_max_cached_index = -1;
284 285 KeyMap m_map_keys GUARDED_BY(cs_desc_man);
286 CryptedKeyMap m_map_crypted_keys GUARDED_BY(cs_desc_man);
287 288 //! keeps track of whether Unlock has run a thorough check before
289 bool m_decryption_thoroughly_checked = false;
290 291 //! Number of pre-generated keys/scripts (part of the look-ahead process, used to detect payments)
292 int64_t m_keypool_size GUARDED_BY(cs_desc_man){DEFAULT_KEYPOOL_SIZE};
293 294 /** Map of a session id to MuSig2 secnonce
295 *
296 * Stores MuSig2 secnonces while the MuSig2 signing session is still ongoing.
297 * Note that these secnonces must not be reused. In order to avoid being tricked into
298 * reusing a nonce, this map is held only in memory and must not be written to disk.
299 * The side effect is that signing sessions cannot persist across restarts, but this
300 * must be done in order to prevent nonce reuse.
301 *
302 * The session id is an arbitrary value set by the signer in order for the signing logic
303 * to find ongoing signing sessions, see MuSig2SessionID.
304 */
305 mutable std::map<uint256, MuSig2SecNonce> m_musig2_secnonces;
306 307 //! Create a new DescriptorScriptPubKeyMan from an existing descriptor (i.e. from an import)
308 DescriptorScriptPubKeyMan(WalletStorage& storage, WalletDescriptor& descriptor, int64_t keypool_size)
309 : ScriptPubKeyMan(storage),
310 m_keypool_size(keypool_size),
311 m_wallet_descriptor(descriptor)
312 {}
313 314 bool AddDescriptorKeyWithDB(WalletBatch& batch, const CKey& key, const CPubKey &pubkey) EXCLUSIVE_LOCKS_REQUIRED(cs_desc_man);
315 316 KeyMap GetKeys() const EXCLUSIVE_LOCKS_REQUIRED(cs_desc_man);
317 318 // Cached FlatSigningProviders to avoid regenerating them each time they are needed.
319 mutable std::map<int32_t, FlatSigningProvider> m_map_signing_providers;
320 // Fetch the SigningProvider for the given script and optionally include private keys
321 std::unique_ptr<FlatSigningProvider> GetSigningProvider(const CScript& script, bool include_private = false) const;
322 // Fetch the SigningProvider for a given index and optionally include private keys. Called by the above functions.
323 std::unique_ptr<FlatSigningProvider> GetSigningProvider(int32_t index, bool include_private = false) const EXCLUSIVE_LOCKS_REQUIRED(cs_desc_man);
324 325 void Load();
326 327 void AddDescriptorKey(const CKey& key, const CPubKey &pubkey);
328 void UpdateWithSigningProvider(WalletBatch& batch, const FlatSigningProvider& signing_provider) EXCLUSIVE_LOCKS_REQUIRED(cs_desc_man);
329 330 //! Setup descriptors based on the given CExtKey
331 void SetupDescriptorGeneration(WalletBatch& batch, const CExtKey& master_key, OutputType addr_type, bool internal);
332 333 protected:
334 //! Create a DescriptorScriptPubKeyMan from existing data (i.e. during loading)
335 DescriptorScriptPubKeyMan(WalletStorage& storage, WalletDescriptor& descriptor, int64_t keypool_size, const KeyMap& keys, const CryptedKeyMap& ckeys);
336 337 DescriptorScriptPubKeyMan(WalletStorage& storage, int64_t keypool_size)
338 : ScriptPubKeyMan(storage),
339 m_keypool_size(keypool_size)
340 {}
341 342 WalletDescriptor m_wallet_descriptor GUARDED_BY(cs_desc_man);
343 344 //! Same as 'TopUp' but designed for use within a batch transaction context
345 bool TopUpWithDB(WalletBatch& batch, unsigned int size = 0);
346 347 public:
348 static std::unique_ptr<DescriptorScriptPubKeyMan> LoadFromStorage(WalletStorage& storage, WalletDescriptor& descriptor, int64_t keypool_size, const KeyMap& keys, const CryptedKeyMap& ckeys);
349 static std::unique_ptr<DescriptorScriptPubKeyMan> CreateFromImport(WalletStorage& storage, WalletDescriptor& descriptor, int64_t keypool_size, const FlatSigningProvider& provider);
350 static std::unique_ptr<DescriptorScriptPubKeyMan> CreateFromMigration(WalletStorage& storage, WalletBatch& batch, WalletDescriptor& descriptor, int64_t keypool_size, const FlatSigningProvider& provider);
351 static std::unique_ptr<DescriptorScriptPubKeyMan> GenerateNewSingleSig(WalletStorage& storage, WalletBatch& batch, int64_t keypool_size, const CExtKey& master_key, OutputType addr_type, bool internal);
352 353 mutable RecursiveMutex cs_desc_man;
354 355 util::Result<CTxDestination> GetNewDestination(OutputType type) override;
356 bool IsMine(const CScript& script) const override;
357 358 bool CheckDecryptionKey(const CKeyingMaterial& master_key) override;
359 bool Encrypt(const CKeyingMaterial& master_key, WalletBatch* batch) override;
360 361 util::Result<CTxDestination> GetReservedDestination(OutputType type, bool internal, int64_t& index) override;
362 void ReturnDestination(int64_t index, bool internal, const CTxDestination& addr) override;
363 364 // Tops up the descriptor cache and m_map_script_pub_keys. The cache is stored in the wallet file
365 // and is used to expand the descriptor in GetNewDestination. DescriptorScriptPubKeyMan relies
366 // more on ephemeral data than LegacyScriptPubKeyMan. For wallets using unhardened derivation
367 // (with or without private keys), the "keypool" is a single xpub.
368 bool TopUp(unsigned int size = 0) override;
369 370 std::vector<WalletDestination> MarkUnusedAddresses(const CScript& script) override;
371 372 bool IsHDEnabled() const override;
373 374 bool HavePrivateKeys() const override;
375 bool HasPrivKey(const CKeyID& keyid) const EXCLUSIVE_LOCKS_REQUIRED(cs_desc_man);
376 //! Retrieve the particular key if it is available. Returns nullopt if the key is not in the wallet, or if the wallet is locked.
377 std::optional<CKey> GetKey(const CKeyID& keyid) const EXCLUSIVE_LOCKS_REQUIRED(cs_desc_man);
378 bool HaveCryptedKeys() const override;
379 380 unsigned int GetKeyPoolSize() const override;
381 382 int64_t GetTimeFirstKey() const override;
383 384 std::unique_ptr<CKeyMetadata> GetMetadata(const CTxDestination& dest) const override;
385 386 bool CanGetAddresses(bool internal = false) const override;
387 388 std::unique_ptr<SigningProvider> GetSolvingProvider(const CScript& script) const override;
389 390 bool CanProvide(const CScript& script, SignatureData& sigdata) override;
391 392 // Fetch the SigningProvider for the given pubkey and always include private keys. This should only be called by signing code.
393 std::unique_ptr<FlatSigningProvider> GetSigningProvider(const CPubKey& pubkey) const;
394 395 bool SignTransaction(CMutableTransaction& tx, const std::map<COutPoint, Coin>& coins, int sighash, std::map<int, bilingual_str>& input_errors) const override;
396 SigningResult SignMessage(const std::string& message, const PKHash& pkhash, std::string& str_sig) const override;
397 std::optional<common::PSBTError> FillPSBT(PartiallySignedTransaction& psbt, const PrecomputedTransactionData& txdata, const common::PSBTFillOptions& options, int* n_signed = nullptr) const override;
398 399 uint256 GetID() const override;
400 401 bool HasWalletDescriptor(const WalletDescriptor& desc) const;
402 util::Result<void> UpdateWalletDescriptor(WalletDescriptor& descriptor, const FlatSigningProvider& provider);
403 bool CanUpdateToWalletDescriptor(const WalletDescriptor& descriptor, std::string& error);
404 void WriteDescriptor();
405 406 WalletDescriptor GetWalletDescriptor() const EXCLUSIVE_LOCKS_REQUIRED(cs_desc_man);
407 std::unordered_set<CScript, SaltedSipHasher> GetScriptPubKeys() const override;
408 std::unordered_set<CScript, SaltedSipHasher> GetScriptPubKeys(int32_t minimum_index) const;
409 int32_t GetEndRange() const;
410 411 [[nodiscard]] bool GetDescriptorString(std::string& out, bool priv) const;
412 413 void UpgradeDescriptorCache();
414 };
415 416 /** struct containing information needed for migrating legacy wallets to descriptor wallets */
417 struct MigrationData
418 {
419 CExtKey master_key;
420 std::vector<std::pair<std::string, int64_t>> watch_descs;
421 std::vector<std::pair<std::string, int64_t>> solvable_descs;
422 std::vector<std::unique_ptr<DescriptorScriptPubKeyMan>> desc_spkms;
423 std::shared_ptr<CWallet> watchonly_wallet{nullptr};
424 std::shared_ptr<CWallet> solvable_wallet{nullptr};
425 };
426 427 } // namespace wallet
428 429 #endif // BITCOIN_WALLET_SCRIPTPUBKEYMAN_H
430