4 files changed, 208 insertions, 0 deletions
diff --git a/doc/policy/README.md b/doc/policy/README.md
new file mode 100644
index 0000000000..6e8686365d
--- /dev/null
+++ b/doc/policy/README.md
@@ -0,0 +1,15 @@
+# Transaction Relay Policy
+
+**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 Limits](mempool-limits.md)
+- [Mempool Replacements](mempool-replacements.md)
+- [Packages](packages.md)
+
diff --git a/doc/policy/mempool-limits.md b/doc/policy/mempool-limits.md
new file mode 100644
index 0000000000..73ab017f1b
--- /dev/null
+++ b/doc/policy/mempool-limits.md
@@ -0,0 +1,65 @@
+# Mempool Limits
+
+## Definitions
+
+Given any two transactions Tx0 and Tx1 where Tx1 spends an output of Tx0,
+Tx0 is a *parent* of Tx1 and Tx1 is a *child* of Tx0.
+
+A transaction's *ancestors* include, recursively, its parents, the parents of its parents, etc.
+A transaction's *descendants* include, recursively, its children, the children of its children, etc.
+
+A mempool entry's *ancestor count* is the total number of in-mempool (unconfirmed) transactions in
+its ancestor set, including itself.
+A mempool entry's *descendant count* is the total number of in-mempool (unconfirmed) transactions in
+its descendant set, including itself.
+
+A mempool entry's *ancestor size* is the aggregated virtual size of in-mempool (unconfirmed)
+transactions in its ancestor set, including itself.
+A mempool entry's *descendant size* is the aggregated virtual size of in-mempool (unconfirmed)
+transactions in its descendant set, including itself.
+
+Transactions submitted to the mempool must not exceed the ancestor and descendant limits (aka
+mempool *package limits*) set by the node (see `-limitancestorcount`, `-limitancestorsize`,
+`-limitdescendantcount`, `-limitdescendantsize`).
+
+## Exemptions
+
+### CPFP Carve Out
+
+**CPFP Carve Out** if a transaction candidate for submission to the
+mempool would cause some mempool entry to exceed its descendant limits, an exemption is made if all
+of the following conditions are met:
+
+1. The candidate transaction is no more than 10,000 virtual bytes.
+
+2. The candidate transaction has an ancestor count of 2 (itself and exactly 1 ancestor).
+
+3. The in-mempool transaction's descendant count, including the candidate transaction, would only
+   exceed the limit by 1.
+
+*Rationale*: this rule was introduced to prevent pinning by domination of a transaction's descendant
+limits in two-party contract protocols such as LN.  Also see the [mailing list
+post](https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2018-November/016518.html).
+
+This rule was introduced in [PR #15681](https://github.com/bitcoin/bitcoin/pull/15681).
+
+### Single-Conflict RBF Carve Out
+
+When a candidate transaction for submission to the mempool would replace mempool entries, it may
+also decrease the descendant count of other mempool entries. Since ancestor/descendant limits are
+calculated prior to removing the would-be-replaced transactions, they may be overestimated.
+
+An exemption is given for a candidate transaction that would replace mempool transactions and meets
+all of the following conditions:
+
+1. The candidate transaction has exactly 1 directly conflicting transaction.
+
+2. The candidate transaction does not spend any unconfirmed inputs that are not also spent by the
+   directly conflicting transaction.
+
+The following discounts are given to account for the would-be-replaced transaction(s):
+
+1. The descendant count limit is temporarily increased by 1.
+
+2. The descendant size limit temporarily is increased by the virtual size of the to-be-replaced
+   directly conflicting transaction.
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)).
diff --git a/doc/policy/packages.md b/doc/policy/packages.md
new file mode 100644
index 0000000000..07698f2af2
--- /dev/null
+++ b/doc/policy/packages.md
@@ -0,0 +1,59 @@
+# Package Mempool Accept
+
+## Definitions
+
+A **package** is an ordered list of transactions, representable by a connected Directed Acyclic
+Graph (a directed edge exists between a transaction that spends the output of another transaction).
+
+For every transaction `t` in a **topologically sorted** package, if any of its parents are present
+in the package, they appear somewhere in the list before `t`.
+
+A **child-with-unconfirmed-parents** package is a topologically sorted package that consists of
+exactly one child and all of its unconfirmed parents (no other transactions may be present).
+The last transaction in the package is the child, and its package can be canonically defined based
+on the current state: each of its inputs must be available in the UTXO set as of the current chain
+tip or some preceding transaction in the package.
+
+## Package Mempool Acceptance Rules
+
+The following rules are enforced for all packages:
+
+* Packages cannot exceed `MAX_PACKAGE_COUNT=25` count and `MAX_PACKAGE_SIZE=101KvB` total size
+   (#20833)
+
+   - *Rationale*: This is already enforced as mempool ancestor/descendant limits. If
+     transactions in a package are all related, exceeding this limit would mean that the package
+     can either be split up or it wouldn't pass individual mempool policy.
+
+   - Note that, if these mempool limits change, package limits should be reconsidered. Users may
+     also configure their mempool limits differently.
+
+* Packages must be topologically sorted. (#20833)
+
+* Packages cannot have conflicting transactions, i.e. no two transactions in a package can spend
+   the same inputs. Packages cannot have duplicate transactions. (#20833)
+
+* No transaction in a package can conflict with a mempool transaction. BIP125 Replace By Fee is
+  currently disabled for packages. (#20833)
+
+   - Package RBF may be enabled in the future.
+
+* When packages are evaluated against ancestor/descendant limits, the union of all transactions'
+  descendants and ancestors is considered. (#21800)
+
+   - *Rationale*: This is essentially a "worst case" heuristic intended for packages that are
+     heavily connected, i.e. some transaction in the package is the ancestor or descendant of all
+     the other transactions.
+
+The following rules are only enforced for packages to be submitted to the mempool (not enforced for
+test accepts):
+
+* Packages must be child-with-unconfirmed-parents packages. This also means packages must contain at
+  least 2 transactions. (#22674)
+
+   - *Rationale*: This allows for fee-bumping by CPFP. Allowing multiple parents makes it possible
+     to fee-bump a batch of transactions. Restricting packages to a defined topology is easier to
+     reason about and simplifies the validation logic greatly.
+
+   - Warning: Batched fee-bumping may be unsafe for some use cases. Users and application developers
+     should take caution if utilizing multi-parent packages.