READ THE CODE

Inside Bitcoin

The code behind the network, with room to understand it.

Stable release v32.1bitcoin/bitcoin · f0de87f04062 ↗3,020 source files · 47.5 MB stored on the server440 file guides

Release published 2026-10-28 · Snapshot fetched 2026-11-01. Latest stable release at fetch time; development branches and Git history are excluded. Only the selected code window and visible folders load here.

6,496 bytes · SHA-256 163aecd5352a863b… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2022-present The Bitcoin Core developers
3# Distributed under the MIT software license, see the accompanying
4# file COPYING or http://www.opensource.org/licenses/mit-license.php.
5"""Test dust limit mempool policy (`-dustrelayfee` parameter)"""
6from decimal import Decimal
7
8from test_framework.messages import (
9    COIN,
10    CTxOut,
11)
12from test_framework.script import (
13    CScript,
14    OP_RETURN,
15    OP_TRUE,
16)
17from test_framework.script_util import (
18    key_to_p2pk_script,
19    key_to_p2pkh_script,
20    key_to_p2wpkh_script,
21    keys_to_multisig_script,
22    output_key_to_p2tr_script,
23    program_to_witness_script,
24    script_to_p2sh_script,
25    script_to_p2wsh_script,
26)
27from test_framework.test_framework import BitcoinTestFramework
28from test_framework.test_node import TestNode
29from test_framework.util import (
30    assert_equal,
31    get_fee,
32)
33from test_framework.wallet import MiniWallet
34from test_framework.wallet_util import generate_keypair
35
36
37DUST_RELAY_TX_FEE = 3000  # default setting [sat/kvB]
38
39
40class DustRelayFeeTest(BitcoinTestFramework):
41    def set_test_params(self):
42        self.num_nodes = 1
43        self.extra_args = [['-permitbaremultisig']]
44
45    def test_dust_output(self, node: TestNode, dust_relay_fee: Decimal,
46                         output_script: CScript, type_desc: str) -> None:
47        # determine dust threshold (see `GetDustThreshold`)
48        if output_script[0] == OP_RETURN:
49            dust_threshold = 0
50        else:
51            tx_size = len(CTxOut(nValue=0, scriptPubKey=output_script).serialize())
52            tx_size += 67 if output_script.IsWitnessProgram() else 148
53            dust_threshold = int(get_fee(tx_size, dust_relay_fee) * COIN)
54        self.log.info(f"-> Test {type_desc} output (size {len(output_script)}, limit {dust_threshold})")
55
56        # amount right on the dust threshold should pass
57        tx = self.wallet.create_self_transfer()["tx"]
58        tx.vout.append(CTxOut(nValue=dust_threshold, scriptPubKey=output_script))
59        tx.vout[0].nValue -= dust_threshold  # keep total output value constant
60        tx_good_hex = tx.serialize().hex()
61        res = node.testmempoolaccept([tx_good_hex])[0]
62        assert_equal(res['allowed'], True)
63
64        # amount just below the dust threshold should fail
65        if dust_threshold > 0:
66            tx.vout[1].nValue -= 1
67            res = node.testmempoolaccept([tx.serialize().hex()])[0]
68            assert_equal(res['allowed'], False)
69            assert_equal(res['reject-reason'], 'dust')
70
71        # finally send the transaction to avoid running out of MiniWallet UTXOs
72        self.wallet.sendrawtransaction(from_node=node, tx_hex=tx_good_hex)
73
74    def test_dustrelay(self):
75        self.log.info("Test that small outputs are acceptable when dust relay rate is set to 0 that would otherwise trigger ephemeral dust rules")
76
77        self.restart_node(0, extra_args=["-dustrelayfee=0"])
78
79        assert_equal(self.nodes[0].getrawmempool(), [])
80
81        # Create two dust outputs. Transaction has zero fees. both dust outputs are unspent, and would have failed individual checks.
82        # The amount is 1 satoshi because create_self_transfer_multi disallows 0.
83        dusty_tx = self.wallet.create_self_transfer_multi(fee_per_output=1000, amount_per_output=1, num_outputs=2)
84        dust_txid = self.nodes[0].sendrawtransaction(hexstring=dusty_tx["hex"], maxfeerate=0)
85
86        assert_equal(self.nodes[0].getrawmempool(), [dust_txid])
87
88        # Spends one dust along with fee input, leave other dust unspent to check ephemeral dust checks aren't being enforced
89        sweep_tx = self.wallet.create_self_transfer_multi(utxos_to_spend=[self.wallet.get_utxo(), dusty_tx["new_utxos"][0]])
90        sweep_txid = self.nodes[0].sendrawtransaction(sweep_tx["hex"])
91
92        mempool_entries = self.nodes[0].getrawmempool()
93        assert dust_txid in mempool_entries
94        assert sweep_txid in mempool_entries
95        assert_equal(len(mempool_entries), 2)
96
97        # Wipe extra arg to reset dust relay
98        self.restart_node(0, extra_args=[])
99
100        assert_equal(self.nodes[0].getrawmempool(), [])
101
102    def run_test(self):
103        self.wallet = MiniWallet(self.nodes[0])
104
105        self.test_dustrelay()
106
107        # prepare output scripts of each standard type
108        _, uncompressed_pubkey = generate_keypair(compressed=False)
109        _, pubkey = generate_keypair(compressed=True)
110
111        output_scripts = (
112            (key_to_p2pk_script(uncompressed_pubkey),          "P2PK (uncompressed)"),
113            (key_to_p2pk_script(pubkey),                       "P2PK (compressed)"),
114            (key_to_p2pkh_script(pubkey),                      "P2PKH"),
115            (script_to_p2sh_script(CScript([OP_TRUE])),        "P2SH"),
116            (key_to_p2wpkh_script(pubkey),                     "P2WPKH"),
117            (script_to_p2wsh_script(CScript([OP_TRUE])),       "P2WSH"),
118            (output_key_to_p2tr_script(pubkey[1:]),            "P2TR"),
119            # witness programs for segwitv2+ can be between 2 and 40 bytes
120            (program_to_witness_script(2,  b'\x66' * 2),       "P2?? (future witness version 2)"),
121            (program_to_witness_script(16, b'\x77' * 40),      "P2?? (future witness version 16)"),
122            # largest possible output script considered standard
123            (keys_to_multisig_script([uncompressed_pubkey]*3), "bare multisig (m-of-3)"),
124            (CScript([OP_RETURN, b'superimportanthash']),      "null data (OP_RETURN)"),
125        )
126
127        # test default (no parameter), disabled (=0) and a bunch of arbitrary dust fee rates [sat/kvB]
128        for dustfee_sat_kvb in (DUST_RELAY_TX_FEE, 0, 1, 66, 500, 1337, 12345, 21212, 333333):
129            dustfee_btc_kvb = dustfee_sat_kvb / Decimal(COIN)
130            if dustfee_sat_kvb == DUST_RELAY_TX_FEE:
131                self.log.info(f"Test default dust limit setting ({dustfee_sat_kvb} sat/kvB)...")
132            else:
133                dust_parameter = f"-dustrelayfee={dustfee_btc_kvb:.8f}"
134                self.log.info(f"Test dust limit setting {dust_parameter} ({dustfee_sat_kvb} sat/kvB)...")
135                self.restart_node(0, extra_args=[dust_parameter, "-permitbaremultisig"])
136
137            for output_script, description in output_scripts:
138                self.test_dust_output(self.nodes[0], dustfee_btc_kvb, output_script, description)
139            self.generate(self.nodes[0], 1)
140
141
142if __name__ == '__main__':
143    DustRelayFeeTest(__file__).main()
144

src/wallet/receive.cpp

src/wallet/coinselection.cpp

src/consensus/validation.h

src/primitives/transaction.cpp

src/script/descriptor.cpp

src/bitcoin-cli.cpp

src/rpc/blockchain.cpp

src/rpc/rawtransaction.cpp

src/init.cpp

src/crypto/sha256.cpp

src/consensus/merkle.h

src/consensus/tx_check.h

src/consensus/tx_verify.h

src/policy/feerate.h

src/policy/feerate.cpp

src/primitives/transaction_identifier.h

src/chainparamsbase.h

src/chainparamsbase.cpp

src/util/moneystr.cpp

src/crypto/ripemd160.h

src/crypto/sha1.h

src/crypto/sha512.h

src/crypto/hmac_sha256.h

src/crypto/hmac_sha512.h

src/crypto/hmac_sha256.cpp

src/crypto/hmac_sha512.cpp

src/crypto/hkdf_sha256_32.h

src/crypto/hkdf_sha256_32.cpp

src/support/cleanse.h

src/support/cleanse.cpp

src/crypto/siphash.cpp

src/crypto/muhash.h

src/crypto/chacha20.h

src/crypto/poly1305.h

src/crypto/chacha20poly1305.h

src/crypto/chacha20poly1305.cpp

src/util/chaintype.cpp

src/util/obfuscation.h

src/util/byte_units.h

src/util/overflow.h

src/blockencodings.cpp

src/net_permissions.cpp

src/policy/packages.cpp

src/policy/rbf.cpp

src/policy/truc_policy.cpp

src/policy/ephemeral_policy.cpp

src/policy/settings.cpp

src/policy/policy.cpp

src/node/transaction.cpp

src/node/coin.cpp

src/rpc/client.cpp

src/rpc/external_signer.cpp

src/rpc/request.cpp

src/rpc/server_util.cpp

src/rpc/fees.cpp

src/rpc/output_script.cpp

src/rpc/rawtransaction_util.cpp

src/rpc/rawtransaction_util.h

src/rpc/register.h

src/rpc/request.h

src/rpc/server_util.h

src/rpc/protocol.h

src/rpc/server.h

src/rpc/signmessage.cpp

src/rpc/txoutproof.cpp

src/rpc/util.cpp

src/rpc/util.h

src/wallet/rpc/addresses.cpp

src/wallet/rpc/backup.cpp

src/wallet/rpc/coins.cpp

src/wallet/rpc/encrypt.cpp

src/wallet/rpc/signmessage.cpp

src/wallet/rpc/util.cpp

src/wallet/rpc/util.h

src/wallet/coincontrol.cpp

src/wallet/coincontrol.h

src/wallet/context.cpp

src/wallet/context.h

src/wallet/crypter.cpp

src/wallet/crypter.h

src/wallet/db.cpp

src/wallet/export.cpp

src/wallet/external_signer_scriptpubkeyman.cpp

src/wallet/rpc/spend.cpp

src/wallet/rpc/transactions.cpp

src/wallet/rpc/wallet.cpp

src/wallet/feebumper.cpp

src/wallet/feebumper.h

src/index/base.h

src/index/base.cpp

src/index/txindex.h

src/index/txindex.cpp

src/index/txindex_key.h

src/index/txospenderindex.h

src/index/txospenderindex.cpp

src/index/blockfilterindex.h

src/index/blockfilterindex.cpp

src/index/coinstatsindex.h

src/index/coinstatsindex.cpp

src/index/db_key.h

src/index/disktxpos.h

src/kernel/chain.cpp

src/kernel/chain.h

src/kernel/checks.cpp

src/kernel/checks.h

src/kernel/context.cpp

src/kernel/context.h

src/kernel/cs_main.cpp

src/kernel/cs_main.h

src/kernel/disconnected_transactions.cpp

src/kernel/disconnected_transactions.h

src/kernel/mempool_removal_reason.cpp

src/kernel/mempool_removal_reason.h

src/kernel/coinstats.cpp

src/kernel/coinstats.h

src/kernel/chainparams.cpp

src/kernel/chainparams.h

src/wallet/sqlite.cpp

src/wallet/sqlite.h

src/wallet/transaction.cpp

src/wallet/transaction.h

src/wallet/dump.cpp

src/wallet/dump.h

src/wallet/init.cpp

src/wallet/walletutil.cpp

src/wallet/walletutil.h

src/wallet/wallettool.cpp

src/wallet/wallettool.h

src/wallet/export.h

src/wallet/migrate.cpp

src/wallet/migrate.h

src/wallet/db.h

src/wallet/walletdb.cpp

src/wallet/interfaces.cpp

src/wallet/scriptpubkeyman.cpp

src/wallet/scriptpubkeyman.h

src/kernel/bitcoinkernel.cpp

src/kernel/bitcoinkernel.h

src/kernel/bitcoinkernel_wrapper.h

src/node/chainstate.cpp

src/node/chainstate.h

src/node/blockstorage.cpp

src/node/blockstorage.h

src/node/mempool_persist.cpp

src/node/mempool_persist.h

src/node/utxo_snapshot.cpp

src/node/utxo_snapshot.h

src/node/kernel_notifications.cpp

src/node/kernel_notifications.h

src/node/blockmanager_args.cpp

src/kernel/blockmanager_opts.h

src/util/expected.cpp

src/policy/settings.h

src/util/types.h

src/kernel/messagestartchars.h

src/kernel/warning.h

src/util/exception.h

src/common/license_info.h

src/node/coins_view_args.h

src/node/database_args.h

src/util/batchpriority.h

src/util/ui_change_type.h

src/node/coins_view_args.cpp

src/node/peerman_args.h

src/util/serfloat.h

src/node/blockmanager_args.h

src/node/database_args.cpp

src/util/overloaded.h

src/interfaces/types.h

src/node/chainstatemanager_args.h

src/node/minisketchwrapper.h

src/util/macros.h

src/util/syserror.h

src/common/run_command.h

src/util/bytevectorhash.cpp

src/node/mempool_persist_args.cpp

src/util/exec.h

src/util/rbf.h

src/crypto/hex_base.h

src/node/mempool_persist_args.h

src/interfaces/echo.h

src/util/any.h

src/util/batchpriority.cpp

src/util/threadnames.h

src/node/coin.h

src/node/mempool_args.h

src/util/asmap.h

src/util/bytevectorhash.h

src/node/context.cpp

src/util/insert.h

src/util/readwritefile.h

src/node/peerman_args.cpp

src/node/interface_ui.cpp

src/interfaces/handler.h

src/node/mining_args.h

src/util/hasher.cpp

src/common/init.h

src/kernel/mempool_limits.h

src/common/system.h

src/crypto/sha3.h

src/util/threadinterrupt.cpp

src/node/protocol_version.h

src/util/exception.cpp

src/common/messages.h

src/node/connection_types.cpp

src/util/bip32.h

src/common/license_info.cpp

src/util/stdmutex.h

src/common/run_command.cpp

src/util/check.cpp

src/util/golombrice.h

src/node/types.h

src/node/timeoffsets.h

src/util/readwritefile.cpp

src/util/fastrange.h

src/util/signalinterrupt.h

src/util/task_runner.h

src/util/syserror.cpp

src/common/interfaces.cpp

src/common/types.h

src/util/threadinterrupt.h

src/kernel/chainstatemanager_opts.h

src/node/psbt.h

src/policy/ephemeral_policy.h

src/util/trace.h

src/common/url.cpp

src/kernel/mempool_options.h

src/util/serfloat.cpp

src/kernel/notifications_interface.h

src/node/timeoffsets.cpp

src/node/warnings.cpp

src/util/hash_type.h

src/crypto/hex_base.cpp

src/node/eviction.h

src/util/tokenbucket.h

src/crypto/aes.h

src/common/pcp.h

src/util/feefrac.cpp

src/node/transaction.h

src/util/threadnames.cpp

src/common/signmessage.h

src/util/exec.cpp

src/util/signalinterrupt.cpp

src/clientversion.cpp

src/common/signmessage.cpp

src/compat/assumptions.h

src/compat/byteswap.h

src/deploymentinfo.cpp

src/deploymentinfo.h

src/deploymentstatus.cpp

src/deploymentstatus.h

src/dummywallet.cpp

src/external_signer.h

src/init/bitcoin-gui.cpp

src/init/bitcoin-node.cpp

src/init/bitcoin-qt.cpp

src/init/bitcoin-wallet.cpp

src/init/bitcoind.cpp

src/init/common.h

src/interfaces/init.h

src/interfaces/ipc.h

src/key_io.h

src/logging/categories.h

src/logging/timer.h

src/mapport.h

src/musig.h

src/net_permissions.h

src/netgroup.h

src/netmessagemaker.h

src/node/chainstatemanager_args.cpp

src/node/connection_types.h

src/node/context.h

src/node/interface_ui.h

src/node/mempool_args.cpp

src/node/mining_args.cpp

src/node/minisketchwrapper.cpp

src/node/txreconciliation.h

src/policy/fees/estimator_args.cpp

src/policy/fees/estimator_args.h

src/policy/fees/estimator_man.cpp

src/policy/fees/estimator_man.h

src/policy/packages.h

src/policy/rbf.h

src/policy/truc_policy.h

src/pow.h

src/primitives/block.cpp

src/randomenv.h

src/rest.h

src/script/keyorigin.h

src/script/parsing.cpp

src/script/parsing.h

src/script/script_error.h

src/script/sigcache.cpp

src/script/sigcache.h

src/script/solver.h

src/script/verify_flags.h

src/semaphore_grant.h

src/signet.h

src/span.h

src/support/allocators/secure.h

src/support/allocators/zeroafterfree.h

src/util/tokenpipe.cpp

src/util/translation.h

src/util/vector.h

src/versionbits.h

src/versionbits_impl.h

src/wallet/external_signer_scriptpubkeyman.h

src/wallet/fees.h

src/wallet/load.h

src/wallet/receive.h

src/wallet/rpc/wallet.h

src/wallet/types.h

src/walletinitinterface.h

src/zmq/zmqabstractnotifier.cpp

Independent explanations by MyBitcoinExplorer. Not affiliated with or endorsed by Bitcoin Core. Guides are educational and do not replace the source or its tests.

Bitcoin Core source © its contributors, distributed under the MIT license. Original notices and bundled third-party licenses are retained in the source tree.