1  // Copyright (c) 2022 The Bitcoin Core developers
 2  // Distributed under the MIT software license, see the accompanying
 3  // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 4  
 5  #ifndef BITCOIN_POLICY_V3_POLICY_H
 6  #define BITCOIN_POLICY_V3_POLICY_H
 7  
 8  #include <consensus/amount.h>
 9  #include <policy/packages.h>
10  #include <policy/policy.h>
11  #include <primitives/transaction.h>
12  #include <txmempool.h>
13  #include <util/result.h>
14  
15  #include <set>
16  #include <string>
17  
18  // This module enforces rules for transactions with nVersion=3 ("v3 transactions") which help make
19  // RBF abilities more robust.
20  
21  // v3 only allows 1 parent and 1 child when unconfirmed.
22  /** Maximum number of transactions including an unconfirmed tx and its descendants. */
23  static constexpr unsigned int V3_DESCENDANT_LIMIT{2};
24  /** Maximum number of transactions including a V3 tx and all its mempool ancestors. */
25  static constexpr unsigned int V3_ANCESTOR_LIMIT{2};
26  
27  /** Maximum sigop-adjusted virtual size of a tx which spends from an unconfirmed v3 transaction. */
28  static constexpr int64_t V3_CHILD_MAX_VSIZE{1000};
29  // These limits are within the default ancestor/descendant limits.
30  static_assert(V3_CHILD_MAX_VSIZE + MAX_STANDARD_TX_WEIGHT / WITNESS_SCALE_FACTOR <= DEFAULT_ANCESTOR_SIZE_LIMIT_KVB * 1000);
31  static_assert(V3_CHILD_MAX_VSIZE + MAX_STANDARD_TX_WEIGHT / WITNESS_SCALE_FACTOR <= DEFAULT_DESCENDANT_SIZE_LIMIT_KVB * 1000);
32  
33  /** Must be called for every transaction, even if not v3. Not strictly necessary for transactions
34   * accepted through AcceptMultipleTransactions.
35   *
36   * Checks the following rules:
37   * 1. A v3 tx must only have v3 unconfirmed ancestors.
38   * 2. A non-v3 tx must only have non-v3 unconfirmed ancestors.
39   * 3. A v3's ancestor set, including itself, must be within V3_ANCESTOR_LIMIT.
40   * 4. A v3's descendant set, including itself, must be within V3_DESCENDANT_LIMIT.
41   * 5. If a v3 tx has any unconfirmed ancestors, the tx's sigop-adjusted vsize must be within
42   * V3_CHILD_MAX_VSIZE.
43   *
44   *
45   * @param[in]   mempool_ancestors       The in-mempool ancestors of ptx.
46   * @param[in]   direct_conflicts        In-mempool transactions this tx conflicts with. These conflicts
47   *                                      are used to more accurately calculate the resulting descendant
48   *                                      count of in-mempool ancestors.
49   * @param[in]   vsize                   The sigop-adjusted virtual size of ptx.
50   *
51   * @returns 3 possibilities:
52   * - std::nullopt if all v3 checks were applied successfully
53   * - debug string + pointer to a mempool sibling if this transaction would be the second child in a
54   *   1-parent-1-child cluster; the caller may consider evicting the specified sibling or return an
55   *   error with the debug string.
56   * - debug string + nullptr if this transaction violates some v3 rule and sibling eviction is not
57   *   applicable.
58   */
59  std::optional<std::pair<std::string, CTransactionRef>> SingleV3Checks(const CTransactionRef& ptx,
60                                            const CTxMemPool::setEntries& mempool_ancestors,
61                                            const std::set<Txid>& direct_conflicts,
62                                            int64_t vsize);
63  
64  /** Must be called for every transaction that is submitted within a package, even if not v3.
65   *
66   * For each transaction in a package:
67   * If it's not a v3 transaction, verify it has no direct v3 parents in the mempool or the package.
68  
69   * If it is a v3 transaction, verify that any direct parents in the mempool or the package are v3.
70   * If such a parent exists, verify that parent has no other children in the package or the mempool,
71   * and that the transaction itself has no children in the package.
72   *
73   * If any v3 violations in the package exist, this test will fail for one of them:
74   * - if a v3 transaction T has a parent in the mempool and a child in the package, then PV3C(T) will fail
75   * - if a v3 transaction T has a parent in the package and a child in the package, then PV3C(T) will fail
76   * - if a v3 transaction T and a v3 (sibling) transaction U have some parent in the mempool,
77   *   then PV3C(T) and PV3C(U) will fail
78   * - if a v3 transaction T and a v3 (sibling) transaction U have some parent in the package,
79   *   then PV3C(T) and PV3C(U) will fail
80   * - if a v3 transaction T has a parent P and a grandparent G in the package, then
81   *   PV3C(P) will fail (though PV3C(G) and PV3C(T) might succeed).
82   *
83   * @returns debug string if an error occurs, std::nullopt otherwise.
84   * */
85  std::optional<std::string> PackageV3Checks(const CTransactionRef& ptx, int64_t vsize,
86                                             const Package& package,
87                                             const CTxMemPool::setEntries& mempool_ancestors);
88  
89  #endif // BITCOIN_POLICY_V3_POLICY_H