walletdb.h raw
1 // Copyright (c) 2009-2010 Satoshi Nakamoto
2 // Copyright (c) 2009-present The Bitcoin Core developers
3 // Distributed under the MIT software license, see the accompanying
4 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
5
6 #ifndef BITCOIN_WALLET_WALLETDB_H
7 #define BITCOIN_WALLET_WALLETDB_H
8
9 #include <key.h>
10 #include <primitives/transaction_identifier.h>
11 #include <script/sign.h>
12 #include <wallet/db.h>
13 #include <wallet/walletutil.h>
14
15 #include <cstdint>
16 #include <string>
17 #include <unordered_set>
18 #include <vector>
19
20 class CScript;
21 class uint160;
22 class uint256;
23 struct CBlockLocator;
24
25 namespace wallet {
26 class CMasterKey;
27 class CWallet;
28 class CWalletTx;
29 struct WalletContext;
30
31 // Logs information about the database, including available engines, features, and other capabilities
32 void LogDBInfo();
33
34 /**
35 * Overview of wallet database classes:
36 *
37 * - WalletBatch is an abstract modifier object for the wallet database, and encapsulates a database
38 * batch update as well as methods to act on the database. It should be agnostic to the database implementation.
39 */
40
41 /** Error statuses for the wallet database.
42 * Values are in order of severity. When multiple errors occur, the most severe (highest value) will be returned.
43 */
44 enum class DBErrors : int
45 {
46 LOAD_OK = 0,
47 NEED_RESCAN = 1,
48 EXTERNAL_SIGNER_SUPPORT_REQUIRED = 3,
49 NONCRITICAL_ERROR = 4,
50 TOO_NEW = 5,
51 UNKNOWN_DESCRIPTOR = 6,
52 LOAD_FAIL = 7,
53 UNEXPECTED_LEGACY_ENTRY = 8,
54 LEGACY_WALLET = 9,
55 CORRUPT = 10,
56 };
57
58 namespace DBKeys {
59 extern const std::string ACENTRY;
60 extern const std::string ACTIVEEXTERNALSPK;
61 extern const std::string ACTIVEINTERNALSPK;
62 extern const std::string BESTBLOCK;
63 extern const std::string BESTBLOCK_NOMERKLE;
64 extern const std::string CRYPTED_KEY;
65 extern const std::string CSCRIPT;
66 extern const std::string DEFAULTKEY;
67 extern const std::string DESTDATA;
68 extern const std::string FLAGS;
69 extern const std::string HDCHAIN;
70 extern const std::string KEY;
71 extern const std::string KEYMETA;
72 extern const std::string LOCKED_UTXO;
73 extern const std::string MASTER_KEY;
74 extern const std::string MINVERSION;
75 extern const std::string NAME;
76 extern const std::string OLD_KEY;
77 extern const std::string ORDERPOSNEXT;
78 extern const std::string POOL;
79 extern const std::string PURPOSE;
80 extern const std::string SETTINGS;
81 extern const std::string TX;
82 extern const std::string VERSION;
83 extern const std::string WALLETDESCRIPTOR;
84 extern const std::string WALLETDESCRIPTORCKEY;
85 extern const std::string WALLETDESCRIPTORKEY;
86 extern const std::string WATCHMETA;
87 extern const std::string WATCHS;
88
89 // Keys in this set pertain only to the legacy wallet (LegacyScriptPubKeyMan) and are removed during migration from legacy to descriptors.
90 extern const std::unordered_set<std::string> LEGACY_TYPES;
91 } // namespace DBKeys
92
93 /* simple HD chain data model */
94 class CHDChain
95 {
96 public:
97 uint32_t nExternalChainCounter;
98 uint32_t nInternalChainCounter;
99 CKeyID seed_id; //!< seed hash160
100 int64_t m_next_external_index{0}; // Next index in the keypool to be used. Memory only.
101 int64_t m_next_internal_index{0}; // Next index in the keypool to be used. Memory only.
102
103 static const int VERSION_HD_BASE = 1;
104 static const int VERSION_HD_CHAIN_SPLIT = 2;
105 static const int CURRENT_VERSION = VERSION_HD_CHAIN_SPLIT;
106 int nVersion;
107
108 CHDChain() { SetNull(); }
109
110 SERIALIZE_METHODS(CHDChain, obj)
111 {
112 READWRITE(obj.nVersion, obj.nExternalChainCounter, obj.seed_id);
113 if (obj.nVersion >= VERSION_HD_CHAIN_SPLIT) {
114 READWRITE(obj.nInternalChainCounter);
115 }
116 }
117
118 void SetNull()
119 {
120 nVersion = CHDChain::CURRENT_VERSION;
121 nExternalChainCounter = 0;
122 nInternalChainCounter = 0;
123 seed_id.SetNull();
124 }
125
126 bool operator==(const CHDChain& chain) const
127 {
128 return seed_id == chain.seed_id;
129 }
130 bool operator<(const CHDChain& chain) const
131 {
132 return seed_id < chain.seed_id;
133 }
134 };
135
136 class CKeyMetadata
137 {
138 public:
139 static const int VERSION_BASIC=1;
140 static const int VERSION_WITH_HDDATA=10;
141 static const int VERSION_WITH_KEY_ORIGIN = 12;
142 static const int CURRENT_VERSION=VERSION_WITH_KEY_ORIGIN;
143 int nVersion;
144 int64_t nCreateTime; // 0 means unknown
145 std::string hdKeypath; //optional HD/bip32 keypath. Still used to determine whether a key is a seed. Also kept for backwards compatibility
146 CKeyID hd_seed_id; //id of the HD seed used to derive this key
147 KeyOriginInfo key_origin; // Key origin info with path and fingerprint
148 bool has_key_origin = false; //!< Whether the key_origin is useful
149
150 CKeyMetadata()
151 {
152 SetNull();
153 }
154 explicit CKeyMetadata(int64_t nCreateTime_)
155 {
156 SetNull();
157 nCreateTime = nCreateTime_;
158 }
159
160 SERIALIZE_METHODS(CKeyMetadata, obj)
161 {
162 READWRITE(obj.nVersion, obj.nCreateTime);
163 if (obj.nVersion >= VERSION_WITH_HDDATA) {
164 READWRITE(obj.hdKeypath, obj.hd_seed_id);
165 }
166 if (obj.nVersion >= VERSION_WITH_KEY_ORIGIN)
167 {
168 READWRITE(obj.key_origin);
169 READWRITE(obj.has_key_origin);
170 }
171 }
172
173 void SetNull()
174 {
175 nVersion = CKeyMetadata::CURRENT_VERSION;
176 nCreateTime = 0;
177 hdKeypath.clear();
178 hd_seed_id.SetNull();
179 key_origin.clear();
180 has_key_origin = false;
181 }
182 };
183
184 struct DbTxnListener
185 {
186 std::function<void()> on_commit, on_abort;
187 };
188
189 /** Access to the wallet database.
190 * Opens the database and provides read and write access to it. Each read and write is its own transaction.
191 * Multiple operation transactions can be started using TxnBegin() and committed using TxnCommit()
192 * Otherwise the transaction will be committed when the object goes out of scope.
193 * Optionally (on by default) it will flush to disk on close.
194 * Every 1000 writes will automatically trigger a flush to disk.
195 */
196 class WalletBatch
197 {
198 private:
199 template <typename K, typename T>
200 bool WriteIC(const K& key, const T& value, bool fOverwrite = true)
201 {
202 if (!m_batch->Write(key, value, fOverwrite)) {
203 return false;
204 }
205 return true;
206 }
207
208 template <typename K>
209 bool EraseIC(const K& key)
210 {
211 if (!m_batch->Erase(key)) {
212 return false;
213 }
214 return true;
215 }
216
217 public:
218 explicit WalletBatch(WalletDatabase &database) :
219 m_batch(database.MakeBatch())
220 {
221 }
222 WalletBatch(const WalletBatch&) = delete;
223 WalletBatch& operator=(const WalletBatch&) = delete;
224
225 bool WriteName(const std::string& strAddress, const std::string& strName);
226 bool EraseName(const std::string& strAddress);
227
228 bool WritePurpose(const std::string& strAddress, const std::string& purpose);
229 bool ErasePurpose(const std::string& strAddress);
230
231 bool WriteTx(const CWalletTx& wtx);
232 bool EraseTx(Txid hash);
233
234 bool WriteKeyMetadata(const CKeyMetadata& meta, const CPubKey& pubkey, bool overwrite);
235 bool WriteKey(const CPubKey& vchPubKey, const CPrivKey& vchPrivKey, const CKeyMetadata &keyMeta);
236 bool WriteCryptedKey(const CPubKey& vchPubKey, const std::vector<unsigned char>& vchCryptedSecret, const CKeyMetadata &keyMeta);
237 bool WriteMasterKey(unsigned int nID, const CMasterKey& kMasterKey);
238 bool EraseMasterKey(unsigned int id);
239
240 bool WriteWatchOnly(const CScript &script, const CKeyMetadata &keymeta);
241 bool EraseWatchOnly(const CScript &script);
242
243 bool WriteBestBlock(const CBlockLocator& locator);
244 bool ReadBestBlock(CBlockLocator& locator);
245
246 // Returns true if wallet stores encryption keys
247 bool IsEncrypted();
248
249 bool WriteOrderPosNext(int64_t nOrderPosNext);
250
251 bool WriteDescriptorKey(const uint256& desc_id, const CPubKey& pubkey, const CPrivKey& privkey);
252 bool WriteCryptedDescriptorKey(const uint256& desc_id, const CPubKey& pubkey, const std::vector<unsigned char>& secret);
253 bool WriteDescriptor(const uint256& desc_id, const WalletDescriptor& descriptor);
254 bool WriteDescriptorDerivedCache(const CExtPubKey& xpub, const uint256& desc_id, uint32_t key_exp_index, uint32_t der_index);
255 bool WriteDescriptorParentCache(const CExtPubKey& xpub, const uint256& desc_id, uint32_t key_exp_index);
256 bool WriteDescriptorLastHardenedCache(const CExtPubKey& xpub, const uint256& desc_id, uint32_t key_exp_index);
257 bool WriteDescriptorCacheItems(const uint256& desc_id, const DescriptorCache& cache);
258
259 bool WriteLockedUTXO(const COutPoint& output);
260 bool EraseLockedUTXO(const COutPoint& output);
261
262 bool WriteAddressPreviouslySpent(const CTxDestination& dest, bool previously_spent);
263 bool WriteAddressReceiveRequest(const CTxDestination& dest, const std::string& id, const std::string& receive_request);
264 bool EraseAddressReceiveRequest(const CTxDestination& dest, const std::string& id);
265 bool EraseAddressData(const CTxDestination& dest);
266
267 bool WriteActiveScriptPubKeyMan(uint8_t type, const uint256& id, bool internal);
268 bool EraseActiveScriptPubKeyMan(uint8_t type, bool internal);
269
270 DBErrors LoadWallet(CWallet* pwallet);
271
272 //! Write the given client_version.
273 bool WriteVersion(int client_version) { return m_batch->Write(DBKeys::VERSION, CLIENT_VERSION); }
274
275 //! Delete records of the given types
276 bool EraseRecords(const std::unordered_set<std::string>& types);
277
278 bool WriteWalletFlags(uint64_t flags);
279 //! Begin a new transaction
280 bool TxnBegin();
281 //! Commit current transaction
282 bool TxnCommit();
283 //! Abort current transaction
284 bool TxnAbort();
285 bool HasActiveTxn() { return m_batch->HasActiveTxn(); }
286
287 //! Registers db txn callback functions
288 void RegisterTxnListener(const DbTxnListener& l);
289
290 private:
291 std::unique_ptr<DatabaseBatch> m_batch;
292
293 // External functions listening to the current db txn outcome.
294 // Listeners are cleared at the end of the transaction.
295 std::vector<DbTxnListener> m_txn_listeners;
296 };
297
298 /**
299 * Executes the provided function 'func' within a database transaction context.
300 *
301 * This function ensures that all db modifications performed within 'func()' are
302 * atomically committed to the db at the end of the process. And, in case of a
303 * failure during execution, all performed changes are rolled back.
304 *
305 * @param database The db connection instance to perform the transaction on.
306 * @param process_desc A description of the process being executed, used for logging purposes in the event of a failure.
307 * @param func The function to be executed within the db txn context. It returns a boolean indicating whether to commit or roll back the txn.
308 * @return true if the db txn executed successfully, false otherwise.
309 */
310 bool RunWithinTxn(WalletDatabase& database, std::string_view process_desc, const std::function<bool(WalletBatch&)>& func);
311
312 bool LoadKey(CWallet* pwallet, DataStream& ssKey, DataStream& ssValue, std::string& strErr);
313 bool LoadCryptedKey(CWallet* pwallet, DataStream& ssKey, DataStream& ssValue, std::string& strErr);
314 bool LoadEncryptionKey(CWallet* pwallet, DataStream& ssKey, DataStream& ssValue, std::string& strErr);
315 bool LoadHDChain(CWallet* pwallet, DataStream& ssValue, std::string& strErr);
316
317 //! Returns true if there are any DBKeys::LEGACY_TYPES record in the wallet db
318 bool HasLegacyRecords(CWallet& wallet);
319 bool HasLegacyRecords(CWallet& wallet, DatabaseBatch& batch);
320 } // namespace wallet
321
322 #endif // BITCOIN_WALLET_WALLETDB_H
323