Inside Bitcoin

1# Package Mempool Accept
2
3## Definitions
4
5A **package** is an ordered list of transactions, representable by a connected Directed Acyclic
6Graph (a directed edge exists between a transaction that spends the output of another transaction).
7
8For every transaction `t` in a **topologically sorted** package, if any of its parents are present
9in the package, they appear somewhere in the list before `t`.
10
11A **child-with-parents** package is a topologically sorted package that consists of exactly one child and at least one
12of its unconfirmed parents.  Not all unconfirmed parents need to be present but no other transactions may be present; the
13parent of a parent should not be in this package (unless this "grandparent" is also a direct parent of the child).
14
15## Package Mempool Acceptance Rules
16
17The following rules are enforced for all packages:
18
19* Packages cannot exceed `MAX_PACKAGE_COUNT=25` count and `MAX_PACKAGE_WEIGHT=404000` total weight
20   (#20833)
21
22   - *Rationale*: We want package size to be as small as possible to mitigate DoS via package
23     validation. However, we want to make sure that the limit does not restrict ancestor
24     packages that would be allowed if submitted individually.
25
26   - Note that, if these mempool limits change, package limits should be reconsidered. Users may
27     also configure their mempool limits differently.
28
29   - Note that this is transaction weight, not "virtual" size as with other limits to allow
30     simpler context-less checks.
31
32* Packages must be topologically sorted. (#20833)
33
34* Packages cannot have conflicting transactions, i.e. no two transactions in a package can spend
35   the same inputs. Packages cannot have duplicate transactions. (#20833)
36
37* Only limited package replacements are currently considered. (#28984)
38
39   - Packages are 1-parent-1-child, with no in-mempool ancestors of the package.
40
41   - The number of distinct clusters containing conflicting transactions can be no more than 100, analogous to
42     regular [replacement rule](./mempool-replacements.md) 5).
43
44   - Replacements must pay more total fees at the incremental relay fee (analogous to
45     regular [replacement rules](./mempool-replacements.md) 3 and 4).
46
47   - Parent feerate must be lower than package feerate.
48
49   - Must improve [feerate diagram](https://delvingbitcoin.org/t/mempool-incentive-compatibility/553). (#29242)
50
51   - *Rationale*: Basic support for package RBF can be used by wallets
52     by making chains of no longer than two, then directly conflicting
53     those chains when needed. Combined with TRUC transactions this can
54     result in more robust fee bumping. More general package RBF may be
55     enabled in the future.
56
57The following rules are only enforced for packages to be submitted to the mempool (not
58enforced for test accepts):
59
60* Packages must be child-with-parents packages. This also means packages must contain at
61  least 1 transaction. (#31096)
62
63   - *Rationale*: This allows for fee-bumping by CPFP. Allowing multiple parents makes it possible
64     to fee-bump a batch of transactions. Restricting packages to a defined topology is easier to
65     reason about and simplifies the validation logic greatly.
66
67   - Warning: Batched fee-bumping may be unsafe for some use cases. Users and application developers
68     should take caution if utilizing multi-parent packages.
69
70* Transactions in the package that have the same txid as another transaction already in the mempool
71  will be removed from the package prior to submission ("deduplication").
72
73   - *Rationale*: Node operators are free to set their mempool policies however they please, nodes
74     may receive transactions in different orders, and malicious counterparties may try to take
75     advantage of policy differences to pin or delay propagation of transactions. As such, it's
76     possible for some package transaction(s) to already be in the mempool, and there is no need to
77     repeat validation for those transactions or double-count them in fees.
78
79   - *Rationale*: We want to prevent potential censorship vectors. We should not reject entire
80     packages because we already have one of the transactions. Also, if an attacker first broadcasts
81     a competing package or transaction with a mutated witness, even though the two
82     same-txid-different-witness transactions are conflicting and cannot replace each other, the
83     honest package should still be considered for acceptance.
84
85### Package Fees and Feerate
86
87*Package Feerate* is the total modified fees (base fees + any fee delta from
88`prioritisetransaction`) divided by the total virtual size of all transactions in the package.
89If any transactions in the package are already in the mempool, they are not submitted again
90("deduplicated") and are thus excluded from this calculation.
91
92To meet the dynamic mempool minimum feerate, i.e., the feerate determined by the transactions
93evicted when the mempool reaches capacity (not the static minimum relay feerate), the total package
94feerate instead of individual feerate can be used. For example, if the mempool minimum feerate is
955sat/vB and a 1sat/vB parent transaction has a high-feerate child, it may be accepted if
96submitted as a package.
97
98*Rationale*: This can be thought of as "CPFP within a package," solving the issue of a presigned
99transaction (i.e. in which a replacement transaction with a higher fee cannot be signed) being
100rejected from the mempool when transaction volume is high and the mempool minimum feerate rises.
101
102Implementation Note: Transactions within a package are always validated individually first, and
103package validation is used for the transactions that failed. Since package feerate is only
104calculated using transactions that are not in the mempool, this implementation detail affects the
105outcome of package validation.
106
107*Rationale*: It would be incorrect to use the fees of transactions that are already in the mempool, as
108we do not want a transaction's fees to be double-counted.
109
110*Rationale*: Packages are intended for incentive-compatible fee-bumping: transaction B is a
111"legitimate" fee-bump for transaction A only if B is a descendant of A and has a *higher* feerate
112than A. We want to prevent "parents pay for children" behavior; fees of parents should not help
113their children, since the parents can be mined without the child.  More generally, if transaction A
114is not needed in order for transaction B to be mined, A's fees cannot help B. In a
115child-with-parents package, simply excluding any parent transactions that meet feerate requirements
116individually is sufficient to ensure this.
117
118*Rationale*: We must not allow a low-feerate child to prevent its parent from being accepted; fees
119of children should not negatively impact their parents, since they are not necessary for the parents
120to be mined. More generally, if transaction B is not needed in order for transaction A to be mined,
121B's fees cannot harm A. In a child-with-parents package, simply validating parents individually
122first is sufficient to ensure this.
123
124*Rationale*: As a principle, we want to avoid accidentally restricting policy in order to be
125backward-compatible for users and applications that rely on p2p transaction relay. Concretely,
126package validation should not prevent the acceptance of a transaction that would otherwise be
127policy-valid on its own. By always accepting a transaction that passes individual validation before
128trying package validation, we prevent any unintentional restriction of policy.
129