aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorglozow <gloriajzhao@gmail.com>2021-10-20 12:02:18 +0100
committerglozow <gloriajzhao@gmail.com>2021-11-29 15:33:07 +0000
commitd59ddc5c3d1c035474d7bc9fa9f8a0eeb1c8498c (patch)
tree9be6b98492de028b2ab1176bc64738e6ff68f12d
parentba26169f6035c238378a3c9647213328a006fa23 (diff)
[packages/doc] define and document package rules
Central place for putting package-related info. This document or parts of it can also be easily ported to other places if deemed appropriate.
-rw-r--r--doc/README.md1
-rw-r--r--doc/policy/README.md10
-rw-r--r--doc/policy/packages.md59
-rw-r--r--src/validation.h10
4 files changed, 72 insertions, 8 deletions
diff --git a/doc/README.md b/doc/README.md
index 4845f00ade..965cbc4511 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -82,6 +82,7 @@ The Bitcoin repo's [root README](/README.md) contains relevant information on th
- [Reduce Memory](reduce-memory.md)
- [Reduce Traffic](reduce-traffic.md)
- [Tor Support](tor.md)
+- [Transaction Relay Policy](policy/README.md)
- [ZMQ](zmq.md)
License
diff --git a/doc/policy/README.md b/doc/policy/README.md
new file mode 100644
index 0000000000..9c83f4b56e
--- /dev/null
+++ b/doc/policy/README.md
@@ -0,0 +1,10 @@
+# Transaction Relay Policy
+
+Policy is a set of validation rules, in addition to consensus, enforced for unconfirmed
+transactions.
+
+This documentation is not an exhaustive list of all policy rules.
+
+- [Packages](packages.md)
+
+
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.
diff --git a/src/validation.h b/src/validation.h
index 256981224a..2621d3e7f1 100644
--- a/src/validation.h
+++ b/src/validation.h
@@ -216,14 +216,8 @@ MempoolAcceptResult AcceptToMemoryPool(CChainState& active_chainstate, CTxMemPoo
bool bypass_limits, bool test_accept=false) EXCLUSIVE_LOCKS_REQUIRED(cs_main);
/**
-* Atomically test acceptance of a package. If the package only contains one tx, package rules still
-* apply. Package validation does not allow BIP125 replacements, so the transaction(s) cannot spend
-* the same inputs as any transaction in the mempool.
-* @param[in] txns Group of transactions which may be independent or contain
-* parent-child dependencies. The transactions must not conflict
-* with each other, i.e., must not spend the same inputs. If any
-* dependencies exist, parents must appear anywhere in the list
-* before their children.
+* Validate (and maybe submit) a package to the mempool. See doc/policy/packages.md for full details
+* on package validation rules.
* @returns a PackageMempoolAcceptResult which includes a MempoolAcceptResult for each transaction.
* If a transaction fails, validation will exit early and some results may be missing.
*/