LBRYCommunity/lbrycrd
1
0
Fork 0
Code Issues 29 Pull requests 1 Projects Releases 32 Packages Wiki Activity

Merge #15777: [docs] Add doxygen comments for keypool classes

Browse source 
f1a77b0c51 [docs] Add doxygen comment for CReserveKey (John Newbery)
37796b2dd4 [docs] Add doxygen comment for CKeyPool (John Newbery)
ef2d515af3 [wallet] move-only: move CReserveKey to be next to CKeyPool (John Newbery)

Pull request description:

  Docs/move-only

  Adds doxygen comments for the CKeyPool and CReserveKey objects. The way these work is pretty confusing and it's easy to overlook details (eg https://github.com/bitcoin/bitcoin/pull/15557#discussion_r271956393).

  These are on the verbose side, but I think too much commenting is better than not enough. Happy to take feedback on what's an appropriate level.

ACKs for commit f1a77b:
  jonatack:
    Thanks, John. Re-ACK f1a77b0c51, doc-only changes with respect to previous review.
  jb55:
    ACK f1a77b0c51

Tree-SHA512: 8bc97c7029cd2e8d9bfd2d2144eeff73474c71eda5a9d10817e1578ca0b70da677252037d83143faaff1808e2193408a21a8a89d36049eac77fd313990f0b67b
This commit is contained in:
MarcoFalke 2019-05-14 09:11:48 -04:00
commit 65526fc866
No known key found for this signature in database
GPG key ID: D2EA4850E7528B25
1 changed files with 101 additions and 31 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

132
src/wallet/wallet.h
View file

@ -141,14 +141,61 @@ enum WalletFlags : uint64_t {
static constexpr uint64_t g_known_wallet_flags = WALLET_FLAG_DISABLE_PRIVATE_KEYS | WALLET_FLAG_BLANK_WALLET | WALLET_FLAG_KEY_ORIGIN_METADATA;
/** A key pool entry */
/** A key from a CWallet's keypool
*
* The wallet holds one (for pre HD-split wallets) or several keypools. These
* are sets of keys that have not yet been used to provide addresses or receive
* change.
*
* The Bitcoin Core wallet was originally a collection of unrelated private
* keys with their associated addresses. If a non-HD wallet generated a
* key/address, gave that address out and then restored a backup from before
* that key's generation, then any funds sent to that address would be
* lost definitively.
*
* The keypool was implemented to avoid this scenario (commit: 10384941). The
* wallet would generate a set of keys (100 by default). When a new public key
* was required, either to give out as an address or to use in a change output,
* it would be drawn from the keypool. The keypool would then be topped up to
* maintain 100 keys. This ensured that as long as the wallet hadn't used more
* than 100 keys since the previous backup, all funds would be safe, since a
* restored wallet would be able to scan for all owned addresses.
*
* A keypool also allowed encrypted wallets to give out addresses without
* having to be decrypted to generate a new private key.
*
* With the introduction of HD wallets (commit: f1902510), the keypool
* essentially became an address look-ahead pool. Restoring old backups can no
* longer definitively lose funds as long as the addresses used were from the
* wallet's HD seed (since all private keys can be rederived from the seed).
* However, if many addresses were used since the backup, then the wallet may
* not know how far ahead in the HD chain to look for its addresses. The
* keypool is used to implement a 'gap limit'. The keypool maintains a set of
* keys (by default 1000) ahead of the last used key and scans for the
* addresses of those keys. This avoids the risk of not seeing transactions
* involving the wallet's addresses, or of re-using the same address.
*
* The HD-split wallet feature added a second keypool (commit: 02592f4c). There
* is an external keypool (for addresses to hand out) and an internal keypool
* (for change addresses).
*
* Keypool keys are stored in the wallet/keystore's keymap. The keypool data is
* stored as sets of indexes in the wallet (setInternalKeyPool,
* setExternalKeyPool and set_pre_split_keypool), and a map from the key to the
* index (m_pool_key_to_index). The CKeyPool object is used to
* serialize/deserialize the pool data to/from the database.
*/
class CKeyPool
{
public:
//! The time at which the key was generated. Set in AddKeypoolPubKeyWithDB
int64_t nTime;
//! The public key
CPubKey vchPubKey;
bool fInternal; // for change outputs
bool m_pre_split; // For keys generated before keypool split upgrade
//! Whether this keypool entry is in the internal keypool (for change outputs)
bool fInternal;
//! Whether this key was generated for a keypool before the wallet was upgraded to HD-split
bool m_pre_split;
CKeyPool();
CKeyPool(const CPubKey& vchPubKeyIn, bool internalIn);
@ -187,6 +234,57 @@ public:
}
};
/** A wrapper to reserve a key from a wallet keypool
*
* CReserveKey is used to reserve a key from the keypool. It is passed around
* during the CreateTransaction/CommitTransaction procedure.
*
* Instantiating a CReserveKey does not reserve a keypool key. To do so,
* GetReservedKey() needs to be called on the object. Once a key has been
* reserved, call KeepKey() on the CReserveKey object to make sure it is not
* returned to the keypool. Call ReturnKey() to return the key to the keypool
* so it can be re-used (for example, if the key was used in a new transaction
* and that transaction was not completed and needed to be aborted).
*
* If a key is reserved and KeepKey() is not called, then the key will be
* returned to the keypool when the CReserveObject goes out of scope.
*/
class CReserveKey
{
protected:
//! The wallet to reserve the keypool key from
CWallet* pwallet;
//! The index of the key in the keypool
int64_t nIndex{-1};
//! The public key
CPubKey vchPubKey;
//! Whether this is from the internal (change output) keypool
bool fInternal{false};
public:
//! Construct a CReserveKey object. This does NOT reserve a key from the keypool yet
explicit CReserveKey(CWallet* pwalletIn)
{
pwallet = pwalletIn;
}
CReserveKey(const CReserveKey&) = delete;
CReserveKey& operator=(const CReserveKey&) = delete;
//! Destructor. If a key has been reserved and not KeepKey'ed, it will be returned to the keypool
~CReserveKey()
{
ReturnKey();
}
//! Reserve a key from the keypool
bool GetReservedKey(CPubKey &pubkey, bool internal = false);
//! Return a key to the keypool
void ReturnKey();
//! Keep the key. Do not return it to the keypool when this object goes out of scope
void KeepKey();
};
/** Address book data */
class CAddressBookData
{
@ -1201,34 +1299,6 @@ public:
*/
void MaybeResendWalletTxs();
/** A key allocated from the key pool. */
class CReserveKey
{
protected:
CWallet* pwallet;
int64_t nIndex{-1};
CPubKey vchPubKey;
bool fInternal{false};
public:
explicit CReserveKey(CWallet* pwalletIn)
{
pwallet = pwalletIn;
}
CReserveKey(const CReserveKey&) = delete;
CReserveKey& operator=(const CReserveKey&) = delete;
~CReserveKey()
{
ReturnKey();
}
void ReturnKey();
bool GetReservedKey(CPubKey &pubkey, bool internal = false);
void KeepKey();
};
/** RAII object to check and reserve a wallet rescan */
class WalletRescanReserver
{