[doc] current rbf policy

2 files changed, 76 insertions, 2 deletions

diff --git a/doc/policy/README.md b/doc/policy/README.md
index 9c83f4b56e..2c4478505a 100644
--- a/doc/policy/README.md
+++ b/doc/policy/README.md
@@ -1,10 +1,15 @@
 # Transaction Relay Policy
 
-Policy is a set of validation rules, in addition to consensus, enforced for unconfirmed
-transactions.
+**Policy** (Mempool or Transaction Relay Policy) is the node's set of validation rules, in addition
+to consensus, enforced for unconfirmed transactions before submitting them to the mempool. These
+rules are local to the node and configurable (e.g. `-minrelaytxfee`, `-limitancestorsize`,
+`-incrementalRelayFee`). Policy may include restrictions on the transaction itself, the transaction
+in relation to the current chain tip, and the transaction in relation to the node's mempool
+contents. Policy is *not* applied to transactions in blocks.
 
 This documentation is not an exhaustive list of all policy rules.
 
+- [Mempool Replacements](mempool-replacements.md)
 - [Packages](packages.md)
 
 
diff --git a/doc/policy/mempool-replacements.md b/doc/policy/mempool-replacements.md
new file mode 100644
index 0000000000..3e844f8d7b
--- /dev/null
+++ b/doc/policy/mempool-replacements.md
@@ -0,0 +1,69 @@
+# Mempool Replacements
+
+## Current Replace-by-Fee Policy
+
+A transaction conflicts with an in-mempool transaction ("directly conflicting transaction") if they
+spend one or more of the same inputs. A transaction may conflict with multiple in-mempool
+transactions.
+
+A transaction ("replacement transaction") may replace its directly conflicting transactions and
+their in-mempool descendants (together, "original transactions") if, in addition to passing all
+other consensus and policy rules, each of the following conditions are met:
+
+1. The directly conflicting transactions all signal replaceability explicitly. A transaction is
+   signaling replaceability if any of its inputs have an nSequence number less than (0xffffffff - 1).
+
+   *Rationale*: See [BIP125
+   explanation](https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki#motivation).
+
+2. The replacement transaction only include an unconfirmed input if that input was included in
+   one of the directly conflicting transactions. An unconfirmed input spends an output from a
+   currently-unconfirmed transaction.
+
+   *Rationale*: When RBF was originally implemented, the mempool did not keep track of
+   ancestor feerates yet. This rule was suggested as a temporary restriction.
+
+3. The replacement transaction pays an absolute fee of at least the sum paid by the original
+   transactions.
+
+   *Rationale*: Only requiring the replacement transaction to have a higher feerate could allow an
+   attacker to bypass node minimum relay feerate requirements and cause the network to repeatedly
+   relay slightly smaller replacement transactions without adding any more fees. Additionally, if
+   any of the original transactions would be included in the next block assembled by an economically
+   rational miner, a replacement policy allowing the replacement transaction to decrease the absolute
+   fees in the next block would be incentive-incompatible.
+
+4. The additional fees (difference between absolute fee paid by the replacement transaction and the
+   sum paid by the original transactions) pays for the replacement transaction's bandwidth at or
+   above the rate set by the node's incremental relay feerate. For example, if the incremental relay
+   feerate is 1 satoshi/vB and the replacement transaction is 500 virtual bytes total, then the
+   replacement pays a fee at least 500 satoshis higher than the sum of the original transactions.
+
+   *Rationale*: Try to prevent DoS attacks where an attacker causes the network to repeatedly relay
+   transactions each paying a tiny additional amount in fees, e.g. just 1 satoshi.
+
+5. The number of original transactions does not exceed 100. More precisely, the sum of all
+   directly conflicting transactions' descendant counts (number of transactions inclusive of itself
+   and its descendants) must not exceed 100; it is possible that this overestimates the true number
+   of original transactions.
+
+   *Rationale*: Try to prevent DoS attacks where an attacker is able to easily occupy and flush out
+   significant portions of the node's mempool using replacements with multiple directly conflicting
+   transactions, each with large descendant sets.
+
+This set of rules is similar but distinct from BIP125.
+
+## History
+
+* Opt-in full replace-by-fee (without inherited signaling) honoured in mempool and mining as of
+  **v0.12.0** ([PR 6871](https://github.com/bitcoin/bitcoin/pull/6871)).
+
+* [BIP125](https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki) defined based on
+  Bitcoin Core implementation.
+
+* The incremental relay feerate used to calculate the required additional fees is distinct from
+  `minRelayTxFee` and configurable using `-incrementalrelayfee`
+  ([PR #9380](https://github.com/bitcoin/bitcoin/pull/9380)).
+
+* RBF enabled by default in the wallet GUI as of **v0.18.1** ([PR
+  #11605](https://github.com/bitcoin/bitcoin/pull/11605)).