Merge bitcoin/bitcoin#31375: multiprocess: Add bitcoin wrapper executable

achow101 · achow101 · commit 012f347685b8 · 2025-05-27T12:38:19.000-07:00
a5ac43d doc: Add release notes describing bitcoin wrapper executable (Ryan Ofsky) 258bda8 doc: Mention bitcoin wrapper executable in documentation (Ryan Ofsky) d2739d7 build: add bitcoin.exe to windows installer (Sjors Provoost) ba649c0 ci: Run multiprocess tests through wrapper executable (Ryan Ofsky) 29bdd74 test: Support BITCOIN_CMD environment variable (Ryan Ofsky) 9c8c688 multiprocess: Add bitcoin wrapper executable (Ryan Ofsky) 5076d20 util: Add cross-platform ExecVp and GetExePath functions (Ryan Ofsky) Pull request description: Intended to make bitcoin command line features more discoverable and allow installing new multiprocess binaries in libexec/ instead of bin/ so they don't cause confusion. Idea and implementation of this were discussed in bitcoin/bitcoin#30983. --- Initial implementation of this feature is deliberately minimal so the UX can evolve in response to feedback and there are not too many details to debate and discuss in a single PR. But many improvements are possible or planned: - Adding manpage and bash completions. - Showing nicer error messages that detect if an executable isn't installed and suggest how to fix [(comment)](bitcoin/bitcoin#31375 (comment)) - Showing wrapper command lines in subcommand in help output [(comment)](bitcoin/bitcoin#31375 (comment)). This could be done conditionally as suggested in the comment or be unconditional. - Showing wrapper command lines in subcommand error output. There is a bitcoin-cli error pointed out in [(comment)](bitcoin/bitcoin#31375 (comment)) that is needlessly confusing. - Integrating help so `bitcoin help subcommand` invokes `bitcoin subcommand -h`. `bitcoin -h subcommand` should also be supported and be equivalent [(comment)](bitcoin/bitcoin#31375 (comment)) - Adding support for `bitcoin-util` subcommands. Ideal interface would probably be more like `bitcoin grind` not `bitcoin util grind` but this has been punted for now. Supporting subcommands directly would require some ArgsManager modifications - Adding a dedicated python functional test for the wrapper. Right now there is some CI coverage by setting the `BITCOIN_CMD` variable, but this doesn't cover things like the help output and version output, and support for different directory layouts. - Better `--multiprocess` (`-m`) / `--monolithic` (`-M`) default selection. Right now, default is monolithic but it probably makes sense to chose more intelligently depending on whether -ipc options are enabled and what binaries are available. - Maybe parsing `bitcoin.conf` and supporting options to control wrapper behavior like custom locations or preferences or aliases. - Better command command line usability. Allow combining short options like (`-ah`). Allow fuzzy matching of subcommands or suggestions if you misspell. (suggested by stickies in review club) - Not directly related to this PR but `bitcoin-cli named` implementation used by the wrapper should do a better job disambiguating named arguments from base64 arguments ending in = as pointed out in [(comment)](bitcoin/bitcoin#31375 (comment)) --- This PR is part of the [process separation project](bitcoin/bitcoin#28722). A review club meeting for it took place in https://bitcoincore.reviews/31375 ACKs for top commit: Sjors: utACK a5ac43d achow101: ACK a5ac43d vasild: ACK a5ac43d theStack: ACK a5ac43d ismaelsadeeq: fwiw my last review implied an ACK a5ac43d hodlinator: ACK a5ac43d Tree-SHA512: 570e6a4ff8bd79ef6554da3d01f36c0a7c6d2dd7dace8f8732eca98f4a8bc2284474a9beadeba783114fe2f3dd08b2041b3da7753bae0b7f881ec50668cb821f
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -94,6 +94,7 @@ endif()
 #=============================
 include(CMakeDependentOption)
 # When adding a new option, end the <help_text> with a full stop for consistency.
+option(BUILD_BITCOIN_BIN "Build bitcoin executable." ON)
 option(BUILD_DAEMON "Build bitcoind executable." ON)
 option(BUILD_GUI "Build bitcoin-qt executable." OFF)
 option(BUILD_CLI "Build bitcoin-cli executable." ON)
@@ -202,6 +203,7 @@ target_link_libraries(core_interface INTERFACE
 
 if(BUILD_FOR_FUZZING)
   message(WARNING "BUILD_FOR_FUZZING=ON will disable all other targets and force BUILD_FUZZ_BINARY=ON.")
+  set(BUILD_BITCOIN_BIN OFF)
   set(BUILD_DAEMON OFF)
   set(BUILD_CLI OFF)
   set(BUILD_TX OFF)
@@ -647,6 +649,7 @@ message("\n")
 message("Configure summary")
 message("=================")
 message("Executables:")
+message("  bitcoin ............................. ${BUILD_BITCOIN_BIN}")
 message("  bitcoind ............................ ${BUILD_DAEMON}")
 if(BUILD_DAEMON AND ENABLE_IPC)
   set(bitcoin_daemon_status ON)
diff --git a/ci/test/00_setup_env_i686_multiprocess.sh b/ci/test/00_setup_env_i686_multiprocess.sh
@@ -20,4 +20,4 @@ export BITCOIN_CONFIG="\
  -DCMAKE_CXX_COMPILER='clang++;-m32' \
  -DAPPEND_CPPFLAGS='-DBOOST_MULTI_INDEX_ENABLE_SAFE_MODE' \
 "
-export BITCOIND=bitcoin-node  # Used in functional tests
+export BITCOIN_CMD="bitcoin -m" # Used in functional tests
diff --git a/cmake/module/GenerateSetupNsi.cmake b/cmake/module/GenerateSetupNsi.cmake
@@ -7,6 +7,7 @@ function(generate_setup_nsi)
   set(abs_top_builddir ${PROJECT_BINARY_DIR})
   set(CLIENT_URL ${PROJECT_HOMEPAGE_URL})
   set(CLIENT_TARNAME "bitcoin")
+  set(BITCOIN_WRAPPER_NAME "bitcoin")
   set(BITCOIN_GUI_NAME "bitcoin-qt")
   set(BITCOIN_DAEMON_NAME "bitcoind")
   set(BITCOIN_CLI_NAME "bitcoin-cli")
diff --git a/cmake/module/Maintenance.cmake b/cmake/module/Maintenance.cmake
@@ -23,7 +23,7 @@ function(add_maintenance_targets)
     return()
   endif()
 
-  foreach(target IN ITEMS bitcoind bitcoin-qt bitcoin-cli bitcoin-tx bitcoin-util bitcoin-wallet test_bitcoin bench_bitcoin)
+  foreach(target IN ITEMS bitcoin bitcoind bitcoin-qt bitcoin-cli bitcoin-tx bitcoin-util bitcoin-wallet test_bitcoin bench_bitcoin)
     if(TARGET ${target})
       list(APPEND executables $<TARGET_FILE:${target}>)
     endif()
@@ -43,7 +43,7 @@ function(add_maintenance_targets)
 endfunction()
 
 function(add_windows_deploy_target)
-  if(MINGW AND TARGET bitcoin-qt AND TARGET bitcoind AND TARGET bitcoin-cli AND TARGET bitcoin-tx AND TARGET bitcoin-wallet AND TARGET bitcoin-util AND TARGET test_bitcoin)
+  if(MINGW AND TARGET bitcoin AND TARGET bitcoin-qt AND TARGET bitcoind AND TARGET bitcoin-cli AND TARGET bitcoin-tx AND TARGET bitcoin-wallet AND TARGET bitcoin-util AND TARGET test_bitcoin)
     find_program(MAKENSIS_EXECUTABLE makensis)
     if(NOT MAKENSIS_EXECUTABLE)
       add_custom_target(deploy
@@ -59,6 +59,7 @@ function(add_windows_deploy_target)
     add_custom_command(
       OUTPUT ${PROJECT_BINARY_DIR}/bitcoin-win64-setup.exe
       COMMAND ${CMAKE_COMMAND} -E make_directory ${PROJECT_BINARY_DIR}/release
+      COMMAND ${CMAKE_STRIP} $<TARGET_FILE:bitcoin> -o ${PROJECT_BINARY_DIR}/release/$<TARGET_FILE_NAME:bitcoin>
       COMMAND ${CMAKE_STRIP} $<TARGET_FILE:bitcoin-qt> -o ${PROJECT_BINARY_DIR}/release/$<TARGET_FILE_NAME:bitcoin-qt>
       COMMAND ${CMAKE_STRIP} $<TARGET_FILE:bitcoind> -o ${PROJECT_BINARY_DIR}/release/$<TARGET_FILE_NAME:bitcoind>
       COMMAND ${CMAKE_STRIP} $<TARGET_FILE:bitcoin-cli> -o ${PROJECT_BINARY_DIR}/release/$<TARGET_FILE_NAME:bitcoin-cli>
diff --git a/contrib/guix/security-check.py b/contrib/guix/security-check.py
@@ -126,6 +126,9 @@ def check_ELF_FORTIFY(binary) -> bool:
     # bitcoin-util does not currently contain any fortified functions
     if 'Bitcoin Core bitcoin-util utility version ' in binary.strings:
         return True
+    # bitcoin wrapper does not currently contain any fortified functions
+    if '--monolithic' in binary.strings:
+        return True
 
     chk_funcs = set()
 
diff --git a/doc/JSON-RPC-interface.md b/doc/JSON-RPC-interface.md
@@ -62,6 +62,8 @@ bitcoin-cli -named createwallet wallet_name=mywallet load_on_startup=true
 bitcoin-cli -named createwallet mywallet load_on_startup=true
 ```
 
+`bitcoin rpc` can also be substituted for `bitcoin-cli -named`, and is a newer alternative.
+
 ## Versioning
 
 The RPC interface might change from one major version of Bitcoin Core to the
diff --git a/doc/README.md b/doc/README.md
@@ -17,6 +17,9 @@ Unpack the files into a directory and run:
 
 - `bin/bitcoin-qt` (GUI) or
 - `bin/bitcoind` (headless)
+- `bin/bitcoin` (wrapper command)
+
+The `bitcoin` command supports subcommands like `bitcoin gui`, `bitcoin node`, and `bitcoin rpc` exposing different functionality. Subcommands can be listed with `bitcoin help`.
 
 ### Windows
 
diff --git a/doc/build-osx.md b/doc/build-osx.md
@@ -199,6 +199,10 @@ cmake --build build --target deploy
 Bitcoin Core should now be available at `./build/bin/bitcoind`.
 If you compiled support for the GUI, it should be available at `./build/bin/bitcoin-qt`.
 
+There is also a multifunction command line interface at `./build/bin/bitcoin`
+supporting subcommands like `bitcoin node`, `bitcoin gui`, `bitcoin rpc`, and
+others that can be listed with `bitcoin help`.
+
 The first time you run `bitcoind` or `bitcoin-qt`, it will start downloading the blockchain.
 This process could take many hours, or even days on slower than average systems.
 
diff --git a/doc/build-unix.md b/doc/build-unix.md
@@ -174,4 +174,5 @@ This example lists the steps necessary to setup and build a command line only di
     cmake --build build
     ctest --test-dir build
     ./build/bin/bitcoind
+    ./build/bin/bitcoin help
 
diff --git a/doc/cjdns.md b/doc/cjdns.md
@@ -113,3 +113,5 @@ To see which CJDNS peers your node is connected to, use `bitcoin-cli -netinfo 4`
 or the `getpeerinfo` RPC (i.e. `bitcoin-cli getpeerinfo`).
 
 You can use the `getnodeaddresses` RPC to fetch a number of CJDNS peers known to your node; run `bitcoin-cli help getnodeaddresses` for details.
+
+`bitcoin rpc` can also be substituted for `bitcoin-cli`.
diff --git a/doc/external-signer.md b/doc/external-signer.md
@@ -14,6 +14,8 @@ Start Bitcoin Core:
 $ bitcoind -signer=../HWI/hwi.py
 ```
 
+`bitcoin node` can also be substituted for `bitcoind`.
+
 ### Device setup
 
 Follow the hardware manufacturers instructions for the initial device setup, as well as their instructions for creating a backup. Alternatively, for some devices, you can use the `setup`, `restore` and `backup` commands provided by [HWI](https://github.com/bitcoin-core/HWI).
@@ -40,6 +42,8 @@ Create a wallet, this automatically imports the public keys:
 $ bitcoin-cli createwallet "hww" true true "" true true true
 ```
 
+`bitcoin rpc` can also be substituted for `bitcoin-cli`.
+
 ### Verify an address
 
 Display an address on the device:
diff --git a/doc/managing-wallets.md b/doc/managing-wallets.md
@@ -15,6 +15,8 @@ The following command, for example, creates a descriptor wallet. More informatio
 $ bitcoin-cli createwallet "wallet-01"
 ```
 
+`bitcoin rpc` can also be substituted for `bitcoin-cli`.
+
 By default, wallets are created in the `wallets` folder of the data directory, which varies by operating system, as shown below. The user can change the default by using the `-datadir` or `-walletdir` initialization parameters.
 
 | Operating System | Default wallet directory                                    |
diff --git a/doc/multiprocess.md b/doc/multiprocess.md
@@ -25,8 +25,8 @@ make -C depends NO_QT=1 MULTIPROCESS=1
 HOST_PLATFORM="x86_64-pc-linux-gnu"
 cmake -B build --toolchain=depends/$HOST_PLATFORM/toolchain.cmake
 cmake --build build
-build/bin/bitcoin-node -regtest -printtoconsole -debug=ipc
-BITCOIND=$(pwd)/build/bin/bitcoin-node build/test/functional/test_runner.py
+build/bin/bitcoin -m node -regtest -printtoconsole -debug=ipc
+BITCOIN_CMD="bitcoin -m" build/test/functional/test_runner.py
 ```
 
 The `cmake` build will pick up settings and library locations from the depends directory, so there is no need to pass `-DENABLE_IPC=ON` as a separate flag when using the depends system (it's controlled by the `MULTIPROCESS=1` option).
@@ -41,6 +41,11 @@ By default when `-DENABLE_IPC=ON` is enabled, the libmultiprocess sources at [..
 
 ## Usage
 
-`bitcoin-node` is a drop-in replacement for `bitcoind`, and `bitcoin-gui` is a drop-in replacement for `bitcoin-qt`, and there are no differences in use or external behavior between the new and old executables. But internally after [#10102](https://github.com/bitcoin/bitcoin/pull/10102), `bitcoin-gui` will spawn a `bitcoin-node` process to run P2P and RPC code, communicating with it across a socket pair, and `bitcoin-node` will spawn `bitcoin-wallet` to run wallet code, also communicating over a socket pair. This will let node, wallet, and GUI code run in separate address spaces for better isolation, and allow future improvements like being able to start and stop components independently on different machines and environments.
-[#19460](https://github.com/bitcoin/bitcoin/pull/19460) also adds a new `bitcoin-node` `-ipcbind` option and a `bitcoind-wallet` `-ipcconnect` option to allow new wallet processes to connect to an existing node process.
-And [#19461](https://github.com/bitcoin/bitcoin/pull/19461) adds a new `bitcoin-gui` `-ipcconnect` option to allow new GUI processes to connect to an existing node process.
+Recommended way to use multiprocess binaries is to invoke `bitcoin` CLI like `bitcoin -m node -debug=ipc` or `bitcoin -m gui -printtoconsole -debug=ipc`.
+
+When the `-m` (`--multiprocess`) option is used the `bitcoin` command will execute multiprocess binaries instead of monolithic ones (`bitcoin-node` instead of `bitcoind`, and `bitcoin-gui` instead of `bitcoin-qt`). The multiprocess binaries can also be invoked directly, but this is not recommended as they may change or be renamed in the future, and they are not installed in the PATH.
+
+The multiprocess binaries currently function the same as the monolithic binaries, except they support an `-ipcbind` option.
+
+In the future, after [#10102](https://github.com/bitcoin/bitcoin/pull/10102) they will have other differences. Specifically `bitcoin-gui` will spawn a `bitcoin-node` process to run P2P and RPC code, communicating with it across a socket pair, and `bitcoin-node` will spawn `bitcoin-wallet` to run wallet code, also communicating over a socket pair. This will let node, wallet, and GUI code run in separate address spaces for better isolation, and allow future improvements like being able to start and stop components independently on different machines and environments. [#19460](https://github.com/bitcoin/bitcoin/pull/19460) also adds a new `bitcoin-wallet -ipcconnect` option to allow new wallet processes to connect to an existing node process.
+And [#19461](https://github.com/bitcoin/bitcoin/pull/19461) adds a new `bitcoin-gui -ipcconnect` option to allow new GUI processes to connect to an existing node process.
diff --git a/doc/multisig-tutorial.md b/doc/multisig-tutorial.md
@@ -31,6 +31,8 @@ do
 done
 ```
 
+`bitcoin rpc` can also be substituted for `bitcoin-cli`.
+
 Extract the xpub of each wallet. To do this, the `listdescriptors` RPC is used. By default, Bitcoin Core single-sig wallets are created using path `m/44'/1'/0'` for PKH, `m/84'/1'/0'` for WPKH, `m/49'/1'/0'` for P2WPKH-nested-in-P2SH and `m/86'/1'/0'` for P2TR based accounts. Each of them uses the chain 0 for external addresses and chain 1 for internal ones, as shown in the example below.
 
 ```
diff --git a/doc/offline-signing-tutorial.md b/doc/offline-signing-tutorial.md
@@ -34,6 +34,8 @@ We are going to first create an `offline_wallet` on the offline host. We will th
 }
 ```
 
+`bitcoin rpc` can also be substituted for `bitcoin-cli`.
+
 > [!NOTE]
 > The use of a passphrase is crucial to encrypt the wallet.dat file. This encryption ensures that even if an unauthorized individual gains access to the offline host, they won't be able to access the wallet's contents. Further details about securing your wallet can be found in  [Managing the Wallet](https://github.com/bitcoin/bitcoin/blob/master/doc/managing-wallets.md#12-encrypting-the-wallet)
 
diff --git a/doc/release-notes-31375.md b/doc/release-notes-31375.md
@@ -0,0 +1,11 @@
+New command line interface
+--------------------------
+
+A new `bitcoin` command line tool has been added to make features more
+discoverable and convenient to use. The `bitcoin` tool just calls other
+executables and does not implement any functionality on its own.  Specifically
+`bitcoin node` is a synonym for `bitcoind`, `bitcoin gui` is a synonym for
+`bitcoin-qt`, and `bitcoin rpc` is a synonym for `bitcoin-cli -named`. Other
+commands and options can be listed with `bitcoin help`. The new tool does not
+replace other tools, so all existing commands should continue working and there
+are no plans to deprecate them.
diff --git a/doc/tor.md b/doc/tor.md
@@ -27,6 +27,8 @@ e.g. for `-onlynet=onion`.
 
 You can use the `getnodeaddresses` RPC to fetch a number of onion peers known to your node; run `bitcoin-cli help getnodeaddresses` for details.
 
+`bitcoin rpc` can also be substituted for `bitcoin-cli`.
+
 ## 1. Run Bitcoin Core behind a Tor proxy
 
 The first step is running Bitcoin Core behind a Tor proxy. This will already anonymize all
@@ -64,6 +66,8 @@ In a typical situation, this suffices to run behind a Tor proxy:
 
     ./bitcoind -proxy=127.0.0.1:9050
 
+`bitcoin node` or `bitcoin gui` can also be substituted for `bitcoind`.
+
 ## 2. Automatically create a Bitcoin Core onion service
 
 Bitcoin Core makes use of Tor's control socket API to create and destroy
diff --git a/doc/zmq.md b/doc/zmq.md
@@ -87,6 +87,8 @@ For instance:
                -zmqpubrawtx=ipc:///tmp/bitcoind.tx.raw \
                -zmqpubhashtxhwm=10000
 
+`bitcoin node` or `bitcoin gui` can also be substituted for `bitcoind`.
+
 Notification types correspond to message topics (details in next section). For instance,
 for the notification `-zmqpubhashtx` the topic is `hashtx`. These options can also be
 provided in bitcoin.conf.
diff --git a/share/setup.nsi.in b/share/setup.nsi.in
@@ -73,6 +73,7 @@ Section -Main SEC0000
     SetOutPath $INSTDIR
     SetOverwrite on
     File @abs_top_builddir@/release/@BITCOIN_GUI_NAME@@EXEEXT@
+    File @abs_top_builddir@/release/@BITCOIN_WRAPPER_NAME@@EXEEXT@
     File /oname=COPYING.txt @abs_top_srcdir@/COPYING
     File /oname=readme.txt @abs_top_srcdir@/doc/README_windows.txt
     File @abs_top_srcdir@/share/examples/bitcoin.conf
@@ -129,6 +130,7 @@ done${UNSECTION_ID}:
 
 # Uninstaller sections
 Section /o -un.Main UNSEC0000
+    Delete /REBOOTOK $INSTDIR\@BITCOIN_WRAPPER_NAME@@EXEEXT@
     Delete /REBOOTOK $INSTDIR\@BITCOIN_GUI_NAME@@EXEEXT@
     Delete /REBOOTOK $INSTDIR\COPYING.txt
     Delete /REBOOTOK $INSTDIR\readme.txt
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
@@ -332,6 +332,12 @@ target_link_libraries(bitcoin_node
     $<TARGET_NAME_IF_EXISTS:USDT::headers>
 )
 
+# Bitcoin wrapper executable that can call other executables.
+if(BUILD_BITCOIN_BIN)
+  add_executable(bitcoin bitcoin.cpp)
+  target_link_libraries(bitcoin core_interface bitcoin_util)
+  install_binary_component(bitcoin)
+endif()
 
 # Bitcoin Core bitcoind.
 if(BUILD_DAEMON)
diff --git a/src/bitcoin.cpp b/src/bitcoin.cpp
diff --git a/src/util/CMakeLists.txt b/src/util/CMakeLists.txt
diff --git a/src/util/exec.cpp b/src/util/exec.cpp
diff --git a/src/util/exec.h b/src/util/exec.h
diff --git a/test/functional/test_framework/test_framework.py b/test/functional/test_framework/test_framework.py
diff --git a/test/functional/test_framework/test_node.py b/test/functional/test_framework/test_node.py

Original file line number	Diff line number	Diff line change
`@@ -20,4 +20,4 @@ export BITCOIN_CONFIG="\`
`20`	`20`	`-DCMAKE_CXX_COMPILER='clang++;-m32' \`
`21`	`21`	`-DAPPEND_CPPFLAGS='-DBOOST_MULTI_INDEX_ENABLE_SAFE_MODE' \`
`22`	`22`	`"`
`23`		`-export BITCOIND=bitcoin-node # Used in functional tests`
	`23`	`+export BITCOIN_CMD="bitcoin -m" # Used in functional tests`