1 // Copyright (c) 2024-present 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_EPHEMERAL_POLICY_H
6 #define BITCOIN_POLICY_EPHEMERAL_POLICY_H
7 8 #include <consensus/amount.h>
9 #include <policy/packages.h>
10 #include <primitives/transaction.h>
11 12 #include <optional>
13 14 class CFeeRate;
15 class CTxMemPool;
16 class TxValidationState;
17 18 /** These utility functions ensure that ephemeral dust is safely
19 * created and spent without unduly risking them entering the utxo
20 * set.
21 22 * This is ensured by requiring:
23 * - PreCheckEphemeralTx checks are respected
24 * - The parent has no child (and 0-fee as implied above to disincentivize mining)
25 * - OR the parent transaction has exactly one child, and the dust is spent by that child
26 *
27 * Imagine three transactions:
28 * TxA, 0-fee with two outputs, one non-dust, one dust
29 * TxB, spends TxA's non-dust
30 * TxC, spends TxA's dust
31 *
32 * All the dust is spent if TxA+TxB+TxC is accepted, but the mining template may just pick
33 * up TxA+TxB rather than the three "legal configurations":
34 * 1) None
35 * 2) TxA+TxB+TxC
36 * 3) TxA+TxC
37 * By requiring the child transaction to sweep any dust from the parent txn, we ensure that
38 * there is a single child only, and this child, or the child's descendants,
39 * are the only way to bring fees.
40 */
41 42 /* All the following checks are only called if standardness rules are being applied. */
43 44 /** Called for each transaction once transaction fees are known.
45 * Does context-less checks about a single transaction.
46 * @returns false if the fee is non-zero and dust exists, populating state. True otherwise.
47 */
48 bool PreCheckEphemeralTx(const CTransaction& tx, CFeeRate dust_relay_rate, CAmount base_fee, CAmount mod_fee, TxValidationState& state);
49 50 /** Called for each transaction(package) if any dust is in the package.
51 * Checks that each transaction's parents have their dust spent by the child,
52 * where parents are either in the mempool or in the package itself.
53 * Sets out_child_state and out_child_wtxid on failure.
54 * @returns true if all dust is properly spent.
55 */
56 bool CheckEphemeralSpends(const Package& package, CFeeRate dust_relay_rate, const CTxMemPool& tx_pool, TxValidationState& out_child_state, Wtxid& out_child_wtxid);
57 58 #endif // BITCOIN_POLICY_EPHEMERAL_POLICY_H
59