pub struct KeyPool { /* private fields */ }Expand 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.