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

#include <scriptpubkeyman.h>

Collaboration diagram for wallet::CKeyPool:

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 117 of file scriptpubkeyman.h.

Constructor & Destructor Documentation

◆ CKeyPool() [1/2]

wallet::CKeyPool::CKeyPool ( )

Definition at line 3435 of file wallet.cpp.

Here is the call graph for this function:

◆ CKeyPool() [2/2]

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

Definition at line 3442 of file wallet.cpp.

Here is the call graph for this function:

Member Function Documentation

◆ Serialize()

template<typename Stream >

void wallet::CKeyPool::Serialize ( Stream & s ) const

inline

Definition at line 133 of file scriptpubkeyman.h.

◆ Unserialize()

template<typename Stream >

void wallet::CKeyPool::Unserialize ( Stream & s )

inline

Definition at line 140 of file scriptpubkeyman.h.

Member Data Documentation

◆ fInternal

bool wallet::CKeyPool::fInternal

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

Definition at line 125 of file scriptpubkeyman.h.

◆ m_pre_split

bool wallet::CKeyPool::m_pre_split

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

Definition at line 127 of file scriptpubkeyman.h.

◆ nTime

int64_t wallet::CKeyPool::nTime

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

Definition at line 121 of file scriptpubkeyman.h.

◆ vchPubKey

CPubKey wallet::CKeyPool::vchPubKey

The public key.

Definition at line 123 of file scriptpubkeyman.h.

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

src/wallet/scriptpubkeyman.h
src/wallet/wallet.cpp

Public Member Functions

Public Attributes