#19461 multiprocess: Add bitcoin-gui -ipcconnect option

Adds an `-ipcconnect` command-line option to `bitcoin-gui` for multiprocess builds, enabling it to connect to an existing `bitcoin-node` process over IPC instead of spawning a new child process. By default (`-ipcconnect=auto`), it attempts to connect to `<datadir>/sockets/node.sock` if present and falls back to spawning a dedicated node process.

Problem: In multiprocess builds, `bitcoin-gui` automatically spawns and owns its own `bitcoin-node` subprocess that shuts down when the GUI closes. Users cannot keep a long-running background node daemon and attach or detach GUI instances independently.

Evidence of importance:

• PR description: 'This allows the GUI to be started and stopped independently of the node. By default with this change, bitcoin-gui will check if a <datadir>/sockets/node.sock socket exists and try to connect to that. If that doesn't work, it will spawn a new node process and start up the same way it did before this PR.'
• PR description: 'Part of the process separation project (issue #28722)'

Scope: This PR is stacked on #10102, #19460, and #29409. Only the single top commit (b6e97e431a) is unique to this PR; the remaining 27 commits and bulk of the +4419/-662 diff belong to the underlying stack and libmultiprocess subtree updates.

Risk of a mistake: medium (gui, other). Mistakes in IPC socket connection or initialization could cause GUI startup failures, unhandled exceptions during disconnection, or silent ignoring of node configuration options.

Changed since the previous assessment: Rebased on updated versions of the base stack (#10102, #19460, #29409), incorporating upstream libmultiprocess subtree merges and btcsignals callback destruction updates, while leaving the final commit unchanged.

Ready · Review #10102 first

Stacked on #10102; the base PR's changes are included in this diff.

Waiting on (from the thread read):

• author: investigating external signer crash reported by Sjors 2023-05-05

Blocked

objection that needs a change, nobody has replied (Sjors)

Thread notes: Added author's rebase announcement; no new claims or support raised.

Objections, suggestions, and questions:

Support:

• laanwj (member) (Concept ACK, 2020-07-09) [read]: option help reviewed, -ipcconnect SGTM as option name reminding of -rpcconnect in -cli
• meshcollider (contributor) (Concept ACK, 2020-09-10): (no reason given) [not substantive]
• Sjors (member) (2023-02-11) [tested]: Other than that, it seems to work. Cool stuff!

Participants:

• laanwj (member, support, 2 statements 2020-07-09 to 2020-07-09): Concept ACK; supported -ipcconnect option name
• maflcko (member, neutral, 2 statements 2020-07-09 to 2025-03-18): commented on command line help parsing; noted CI failure
• meshcollider (contributor, support, 1 statements 2020-09-10 to 2020-09-10): Concept ACK
• Sjors (member, objection, 4 statements 2021-04-27 to 2023-05-05): tested GUI over SSH tunnel; reported assertion failures when using external signer or PSBTs over IPC
• ClaraBara22 (none, neutral, 1 statements 2022-03-21 to 2022-03-21): approved without substantive review
• jimhashhq (none, objection, 2 statements 2025-03-27 to 2025-04-08): tested connection; reported node crash when GUI connects without -disablewallet to node started with -disablewallet

Depends on: #10102, #19460, #29409

Enables:

• #28722

Based on (shares commits with): #10102, #19460, #29409

236 lines under test/bench/ci.

• src/ipc/capnp/wallet.capnp +305/-0
• src/ipc/capnp/wallet.cpp +251/-0
• src/ipc/capnp/common-types.h +248/-2
• src/ipc/libmultiprocess/src/mp/util.cpp +216/-31
• src/ipc/capnp/chain.cpp +226/-0
• src/ipc/capnp/node.capnp +214/-0
• src/ipc/libmultiprocess/test/mp/test/test.cpp +208/-6
• src/ipc/libmultiprocess/test/mp/test/connect_tests.cpp +212/-0
• src/ipc/capnp/chain.capnp +207/-0
• src/ipc/libmultiprocess/src/mp/proxy.cpp +106/-47
• src/ipc/capnp/chain-types.h +128/-0
• src/ipc/libmultiprocess/test/mp/test/listen_tests.cpp +48/-77
• src/ipc/libmultiprocess/include/mp/proxy-io.h +79/-42
• src/ipc/capnp/node-types.h +110/-0
• src/ipc/capnp/node.cpp +97/-0
• src/ipc/libmultiprocess/src/mp/gen.cpp +48/-45
• src/init/bitcoin-wallet-ipc.cpp +85/-0
• src/ipc/libmultiprocess/test/mp/test/unixlistener.h +84/-0
• src/ipc/libmultiprocess/include/mp/util.h +63/-15
• src/util/btcsignals.h +65/-13
• src/test/btcsignals_tests.cpp +74/-0
• src/ipc/capnp/wallet-types.h +70/-0
• src/ipc/capnp/common.capnp +66/-0
• src/ipc/libmultiprocess/test/mp/test/foo.h +56/-1
• src/ipc/libmultiprocess/include/mp/proxy-types.h +40/-14
• src/ipc/libmultiprocess/include/mp/proxy.h +30/-23
• src/ipc/capnp/common.cpp +51/-0
• src/qt/bitcoin.cpp +35/-8
• src/ipc/libmultiprocess/cmake/compat_config.cmake +0/-42
• src/ipc/capnp/init.cpp +40/-0
• src/ipc/capnp/node.h +40/-0
• src/ipc/libmultiprocess/include/mp/type-number.h +24/-15
• test/functional/test_framework/test_node.py +31/-8
• src/ipc/capnp/wallet.h +36/-0
• src/init/bitcoin-node.cpp +23/-12
• src/ipc/libmultiprocess/ci/scripts/ci.sh +34/-1
• src/ipc/libmultiprocess/.github/workflows/ci.yml +19/-14
• src/ipc/libmultiprocess/CMakeLists.txt +24/-9
• src/ipc/libmultiprocess/test/mp/test/spawn_tests.cpp +28/-5
• test/functional/interface_ipc.py +32/-0
• src/init/bitcoin-gui.cpp +9/-20
• src/ipc/CMakeLists.txt +28/-0
• src/ipc/libmultiprocess/test/mp/test/foo.capnp +28/-0
• src/ipc/capnp/common.h +27/-0
• src/ipc/libmultiprocess/include/mp/type-chrono.h +25/-2
• src/ipc/libmultiprocess/test/mp/test/common.h +27/-0
• src/ipc/capnp/init-types.h +25/-0
• src/ipc/libmultiprocess/include/mp/type-struct.h +12/-12
• src/bitcoin-wallet.cpp +19/-3
• src/ipc/libmultiprocess/cmake/iwyu-wrapper.sh +22/-0
• src/ipc/libmultiprocess/include/mp/type-interface.h +10/-10
• src/ipc/libmultiprocess/shell.nix +13/-6
• src/ipc/libmultiprocess/include/mp/type-context.h +15/-3
• src/ipc/capnp/handler.capnp +17/-0
• CMakeLists.txt +14/-0
• src/ipc/capnp/context.h +14/-0
• src/ipc/libmultiprocess/.clang-tidy +12/-2
• src/node/interfaces.cpp +10/-4
• src/ipc/capnp/init.capnp +13/-0
• src/ipc/libmultiprocess/.github/workflows/bitcoin-core-ci.yml +8/-5
• src/ipc/libmultiprocess/example/calculator.cpp +4/-9
• src/ipc/libmultiprocess/example/printer.cpp +4/-9
• src/CMakeLists.txt +9/-3
• src/ipc/libmultiprocess/example/example.cpp +7/-5
• src/ipc/libmultiprocess/include/mp/type-char.h +9/-3
• test/functional/combine_logs.py +12/-0
• test/functional/feature_block.py +10/-2
• test/functional/wallet_multiwallet.py +6/-6
• src/wallet/wallettool.cpp +5/-6
• src/interfaces/node.h +5/-5
• src/ipc/capnp/handler-types.h +10/-0
• src/ipc/interfaces.cpp +6/-4
• src/ipc/libmultiprocess/ci/scripts/run.sh +6/-4
• src/ipc/libmultiprocess/doc/versions.md +8/-2
• src/ipc/libmultiprocess/include/mp/type-map.h +6/-4
• src/init.cpp +6/-3
• src/interfaces/chain.h +5/-4
• src/qt/bitcoin.h +7/-2
• src/ipc/libmultiprocess/ci/configs/netbsd.bash +1/-7
• src/ipc/libmultiprocess/cmake/pthread_checks.cmake +8/-0
• src/ipc/libmultiprocess/include/mp/type-set.h +4/-4
• src/ipc/libmultiprocess/include/mp/type-threadmap.h +4/-4
• src/ipc/libmultiprocess/include/mp/type-unordered-set.h +4/-4
• src/ipc/libmultiprocess/include/mp/type-vector.h +4/-4
• src/wallet/init.cpp +8/-0
• test/functional/wallet_fast_rescan.py +4/-4
• test/functional/wallet_resendwallettransactions.py +4/-4
• src/ipc/libmultiprocess/ci/configs/olddeps.bash +5/-2
• src/ipc/libmultiprocess/test/mp/test/foo-types.h +7/-0
• doc/multiprocess.md +6/-0
• src/bitcoind.cpp +4/-2
• src/init/basic.cpp +3/-3
• src/ipc/libmultiprocess/ci/configs/newdeps.bash +6/-0
• src/ipc/libmultiprocess/doc/design.md +3/-3
• src/ipc/libmultiprocess/doc/usage.md +6/-0
• src/qt/initexecutor.cpp +3/-3
• src/qt/test/apptests.h +5/-1
• src/util/result.h +5/-1
• src/wallet/imports.h +5/-1
• src/wallet/wallettool.h +5/-1
• test/functional/wallet_groups.py +3/-3
• src/interfaces/init.h +4/-1
• src/interfaces/ipc.h +4/-1
• src/ipc/context.h +5/-0
• src/ipc/libmultiprocess/include/mp/type-data.h +2/-3
• src/wallet/types.h +5/-0
• src/init.h +2/-2
• src/interfaces/wallet.h +3/-1
• src/ipc/libmultiprocess/ci/configs/sanitize.bash +2/-2
• src/ipc/libmultiprocess/ci/scripts/config.sh +2/-2
• src/ipc/libmultiprocess/include/mp/type-string.h +3/-1
• src/qt/test/apptests.cpp +2/-2
• src/qt/walletcontroller.cpp +2/-2
• src/init/common.cpp +2/-1
• src/net.h +3/-0
• src/net_processing.h +3/-0
• src/wallet/coincontrol.h +3/-0
• test/lint/git-subtree-check.sh +2/-1
• contrib/devtools/circular-dependencies.py +1/-1
• doc/design/libraries.md +1/-1
• src/bitcoin-cli.cpp +1/-1
• src/init/common.h +1/-1
• src/ipc/libmultiprocess/ci/configs/default.bash +1/-1
• src/ipc/libmultiprocess/ci/configs/freebsd.bash +1/-1
• src/ipc/libmultiprocess/ci/configs/gnu32.bash +1/-1
• src/ipc/libmultiprocess/ci/configs/llvm.bash +1/-1
• src/ipc/libmultiprocess/ci/configs/macos.bash +1/-1
• src/ipc/libmultiprocess/ci/configs/openbsd.bash +1/-1
• src/ipc/libmultiprocess/cmake/TargetCapnpSources.cmake +1/-1
• src/ipc/libmultiprocess/doc/install.md +1/-1
• src/ipc/libmultiprocess/include/mp/type-function.h +1/-1
• src/ipc/libmultiprocess/include/mp/version.h +1/-1
• src/ipc/stub.cpp +1/-1
• src/netbase.h +2/-0
• src/qt/initexecutor.h +1/-1
• src/rpc/request.h +2/-0
• src/test/util/setup_common.cpp +1/-1
• src/wallet/interfaces.cpp +1/-1
• src/wallet/wallet.h +2/-0
• test/functional/wallet_createwallet.py +1/-1
• test/functional/wallet_descriptor.py +1/-1
• test/functional/wallet_encryption.py +1/-1
• test/functional/wallet_importdescriptors.py +1/-1
• test/functional/wallet_reorgsrestore.py +1/-1
• test/functional/wallet_startup.py +1/-1
• src/ipc/libmultiprocess/ci/README.md +1/-0
• src/ipc/libmultiprocess/include/mp/config.h.in +1/-0
• src/ipc/libmultiprocess/test/CMakeLists.txt +1/-0
• test/functional/feature_config_args.py +1/-0
• test/functional/feature_taproot.py +1/-0
• test/functional/test_framework/ipc_util.py +1/-0
• test/functional/wallet_transactiontime_rescan.py +1/-0

The short text the ranking pass compares across PRs.

Adds an -ipcconnect option to bitcoin-gui in multiprocess builds, allowing the GUI to connect over IPC to an already-running bitcoin-node daemon instead of spawning a new node subprocess. By default (-ipcconnect=auto), the GUI checks for a socket at sockets/node.sock and connects if available, falling back to spawning a node if not. This allows users of experimental multiprocess builds to start and stop GUI instances independently of the background node. The PR is part of the process separation project (#28722) and is stacked on #10102, #19460, and #29409, containing only a single unique commit.

P2 · new feature

Allows `bitcoin-gui` to start and stop independently of `bitcoin-node` over IPC, marking substantial progress toward running the GUI and node as separate processes (issue #28722).

Membership: Adds the `-ipcconnect` option to `bitcoin-gui` and manages socket connections to `bitcoin-node` over IPC.

Factors: security/stability 0, bug 0, performance 0, user value 2, leverage 2