Merge bitcoin/bitcoin#31080: fees: document non-monotonic estimation edge case

1e0de7a6ba926487c8a075856b74af2a3a0eb8ef fees: document non-monotonic estimation edge case (willcl-ark)

Pull request description:

  Closes: https://github.com/bitcoin/bitcoin/issues/11800

  In scenarios where data is available for higher targets but not for lower ones, this method *may* return lower fee rates for higher confirmation targets. This could occur if `estimateCombinedFee` returns no valid data (`-1`) for some estimates for a low target, but **does** return valid data for a higher target.

  Users of this function should be aware of this potential, if unlikely, inconsistency in behaviour in data-sparse scenarios.

ACKs for top commit:
  adamandrews1:
    Code review ACK 1e0de7a
  ismaelsadeeq:
    Code review ACK 1e0de7a6ba926487c8a075856b74af2a3a0eb8ef
  glozow:
    ACK 1e0de7a6ba926487c8a075856b74af2a3a0eb8ef

Tree-SHA512: 161e5dafdd131570853a89491753ae39a7b725d1a86cab5a7294c2a5939da1a9a5f2c4aca0900e9ad810e828b6e0e636f256384e3d1fda6dd552da189bbbe747

src/policy/fees.cpp

@@ -905,6 +905,14 @@ CFeeRate CBlockPolicyEstimator::estimateSmartFee(int confTarget, FeeCalculation
      * horizons so we already have monotonically increasing estimates and
      * the purpose of conservative estimates is not to let short term
      * fluctuations lower our estimates by too much.
+     *
+     * Note: In certain rare edge cases, monotonically increasing estimates may
+     * not be guaranteed. Specifically, given two targets N and M, where M > N,
+     * if a sub-estimate for target N fails to return a valid fee rate, while
+     * target M has valid fee rate for that sub-estimate, target M may result
+     * in a higher fee rate estimate than target N.
+     *
+     * See: https://github.com/bitcoin/bitcoin/issues/11800#issuecomment-349697807
      */
     double halfEst = estimateCombinedFee(confTarget/2, HALF_SUCCESS_PCT, true, &tempResult);
     if (feeCalc) {