Bitcoin Core  0.20.99
P2P Digital Currency
Public Member Functions | Public Attributes | List of all members
CKeyPool Class Reference

A key from a CWallet's keypool. More...

#include <scriptpubkeyman.h>

Collaboration diagram for CKeyPool:
[legend]

Public Member Functions

 CKeyPool ()
 
 CKeyPool (const CPubKey &vchPubKeyIn, bool internalIn)
 
template<typename Stream >
void Serialize (Stream &s) const
 
template<typename Stream >
void Unserialize (Stream &s)
 

Public Attributes

int64_t nTime
 The time at which the key was generated. Set in AddKeypoolPubKeyWithDB. More...
 
CPubKey vchPubKey
 The public key. More...
 
bool fInternal
 Whether this keypool entry is in the internal keypool (for change outputs) More...
 
bool m_pre_split
 Whether this key was generated for a keypool before the wallet was upgraded to HD-split. More...
 

Detailed Description

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. In the unlikely case where none of the addresses in the gap limit are used on-chain, the look-ahead will not be incremented to keep a constant size and addresses beyond this range will not be detected by an old backup. For this reason, it is not recommended to decrease keypool size lower than default value.

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.

Definition at line 100 of file scriptpubkeyman.h.

Constructor & Destructor Documentation

◆ CKeyPool() [1/2]

CKeyPool::CKeyPool ( )

Definition at line 4173 of file wallet.cpp.

Here is the call graph for this function:

◆ CKeyPool() [2/2]

CKeyPool::CKeyPool ( const CPubKey vchPubKeyIn,
bool  internalIn 
)

Definition at line 4180 of file wallet.cpp.

Here is the call graph for this function:

Member Function Documentation

◆ Serialize()

template<typename Stream >
void CKeyPool::Serialize ( Stream &  s) const
inline

Definition at line 116 of file scriptpubkeyman.h.

◆ Unserialize()

template<typename Stream >
void CKeyPool::Unserialize ( Stream &  s)
inline

Definition at line 126 of file scriptpubkeyman.h.

Member Data Documentation

◆ fInternal

bool CKeyPool::fInternal

Whether this keypool entry is in the internal keypool (for change outputs)

Definition at line 108 of file scriptpubkeyman.h.

◆ m_pre_split

bool CKeyPool::m_pre_split

Whether this key was generated for a keypool before the wallet was upgraded to HD-split.

Definition at line 110 of file scriptpubkeyman.h.

◆ nTime

int64_t CKeyPool::nTime

The time at which the key was generated. Set in AddKeypoolPubKeyWithDB.

Definition at line 104 of file scriptpubkeyman.h.

◆ vchPubKey

CPubKey CKeyPool::vchPubKey

The public key.

Definition at line 106 of file scriptpubkeyman.h.


The documentation for this class was generated from the following files: