Rules for creating and spending ephemeral dust

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
14class CFeeRate;
15class CTxMemPool;
16class 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 */
48bool 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 */
56bool 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