fees: document non-monotonic estimation edge case

Closes: #11800

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: bitcoin/bitcoin#11800 (comment)

Author: willcl-ark

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) {