From 258bda80c009a25d1f1bdeffccf9ed1ffde29cb2 Mon Sep 17 00:00:00 2001 From: Ryan Ofsky Date: Tue, 15 Apr 2025 10:19:27 -0400 Subject: [PATCH] doc: Mention bitcoin wrapper executable in documentation --- doc/JSON-RPC-interface.md | 2 ++ doc/README.md | 3 +++ doc/build-osx.md | 4 ++++ doc/build-unix.md | 1 + doc/cjdns.md | 2 ++ doc/external-signer.md | 4 ++++ doc/managing-wallets.md | 2 ++ doc/multiprocess.md | 15 ++++++++++----- doc/multisig-tutorial.md | 2 ++ doc/offline-signing-tutorial.md | 2 ++ doc/tor.md | 4 ++++ doc/zmq.md | 2 ++ 12 files changed, 38 insertions(+), 5 deletions(-) diff --git a/doc/JSON-RPC-interface.md b/doc/JSON-RPC-interface.md index 10d8ee52ebe..e7f085a377a 100644 --- 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 index 79ca53ce763..0959c6c7f04 100644 --- 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 index b30568b50cd..08e2e54c2aa 100644 --- 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 index d8857d43a79..591b229ecb7 100644 --- 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 index 031cd1978bb..35fe87adfac 100644 --- 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 index 1468e852ef6..c1b6b20ce01 100644 --- 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 index d24c4139802..0e052bd8dbb 100644 --- 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 index 33c5a44aa82..5a91b513de5 100644 --- 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 index 57d3d8d6722..0c39bc6c9ca 100644 --- 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 index 522303b032e..2b21af2441a 100644 --- 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/tor.md b/doc/tor.md index 30c2381049a..ef31bcc87dd 100644 --- 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 index c04f6db21b7..9637144d502 100644 --- 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.