message: [docs] Add doxygen comment for CKeyPool
diff: @@ -135,14 +135,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);
  