diff --git a/CMakeLists.txt b/CMakeLists.txt index 37daf51c7c..417c1d577a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -28,9 +28,9 @@ get_directory_property(precious_variables CACHE_VARIABLES) #============================= set(CLIENT_NAME "Elements Core") set(CLIENT_VERSION_MAJOR 29) -set(CLIENT_VERSION_MINOR 1) +set(CLIENT_VERSION_MINOR 2) set(CLIENT_VERSION_BUILD 0) -set(CLIENT_VERSION_RC 0) +set(CLIENT_VERSION_RC 1) set(CLIENT_VERSION_IS_RELEASE "true") set(COPYRIGHT_YEAR "2025") diff --git a/ci/test/01_base_install.sh b/ci/test/01_base_install.sh index 0044889fb7..a339b8f541 100755 --- a/ci/test/01_base_install.sh +++ b/ci/test/01_base_install.sh @@ -55,10 +55,9 @@ if [ -n "$PIP_PACKAGES" ]; then fi if [[ -n "${USE_INSTRUMENTED_LIBCPP}" ]]; then + ${CI_RETRY_EXE} git clone --depth=1 https://github.com/llvm/llvm-project -b "llvmorg-21.1.1" /llvm-project + if [ -n "${APT_LLVM_V}" ]; then - ${CI_RETRY_EXE} git clone --depth=1 https://github.com/llvm/llvm-project -b "llvmorg-$( clang --version | sed --silent 's@.*clang version \([0-9.]*\).*@\1@p' )" /llvm-project - else - ${CI_RETRY_EXE} git clone --depth=1 https://github.com/llvm/llvm-project -b "llvmorg-21.1.0" /llvm-project cmake -G Ninja -B /clang_build/ \ -DLLVM_ENABLE_PROJECTS="clang" \ diff --git a/cmake/module/FindUSDT.cmake b/cmake/module/FindUSDT.cmake index 0be7c28ff5..234a099f3f 100644 --- a/cmake/module/FindUSDT.cmake +++ b/cmake/module/FindUSDT.cmake @@ -36,6 +36,10 @@ if(USDT_INCLUDE_DIR) include(CheckCXXSourceCompiles) set(CMAKE_REQUIRED_INCLUDES ${USDT_INCLUDE_DIR}) check_cxx_source_compiles(" + #if defined(__arm__) + # define STAP_SDT_ARG_CONSTRAINT g + #endif + // Setting SDT_USE_VARIADIC lets systemtap (sys/sdt.h) know that we want to use // the optional variadic macros to define tracepoints. #define SDT_USE_VARIADIC 1 diff --git a/doc/man/bitcoin-cli.1 b/doc/man/bitcoin-cli.1 new file mode 100644 index 0000000000..a8dc092a6c --- /dev/null +++ b/doc/man/bitcoin-cli.1 @@ -0,0 +1,201 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH BITCOIN-CLI "1" "September 2025" "bitcoin-cli v29.2.0rc1" "User Commands" +.SH NAME +bitcoin-cli \- manual page for bitcoin-cli v29.2.0rc1 +.SH SYNOPSIS +.B bitcoin-cli +[\fI\,options\/\fR] \fI\, \/\fR[\fI\,params\/\fR] +.br +.B bitcoin-cli +[\fI\,options\/\fR] \fI\,-named \/\fR[\fI\,name=value\/\fR]... +.br +.B bitcoin-cli +[\fI\,options\/\fR] \fI\,help\/\fR +.br +.B bitcoin-cli +[\fI\,options\/\fR] \fI\,help \/\fR +.SH DESCRIPTION +Bitcoin Core RPC client version v29.2.0rc1 +.PP +The bitcoin\-cli utility provides a command line interface to interact with a Bitcoin Core RPC server. +.PP +It can be used to query network information, manage wallets, create or broadcast transactions, and control the Bitcoin Core server. +.PP +Use the "help" command to list all commands. Use "help " to show help for that command. +The \fB\-named\fR option allows you to specify parameters using the key=value format, eliminating the need to pass unused positional parameters. +.SH OPTIONS +.HP +\fB\-color=\fR +.IP +Color setting for CLI output (default: auto). Valid values: always, auto +(add color codes when standard output is connected to a terminal +and OS is not WIN32), never. Only applies to the output of +\fB\-getinfo\fR. +.HP +\fB\-conf=\fR +.IP +Specify configuration file. Relative paths will be prefixed by datadir +location. (default: bitcoin.conf) +.HP +\fB\-datadir=\fR +.IP +Specify data directory +.HP +\fB\-help\fR +.IP +Print this help message and exit (also \fB\-h\fR or \-?) +.HP +\fB\-named\fR +.IP +Pass named instead of positional arguments (default: false) +.HP +\fB\-rpcclienttimeout=\fR +.IP +Timeout in seconds during HTTP requests, or 0 for no timeout. (default: +900) +.HP +\fB\-rpcconnect=\fR +.IP +Send commands to node running on (default: 127.0.0.1) +.HP +\fB\-rpccookiefile=\fR +.IP +Location of the auth cookie. Relative paths will be prefixed by a +net\-specific datadir location. (default: data dir) +.HP +\fB\-rpcpassword=\fR +.IP +Password for JSON\-RPC connections +.HP +\fB\-rpcport=\fR +.IP +Connect to JSON\-RPC on (default: 8332, testnet: 18332, testnet4: +48332, signet: 38332, regtest: 18443) +.HP +\fB\-rpcuser=\fR +.IP +Username for JSON\-RPC connections +.HP +\fB\-rpcwait\fR +.IP +Wait for RPC server to start +.HP +\fB\-rpcwaittimeout=\fR +.IP +Timeout in seconds to wait for the RPC server to start, or 0 for no +timeout. (default: 0) +.HP +\fB\-rpcwallet=\fR +.IP +Send RPC for non\-default wallet on RPC server (needs to exactly match +corresponding \fB\-wallet\fR option passed to bitcoind). This changes +the RPC endpoint used, e.g. +http://127.0.0.1:8332/wallet/ +.HP +\fB\-stdin\fR +.IP +Read extra arguments from standard input, one per line until EOF/Ctrl\-D +(recommended for sensitive information such as passphrases). When +combined with \fB\-stdinrpcpass\fR, the first line from standard input +is used for the RPC password. +.HP +\fB\-stdinrpcpass\fR +.IP +Read RPC password from standard input as a single line. When combined +with \fB\-stdin\fR, the first line from standard input is used for the +RPC password. When combined with \fB\-stdinwalletpassphrase\fR, +\fB\-stdinrpcpass\fR consumes the first line, and \fB\-stdinwalletpassphrase\fR +consumes the second. +.HP +\fB\-stdinwalletpassphrase\fR +.IP +Read wallet passphrase from standard input as a single line. When +combined with \fB\-stdin\fR, the first line from standard input is used +for the wallet passphrase. +.HP +\fB\-version\fR +.IP +Print version and exit +.PP +Debugging/Testing options: +.PP +Chain selection options: +.HP +\fB\-chain=\fR +.IP +Use the chain (default: main). Allowed values: main, test, +testnet4, signet, regtest +.HP +\fB\-signet\fR +.IP +Use the signet chain. Equivalent to \fB\-chain\fR=\fI\,signet\/\fR. Note that the network +is defined by the \fB\-signetchallenge\fR parameter +.HP +\fB\-signetchallenge\fR +.IP +Blocks must satisfy the given script to be considered valid (only for +signet networks; defaults to the global default signet test +network challenge) +.HP +\fB\-signetseednode\fR +.IP +Specify a seed node for the signet network, in the hostname[:port] +format, e.g. sig.net:1234 (may be used multiple times to specify +multiple seed nodes; defaults to the global default signet test +network seed node(s)) +.HP +\fB\-testnet\fR +.IP +Use the testnet3 chain. Equivalent to \fB\-chain\fR=\fI\,test\/\fR. Support for testnet3 +is deprecated and will be removed in an upcoming release. +Consider moving to testnet4 now by using \fB\-testnet4\fR. +.HP +\fB\-testnet4\fR +.IP +Use the testnet4 chain. Equivalent to \fB\-chain\fR=\fI\,testnet4\/\fR. +.PP +CLI Commands: +.HP +\fB\-addrinfo\fR +.IP +Get the number of addresses known to the node, per network and total, +after filtering for quality and recency. The total number of +addresses known to the node may be higher. +.HP +\fB\-generate\fR +.IP +Generate blocks, equivalent to RPC getnewaddress followed by RPC +generatetoaddress. Optional positional integer arguments are +number of blocks to generate (default: 1) and maximum iterations +to try (default: 1000000), equivalent to RPC generatetoaddress +nblocks and maxtries arguments. Example: bitcoin\-cli \fB\-generate\fR 4 +1000 +.HP +\fB\-getinfo\fR +.IP +Get general information from the remote server. Note that unlike +server\-side RPC calls, the output of \fB\-getinfo\fR is the result of +multiple non\-atomic requests. Some entries in the output may +represent results from different states (e.g. wallet balance may +be as of a different block from the chain state reported) +.HP +\fB\-netinfo\fR +.IP +Get network peer connection information from the remote server. An +optional argument from 0 to 4 can be passed for different peers +listings (default: 0). If a non\-zero value is passed, an +additional "outonly" (or "o") argument can be passed to see +outbound peers only. Pass "help" (or "h") for detailed help +documentation. +.SH COPYRIGHT +Copyright (C) 2009-2025 The Bitcoin Core developers + +Please contribute if you find Bitcoin Core useful. Visit + for further information about the software. +The source code is available from . + +This is experimental software. +Distributed under the MIT software license, see the accompanying file COPYING +or +.SH "SEE ALSO" +bitcoind(1), bitcoin-cli(1), bitcoin-tx(1), bitcoin-wallet(1), bitcoin-util(1), bitcoin-qt(1) diff --git a/doc/man/bitcoin-qt.1 b/doc/man/bitcoin-qt.1 new file mode 100644 index 0000000000..7821b8fb44 --- /dev/null +++ b/doc/man/bitcoin-qt.1 @@ -0,0 +1,852 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH BITCOIN-QT "1" "September 2025" "bitcoin-qt v29.2.0rc1" "User Commands" +.SH NAME +bitcoin-qt \- manual page for bitcoin-qt v29.2.0rc1 +.SH SYNOPSIS +.B bitcoin-qt +[\fI\,options\/\fR] [\fI\,URI\/\fR] +.SH DESCRIPTION +Bitcoin Core version v29.2.0rc1 +.PP +The bitcoin\-qt application provides a graphical interface for interacting with Bitcoin Core. +.PP +It combines the core functionalities of bitcoind with a user\-friendly interface for wallet management, transaction history, and network statistics. +.PP +It is suitable for users who prefer a graphical over a command\-line interface. +.PP +You can optionally specify a payment [URI], in e.g. the BIP21 URI format. +.SH OPTIONS +.HP +\fB\-alertnotify=\fR +.IP +Execute command when an alert is raised (%s in cmd is replaced by +message) +.HP +\fB\-allowignoredconf\fR +.IP +For backwards compatibility, treat an unused bitcoin.conf file in the +datadir as a warning, not an error. +.HP +\fB\-assumevalid=\fR +.IP +If this block is in the chain assume that it and its ancestors are valid +and potentially skip their script verification (0 to verify all, +default: +00000000000000000001b658dd1120e82e66d2790811f89ede9742ada3ed6d77, +testnet3: +00000000000003fc7967410ba2d0a8a8d50daedc318d43e8baf1a9782c236a57, +testnet4: +0000000000003ed4f08dbdf6f7d6b271a6bcffce25675cb40aa9fa43179a89f3, +signet: +000000895a110f46e59eb82bbc5bfb67fa314656009c295509c21b4999f5180a) +.HP +\fB\-blockfilterindex=\fR +.IP +Maintain an index of compact filters by block (default: 0, values: +basic). If is not supplied or if = 1, indexes for +all known types are enabled. +.HP +\fB\-blocknotify=\fR +.IP +Execute command when the best block changes (%s in cmd is replaced by +block hash) +.HP +\fB\-blockreconstructionextratxn=\fR +.IP +Extra transactions to keep in memory for compact block reconstructions +(default: 100) +.HP +\fB\-blocksdir=\fR +.IP +Specify directory to hold blocks subdirectory for *.dat files (default: +) +.HP +\fB\-blocksonly\fR +.IP +Whether to reject transactions from network peers. Disables automatic +broadcast and rebroadcast of transactions, unless the source peer +has the 'forcerelay' permission. RPC transactions are not +affected. (default: 0) +.HP +\fB\-blocksxor\fR +.IP +Whether an XOR\-key applies to blocksdir *.dat files. The created XOR\-key +will be zeros for an existing blocksdir or when `\-blocksxor=0` is +set, and random for a freshly initialized blocksdir. (default: 1) +.HP +\fB\-coinstatsindex\fR +.IP +Maintain coinstats index used by the gettxoutsetinfo RPC (default: 0) +.HP +\fB\-conf=\fR +.IP +Specify path to read\-only configuration file. Relative paths will be +prefixed by datadir location (only useable from command line, not +configuration file) (default: bitcoin.conf) +.HP +\fB\-daemon\fR +.IP +Run in the background as a daemon and accept commands (default: 0) +.HP +\fB\-daemonwait\fR +.IP +Wait for initialization to be finished before exiting. This implies +\fB\-daemon\fR (default: 0) +.HP +\fB\-datadir=\fR +.IP +Specify data directory +.HP +\fB\-dbcache=\fR +.IP +Maximum database cache size MiB (minimum 4, default: 450). Make sure +you have enough RAM. In addition, unused memory allocated to the +mempool is shared with this cache (see \fB\-maxmempool\fR). +.HP +\fB\-debuglogfile=\fR +.IP +Specify location of debug log file (default: debug.log). Relative paths +will be prefixed by a net\-specific datadir location. Pass +\fB\-nodebuglogfile\fR to disable writing the log to a file. +.HP +\fB\-help\fR +.IP +Print this help message and exit (also \fB\-h\fR or \-?) +.HP +\fB\-includeconf=\fR +.IP +Specify additional configuration file, relative to the \fB\-datadir\fR path +(only useable from configuration file, not command line) +.HP +\fB\-loadblock=\fR +.IP +Imports blocks from external file on startup +.HP +\fB\-maxmempool=\fR +.IP +Keep the transaction memory pool below megabytes (default: 300) +.HP +\fB\-maxorphantx=\fR +.IP +Keep at most unconnectable transactions in memory (default: 100) +.HP +\fB\-mempoolexpiry=\fR +.IP +Do not keep transactions in the mempool longer than hours (default: +336) +.HP +\fB\-par=\fR +.IP +Set the number of script verification threads (0 = auto, up to 15, <0 = +leave that many cores free, default: 0) +.HP +\fB\-persistmempool\fR +.IP +Whether to save the mempool on shutdown and load on restart (default: 1) +.HP +\fB\-persistmempoolv1\fR +.IP +Whether a mempool.dat file created by \fB\-persistmempool\fR or the savemempool +RPC will be written in the legacy format (version 1) or the +current format (version 2). This temporary option will be removed +in the future. (default: 0) +.HP +\fB\-pid=\fR +.IP +Specify pid file. Relative paths will be prefixed by a net\-specific +datadir location. (default: bitcoind.pid) +.HP +\fB\-prune=\fR +.IP +Reduce storage requirements by enabling pruning (deleting) of old +blocks. This allows the pruneblockchain RPC to be called to +delete specific blocks and enables automatic pruning of old +blocks if a target size in MiB is provided. This mode is +incompatible with \fB\-txindex\fR. Warning: Reverting this setting +requires re\-downloading the entire blockchain. (default: 0 = +disable pruning blocks, 1 = allow manual pruning via RPC, >=550 = +automatically prune block files to stay under the specified +target size in MiB) +.HP +\fB\-reindex\fR +.IP +If enabled, wipe chain state and block index, and rebuild them from +blk*.dat files on disk. Also wipe and rebuild other optional +indexes that are active. If an assumeutxo snapshot was loaded, +its chainstate will be wiped as well. The snapshot can then be +reloaded via RPC. +.HP +\fB\-reindex\-chainstate\fR +.IP +If enabled, wipe chain state, and rebuild it from blk*.dat files on +disk. If an assumeutxo snapshot was loaded, its chainstate will +be wiped as well. The snapshot can then be reloaded via RPC. +.HP +\fB\-settings=\fR +.IP +Specify path to dynamic settings data file. Can be disabled with +\fB\-nosettings\fR. File is written at runtime and not meant to be +edited by users (use bitcoin.conf instead for custom settings). +Relative paths will be prefixed by datadir location. (default: +settings.json) +.HP +\fB\-shutdownnotify=\fR +.IP +Execute command immediately before beginning shutdown. The need for +shutdown may be urgent, so be careful not to delay it long (if +the command doesn't require interaction with the server, consider +having it fork into the background). +.HP +\fB\-startupnotify=\fR +.IP +Execute command on startup. +.HP +\fB\-txindex\fR +.IP +Maintain a full transaction index, used by the getrawtransaction rpc +call (default: 0) +.HP +\fB\-version\fR +.IP +Print version and exit +.PP +Connection options: +.HP +\fB\-addnode=\fR +.IP +Add a node to connect to and attempt to keep the connection open (see +the addnode RPC help for more info). This option can be specified +multiple times to add multiple nodes; connections are limited to +8 at a time and are counted separately from the \fB\-maxconnections\fR +limit. +.HP +\fB\-asmap=\fR +.IP +Specify asn mapping used for bucketing of the peers (default: +ip_asn.map). Relative paths will be prefixed by the net\-specific +datadir location. +.HP +\fB\-bantime=\fR +.IP +Default duration (in seconds) of manually configured bans (default: +86400) +.HP +\fB\-bind=\fR[:][=onion] +.IP +Bind to given address and always listen on it (default: 0.0.0.0). Use +[host]:port notation for IPv6. Append =onion to tag any incoming +connections to that address and port as incoming Tor connections +(default: 127.0.0.1:8334=onion, testnet3: 127.0.0.1:18334=onion, +testnet4: 127.0.0.1:48334=onion, signet: 127.0.0.1:38334=onion, +regtest: 127.0.0.1:18445=onion) +.HP +\fB\-cjdnsreachable\fR +.IP +If set, then this host is configured for CJDNS (connecting to fc00::/8 +addresses would lead us to the CJDNS network, see doc/cjdns.md) +(default: 0) +.HP +\fB\-connect=\fR +.IP +Connect only to the specified node; \fB\-noconnect\fR disables automatic +connections (the rules for this peer are the same as for +\fB\-addnode\fR). This option can be specified multiple times to connect +to multiple nodes. +.HP +\fB\-discover\fR +.IP +Discover own IP addresses (default: 1 when listening and no \fB\-externalip\fR +or \fB\-proxy\fR) +.HP +\fB\-dns\fR +.IP +Allow DNS lookups for \fB\-addnode\fR, \fB\-seednode\fR and \fB\-connect\fR (default: 1) +.HP +\fB\-dnsseed\fR +.IP +Query for peer addresses via DNS lookup, if low on addresses (default: 1 +unless \fB\-connect\fR used or \fB\-maxconnections\fR=\fI\,0\/\fR) +.HP +\fB\-externalip=\fR +.IP +Specify your own public address +.HP +\fB\-fixedseeds\fR +.IP +Allow fixed seeds if DNS seeds don't provide peers (default: 1) +.HP +\fB\-forcednsseed\fR +.IP +Always query for peer addresses via DNS lookup (default: 0) +.HP +\fB\-i2pacceptincoming\fR +.IP +Whether to accept inbound I2P connections (default: 1). Ignored if +\fB\-i2psam\fR is not set. Listening for inbound I2P connections is done +through the SAM proxy, not by binding to a local address and +port. +.HP +\fB\-i2psam=\fR +.IP +I2P SAM proxy to reach I2P peers and accept I2P connections (default: +none) +.HP +\fB\-listen\fR +.IP +Accept connections from outside (default: 1 if no \fB\-proxy\fR, \fB\-connect\fR or +\fB\-maxconnections\fR=\fI\,0\/\fR) +.HP +\fB\-listenonion\fR +.IP +Automatically create Tor onion service (default: 1) +.HP +\fB\-maxconnections=\fR +.IP +Maintain at most automatic connections to peers (default: 125). This +limit does not apply to connections manually added via \fB\-addnode\fR +or the addnode RPC, which have a separate limit of 8. +.HP +\fB\-maxreceivebuffer=\fR +.IP +Maximum per\-connection receive buffer, *1000 bytes (default: 5000) +.HP +\fB\-maxsendbuffer=\fR +.IP +Maximum per\-connection memory usage for the send buffer, *1000 bytes +(default: 1000) +.HP +\fB\-maxuploadtarget=\fR +.IP +Tries to keep outbound traffic under the given target per 24h. Limit +does not apply to peers with 'download' permission or blocks +created within past week. 0 = no limit (default: 0M). Optional +suffix units [k|K|m|M|g|G|t|T] (default: M). Lowercase is 1000 +base while uppercase is 1024 base +.HP +\fB\-natpmp\fR +.IP +Use PCP or NAT\-PMP to map the listening port (default: 0) +.HP +\fB\-networkactive\fR +.IP +Enable all P2P network activity (default: 1). Can be changed by the +setnetworkactive RPC command +.HP +\fB\-onion=\fR +.IP +Use separate SOCKS5 proxy to reach peers via Tor onion services, set +\fB\-noonion\fR to disable (default: \fB\-proxy\fR). May be a local file path +prefixed with 'unix:'. +.HP +\fB\-onlynet=\fR +.IP +Make automatic outbound connections only to network (ipv4, ipv6, +onion, i2p, cjdns). Inbound and manual connections are not +affected by this option. It can be specified multiple times to +allow multiple networks. +.HP +\fB\-peerblockfilters\fR +.IP +Serve compact block filters to peers per BIP 157 (default: 0) +.HP +\fB\-peerbloomfilters\fR +.IP +Support filtering of blocks and transaction with bloom filters (default: +0) +.HP +\fB\-port=\fR +.IP +Listen for connections on (default: 8333, testnet3: 18333, +testnet4: 48333, signet: 38333, regtest: 18444). Not relevant for +I2P (see doc/i2p.md). If set to a value x, the default onion +listening port will be set to x+1. +.HP +\fB\-proxy=\fR +.IP +Connect through SOCKS5 proxy, set \fB\-noproxy\fR to disable (default: +disabled). May be a local file path prefixed with 'unix:' if the +proxy supports it. +.HP +\fB\-proxyrandomize\fR +.IP +Randomize credentials for every proxy connection. This enables Tor +stream isolation (default: 1) +.HP +\fB\-seednode=\fR +.IP +Connect to a node to retrieve peer addresses, and disconnect. This +option can be specified multiple times to connect to multiple +nodes. During startup, seednodes will be tried before dnsseeds. +.HP +\fB\-timeout=\fR +.IP +Specify socket connection timeout in milliseconds. If an initial attempt +to connect is unsuccessful after this amount of time, drop it +(minimum: 1, default: 5000) +.HP +\fB\-torcontrol=\fR: +.IP +Tor control host and port to use if onion listening enabled (default: +127.0.0.1:9051). If no port is specified, the default port of +9051 will be used. +.HP +\fB\-torpassword=\fR +.IP +Tor control port password (default: empty) +.HP +\fB\-v2transport\fR +.IP +Support v2 transport (default: 1) +.HP +\fB\-whitebind=\fR<[permissions@]addr> +.IP +Bind to the given address and add permission flags to the peers +connecting to it. Use [host]:port notation for IPv6. Allowed +permissions: bloomfilter (allow requesting BIP37 filtered blocks +and transactions), noban (do not ban for misbehavior; implies +download), forcerelay (relay transactions that are already in the +mempool; implies relay), relay (relay even in \fB\-blocksonly\fR mode, +and unlimited transaction announcements), mempool (allow +requesting BIP35 mempool contents), download (allow getheaders +during IBD, no disconnect after maxuploadtarget limit), addr +(responses to GETADDR avoid hitting the cache and contain random +records with the most up\-to\-date info). Specify multiple +permissions separated by commas (default: +download,noban,mempool,relay). Can be specified multiple times. +.HP +\fB\-whitelist=\fR<[permissions@]IP address or network> +.IP +Add permission flags to the peers using the given IP address (e.g. +1.2.3.4) or CIDR\-notated network (e.g. 1.2.3.0/24). Uses the same +permissions as \fB\-whitebind\fR. Additional flags "in" and "out" +control whether permissions apply to incoming connections and/or +manual (default: incoming only). Can be specified multiple times. +.PP +Wallet options: +.HP +\fB\-addresstype\fR +.IP +What type of addresses to use ("legacy", "p2sh\-segwit", "bech32", or +"bech32m", default: "bech32") +.HP +\fB\-avoidpartialspends\fR +.IP +Group outputs by address, selecting many (possibly all) or none, instead +of selecting on a per\-output basis. Privacy is improved as +addresses are mostly swept with fewer transactions and outputs +are aggregated in clean change addresses. It may result in higher +fees due to less optimal coin selection caused by this added +limitation and possibly a larger\-than\-necessary number of inputs +being used. Always enabled for wallets with "avoid_reuse" +enabled, otherwise default: 0. +.HP +\fB\-changetype\fR +.IP +What type of change to use ("legacy", "p2sh\-segwit", "bech32", or +"bech32m"). Default is "legacy" when \fB\-addresstype\fR=\fI\,legacy\/\fR, else it +is an implementation detail. +.HP +\fB\-consolidatefeerate=\fR +.IP +The maximum feerate (in BTC/kvB) at which transaction building may use +more inputs than strictly necessary so that the wallet's UTXO +pool can be reduced (default: 0.0001). +.HP +\fB\-disablewallet\fR +.IP +Do not load the wallet and disable wallet RPC calls +.HP +\fB\-discardfee=\fR +.IP +The fee rate (in BTC/kvB) that indicates your tolerance for discarding +change by adding it to the fee (default: 0.0001). Note: An output +is discarded if it is dust at this rate, but we will always +discard up to the dust relay fee and a discard fee above that is +limited by the fee estimate for the longest target +.HP +\fB\-fallbackfee=\fR +.IP +A fee rate (in BTC/kvB) that will be used when fee estimation has +insufficient data. 0 to entirely disable the fallbackfee feature. +(default: 0.00) +.HP +\fB\-keypool=\fR +.IP +Set key pool size to (default: 1000). Warning: Smaller sizes may +increase the risk of losing funds when restoring from an old +backup, if none of the addresses in the original keypool have +been used. +.HP +\fB\-maxapsfee=\fR +.IP +Spend up to this amount in additional (absolute) fees (in BTC) if it +allows the use of partial spend avoidance (default: 0.00) +.HP +\fB\-mintxfee=\fR +.IP +Fee rates (in BTC/kvB) smaller than this are considered zero fee for +transaction creation (default: 0.00001) +.HP +\fB\-paytxfee=\fR +.IP +Fee rate (in BTC/kvB) to add to transactions you send (default: 0.00) +.HP +\fB\-signer=\fR +.IP +External signing tool, see doc/external\-signer.md +.HP +\fB\-spendzeroconfchange\fR +.IP +Spend unconfirmed change when sending transactions (default: 1) +.HP +\fB\-txconfirmtarget=\fR +.IP +If paytxfee is not set, include enough fee so transactions begin +confirmation on average within n blocks (default: 6) +.HP +\fB\-wallet=\fR +.IP +Specify wallet path to load at startup. Can be used multiple times to +load multiple wallets. Path is to a directory containing wallet +data and log files. If the path is not absolute, it is +interpreted relative to . This only loads existing +wallets and does not create new ones. For backwards compatibility +this also accepts names of existing top\-level data files in +. +.HP +\fB\-walletbroadcast\fR +.IP +Make the wallet broadcast transactions (default: 1) +.HP +\fB\-walletdir=\fR +.IP +Specify directory to hold wallets (default: /wallets if it +exists, otherwise ) +.HP +\fB\-walletnotify=\fR +.IP +Execute command when a wallet transaction changes. %s in cmd is replaced +by TxID, %w is replaced by wallet name, %b is replaced by the +hash of the block including the transaction (set to 'unconfirmed' +if the transaction is not included) and %h is replaced by the +block height (\fB\-1\fR if not included). %w is not currently +implemented on windows. On systems where %w is supported, it +should NOT be quoted because this would break shell escaping used +to invoke the command. +.HP +\fB\-walletrbf\fR +.IP +Send transactions with full\-RBF opt\-in enabled (RPC only, default: 1) +.PP +ZeroMQ notification options: +.HP +\fB\-zmqpubhashblock=\fR
+.IP +Enable publish hash block in
+.HP +\fB\-zmqpubhashblockhwm=\fR +.IP +Set publish hash block outbound message high water mark (default: 1000) +.HP +\fB\-zmqpubhashtx=\fR
+.IP +Enable publish hash transaction in
+.HP +\fB\-zmqpubhashtxhwm=\fR +.IP +Set publish hash transaction outbound message high water mark (default: +1000) +.HP +\fB\-zmqpubrawblock=\fR
+.IP +Enable publish raw block in
+.HP +\fB\-zmqpubrawblockhwm=\fR +.IP +Set publish raw block outbound message high water mark (default: 1000) +.HP +\fB\-zmqpubrawtx=\fR
+.IP +Enable publish raw transaction in
+.HP +\fB\-zmqpubrawtxhwm=\fR +.IP +Set publish raw transaction outbound message high water mark (default: +1000) +.HP +\fB\-zmqpubsequence=\fR
+.IP +Enable publish hash block and tx sequence in
+.HP +\fB\-zmqpubsequencehwm=\fR +.IP +Set publish hash sequence message high water mark (default: 1000) +.PP +Debugging/Testing options: +.HP +\fB\-debug=\fR +.IP +Output debug and trace logging (default: \fB\-nodebug\fR, supplying +is optional). If is not supplied or if is 1 +or "all", output all debug logging. If is 0 or "none", +any other categories are ignored. Other valid values for + are: addrman, bench, blockstorage, cmpctblock, coindb, +estimatefee, http, i2p, ipc, leveldb, libevent, mempool, +mempoolrej, net, proxy, prune, qt, rand, reindex, rpc, scan, +selectcoins, tor, txpackages, txreconciliation, validation, +walletdb, zmq. This option can be specified multiple times to +output multiple categories. +.HP +\fB\-debugexclude=\fR +.IP +Exclude debug and trace logging for a category. Can be used in +conjunction with \fB\-debug\fR=\fI\,1\/\fR to output debug and trace logging for +all categories except the specified category. This option can be +specified multiple times to exclude multiple categories. This +takes priority over "\-debug" +.HP +\fB\-help\-debug\fR +.IP +Print help message with debugging options and exit +.HP +\fB\-logips\fR +.IP +Include IP addresses in debug output (default: 0) +.HP +\fB\-loglevelalways\fR +.IP +Always prepend a category and level (default: 0) +.HP +\fB\-logsourcelocations\fR +.IP +Prepend debug output with name of the originating source location +(source file, line number and function name) (default: 0) +.HP +\fB\-logthreadnames\fR +.IP +Prepend debug output with name of the originating thread (default: 0) +.HP +\fB\-logtimestamps\fR +.IP +Prepend debug output with timestamp (default: 1) +.HP +\fB\-maxtxfee=\fR +.IP +Maximum total fees (in BTC) to use in a single wallet transaction; +setting this too low may abort large transactions (default: 0.10) +.HP +\fB\-printtoconsole\fR +.IP +Send trace/debug info to console (default: 1 when no \fB\-daemon\fR. To disable +logging to file, set \fB\-nodebuglogfile\fR) +.HP +\fB\-shrinkdebugfile\fR +.IP +Shrink debug.log file on client startup (default: 1 when no \fB\-debug\fR) +.HP +\fB\-uacomment=\fR +.IP +Append comment to the user agent string +.PP +Chain selection options: +.HP +\fB\-chain=\fR +.IP +Use the chain (default: main). Allowed values: main, test, +testnet4, signet, regtest +.HP +\fB\-signet\fR +.IP +Use the signet chain. Equivalent to \fB\-chain\fR=\fI\,signet\/\fR. Note that the network +is defined by the \fB\-signetchallenge\fR parameter +.HP +\fB\-signetchallenge\fR +.IP +Blocks must satisfy the given script to be considered valid (only for +signet networks; defaults to the global default signet test +network challenge) +.HP +\fB\-signetseednode\fR +.IP +Specify a seed node for the signet network, in the hostname[:port] +format, e.g. sig.net:1234 (may be used multiple times to specify +multiple seed nodes; defaults to the global default signet test +network seed node(s)) +.HP +\fB\-testnet\fR +.IP +Use the testnet3 chain. Equivalent to \fB\-chain\fR=\fI\,test\/\fR. Support for testnet3 +is deprecated and will be removed in an upcoming release. +Consider moving to testnet4 now by using \fB\-testnet4\fR. +.HP +\fB\-testnet4\fR +.IP +Use the testnet4 chain. Equivalent to \fB\-chain\fR=\fI\,testnet4\/\fR. +.PP +Node relay options: +.HP +\fB\-bytespersigop\fR +.IP +Equivalent bytes per sigop in transactions for relay and mining +(default: 20) +.HP +\fB\-datacarrier\fR +.IP +Relay and mine data carrier transactions (default: 1) +.HP +\fB\-datacarriersize\fR +.IP +Relay and mine transactions whose data\-carrying raw scriptPubKey is of +this size or less (default: 83) +.HP +\fB\-minrelaytxfee=\fR +.IP +Fees (in BTC/kvB) smaller than this are considered zero fee for +relaying, mining and transaction creation (default: 0.000001) +.HP +\fB\-permitbaremultisig\fR +.IP +Relay transactions creating non\-P2SH multisig outputs (default: 1) +.HP +\fB\-whitelistforcerelay\fR +.IP +Add 'forcerelay' permission to whitelisted peers with default +permissions. This will relay transactions even if the +transactions were already in the mempool. (default: 0) +.HP +\fB\-whitelistrelay\fR +.IP +Add 'relay' permission to whitelisted peers with default permissions. +This will accept relayed transactions even when not relaying +transactions (default: 1) +.PP +Block creation options: +.HP +\fB\-blockmaxweight=\fR +.IP +Set maximum BIP141 block weight (default: 4000000) +.HP +\fB\-blockmintxfee=\fR +.IP +Set lowest fee rate (in BTC/kvB) for transactions to be included in +block creation. (default: 0.00000001) +.HP +\fB\-blockreservedweight=\fR +.IP +Reserve space for the fixed\-size block header plus the largest coinbase +transaction the mining software may add to the block. (default: +8000). +.PP +RPC server options: +.HP +\fB\-rest\fR +.IP +Accept public REST requests (default: 0) +.HP +\fB\-rpcallowip=\fR +.IP +Allow JSON\-RPC connections from specified source. Valid values for +are a single IP (e.g. 1.2.3.4), a network/netmask (e.g. +1.2.3.4/255.255.255.0), a network/CIDR (e.g. 1.2.3.4/24), all +ipv4 (0.0.0.0/0), or all ipv6 (::/0). This option can be +specified multiple times +.HP +\fB\-rpcauth=\fR +.IP +Username and HMAC\-SHA\-256 hashed password for JSON\-RPC connections. The +field comes in the format: :$. A +canonical python script is included in share/rpcauth. The client +then connects normally using the +rpcuser=/rpcpassword= pair of arguments. This +option can be specified multiple times +.HP +\fB\-rpcbind=\fR[:port] +.IP +Bind to given address to listen for JSON\-RPC connections. Do not expose +the RPC server to untrusted networks such as the public internet! +This option is ignored unless \fB\-rpcallowip\fR is also passed. Port is +optional and overrides \fB\-rpcport\fR. Use [host]:port notation for +IPv6. This option can be specified multiple times (default: +127.0.0.1 and ::1 i.e., localhost) +.HP +\fB\-rpccookiefile=\fR +.IP +Location of the auth cookie. Relative paths will be prefixed by a +net\-specific datadir location. (default: data dir) +.HP +\fB\-rpccookieperms=\fR +.IP +Set permissions on the RPC auth cookie file so that it is readable by +[owner|group|all] (default: owner [via umask 0077]) +.HP +\fB\-rpcpassword=\fR +.IP +Password for JSON\-RPC connections +.HP +\fB\-rpcport=\fR +.IP +Listen for JSON\-RPC connections on (default: 8332, testnet3: +18332, testnet4: 48332, signet: 38332, regtest: 18443) +.HP +\fB\-rpcthreads=\fR +.IP +Set the number of threads to service RPC calls (default: 16) +.HP +\fB\-rpcuser=\fR +.IP +Username for JSON\-RPC connections +.HP +\fB\-rpcwhitelist=\fR +.IP +Set a whitelist to filter incoming RPC calls for a specific user. The +field comes in the format: :,,...,. If multiple whitelists are set for a given user, +they are set\-intersected. See \fB\-rpcwhitelistdefault\fR documentation +for information on default whitelist behavior. +.HP +\fB\-rpcwhitelistdefault\fR +.IP +Sets default behavior for rpc whitelisting. Unless rpcwhitelistdefault +is set to 0, if any \fB\-rpcwhitelist\fR is set, the rpc server acts as +if all rpc users are subject to empty\-unless\-otherwise\-specified +whitelists. If rpcwhitelistdefault is set to 1 and no +\fB\-rpcwhitelist\fR is set, rpc server acts as if all rpc users are +subject to empty whitelists. +.HP +\fB\-server\fR +.IP +Accept command line and JSON\-RPC commands +.PP +UI Options: +.HP +\fB\-choosedatadir\fR +.IP +Choose data directory on startup (default: 0) +.HP +\fB\-lang=\fR +.IP +Set language, for example "de_DE" (default: system locale) +.HP +\fB\-min\fR +.IP +Start minimized +.HP +\fB\-resetguisettings\fR +.IP +Reset all settings changed in the GUI +.HP +\fB\-splash\fR +.IP +Show splash screen on startup (default: 1) +.SH COPYRIGHT +Copyright (C) 2009-2025 The Bitcoin Core developers + +Please contribute if you find Bitcoin Core useful. Visit + for further information about the software. +The source code is available from . + +This is experimental software. +Distributed under the MIT software license, see the accompanying file COPYING +or +.SH "SEE ALSO" +bitcoind(1), bitcoin-cli(1), bitcoin-tx(1), bitcoin-wallet(1), bitcoin-util(1), bitcoin-qt(1) diff --git a/doc/man/bitcoin-tx.1 b/doc/man/bitcoin-tx.1 new file mode 100644 index 0000000000..a14a6be602 --- /dev/null +++ b/doc/man/bitcoin-tx.1 @@ -0,0 +1,159 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH BITCOIN-TX "1" "September 2025" "bitcoin-tx v29.2.0rc1" "User Commands" +.SH NAME +bitcoin-tx \- manual page for bitcoin-tx v29.2.0rc1 +.SH SYNOPSIS +.B bitcoin-tx +[\fI\,options\/\fR] \fI\, \/\fR[\fI\,commands\/\fR] +.br +.B bitcoin-tx +[\fI\,options\/\fR] \fI\,-create \/\fR[\fI\,commands\/\fR] +.SH DESCRIPTION +Bitcoin Core bitcoin\-tx utility version v29.2.0rc1 +.PP +The bitcoin\-tx tool is used for creating and modifying bitcoin transactions. +.PP +bitcoin\-tx can be used with " [commands]" to update a hex\-encoded bitcoin transaction, or with "\-create [commands]" to create a hex\-encoded bitcoin transaction. +.SH OPTIONS +.HP +\fB\-create\fR +.IP +Create new, empty TX. +.HP +\fB\-help\fR +.IP +Print this help message and exit (also \fB\-h\fR or \-?) +.HP +\fB\-json\fR +.IP +Select JSON output +.HP +\fB\-txid\fR +.IP +Output only the hex\-encoded transaction id of the resultant transaction. +.HP +\fB\-version\fR +.IP +Print version and exit +.PP +Debugging/Testing options: +.PP +Chain selection options: +.HP +\fB\-chain=\fR +.IP +Use the chain (default: main). Allowed values: main, test, +testnet4, signet, regtest +.HP +\fB\-signet\fR +.IP +Use the signet chain. Equivalent to \fB\-chain\fR=\fI\,signet\/\fR. Note that the network +is defined by the \fB\-signetchallenge\fR parameter +.HP +\fB\-signetchallenge\fR +.IP +Blocks must satisfy the given script to be considered valid (only for +signet networks; defaults to the global default signet test +network challenge) +.HP +\fB\-signetseednode\fR +.IP +Specify a seed node for the signet network, in the hostname[:port] +format, e.g. sig.net:1234 (may be used multiple times to specify +multiple seed nodes; defaults to the global default signet test +network seed node(s)) +.HP +\fB\-testnet\fR +.IP +Use the testnet3 chain. Equivalent to \fB\-chain\fR=\fI\,test\/\fR. Support for testnet3 +is deprecated and will be removed in an upcoming release. +Consider moving to testnet4 now by using \fB\-testnet4\fR. +.HP +\fB\-testnet4\fR +.IP +Use the testnet4 chain. Equivalent to \fB\-chain\fR=\fI\,testnet4\/\fR. +.PP +Commands: +.IP +delin=N +.IP +Delete input N from TX +.IP +delout=N +.IP +Delete output N from TX +.IP +in=TXID:VOUT(:SEQUENCE_NUMBER) +.IP +Add input to TX +.IP +locktime=N +.IP +Set TX lock time to N +.IP +nversion=N +.IP +Set TX version to N +.IP +outaddr=VALUE:ADDRESS +.IP +Add address\-based output to TX +.IP +outdata=[VALUE:]DATA +.IP +Add data\-based output to TX +.IP +outmultisig=VALUE:REQUIRED:PUBKEYS:PUBKEY1:PUBKEY2:....[:FLAGS] +.IP +Add Pay To n\-of\-m Multi\-sig output to TX. n = REQUIRED, m = PUBKEYS. +Optionally add the "W" flag to produce a +pay\-to\-witness\-script\-hash output. Optionally add the "S" flag to +wrap the output in a pay\-to\-script\-hash. +.IP +outpubkey=VALUE:PUBKEY[:FLAGS] +.IP +Add pay\-to\-pubkey output to TX. Optionally add the "W" flag to produce a +pay\-to\-witness\-pubkey\-hash output. Optionally add the "S" flag to +wrap the output in a pay\-to\-script\-hash. +.IP +outscript=VALUE:SCRIPT[:FLAGS] +.IP +Add raw script output to TX. Optionally add the "W" flag to produce a +pay\-to\-witness\-script\-hash output. Optionally add the "S" flag to +wrap the output in a pay\-to\-script\-hash. +.IP +replaceable(=N) +.IP +Sets Replace\-By\-Fee (RBF) opt\-in sequence number for input N. If N is +not provided, the command attempts to opt\-in all available inputs +for RBF. If the transaction has no inputs, this option is +ignored. +.IP +sign=SIGHASH\-FLAGS +.IP +Add zero or more signatures to transaction. This command requires JSON +registers:prevtxs=JSON object, privatekeys=JSON object. See +signrawtransactionwithkey docs for format of sighash flags, JSON +objects. +.PP +Register Commands: +.IP +load=NAME:FILENAME +.IP +Load JSON file FILENAME into register NAME +.IP +set=NAME:JSON\-STRING +.IP +Set register NAME to given JSON\-STRING +.SH COPYRIGHT +Copyright (C) 2009-2025 The Bitcoin Core developers + +Please contribute if you find Bitcoin Core useful. Visit + for further information about the software. +The source code is available from . + +This is experimental software. +Distributed under the MIT software license, see the accompanying file COPYING +or +.SH "SEE ALSO" +bitcoind(1), bitcoin-cli(1), bitcoin-tx(1), bitcoin-wallet(1), bitcoin-util(1), bitcoin-qt(1) diff --git a/doc/man/bitcoin-util.1 b/doc/man/bitcoin-util.1 new file mode 100644 index 0000000000..e0cc27e2d7 --- /dev/null +++ b/doc/man/bitcoin-util.1 @@ -0,0 +1,78 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH BITCOIN-UTIL "1" "September 2025" "bitcoin-util v29.2.0rc1" "User Commands" +.SH NAME +bitcoin-util \- manual page for bitcoin-util v29.2.0rc1 +.SH SYNOPSIS +.B bitcoin-util +[\fI\,options\/\fR] [\fI\,command\/\fR] +.br +.B bitcoin-util +[\fI\,options\/\fR] \fI\,grind \/\fR +.SH DESCRIPTION +Bitcoin Core bitcoin\-util utility version v29.2.0rc1 +.PP +The bitcoin\-util tool provides bitcoin related functionality that does not rely on the ability to access a running node. Available [commands] are listed below. +.SH OPTIONS +.HP +\fB\-help\fR +.IP +Print this help message and exit (also \fB\-h\fR or \-?) +.HP +\fB\-version\fR +.IP +Print version and exit +.PP +Debugging/Testing options: +.PP +Chain selection options: +.HP +\fB\-chain=\fR +.IP +Use the chain (default: main). Allowed values: main, test, +testnet4, signet, regtest +.HP +\fB\-signet\fR +.IP +Use the signet chain. Equivalent to \fB\-chain\fR=\fI\,signet\/\fR. Note that the network +is defined by the \fB\-signetchallenge\fR parameter +.HP +\fB\-signetchallenge\fR +.IP +Blocks must satisfy the given script to be considered valid (only for +signet networks; defaults to the global default signet test +network challenge) +.HP +\fB\-signetseednode\fR +.IP +Specify a seed node for the signet network, in the hostname[:port] +format, e.g. sig.net:1234 (may be used multiple times to specify +multiple seed nodes; defaults to the global default signet test +network seed node(s)) +.HP +\fB\-testnet\fR +.IP +Use the testnet3 chain. Equivalent to \fB\-chain\fR=\fI\,test\/\fR. Support for testnet3 +is deprecated and will be removed in an upcoming release. +Consider moving to testnet4 now by using \fB\-testnet4\fR. +.HP +\fB\-testnet4\fR +.IP +Use the testnet4 chain. Equivalent to \fB\-chain\fR=\fI\,testnet4\/\fR. +.PP +Commands: +.IP +grind +.IP +Perform proof of work on hex header string +.SH COPYRIGHT +Copyright (C) 2009-2025 The Bitcoin Core developers + +Please contribute if you find Bitcoin Core useful. Visit + for further information about the software. +The source code is available from . + +This is experimental software. +Distributed under the MIT software license, see the accompanying file COPYING +or +.SH "SEE ALSO" +bitcoind(1), bitcoin-cli(1), bitcoin-tx(1), bitcoin-wallet(1), bitcoin-util(1), bitcoin-qt(1) diff --git a/doc/man/bitcoin-wallet.1 b/doc/man/bitcoin-wallet.1 new file mode 100644 index 0000000000..58bbf2715b --- /dev/null +++ b/doc/man/bitcoin-wallet.1 @@ -0,0 +1,136 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH BITCOIN-WALLET "1" "September 2025" "bitcoin-wallet v29.2.0rc1" "User Commands" +.SH NAME +bitcoin-wallet \- manual page for bitcoin-wallet v29.2.0rc1 +.SH SYNOPSIS +.B bitcoin-wallet +[\fI\,options\/\fR] \fI\,\/\fR +.SH DESCRIPTION +Bitcoin Core bitcoin\-wallet utility version v29.2.0rc1 +.PP +bitcoin\-wallet is an offline tool for creating and interacting with Bitcoin Core wallet files. +.PP +By default bitcoin\-wallet will act on wallets in the default mainnet wallet directory in the datadir. +.PP +To change the target wallet, use the \fB\-datadir\fR, \fB\-wallet\fR and (test)chain selection arguments. +.SH OPTIONS +.HP +\fB\-datadir=\fR +.IP +Specify data directory +.HP +\fB\-descriptors\fR +.IP +Create descriptors wallet. Only for 'create' +.HP +\fB\-dumpfile=\fR +.IP +When used with 'dump', writes out the records to this file. When used +with 'createfromdump', loads the records into a new wallet. +.HP +\fB\-format=\fR +.IP +The format of the wallet file to create. Either "bdb" or "sqlite". Only +used with 'createfromdump' +.HP +\fB\-help\fR +.IP +Print this help message and exit (also \fB\-h\fR or \-?) +.HP +\fB\-legacy\fR +.IP +Create legacy wallet. Only for 'create' +.HP +\fB\-version\fR +.IP +Print version and exit +.HP +\fB\-wallet=\fR +.IP +Specify wallet name +.PP +Debugging/Testing options: +.HP +\fB\-debug=\fR +.IP +Output debugging information (default: 0). +.HP +\fB\-printtoconsole\fR +.IP +Send trace/debug info to console (default: 1 when no \fB\-debug\fR is true, 0 +otherwise). +.HP +\fB\-withinternalbdb\fR +.IP +Use the internal Berkeley DB parser when dumping a Berkeley DB wallet +file (default: false) +.PP +Chain selection options: +.HP +\fB\-chain=\fR +.IP +Use the chain (default: main). Allowed values: main, test, +testnet4, signet, regtest +.HP +\fB\-signet\fR +.IP +Use the signet chain. Equivalent to \fB\-chain\fR=\fI\,signet\/\fR. Note that the network +is defined by the \fB\-signetchallenge\fR parameter +.HP +\fB\-signetchallenge\fR +.IP +Blocks must satisfy the given script to be considered valid (only for +signet networks; defaults to the global default signet test +network challenge) +.HP +\fB\-signetseednode\fR +.IP +Specify a seed node for the signet network, in the hostname[:port] +format, e.g. sig.net:1234 (may be used multiple times to specify +multiple seed nodes; defaults to the global default signet test +network seed node(s)) +.HP +\fB\-testnet\fR +.IP +Use the testnet3 chain. Equivalent to \fB\-chain\fR=\fI\,test\/\fR. Support for testnet3 +is deprecated and will be removed in an upcoming release. +Consider moving to testnet4 now by using \fB\-testnet4\fR. +.HP +\fB\-testnet4\fR +.IP +Use the testnet4 chain. Equivalent to \fB\-chain\fR=\fI\,testnet4\/\fR. +.PP +Commands: +.IP +create +.IP +Create new wallet file +.IP +createfromdump +.IP +Create new wallet file from dumped records +.IP +dump +.IP +Print out all of the wallet key\-value records +.IP +info +.IP +Get wallet info +.IP +salvage +.IP +Attempt to recover private keys from a corrupt wallet. Warning: +\&'salvage' is experimental. +.SH COPYRIGHT +Copyright (C) 2009-2025 The Bitcoin Core developers + +Please contribute if you find Bitcoin Core useful. Visit + for further information about the software. +The source code is available from . + +This is experimental software. +Distributed under the MIT software license, see the accompanying file COPYING +or +.SH "SEE ALSO" +bitcoind(1), bitcoin-cli(1), bitcoin-tx(1), bitcoin-wallet(1), bitcoin-util(1), bitcoin-qt(1) diff --git a/doc/man/bitcoind.1 b/doc/man/bitcoind.1 new file mode 100644 index 0000000000..0846f3e061 --- /dev/null +++ b/doc/man/bitcoind.1 @@ -0,0 +1,830 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH BITCOIND "1" "September 2025" "bitcoind v29.2.0rc1" "User Commands" +.SH NAME +bitcoind \- manual page for bitcoind v29.2.0rc1 +.SH SYNOPSIS +.B bitcoind +[\fI\,options\/\fR] +.SH DESCRIPTION +Bitcoin Core daemon version v29.2.0rc1 +.PP +The Bitcoin Core daemon (bitcoind) is a headless program that connects to the Bitcoin network to validate and relay transactions and blocks, as well as relaying addresses. +.PP +It provides the backbone of the Bitcoin network and its RPC, REST and ZMQ services can provide various transaction, block and address\-related services. +.PP +There is an optional wallet component which provides transaction services. +.PP +It can be used in a headless environment or as part of a server setup. +.SH OPTIONS +.HP +\fB\-alertnotify=\fR +.IP +Execute command when an alert is raised (%s in cmd is replaced by +message) +.HP +\fB\-allowignoredconf\fR +.IP +For backwards compatibility, treat an unused bitcoin.conf file in the +datadir as a warning, not an error. +.HP +\fB\-assumevalid=\fR +.IP +If this block is in the chain assume that it and its ancestors are valid +and potentially skip their script verification (0 to verify all, +default: +00000000000000000001b658dd1120e82e66d2790811f89ede9742ada3ed6d77, +testnet3: +00000000000003fc7967410ba2d0a8a8d50daedc318d43e8baf1a9782c236a57, +testnet4: +0000000000003ed4f08dbdf6f7d6b271a6bcffce25675cb40aa9fa43179a89f3, +signet: +000000895a110f46e59eb82bbc5bfb67fa314656009c295509c21b4999f5180a) +.HP +\fB\-blockfilterindex=\fR +.IP +Maintain an index of compact filters by block (default: 0, values: +basic). If is not supplied or if = 1, indexes for +all known types are enabled. +.HP +\fB\-blocknotify=\fR +.IP +Execute command when the best block changes (%s in cmd is replaced by +block hash) +.HP +\fB\-blockreconstructionextratxn=\fR +.IP +Extra transactions to keep in memory for compact block reconstructions +(default: 100) +.HP +\fB\-blocksdir=\fR +.IP +Specify directory to hold blocks subdirectory for *.dat files (default: +) +.HP +\fB\-blocksonly\fR +.IP +Whether to reject transactions from network peers. Disables automatic +broadcast and rebroadcast of transactions, unless the source peer +has the 'forcerelay' permission. RPC transactions are not +affected. (default: 0) +.HP +\fB\-blocksxor\fR +.IP +Whether an XOR\-key applies to blocksdir *.dat files. The created XOR\-key +will be zeros for an existing blocksdir or when `\-blocksxor=0` is +set, and random for a freshly initialized blocksdir. (default: 1) +.HP +\fB\-coinstatsindex\fR +.IP +Maintain coinstats index used by the gettxoutsetinfo RPC (default: 0) +.HP +\fB\-conf=\fR +.IP +Specify path to read\-only configuration file. Relative paths will be +prefixed by datadir location (only useable from command line, not +configuration file) (default: bitcoin.conf) +.HP +\fB\-daemon\fR +.IP +Run in the background as a daemon and accept commands (default: 0) +.HP +\fB\-daemonwait\fR +.IP +Wait for initialization to be finished before exiting. This implies +\fB\-daemon\fR (default: 0) +.HP +\fB\-datadir=\fR +.IP +Specify data directory +.HP +\fB\-dbcache=\fR +.IP +Maximum database cache size MiB (minimum 4, default: 450). Make sure +you have enough RAM. In addition, unused memory allocated to the +mempool is shared with this cache (see \fB\-maxmempool\fR). +.HP +\fB\-debuglogfile=\fR +.IP +Specify location of debug log file (default: debug.log). Relative paths +will be prefixed by a net\-specific datadir location. Pass +\fB\-nodebuglogfile\fR to disable writing the log to a file. +.HP +\fB\-help\fR +.IP +Print this help message and exit (also \fB\-h\fR or \-?) +.HP +\fB\-includeconf=\fR +.IP +Specify additional configuration file, relative to the \fB\-datadir\fR path +(only useable from configuration file, not command line) +.HP +\fB\-loadblock=\fR +.IP +Imports blocks from external file on startup +.HP +\fB\-maxmempool=\fR +.IP +Keep the transaction memory pool below megabytes (default: 300) +.HP +\fB\-maxorphantx=\fR +.IP +Keep at most unconnectable transactions in memory (default: 100) +.HP +\fB\-mempoolexpiry=\fR +.IP +Do not keep transactions in the mempool longer than hours (default: +336) +.HP +\fB\-par=\fR +.IP +Set the number of script verification threads (0 = auto, up to 15, <0 = +leave that many cores free, default: 0) +.HP +\fB\-persistmempool\fR +.IP +Whether to save the mempool on shutdown and load on restart (default: 1) +.HP +\fB\-persistmempoolv1\fR +.IP +Whether a mempool.dat file created by \fB\-persistmempool\fR or the savemempool +RPC will be written in the legacy format (version 1) or the +current format (version 2). This temporary option will be removed +in the future. (default: 0) +.HP +\fB\-pid=\fR +.IP +Specify pid file. Relative paths will be prefixed by a net\-specific +datadir location. (default: bitcoind.pid) +.HP +\fB\-prune=\fR +.IP +Reduce storage requirements by enabling pruning (deleting) of old +blocks. This allows the pruneblockchain RPC to be called to +delete specific blocks and enables automatic pruning of old +blocks if a target size in MiB is provided. This mode is +incompatible with \fB\-txindex\fR. Warning: Reverting this setting +requires re\-downloading the entire blockchain. (default: 0 = +disable pruning blocks, 1 = allow manual pruning via RPC, >=550 = +automatically prune block files to stay under the specified +target size in MiB) +.HP +\fB\-reindex\fR +.IP +If enabled, wipe chain state and block index, and rebuild them from +blk*.dat files on disk. Also wipe and rebuild other optional +indexes that are active. If an assumeutxo snapshot was loaded, +its chainstate will be wiped as well. The snapshot can then be +reloaded via RPC. +.HP +\fB\-reindex\-chainstate\fR +.IP +If enabled, wipe chain state, and rebuild it from blk*.dat files on +disk. If an assumeutxo snapshot was loaded, its chainstate will +be wiped as well. The snapshot can then be reloaded via RPC. +.HP +\fB\-settings=\fR +.IP +Specify path to dynamic settings data file. Can be disabled with +\fB\-nosettings\fR. File is written at runtime and not meant to be +edited by users (use bitcoin.conf instead for custom settings). +Relative paths will be prefixed by datadir location. (default: +settings.json) +.HP +\fB\-shutdownnotify=\fR +.IP +Execute command immediately before beginning shutdown. The need for +shutdown may be urgent, so be careful not to delay it long (if +the command doesn't require interaction with the server, consider +having it fork into the background). +.HP +\fB\-startupnotify=\fR +.IP +Execute command on startup. +.HP +\fB\-txindex\fR +.IP +Maintain a full transaction index, used by the getrawtransaction rpc +call (default: 0) +.HP +\fB\-version\fR +.IP +Print version and exit +.PP +Connection options: +.HP +\fB\-addnode=\fR +.IP +Add a node to connect to and attempt to keep the connection open (see +the addnode RPC help for more info). This option can be specified +multiple times to add multiple nodes; connections are limited to +8 at a time and are counted separately from the \fB\-maxconnections\fR +limit. +.HP +\fB\-asmap=\fR +.IP +Specify asn mapping used for bucketing of the peers (default: +ip_asn.map). Relative paths will be prefixed by the net\-specific +datadir location. +.HP +\fB\-bantime=\fR +.IP +Default duration (in seconds) of manually configured bans (default: +86400) +.HP +\fB\-bind=\fR[:][=onion] +.IP +Bind to given address and always listen on it (default: 0.0.0.0). Use +[host]:port notation for IPv6. Append =onion to tag any incoming +connections to that address and port as incoming Tor connections +(default: 127.0.0.1:8334=onion, testnet3: 127.0.0.1:18334=onion, +testnet4: 127.0.0.1:48334=onion, signet: 127.0.0.1:38334=onion, +regtest: 127.0.0.1:18445=onion) +.HP +\fB\-cjdnsreachable\fR +.IP +If set, then this host is configured for CJDNS (connecting to fc00::/8 +addresses would lead us to the CJDNS network, see doc/cjdns.md) +(default: 0) +.HP +\fB\-connect=\fR +.IP +Connect only to the specified node; \fB\-noconnect\fR disables automatic +connections (the rules for this peer are the same as for +\fB\-addnode\fR). This option can be specified multiple times to connect +to multiple nodes. +.HP +\fB\-discover\fR +.IP +Discover own IP addresses (default: 1 when listening and no \fB\-externalip\fR +or \fB\-proxy\fR) +.HP +\fB\-dns\fR +.IP +Allow DNS lookups for \fB\-addnode\fR, \fB\-seednode\fR and \fB\-connect\fR (default: 1) +.HP +\fB\-dnsseed\fR +.IP +Query for peer addresses via DNS lookup, if low on addresses (default: 1 +unless \fB\-connect\fR used or \fB\-maxconnections\fR=\fI\,0\/\fR) +.HP +\fB\-externalip=\fR +.IP +Specify your own public address +.HP +\fB\-fixedseeds\fR +.IP +Allow fixed seeds if DNS seeds don't provide peers (default: 1) +.HP +\fB\-forcednsseed\fR +.IP +Always query for peer addresses via DNS lookup (default: 0) +.HP +\fB\-i2pacceptincoming\fR +.IP +Whether to accept inbound I2P connections (default: 1). Ignored if +\fB\-i2psam\fR is not set. Listening for inbound I2P connections is done +through the SAM proxy, not by binding to a local address and +port. +.HP +\fB\-i2psam=\fR +.IP +I2P SAM proxy to reach I2P peers and accept I2P connections (default: +none) +.HP +\fB\-listen\fR +.IP +Accept connections from outside (default: 1 if no \fB\-proxy\fR, \fB\-connect\fR or +\fB\-maxconnections\fR=\fI\,0\/\fR) +.HP +\fB\-listenonion\fR +.IP +Automatically create Tor onion service (default: 1) +.HP +\fB\-maxconnections=\fR +.IP +Maintain at most automatic connections to peers (default: 125). This +limit does not apply to connections manually added via \fB\-addnode\fR +or the addnode RPC, which have a separate limit of 8. +.HP +\fB\-maxreceivebuffer=\fR +.IP +Maximum per\-connection receive buffer, *1000 bytes (default: 5000) +.HP +\fB\-maxsendbuffer=\fR +.IP +Maximum per\-connection memory usage for the send buffer, *1000 bytes +(default: 1000) +.HP +\fB\-maxuploadtarget=\fR +.IP +Tries to keep outbound traffic under the given target per 24h. Limit +does not apply to peers with 'download' permission or blocks +created within past week. 0 = no limit (default: 0M). Optional +suffix units [k|K|m|M|g|G|t|T] (default: M). Lowercase is 1000 +base while uppercase is 1024 base +.HP +\fB\-natpmp\fR +.IP +Use PCP or NAT\-PMP to map the listening port (default: 0) +.HP +\fB\-networkactive\fR +.IP +Enable all P2P network activity (default: 1). Can be changed by the +setnetworkactive RPC command +.HP +\fB\-onion=\fR +.IP +Use separate SOCKS5 proxy to reach peers via Tor onion services, set +\fB\-noonion\fR to disable (default: \fB\-proxy\fR). May be a local file path +prefixed with 'unix:'. +.HP +\fB\-onlynet=\fR +.IP +Make automatic outbound connections only to network (ipv4, ipv6, +onion, i2p, cjdns). Inbound and manual connections are not +affected by this option. It can be specified multiple times to +allow multiple networks. +.HP +\fB\-peerblockfilters\fR +.IP +Serve compact block filters to peers per BIP 157 (default: 0) +.HP +\fB\-peerbloomfilters\fR +.IP +Support filtering of blocks and transaction with bloom filters (default: +0) +.HP +\fB\-port=\fR +.IP +Listen for connections on (default: 8333, testnet3: 18333, +testnet4: 48333, signet: 38333, regtest: 18444). Not relevant for +I2P (see doc/i2p.md). If set to a value x, the default onion +listening port will be set to x+1. +.HP +\fB\-proxy=\fR +.IP +Connect through SOCKS5 proxy, set \fB\-noproxy\fR to disable (default: +disabled). May be a local file path prefixed with 'unix:' if the +proxy supports it. +.HP +\fB\-proxyrandomize\fR +.IP +Randomize credentials for every proxy connection. This enables Tor +stream isolation (default: 1) +.HP +\fB\-seednode=\fR +.IP +Connect to a node to retrieve peer addresses, and disconnect. This +option can be specified multiple times to connect to multiple +nodes. During startup, seednodes will be tried before dnsseeds. +.HP +\fB\-timeout=\fR +.IP +Specify socket connection timeout in milliseconds. If an initial attempt +to connect is unsuccessful after this amount of time, drop it +(minimum: 1, default: 5000) +.HP +\fB\-torcontrol=\fR: +.IP +Tor control host and port to use if onion listening enabled (default: +127.0.0.1:9051). If no port is specified, the default port of +9051 will be used. +.HP +\fB\-torpassword=\fR +.IP +Tor control port password (default: empty) +.HP +\fB\-v2transport\fR +.IP +Support v2 transport (default: 1) +.HP +\fB\-whitebind=\fR<[permissions@]addr> +.IP +Bind to the given address and add permission flags to the peers +connecting to it. Use [host]:port notation for IPv6. Allowed +permissions: bloomfilter (allow requesting BIP37 filtered blocks +and transactions), noban (do not ban for misbehavior; implies +download), forcerelay (relay transactions that are already in the +mempool; implies relay), relay (relay even in \fB\-blocksonly\fR mode, +and unlimited transaction announcements), mempool (allow +requesting BIP35 mempool contents), download (allow getheaders +during IBD, no disconnect after maxuploadtarget limit), addr +(responses to GETADDR avoid hitting the cache and contain random +records with the most up\-to\-date info). Specify multiple +permissions separated by commas (default: +download,noban,mempool,relay). Can be specified multiple times. +.HP +\fB\-whitelist=\fR<[permissions@]IP address or network> +.IP +Add permission flags to the peers using the given IP address (e.g. +1.2.3.4) or CIDR\-notated network (e.g. 1.2.3.0/24). Uses the same +permissions as \fB\-whitebind\fR. Additional flags "in" and "out" +control whether permissions apply to incoming connections and/or +manual (default: incoming only). Can be specified multiple times. +.PP +Wallet options: +.HP +\fB\-addresstype\fR +.IP +What type of addresses to use ("legacy", "p2sh\-segwit", "bech32", or +"bech32m", default: "bech32") +.HP +\fB\-avoidpartialspends\fR +.IP +Group outputs by address, selecting many (possibly all) or none, instead +of selecting on a per\-output basis. Privacy is improved as +addresses are mostly swept with fewer transactions and outputs +are aggregated in clean change addresses. It may result in higher +fees due to less optimal coin selection caused by this added +limitation and possibly a larger\-than\-necessary number of inputs +being used. Always enabled for wallets with "avoid_reuse" +enabled, otherwise default: 0. +.HP +\fB\-changetype\fR +.IP +What type of change to use ("legacy", "p2sh\-segwit", "bech32", or +"bech32m"). Default is "legacy" when \fB\-addresstype\fR=\fI\,legacy\/\fR, else it +is an implementation detail. +.HP +\fB\-consolidatefeerate=\fR +.IP +The maximum feerate (in BTC/kvB) at which transaction building may use +more inputs than strictly necessary so that the wallet's UTXO +pool can be reduced (default: 0.0001). +.HP +\fB\-disablewallet\fR +.IP +Do not load the wallet and disable wallet RPC calls +.HP +\fB\-discardfee=\fR +.IP +The fee rate (in BTC/kvB) that indicates your tolerance for discarding +change by adding it to the fee (default: 0.0001). Note: An output +is discarded if it is dust at this rate, but we will always +discard up to the dust relay fee and a discard fee above that is +limited by the fee estimate for the longest target +.HP +\fB\-fallbackfee=\fR +.IP +A fee rate (in BTC/kvB) that will be used when fee estimation has +insufficient data. 0 to entirely disable the fallbackfee feature. +(default: 0.00) +.HP +\fB\-keypool=\fR +.IP +Set key pool size to (default: 1000). Warning: Smaller sizes may +increase the risk of losing funds when restoring from an old +backup, if none of the addresses in the original keypool have +been used. +.HP +\fB\-maxapsfee=\fR +.IP +Spend up to this amount in additional (absolute) fees (in BTC) if it +allows the use of partial spend avoidance (default: 0.00) +.HP +\fB\-mintxfee=\fR +.IP +Fee rates (in BTC/kvB) smaller than this are considered zero fee for +transaction creation (default: 0.00001) +.HP +\fB\-paytxfee=\fR +.IP +Fee rate (in BTC/kvB) to add to transactions you send (default: 0.00) +.HP +\fB\-signer=\fR +.IP +External signing tool, see doc/external\-signer.md +.HP +\fB\-spendzeroconfchange\fR +.IP +Spend unconfirmed change when sending transactions (default: 1) +.HP +\fB\-txconfirmtarget=\fR +.IP +If paytxfee is not set, include enough fee so transactions begin +confirmation on average within n blocks (default: 6) +.HP +\fB\-wallet=\fR +.IP +Specify wallet path to load at startup. Can be used multiple times to +load multiple wallets. Path is to a directory containing wallet +data and log files. If the path is not absolute, it is +interpreted relative to . This only loads existing +wallets and does not create new ones. For backwards compatibility +this also accepts names of existing top\-level data files in +. +.HP +\fB\-walletbroadcast\fR +.IP +Make the wallet broadcast transactions (default: 1) +.HP +\fB\-walletdir=\fR +.IP +Specify directory to hold wallets (default: /wallets if it +exists, otherwise ) +.HP +\fB\-walletnotify=\fR +.IP +Execute command when a wallet transaction changes. %s in cmd is replaced +by TxID, %w is replaced by wallet name, %b is replaced by the +hash of the block including the transaction (set to 'unconfirmed' +if the transaction is not included) and %h is replaced by the +block height (\fB\-1\fR if not included). %w is not currently +implemented on windows. On systems where %w is supported, it +should NOT be quoted because this would break shell escaping used +to invoke the command. +.HP +\fB\-walletrbf\fR +.IP +Send transactions with full\-RBF opt\-in enabled (RPC only, default: 1) +.PP +ZeroMQ notification options: +.HP +\fB\-zmqpubhashblock=\fR
+.IP +Enable publish hash block in
+.HP +\fB\-zmqpubhashblockhwm=\fR +.IP +Set publish hash block outbound message high water mark (default: 1000) +.HP +\fB\-zmqpubhashtx=\fR
+.IP +Enable publish hash transaction in
+.HP +\fB\-zmqpubhashtxhwm=\fR +.IP +Set publish hash transaction outbound message high water mark (default: +1000) +.HP +\fB\-zmqpubrawblock=\fR
+.IP +Enable publish raw block in
+.HP +\fB\-zmqpubrawblockhwm=\fR +.IP +Set publish raw block outbound message high water mark (default: 1000) +.HP +\fB\-zmqpubrawtx=\fR
+.IP +Enable publish raw transaction in
+.HP +\fB\-zmqpubrawtxhwm=\fR +.IP +Set publish raw transaction outbound message high water mark (default: +1000) +.HP +\fB\-zmqpubsequence=\fR
+.IP +Enable publish hash block and tx sequence in
+.HP +\fB\-zmqpubsequencehwm=\fR +.IP +Set publish hash sequence message high water mark (default: 1000) +.PP +Debugging/Testing options: +.HP +\fB\-debug=\fR +.IP +Output debug and trace logging (default: \fB\-nodebug\fR, supplying +is optional). If is not supplied or if is 1 +or "all", output all debug logging. If is 0 or "none", +any other categories are ignored. Other valid values for + are: addrman, bench, blockstorage, cmpctblock, coindb, +estimatefee, http, i2p, ipc, leveldb, libevent, mempool, +mempoolrej, net, proxy, prune, qt, rand, reindex, rpc, scan, +selectcoins, tor, txpackages, txreconciliation, validation, +walletdb, zmq. This option can be specified multiple times to +output multiple categories. +.HP +\fB\-debugexclude=\fR +.IP +Exclude debug and trace logging for a category. Can be used in +conjunction with \fB\-debug\fR=\fI\,1\/\fR to output debug and trace logging for +all categories except the specified category. This option can be +specified multiple times to exclude multiple categories. This +takes priority over "\-debug" +.HP +\fB\-help\-debug\fR +.IP +Print help message with debugging options and exit +.HP +\fB\-logips\fR +.IP +Include IP addresses in debug output (default: 0) +.HP +\fB\-loglevelalways\fR +.IP +Always prepend a category and level (default: 0) +.HP +\fB\-logsourcelocations\fR +.IP +Prepend debug output with name of the originating source location +(source file, line number and function name) (default: 0) +.HP +\fB\-logthreadnames\fR +.IP +Prepend debug output with name of the originating thread (default: 0) +.HP +\fB\-logtimestamps\fR +.IP +Prepend debug output with timestamp (default: 1) +.HP +\fB\-maxtxfee=\fR +.IP +Maximum total fees (in BTC) to use in a single wallet transaction; +setting this too low may abort large transactions (default: 0.10) +.HP +\fB\-printtoconsole\fR +.IP +Send trace/debug info to console (default: 1 when no \fB\-daemon\fR. To disable +logging to file, set \fB\-nodebuglogfile\fR) +.HP +\fB\-shrinkdebugfile\fR +.IP +Shrink debug.log file on client startup (default: 1 when no \fB\-debug\fR) +.HP +\fB\-uacomment=\fR +.IP +Append comment to the user agent string +.PP +Chain selection options: +.HP +\fB\-chain=\fR +.IP +Use the chain (default: main). Allowed values: main, test, +testnet4, signet, regtest +.HP +\fB\-signet\fR +.IP +Use the signet chain. Equivalent to \fB\-chain\fR=\fI\,signet\/\fR. Note that the network +is defined by the \fB\-signetchallenge\fR parameter +.HP +\fB\-signetchallenge\fR +.IP +Blocks must satisfy the given script to be considered valid (only for +signet networks; defaults to the global default signet test +network challenge) +.HP +\fB\-signetseednode\fR +.IP +Specify a seed node for the signet network, in the hostname[:port] +format, e.g. sig.net:1234 (may be used multiple times to specify +multiple seed nodes; defaults to the global default signet test +network seed node(s)) +.HP +\fB\-testnet\fR +.IP +Use the testnet3 chain. Equivalent to \fB\-chain\fR=\fI\,test\/\fR. Support for testnet3 +is deprecated and will be removed in an upcoming release. +Consider moving to testnet4 now by using \fB\-testnet4\fR. +.HP +\fB\-testnet4\fR +.IP +Use the testnet4 chain. Equivalent to \fB\-chain\fR=\fI\,testnet4\/\fR. +.PP +Node relay options: +.HP +\fB\-bytespersigop\fR +.IP +Equivalent bytes per sigop in transactions for relay and mining +(default: 20) +.HP +\fB\-datacarrier\fR +.IP +Relay and mine data carrier transactions (default: 1) +.HP +\fB\-datacarriersize\fR +.IP +Relay and mine transactions whose data\-carrying raw scriptPubKey is of +this size or less (default: 83) +.HP +\fB\-minrelaytxfee=\fR +.IP +Fees (in BTC/kvB) smaller than this are considered zero fee for +relaying, mining and transaction creation (default: 0.000001) +.HP +\fB\-permitbaremultisig\fR +.IP +Relay transactions creating non\-P2SH multisig outputs (default: 1) +.HP +\fB\-whitelistforcerelay\fR +.IP +Add 'forcerelay' permission to whitelisted peers with default +permissions. This will relay transactions even if the +transactions were already in the mempool. (default: 0) +.HP +\fB\-whitelistrelay\fR +.IP +Add 'relay' permission to whitelisted peers with default permissions. +This will accept relayed transactions even when not relaying +transactions (default: 1) +.PP +Block creation options: +.HP +\fB\-blockmaxweight=\fR +.IP +Set maximum BIP141 block weight (default: 4000000) +.HP +\fB\-blockmintxfee=\fR +.IP +Set lowest fee rate (in BTC/kvB) for transactions to be included in +block creation. (default: 0.00000001) +.HP +\fB\-blockreservedweight=\fR +.IP +Reserve space for the fixed\-size block header plus the largest coinbase +transaction the mining software may add to the block. (default: +8000). +.PP +RPC server options: +.HP +\fB\-rest\fR +.IP +Accept public REST requests (default: 0) +.HP +\fB\-rpcallowip=\fR +.IP +Allow JSON\-RPC connections from specified source. Valid values for +are a single IP (e.g. 1.2.3.4), a network/netmask (e.g. +1.2.3.4/255.255.255.0), a network/CIDR (e.g. 1.2.3.4/24), all +ipv4 (0.0.0.0/0), or all ipv6 (::/0). This option can be +specified multiple times +.HP +\fB\-rpcauth=\fR +.IP +Username and HMAC\-SHA\-256 hashed password for JSON\-RPC connections. The +field comes in the format: :$. A +canonical python script is included in share/rpcauth. The client +then connects normally using the +rpcuser=/rpcpassword= pair of arguments. This +option can be specified multiple times +.HP +\fB\-rpcbind=\fR[:port] +.IP +Bind to given address to listen for JSON\-RPC connections. Do not expose +the RPC server to untrusted networks such as the public internet! +This option is ignored unless \fB\-rpcallowip\fR is also passed. Port is +optional and overrides \fB\-rpcport\fR. Use [host]:port notation for +IPv6. This option can be specified multiple times (default: +127.0.0.1 and ::1 i.e., localhost) +.HP +\fB\-rpccookiefile=\fR +.IP +Location of the auth cookie. Relative paths will be prefixed by a +net\-specific datadir location. (default: data dir) +.HP +\fB\-rpccookieperms=\fR +.IP +Set permissions on the RPC auth cookie file so that it is readable by +[owner|group|all] (default: owner [via umask 0077]) +.HP +\fB\-rpcpassword=\fR +.IP +Password for JSON\-RPC connections +.HP +\fB\-rpcport=\fR +.IP +Listen for JSON\-RPC connections on (default: 8332, testnet3: +18332, testnet4: 48332, signet: 38332, regtest: 18443) +.HP +\fB\-rpcthreads=\fR +.IP +Set the number of threads to service RPC calls (default: 16) +.HP +\fB\-rpcuser=\fR +.IP +Username for JSON\-RPC connections +.HP +\fB\-rpcwhitelist=\fR +.IP +Set a whitelist to filter incoming RPC calls for a specific user. The +field comes in the format: :,,...,. If multiple whitelists are set for a given user, +they are set\-intersected. See \fB\-rpcwhitelistdefault\fR documentation +for information on default whitelist behavior. +.HP +\fB\-rpcwhitelistdefault\fR +.IP +Sets default behavior for rpc whitelisting. Unless rpcwhitelistdefault +is set to 0, if any \fB\-rpcwhitelist\fR is set, the rpc server acts as +if all rpc users are subject to empty\-unless\-otherwise\-specified +whitelists. If rpcwhitelistdefault is set to 1 and no +\fB\-rpcwhitelist\fR is set, rpc server acts as if all rpc users are +subject to empty whitelists. +.HP +\fB\-server\fR +.IP +Accept command line and JSON\-RPC commands +.SH COPYRIGHT +Copyright (C) 2009-2025 The Bitcoin Core developers + +Please contribute if you find Bitcoin Core useful. Visit + for further information about the software. +The source code is available from . + +This is experimental software. +Distributed under the MIT software license, see the accompanying file COPYING +or +.SH "SEE ALSO" +bitcoind(1), bitcoin-cli(1), bitcoin-tx(1), bitcoin-wallet(1), bitcoin-util(1), bitcoin-qt(1) diff --git a/doc/release-notes.md b/doc/release-notes.md index b73e52dc57..0325d3a3e2 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -1,6 +1,6 @@ -Bitcoin Core version 29.x is now available from: +Bitcoin Core version 29.2rc1 is now available from: - + This release includes various bug fixes and performance improvements, as well as updated translations. @@ -37,19 +37,37 @@ unsupported systems. Notable changes =============== +### P2P + +- #32646 p2p: Add witness mutation check inside FillBlock +- #33296 net: check for empty header before calling FillBlock +- #33395 net: do not apply whitelist permissions to onion inbounds + ### CI - #32999 ci: Use APT_LLVM_V in msan task - #33099 ci: allow for any libc++ intrumentation & use it for TSAN - #33258 ci: use LLVM 21 +- #33364 ci: always use tag for LLVM checkout + +### Misc + +- #33310 trace: Workaround GCC bug compiling with old systemtap +- #33340 Fix benchmark CSV output Credits ======= Thanks to everyone who directly contributed to this release: +- Eugene Siegel - fanquake +- Greg Sanders +- Hennadii Stepanov +- Luke Dashjr - MarcoFalke +- Martin Zumsande +- Vasil Dimov As well as to everyone that helped with translations on [Transifex](https://explore.transifex.com/bitcoin/bitcoin/). diff --git a/src/blockencodings.cpp b/src/blockencodings.cpp index 1acc808107..82bfd8fab3 100644 --- a/src/blockencodings.cpp +++ b/src/blockencodings.cpp @@ -186,7 +186,7 @@ bool PartiallyDownloadedBlock::IsTxAvailable(size_t index) const return txn_available[index] != nullptr; } -ReadStatus PartiallyDownloadedBlock::FillBlock(CBlock& block, const std::vector& vtx_missing, bool check_pow) +ReadStatus PartiallyDownloadedBlock::FillBlock(CBlock& block, const std::vector& vtx_missing, bool segwit_active) { if (header.IsNull()) return READ_STATUS_INVALID; @@ -211,16 +211,11 @@ ReadStatus PartiallyDownloadedBlock::FillBlock(CBlock& block, const std::vector< if (vtx_missing.size() != tx_missing_offset) return READ_STATUS_INVALID; - BlockValidationState state; - CheckBlockFn check_block = m_check_block_mock ? m_check_block_mock : CheckBlock; - if (!check_block(block, state, Params().GetConsensus(), /*fCheckPoW=*/check_pow, /*fCheckMerkleRoot=*/true)) { - // TODO: We really want to just check merkle tree manually here, - // but that is expensive, and CheckBlock caches a block's - // "checked-status" (in the CBlock?). CBlock should be able to - // check its own merkle root and cache that check. - if (state.GetResult() == BlockValidationResult::BLOCK_MUTATED) - return READ_STATUS_FAILED; // Possible Short ID collision - return READ_STATUS_CHECKBLOCK_FAILED; + // Check for possible mutations early now that we have a seemingly good block + IsBlockMutatedFn check_mutated{m_check_block_mutated_mock ? m_check_block_mutated_mock : IsBlockMutated}; + if (check_mutated(/*block=*/block, + /*check_witness_root=*/segwit_active)) { + return READ_STATUS_FAILED; // Possible Short ID collision } LogDebug(BCLog::CMPCTBLOCK, "Successfully reconstructed block %s with %lu txn prefilled, %lu txn from mempool (incl at least %lu from extra pool) and %lu txn requested\n", hash.ToString(), prefilled_count, mempool_count, extra_count, vtx_missing.size()); diff --git a/src/blockencodings.h b/src/blockencodings.h index 187a0bcb17..3a8e2eb4a6 100644 --- a/src/blockencodings.h +++ b/src/blockencodings.h @@ -84,8 +84,6 @@ typedef enum ReadStatus_t READ_STATUS_OK, READ_STATUS_INVALID, // Invalid object, peer is sending bogus crap READ_STATUS_FAILED, // Failed to process object - READ_STATUS_CHECKBLOCK_FAILED, // Used only by FillBlock to indicate a - // failure in CheckBlock. } ReadStatus; class CBlockHeaderAndShortTxIDs { @@ -141,8 +139,8 @@ public: CBlockHeader header; // Can be overridden for testing - using CheckBlockFn = std::function; - CheckBlockFn m_check_block_mock{nullptr}; + using IsBlockMutatedFn = std::function; + IsBlockMutatedFn m_check_block_mutated_mock{nullptr}; explicit PartiallyDownloadedBlock(CTxMemPool* poolIn) : pool(poolIn) {} @@ -150,7 +148,8 @@ public: // extra_txn is a list of extra orphan/conflicted/etc transactions to look at ReadStatus InitData(const CBlockHeaderAndShortTxIDs& cmpctblock, const std::vector& extra_txn); bool IsTxAvailable(size_t index) const; - ReadStatus FillBlock(CBlock& block, const std::vector& vtx_missing, bool check_pow = true); + // segwit_active enforces witness mutation checks just before reporting a healthy status + ReadStatus FillBlock(CBlock& block, const std::vector& vtx_missing, bool segwit_active); }; #endif // BITCOIN_BLOCKENCODINGS_H diff --git a/src/crypto/sha256.cpp b/src/crypto/sha256.cpp index f5cb7fa80f..97d5b5568f 100644 --- a/src/crypto/sha256.cpp +++ b/src/crypto/sha256.cpp @@ -627,7 +627,7 @@ std::string SHA256AutoDetect(sha256_implementation::UseImplementation use_implem Transform = sha256_x86_shani::Transform; TransformD64 = TransformD64Wrapper; TransformD64_2way = sha256d64_x86_shani::Transform_2way; - ret = "x86_shani(1way,2way)"; + ret = "x86_shani(1way;2way)"; have_sse4 = false; // Disable SSE4/AVX2; have_avx2 = false; } @@ -641,14 +641,14 @@ std::string SHA256AutoDetect(sha256_implementation::UseImplementation use_implem #endif #if defined(ENABLE_SSE41) TransformD64_4way = sha256d64_sse41::Transform_4way; - ret += ",sse41(4way)"; + ret += ";sse41(4way)"; #endif } #if defined(ENABLE_AVX2) if (have_avx2 && have_avx && enabled_avx) { TransformD64_8way = sha256d64_avx2::Transform_8way; - ret += ",avx2(8way)"; + ret += ";avx2(8way)"; } #endif #endif // defined(HAVE_GETCPUID) @@ -682,7 +682,7 @@ std::string SHA256AutoDetect(sha256_implementation::UseImplementation use_implem Transform = sha256_arm_shani::Transform; TransformD64 = TransformD64Wrapper; TransformD64_2way = sha256d64_arm_shani::Transform_2way; - ret = "arm_shani(1way,2way)"; + ret = "arm_shani(1way;2way)"; } #endif #endif // DISABLE_OPTIMIZED_SHA256 diff --git a/src/net.cpp b/src/net.cpp index 94159714a3..9de594cbbb 100644 --- a/src/net.cpp +++ b/src/net.cpp @@ -575,9 +575,9 @@ void CNode::CloseSocketDisconnect() m_i2p_sam_session.reset(); } -void CConnman::AddWhitelistPermissionFlags(NetPermissionFlags& flags, const CNetAddr &addr, const std::vector& ranges) const { +void CConnman::AddWhitelistPermissionFlags(NetPermissionFlags& flags, std::optional addr, const std::vector& ranges) const { for (const auto& subnet : ranges) { - if (subnet.m_subnet.Match(addr)) { + if (addr.has_value() && subnet.m_subnet.Match(addr.value())) { NetPermissions::AddFlag(flags, subnet.m_flags); } } @@ -1767,7 +1767,11 @@ void CConnman::CreateNodeFromAcceptedSocket(std::unique_ptr&& sock, { int nInbound = 0; - AddWhitelistPermissionFlags(permission_flags, addr, vWhitelistedRangeIncoming); + const bool inbound_onion = std::find(m_onion_binds.begin(), m_onion_binds.end(), addr_bind) != m_onion_binds.end(); + + // Tor inbound connections do not reveal the peer's actual network address. + // Therefore do not apply address-based whitelist permissions to them. + AddWhitelistPermissionFlags(permission_flags, inbound_onion ? std::optional{} : addr, vWhitelistedRangeIncoming); { LOCK(m_nodes_mutex); @@ -1822,7 +1826,6 @@ void CConnman::CreateNodeFromAcceptedSocket(std::unique_ptr&& sock, NodeId id = GetNewNodeId(); uint64_t nonce = GetDeterministicRandomizer(RANDOMIZER_ID_LOCALHOSTNONCE).Write(id).Finalize(); - const bool inbound_onion = std::find(m_onion_binds.begin(), m_onion_binds.end(), addr_bind) != m_onion_binds.end(); // The V2Transport transparently falls back to V1 behavior when an incoming V1 connection is // detected, so use it whenever we signal NODE_P2P_V2. ServiceFlags local_services = GetLocalServices(); diff --git a/src/net.h b/src/net.h index 86e8a022b2..0233ba8716 100644 --- a/src/net.h +++ b/src/net.h @@ -1364,7 +1364,7 @@ private: bool AttemptToEvictConnection(); CNode* ConnectNode(CAddress addrConnect, const char *pszDest, bool fCountFailure, ConnectionType conn_type, bool use_v2transport) EXCLUSIVE_LOCKS_REQUIRED(!m_unused_i2p_sessions_mutex); - void AddWhitelistPermissionFlags(NetPermissionFlags& flags, const CNetAddr &addr, const std::vector& ranges) const; + void AddWhitelistPermissionFlags(NetPermissionFlags& flags, std::optional addr, const std::vector& ranges) const; void DeleteNode(CNode* pnode); diff --git a/src/net_processing.cpp b/src/net_processing.cpp index d5ef6537e2..dcc9edae2e 100644 --- a/src/net_processing.cpp +++ b/src/net_processing.cpp @@ -3375,7 +3375,21 @@ void PeerManagerImpl::ProcessCompactBlockTxns(CNode& pfrom, Peer& peer, const Bl } PartiallyDownloadedBlock& partialBlock = *range_flight.first->second.second->partialBlock; - ReadStatus status = partialBlock.FillBlock(*pblock, block_transactions.txn); + + if (partialBlock.header.IsNull()) { + // It is possible for the header to be empty if a previous call to FillBlock wiped the header, but left + // the PartiallyDownloadedBlock pointer around (i.e. did not call RemoveBlockRequest). In this case, we + // should not call LookupBlockIndex below. + RemoveBlockRequest(block_transactions.blockhash, pfrom.GetId()); + Misbehaving(peer, "previous compact block reconstruction attempt failed"); + LogDebug(BCLog::NET, "Peer %d sent compact block transactions multiple times", pfrom.GetId()); + return; + } + + // We should not have gotten this far in compact block processing unless it's attached to a known header + const CBlockIndex* prev_block{Assume(m_chainman.m_blockman.LookupBlockIndex(partialBlock.header.hashPrevBlock))}; + ReadStatus status = partialBlock.FillBlock(*pblock, block_transactions.txn, + /*segwit_active=*/DeploymentActiveAfter(prev_block, m_chainman, Consensus::DEPLOYMENT_SEGWIT)); if (status == READ_STATUS_INVALID) { RemoveBlockRequest(block_transactions.blockhash, pfrom.GetId()); // Reset in-flight state in case Misbehaving does not result in a disconnect Misbehaving(peer, "invalid compact block/non-matching block transactions"); @@ -3383,6 +3397,9 @@ void PeerManagerImpl::ProcessCompactBlockTxns(CNode& pfrom, Peer& peer, const Bl } else if (status == READ_STATUS_FAILED) { if (first_in_flight) { // Might have collided, fall back to getdata now :( + // We keep the failed partialBlock to disallow processing another compact block announcement from the same + // peer for the same block. We let the full block download below continue under the same m_downloading_since + // timer. std::vector invs; invs.emplace_back(MSG_BLOCK | GetFetchFlags(peer), block_transactions.blockhash); MakeAndPushMessage(pfrom, NetMsgType::GETDATA, invs); @@ -3392,23 +3409,7 @@ void PeerManagerImpl::ProcessCompactBlockTxns(CNode& pfrom, Peer& peer, const Bl return; } } else { - // Block is either okay, or possibly we received - // READ_STATUS_CHECKBLOCK_FAILED. - // Note that CheckBlock can only fail for one of a few reasons: - // 1. bad-proof-of-work (impossible here, because we've already - // accepted the header) - // 2. merkleroot doesn't match the transactions given (already - // caught in FillBlock with READ_STATUS_FAILED, so - // impossible here) - // 3. the block is otherwise invalid (eg invalid coinbase, - // block is too big, too many legacy sigops, etc). - // So if CheckBlock failed, #3 is the only possibility. - // Under BIP 152, we don't discourage the peer unless proof of work is - // invalid (we don't require all the stateless checks to have - // been run). This is handled below, so just treat this as - // though the block was successfully read, and rely on the - // handling in ProcessNewBlock to ensure the block index is - // updated, etc. + // Block is okay for further processing RemoveBlockRequest(block_transactions.blockhash, pfrom.GetId()); // it is now an empty pointer fBlockRead = true; // mapBlockSource is used for potentially punishing peers and @@ -4538,7 +4539,9 @@ void PeerManagerImpl::ProcessMessage(CNode& pfrom, const std::string& msg_type, return; } std::vector dummy; - status = tempBlock.FillBlock(*pblock, dummy); + const CBlockIndex* prev_block{Assume(m_chainman.m_blockman.LookupBlockIndex(cmpctblock.header.hashPrevBlock))}; + status = tempBlock.FillBlock(*pblock, dummy, + /*segwit_active=*/DeploymentActiveAfter(prev_block, m_chainman, Consensus::DEPLOYMENT_SEGWIT)); if (status == READ_STATUS_OK) { fBlockReconstructed = true; } diff --git a/src/rpc/mining.cpp b/src/rpc/mining.cpp index 79963058a7..ac1b7c30a6 100644 --- a/src/rpc/mining.cpp +++ b/src/rpc/mining.cpp @@ -1471,13 +1471,11 @@ static RPCHelpMan consumecompactsketch() if (req.indexes.empty()) { std::shared_ptr pblock = std::make_shared(); std::vector dummy; - ReadStatus status = partialBlock.FillBlock(*pblock, dummy, false /* don't get pow */); + ReadStatus status = partialBlock.FillBlock(*pblock, dummy, /*segwit_active=*/true); if (status == READ_STATUS_INVALID) { throw JSONRPCError(RPC_DESERIALIZATION_ERROR, "Bogus crap sketch."); } else if (status == READ_STATUS_FAILED) { throw JSONRPCError(RPC_DESERIALIZATION_ERROR, "Failed to complete block though all transactions were apparently found. Could be random short ID collision; requires full block instead."); - } else if (status == READ_STATUS_CHECKBLOCK_FAILED) { - throw JSONRPCError(RPC_DESERIALIZATION_ERROR, "Checkblock failed."); } DataStream ssBlock{}; ssBlock << TX_WITH_WITNESS(*pblock); diff --git a/src/test/blockencodings_tests.cpp b/src/test/blockencodings_tests.cpp index ed95a8831e..d40a0a94ae 100644 --- a/src/test/blockencodings_tests.cpp +++ b/src/test/blockencodings_tests.cpp @@ -95,21 +95,21 @@ BOOST_AUTO_TEST_CASE(SimpleRoundTripTest) CBlock block2; { PartiallyDownloadedBlock tmp = partialBlock; - BOOST_CHECK(partialBlock.FillBlock(block2, {}) == READ_STATUS_INVALID); // No transactions + BOOST_CHECK(partialBlock.FillBlock(block2, {}, /*segwit_active=*/true) == READ_STATUS_INVALID); // No transactions partialBlock = tmp; } // Wrong transaction { PartiallyDownloadedBlock tmp = partialBlock; - partialBlock.FillBlock(block2, {block.vtx[2]}); // Current implementation doesn't check txn here, but don't require that + partialBlock.FillBlock(block2, {block.vtx[2]}, /*segwit_active=*/true); // Current implementation doesn't check txn here, but don't require that partialBlock = tmp; } bool mutated; BOOST_CHECK(block.hashMerkleRoot != BlockMerkleRoot(block2, &mutated)); CBlock block3; - BOOST_CHECK(partialBlock.FillBlock(block3, {block.vtx[1]}) == READ_STATUS_OK); + BOOST_CHECK(partialBlock.FillBlock(block3, {block.vtx[1]}, /*segwit_active=*/true) == READ_STATUS_OK); BOOST_CHECK_EQUAL(block.GetHash().ToString(), block3.GetHash().ToString()); BOOST_CHECK_EQUAL(block.hashMerkleRoot.ToString(), BlockMerkleRoot(block3, &mutated).ToString()); BOOST_CHECK(!mutated); @@ -182,14 +182,14 @@ BOOST_AUTO_TEST_CASE(NonCoinbasePreforwardRTTest) CBlock block2; { PartiallyDownloadedBlock tmp = partialBlock; - BOOST_CHECK(partialBlock.FillBlock(block2, {}) == READ_STATUS_INVALID); // No transactions + BOOST_CHECK(partialBlock.FillBlock(block2, {}, /*segwit_active=*/true) == READ_STATUS_INVALID); // No transactions partialBlock = tmp; } // Wrong transaction { PartiallyDownloadedBlock tmp = partialBlock; - partialBlock.FillBlock(block2, {block.vtx[1]}); // Current implementation doesn't check txn here, but don't require that + partialBlock.FillBlock(block2, {block.vtx[1]}, /*segwit_active=*/true); // Current implementation doesn't check txn here, but don't require that partialBlock = tmp; } BOOST_CHECK_EQUAL(pool.get(block.vtx[2]->GetHash()).use_count(), SHARED_TX_OFFSET + 2); // +2 because of partialBlock and block2 @@ -198,7 +198,7 @@ BOOST_AUTO_TEST_CASE(NonCoinbasePreforwardRTTest) CBlock block3; PartiallyDownloadedBlock partialBlockCopy = partialBlock; - BOOST_CHECK(partialBlock.FillBlock(block3, {block.vtx[0]}) == READ_STATUS_OK); + BOOST_CHECK(partialBlock.FillBlock(block3, {block.vtx[0]}, /*segwit_active=*/true) == READ_STATUS_OK); BOOST_CHECK_EQUAL(block.GetHash().ToString(), block3.GetHash().ToString()); BOOST_CHECK_EQUAL(block.hashMerkleRoot.ToString(), BlockMerkleRoot(block3, &mutated).ToString()); BOOST_CHECK(!mutated); @@ -252,7 +252,7 @@ BOOST_AUTO_TEST_CASE(SufficientPreforwardRTTest) CBlock block2; PartiallyDownloadedBlock partialBlockCopy = partialBlock; - BOOST_CHECK(partialBlock.FillBlock(block2, {}) == READ_STATUS_OK); + BOOST_CHECK(partialBlock.FillBlock(block2, {}, /*segwit_active=*/true) == READ_STATUS_OK); BOOST_CHECK_EQUAL(block.GetHash().ToString(), block2.GetHash().ToString()); bool mutated; BOOST_CHECK_EQUAL(block.hashMerkleRoot.ToString(), BlockMerkleRoot(block2, &mutated).ToString()); @@ -300,7 +300,7 @@ BOOST_AUTO_TEST_CASE(EmptyBlockRoundTripTest) CBlock block2; std::vector vtx_missing; - BOOST_CHECK(partialBlock.FillBlock(block2, vtx_missing) == READ_STATUS_OK); + BOOST_CHECK(partialBlock.FillBlock(block2, vtx_missing, /*segwit_active=*/true) == READ_STATUS_OK); BOOST_CHECK_EQUAL(block.GetHash().ToString(), block2.GetHash().ToString()); BOOST_CHECK_EQUAL(block.hashMerkleRoot.ToString(), BlockMerkleRoot(block2, &mutated).ToString()); BOOST_CHECK(!mutated); diff --git a/src/test/fuzz/partially_downloaded_block.cpp b/src/test/fuzz/partially_downloaded_block.cpp index 82d781cd53..c9635cae8c 100644 --- a/src/test/fuzz/partially_downloaded_block.cpp +++ b/src/test/fuzz/partially_downloaded_block.cpp @@ -32,14 +32,10 @@ void initialize_pdb() g_setup = testing_setup.get(); } -PartiallyDownloadedBlock::CheckBlockFn FuzzedCheckBlock(std::optional result) +PartiallyDownloadedBlock::IsBlockMutatedFn FuzzedIsBlockMutated(bool result) { - return [result](const CBlock&, BlockValidationState& state, const Consensus::Params&, bool, bool) { - if (result) { - return state.Invalid(*result); - } - - return true; + return [result](const CBlock& block, bool) { + return result; }; } @@ -111,36 +107,22 @@ FUZZ_TARGET(partially_downloaded_block, .init = initialize_pdb) skipped_missing |= (!pdb.IsTxAvailable(i) && skip); } - // Mock CheckBlock - bool fail_check_block{fuzzed_data_provider.ConsumeBool()}; - auto validation_result = - fuzzed_data_provider.PickValueInArray( - {BlockValidationResult::BLOCK_RESULT_UNSET, - BlockValidationResult::BLOCK_CONSENSUS, - BlockValidationResult::BLOCK_CACHED_INVALID, - BlockValidationResult::BLOCK_INVALID_HEADER, - BlockValidationResult::BLOCK_MUTATED, - BlockValidationResult::BLOCK_MISSING_PREV, - BlockValidationResult::BLOCK_INVALID_PREV, - BlockValidationResult::BLOCK_TIME_FUTURE, - BlockValidationResult::BLOCK_CHECKPOINT, - BlockValidationResult::BLOCK_HEADER_LOW_WORK}); - pdb.m_check_block_mock = FuzzedCheckBlock( - fail_check_block ? - std::optional{validation_result} : - std::nullopt); + bool segwit_active{fuzzed_data_provider.ConsumeBool()}; + + // Mock IsBlockMutated + bool fail_block_mutated{fuzzed_data_provider.ConsumeBool()}; + pdb.m_check_block_mutated_mock = FuzzedIsBlockMutated(fail_block_mutated); CBlock reconstructed_block; - auto fill_status{pdb.FillBlock(reconstructed_block, missing)}; + auto fill_status{pdb.FillBlock(reconstructed_block, missing, segwit_active)}; switch (fill_status) { case READ_STATUS_OK: assert(!skipped_missing); - assert(!fail_check_block); + assert(!fail_block_mutated); assert(block->GetHash() == reconstructed_block.GetHash()); break; - case READ_STATUS_CHECKBLOCK_FAILED: [[fallthrough]]; case READ_STATUS_FAILED: - assert(fail_check_block); + assert(fail_block_mutated); break; case READ_STATUS_INVALID: break; diff --git a/src/util/trace.h b/src/util/trace.h index 3deefeade3..ab005dd8bc 100644 --- a/src/util/trace.h +++ b/src/util/trace.h @@ -9,6 +9,13 @@ #ifdef ENABLE_TRACING +// Workaround for https://gcc.gnu.org/bugzilla/show_bug.cgi?id=103395 +// systemtap 4.6 on 32-bit ARM triggers internal compiler error +// (this workaround is included in systemtap 4.7+) +#if defined(__arm__) +# define STAP_SDT_ARG_CONSTRAINT g +#endif + // Setting SDT_USE_VARIADIC lets systemtap (sys/sdt.h) know that we want to use // the optional variadic macros to define tracepoints. #define SDT_USE_VARIADIC 1 diff --git a/test/functional/p2p_compactblocks.py b/test/functional/p2p_compactblocks.py index 437bd173f2..0fcd19c2c6 100755 --- a/test/functional/p2p_compactblocks.py +++ b/test/functional/p2p_compactblocks.py @@ -568,6 +568,42 @@ class CompactBlocksTest(BitcoinTestFramework): test_node.send_and_ping(msg_block(block)) assert_equal(int(node.getbestblockhash(), 16), block.sha256) + # Multiple blocktxn responses will cause a node to get disconnected. + def test_multiple_blocktxn_response(self, test_node): + node = self.nodes[0] + utxo = self.utxos[0] + + block = self.build_block_with_transactions(node, utxo, 2) + + # Send compact block + comp_block = HeaderAndShortIDs() + comp_block.initialize_from_block(block, prefill_list=[0], use_witness=True) + test_node.send_and_ping(msg_cmpctblock(comp_block.to_p2p())) + absolute_indexes = [] + with p2p_lock: + assert "getblocktxn" in test_node.last_message + absolute_indexes = test_node.last_message["getblocktxn"].block_txn_request.to_absolute() + assert_equal(absolute_indexes, [1, 2]) + + # Send a blocktxn that does not succeed in reconstruction, triggering + # getdata fallback. + msg = msg_blocktxn() + msg.block_transactions = BlockTransactions(block.sha256, [block.vtx[2]] + [block.vtx[1]]) + test_node.send_and_ping(msg) + + # Tip should not have updated + assert_equal(int(node.getbestblockhash(), 16), block.hashPrevBlock) + + # We should receive a getdata request + test_node.wait_for_getdata([block.sha256], timeout=10) + assert test_node.last_message["getdata"].inv[0].type == MSG_BLOCK or \ + test_node.last_message["getdata"].inv[0].type == MSG_BLOCK | MSG_WITNESS_FLAG + + # Send the same blocktxn and assert the sender gets disconnected. + with node.assert_debug_log(['previous compact block reconstruction attempt failed']): + test_node.send_message(msg) + test_node.wait_for_disconnect() + def test_getblocktxn_handler(self, test_node): node = self.nodes[0] # bitcoind will not send blocktxn responses for blocks whose height is @@ -961,6 +997,12 @@ class CompactBlocksTest(BitcoinTestFramework): self.log.info("Testing handling of invalid compact blocks...") self.test_invalid_tx_in_compactblock(self.segwit_node) + self.log.info("Testing handling of multiple blocktxn responses...") + self.test_multiple_blocktxn_response(self.segwit_node) + + # The previous test will lead to a disconnection. Reconnect before continuing. + self.segwit_node = self.nodes[0].add_p2p_connection(TestP2PConn()) + self.log.info("Testing invalid index in cmpctblock message...") self.test_invalid_cmpctblock_message()