Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion .github/actions/build-bitcoind/action.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
name: Build bitcoind
description: Build bitcoind with depends.
inputs:
repo-url:
description: Bitcoin Core repository to build
required: false
default: https://github.com/bitcoin/bitcoin.git
branch:
description: Branch of the repository to build
required: false
default: master
runs:
using: composite
steps:
Expand All @@ -19,11 +28,13 @@ runs:
- shell: bash
env:
CCACHE_MAXSIZE: '20M'
BITCOIN_REPO_URL: ${{ inputs.repo-url }}
BITCOIN_REPO_BRANCH: ${{ inputs.branch }}
run: |
ccache --zero-stats
cd test; ./setup_environment.sh --bitcoind; cd ..
ccache --show-stats --verbose
tar -czf bitcoind.tar.gz test/work/bitcoin/build/bin/bitcoind
tar -czf bitcoind.tar.gz test/work/bitcoin/build/bin/bitcoind test/work/bitcoin/build/bin/bitcoin-node

- uses: actions/cache/save@v4
if: github.event_name != 'pull_request' && steps.ccache-cache.outputs.cache-hit != 'true'
Expand Down
44 changes: 44 additions & 0 deletions .github/actions/test-core-ipc/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
name: Test Core IPC
description: Run the Bitcoin Core IPC signer test against an installed HWI wheel.
runs:
using: composite
steps:
# The install-sim action uses poetry for some devices.
- shell: bash
run: |
pip install poetry

- uses: actions/download-artifact@v8
with:
name: dist
path: dist/

# Install the wheel with the ipc extra, so the test drives the packaged
# hwi rather than the source tree.
- name: Install (Wheel)
shell: bash
run: |
wheel=$(ls dist/*.whl)
pip install "${wheel}[ipc]"

- uses: actions/download-artifact@v8
with:
name: bitcoind

- shell: bash
run: |
tar -xvf bitcoind.tar.gz

- uses: ./.github/actions/install-sim
with:
device: ${{ matrix.device }}

- name: Run test
shell: bash
run: |
cd test; ./run_tests.py --${{ matrix.device }} --core-ipc-only --interface=cli --device-only; cd ..

- if: failure()
shell: bash
run: |
tail -v -n +1 test/*.std*
5 changes: 5 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -188,6 +188,11 @@ jobs:
steps:
- uses: actions/checkout@v7
- uses: ./.github/actions/build-bitcoind
with:
# The IPC signer test needs Bitcoin Core's external signer over IPC
# branch, which is not merged yet: bitcoin/bitcoin#TBD
repo-url: https://github.com/Sjors/bitcoin.git
branch: 2026/09/hwi-ipc

test-trezor-1:
uses: ./.github/workflows/device-test.yml
Expand Down
11 changes: 10 additions & 1 deletion .github/workflows/device-test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ on:

jobs:
test-device:
name: Python ${{ matrix.python-version }} ${{ matrix.device }} ${{ matrix.test.script || matrix.test.interface }}
name: Python ${{ matrix.python-version }} ${{ matrix.device }} ${{ matrix.test.core_ipc && format('Core IPC ({0})', matrix.test.core_ipc) || matrix.test.script || matrix.test.interface }}
runs-on: ${{ inputs.runs-on }}
timeout-minutes: 45
strategy:
Expand All @@ -32,6 +32,12 @@ jobs:
- {script: 'Wheel'}
- {script: 'Sdist'}
- {script: 'Bindist'}
# The Bitcoin Core IPC signer test gets one dedicated job per device,
# on the newest Python and against the wheel.
include:
- python-version: '3.14'
device: ${{ inputs.device }}
test: {core_ipc: 'Wheel'}
container: python:${{ matrix.python-version }}
steps:
- uses: actions/checkout@v7
Expand All @@ -41,3 +47,6 @@ jobs:
- name: run dist test
if: ${{ matrix.test.script }}
uses: ./.github/actions/test-dist
- name: run Core IPC test
if: ${{ matrix.test.core_ipc }}
uses: ./.github/actions/test-core-ipc
16 changes: 16 additions & 0 deletions hwilib/_cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,14 @@ def install_udev_rules_handler(args: argparse.Namespace) -> Dict[str, bool]:
def register_descriptor_handler(args: argparse.Namespace, client: HardwareWalletClient) -> Dict[str, str]:
return register_descriptor(client, args.name, args.descriptor)

def ipc_signer_handler(args: argparse.Namespace) -> Dict[str, Any]:
from ._ipc import ipc_signer_handler as run_ipc_signer
result: Dict[str, Any] = {}
with handle_errors(result=result):
run_ipc_signer(args)
result = {'success': True}
return result

class HWIHelpFormatter(argparse.ArgumentDefaultsHelpFormatter, argparse.RawDescriptionHelpFormatter):
pass

Expand Down Expand Up @@ -254,6 +262,10 @@ def get_parser() -> HWIArgumentParser:
register_descriptor_parser.add_argument("descriptor", help="The descriptor to register.")
register_descriptor_parser.set_defaults(func=register_descriptor_handler)

ipc_parser = subparsers.add_parser('ipc', help='Connect to a Bitcoin Core node IPC socket and serve as its external signer until the node disconnects')
ipc_parser.add_argument('--socket-path', help='Path to the unix socket the node listens on with -ipcbind. Defaults to node.sock in the default Bitcoin Core datadir of the chain given by --chain', default=None)
ipc_parser.set_defaults(func=ipc_signer_handler)

if sys.platform.startswith("linux"):
udevrules_parser = subparsers.add_parser('installudevrules', help='Install and load the udev rule files for the hardware wallet devices')
udevrules_parser.add_argument('--location', help='The path where the udev rules files will be copied', default='/etc/udev/rules.d/')
Expand Down Expand Up @@ -299,6 +311,10 @@ def process_commands(cli_args: List[str]) -> Any:
if command == 'enumerate':
return args.func(args)

# Serve as a Bitcoin Core external signer over IPC
if command == 'ipc':
return args.func(args)

# Install the devices udev rules for Linux
if command == 'installudevrules':
with handle_errors(msg="installudevrules failed:", result=result):
Expand Down
36 changes: 35 additions & 1 deletion hwilib/_gui.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,12 @@
import json
import logging
import sys
import threading
import time
from typing import Callable

from . import commands, __version__
from . import _ipc
from ._cli import HWIArgumentParser
from .errors import handle_errors, DEVICE_NOT_INITIALIZED
from .common import AddressType, Chain
Expand All @@ -27,7 +29,7 @@
exit(-1)

from PySide2.QtGui import QRegExpValidator
from PySide2.QtWidgets import QApplication, QDialog, QDialogButtonBox, QFileDialog, QLineEdit, QMessageBox, QMainWindow, QMenu
from PySide2.QtWidgets import QApplication, QDialog, QDialogButtonBox, QFileDialog, QLabel, QLineEdit, QMessageBox, QMainWindow, QMenu
from PySide2.QtCore import QCoreApplication, QRegExp, Signal, Slot

def do_command(f, *args, **kwargs):
Expand Down Expand Up @@ -321,6 +323,8 @@ def attestation_check(self, result: bool) -> None:
pass

class HWIQt(QMainWindow):
ipc_status_changed = Signal(str)

def __init__(self, passphrase=None, chain=Chain.MAIN, allow_emulators: bool = False):
super(HWIQt, self).__init__()
self.ui = Ui_MainWindow()
Expand Down Expand Up @@ -357,6 +361,36 @@ def __init__(self, passphrase=None, chain=Chain.MAIN, allow_emulators: bool = Fa

self.ui.enumerate_combobox.currentIndexChanged.connect(self.get_client_and_device_info)

self.ipc_status_label = QLabel()
self.statusBar().addPermanentWidget(self.ipc_status_label)
self.ipc_status_changed.connect(self.set_ipc_status)
self.start_ipc_signer_service()

@Slot(str)
def set_ipc_status(self, status):
logging.info(status)
self.ipc_status_label.setText(status)

def start_ipc_signer_service(self):
"""Serve as the external signer of a Bitcoin Core node over IPC, if
one is listening on the default socket path for our chain."""
if _ipc.capnp is None:
self.set_ipc_status('Core IPC: unavailable (install pycapnp)')
return
socket_path = _ipc.default_socket_path(self.chain)
self.set_ipc_status('Core IPC: connecting...')

def serve():
try:
_ipc.run_signer_service(
socket_path, self.passphrase, self.allow_emulators,
on_registered=lambda: self.ipc_status_changed.emit(f'Core IPC: connected ({socket_path})'))
self.ipc_status_changed.emit('Core IPC: disconnected')
except Exception as e:
self.ipc_status_changed.emit(f'Core IPC: not connected ({e})')

threading.Thread(target=serve, name='ipc-signer', daemon=True).start()

def clear_info(self):
self.ui.getxpub_button.setEnabled(False)
self.ui.signtx_button.setEnabled(False)
Expand Down
166 changes: 166 additions & 0 deletions hwilib/_ipc.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,166 @@
"""
Bitcoin Core IPC signer service
*******************************

Serve HWI as a Bitcoin Core external signer over Cap'n Proto IPC.

Bitcoin Core's ``bitcoin-node`` binary can listen on a unix socket with
``-ipcbind=unix``. This module connects to that socket and registers HWI as
the node's external signer backend, replacing the ``-signer=<cmd>`` model of
spawning ``hwi`` for every operation. See Bitcoin Core's
``doc/external-signer.md`` and the schemas in ``hwilib/ipc/schema``.

Each signer call resolves the device by fingerprint with a fresh client,
matching the behavior of one CLI invocation per operation. Expected failures
(device missing, user cancel) are reported in-band via the ``error``/
``result`` fields; an uncaught exception here reaches the node as a
transport error and makes it drop the registration.
"""

import argparse
import asyncio
import base64
import logging
import os
import sys
from pathlib import Path
from typing import Any, Callable, Dict, Optional

# Optional dependency: everything except serving works without it, so e.g.
# default_socket_path() stays importable in environments without the extra.
try:
import capnp # type: ignore
except ImportError:
capnp = None

from . import commands
from .common import Chain
from .errors import DEVICE_CONN_ERROR, UnavailableActionError, handle_errors
from .hwwclient import HardwareWalletClient

SCHEMA_DIR = Path(__file__).parent / "ipc" / "schema"


def default_socket_path(chain: Chain) -> str:
"""The default path of Bitcoin Core's -ipcbind=unix socket for this
platform and chain: <datadir>/<chain subdirectory>/node.sock."""
if sys.platform == "win32":
datadir = Path(os.environ["APPDATA"]) / "Bitcoin"
elif sys.platform == "darwin":
datadir = Path.home() / "Library" / "Application Support" / "Bitcoin"
else:
datadir = Path.home() / ".bitcoin"
subdir = {
Chain.MAIN: None,
Chain.TEST: "testnet3",
Chain.REGTEST: "regtest",
Chain.SIGNET: "signet",
Chain.TESTNET4: "testnet4",
}[chain]
if subdir is not None:
datadir = datadir / subdir
return str(datadir / "node.sock")


def load_schemas() -> Any:
imports = [str(SCHEMA_DIR)]
signer = capnp.load(str(SCHEMA_DIR / "signer.capnp"), imports=imports)
init = capnp.load(str(SCHEMA_DIR / "init.capnp"), imports=imports)
return init, signer


def make_signer_server(signer_schema: Any, password: str, allow_emulators: bool) -> Any:

class SignerServer(signer_schema.ExternalSignerService.Server): # type: ignore

def _with_client(self, fingerprint: str, chain_str: str, func: Callable[[HardwareWalletClient], Dict[str, Any]]) -> Dict[str, Any]:
"""Resolve the device by fingerprint, run func with a fresh
client, and close it. Mirrors one CLI invocation."""
result: Dict[str, Any] = {}
with handle_errors(result=result):
chain = Chain.argparse(chain_str)
if not isinstance(chain, Chain):
raise Exception(f"Invalid chain: {chain_str}")
client = commands.find_device(password=password, fingerprint=fingerprint, chain=chain, allow_emulators=allow_emulators)
if client is None:
return {"error": "Could not find device with specified fingerprint", "code": DEVICE_CONN_ERROR}
try:
result = func(client)
finally:
with handle_errors(result={}):
client.close()
return result

async def enumerate(self, chain, _context, **kwargs):
chain_enum = Chain.argparse(chain)
if not isinstance(chain_enum, Chain):
raise Exception(f"Invalid chain: {chain}")
devices = commands.enumerate(password=password, chain=chain_enum, allow_emulators=allow_emulators)
# The typed API carries no per-device error entries: skip
# devices which failed to report a fingerprint.
_context.results.result = [
{"fingerprint": d["fingerprint"], "name": d.get("model", "")}
for d in devices if d.get("fingerprint")
]

async def getDescriptors(self, fingerprint, chain, account, _context, **kwargs):
res = self._with_client(fingerprint, chain, lambda client: commands.getdescriptors(client, account))
r = _context.results
if "error" in res:
r.error = res["error"]
r.result = False
else:
r.receive = res["receive"]
r.internal = res["internal"]
r.result = True

async def displayAddress(self, fingerprint, chain, descriptor, _context, **kwargs):
res = self._with_client(fingerprint, chain, lambda client: commands.displayaddress(client, desc=descriptor))
r = _context.results
if "error" in res:
r.error = res["error"]
r.result = False
else:
r.address = res["address"]
r.result = True

async def signTransaction(self, fingerprint, chain, psbt, _context, **kwargs):
psbt_b64 = base64.b64encode(bytes(psbt)).decode("ascii")
res = self._with_client(fingerprint, chain, lambda client: commands.signtx(client, psbt_b64))
r = _context.results
if "error" in res:
r.error = res["error"]
r.result = False
else:
r.signedPsbt = base64.b64decode(res["psbt"])
r.result = True

return SignerServer


async def serve(socket_path: str, password: str, allow_emulators: bool, on_registered: Optional[Callable[[], None]] = None) -> None:
init_schema, signer_schema = load_schemas()
connection = await capnp.AsyncIoStream.create_unix_connection(socket_path)
client = capnp.TwoPartyClient(connection)
init = client.bootstrap().cast_as(init_schema.Init)
server_class = make_signer_server(signer_schema, password, allow_emulators)
await init.registerExternalSigner(server_class())
logging.info(f"Registered as external signer with the node at {socket_path}")
if on_registered is not None:
on_registered()
# Serve signer calls until the node disconnects.
await client.on_disconnect()
logging.info("Node disconnected, exiting")


def run_signer_service(socket_path: str, password: str, allow_emulators: bool, on_registered: Optional[Callable[[], None]] = None) -> None:
"""Connect to the node, register as its external signer and serve until
the node disconnects. Blocks the calling thread."""
if capnp is None:
raise UnavailableActionError("IPC support requires the pycapnp package. Install it with: pip install hwi[ipc]")
asyncio.run(capnp.run(serve(socket_path, password, allow_emulators, on_registered)))


def ipc_signer_handler(args: argparse.Namespace) -> None:
socket_path = args.socket_path or default_socket_path(args.chain)
run_signer_service(socket_path, args.password, args.allow_emulators)
Empty file added hwilib/ipc/__init__.py
Empty file.
Loading
Loading