DOCSEARCHbyAlgolia
Submit Docs

Bitcoin Hardware Wallet Interface (HWI)

repository·master·Indexed 20 days ago

https://github.com/bitcoin-core/hwi

A Python library and CLI tool providing a standardized interface for interacting with various Bitcoin hardware wallets. HWI abstracts device-specific driver logic into a unified API, supporting devices such as Ledger Nano S/X, Trezor, BitBox02, Coldcard, Blockstream Jade, and KeepKey. It includes a support matrix for features like xpub retrieval and message signing, and provides tools for building standalone binaries and PyPI distributions.

Tokens
15.9K
Snippets
51
Records
70
Agent score
69%

What's inside hwi

  1. Overview of the Python Jade Library

    master
    The Python Jade Library is a stripped-down version of the official Blockstream Jade Python library (based on tag 1.0.33). It is designed to provide the core functionality required for interacting with Jade hardware wallets while reducing complexity by removing the BLE (Bluetooth Low Energy) module to minimize transitive dependencies.

  2. Overview of the Python Trezor Library

    master

    The Python Trezor Library used in HWI is a stripped-down version of the official python-trezor library. It is specifically optimized for HWI by removing unnecessary features and focusing on core Bitcoin functionality.

    Key differences from the official library include:

    • No Altcoin Support: Support for non-Bitcoin assets has been removed.
    • Reduced API Surface: Functions not required by HWI have been removed.
    • Firmware Version Control: You can optionally disable firmware version checks when calling methods via TrezorClient.call.

  3. Overview of the Python BitBox02 Library

    master

    This library is a modified version of the official BitBox02 Python library, specifically adapted for use within the hwi ecosystem. It is based on the py-bitbox02-7.0.0 tag from the official BitBoxSwiss firmware repository.

    Key modifications include:

    • Internalized Base58: Uses a built-in base58 implementation instead of requiring an external base58 library.
    • Relative Imports: Uses relative imports between the bitbox02 and communication modules to ensure the library functions correctly without requiring manual module installation of dependencies.

  5. Overview of the Ledger Bitcoin application client

    master
    The ledger_bitcoin client is a stripped-down version of the official Ledger Bitcoin application client. It is designed to interface with Ledger hardware wallets specifically for Bitcoin operations. It has been modified from the original LedgerHQ implementation to use relative imports from the HWI library (such as common.py, key.py, psbt.py, etc.) to avoid code duplication and ensure compatibility with the HWI ecosystem.

  6. Overview of the Coldcard Library (ckcc)

    master

    The Coldcard Library is a stripped-down and modified version of the official ckcc-protocol library. It is designed to provide the core protocol functionality for interacting with Coldcard hardware wallets while minimizing dependencies and footprint.

    Key modifications from the original ckcc-protocol include:

    • The CLI (Command Line Interface) has been removed.
    • The pycoin dependency has been removed.

  7. Overview of LedgerCOMM

    master

    LedgerCOMM is a modified version of the official LedgerHQ ledgercomm library. It is specifically adapted to support Python 3.6 environments, whereas the official library requires Python 3.8 or higher.

    Key modifications include:

    • Removal of typing.Literal to ensure compatibility with older Python versions.
    • Removal of the CLI tool.
    • Transition to using relative imports instead of the ledgercomm package name.
    • Enhanced Transport capabilities by adding hid_path, allowing users to specify a specific HID path instead of relying on the library to automatically select the first available device.

  8. Configure address types and derivation paths in HWI

    master

    HWI supports different BIP derivation paths based on the address type requested. When using Bitcoin Core descriptors, HWI follows BIP 44, 49, and 84.

    Supported Address Types

    • Native SegWit (P2WPKH): Uses BIP 84. Default derivation: m/84h/0h/0h/0 (receiving) and m/84h/0h/0h/1 (change).
    • Legacy (P2PKH): Use --addr-type legacy. Uses BIP 44. Derivation: m/44h/0h/0h/0 (receiving) and m/44h/0h/0h/1 (change).
    • Nested SegWit (P2SH-P2WPKH): Use --addr-type sh_wit. Uses BIP 49. Derivation: m/49h/0h/0h/0 (receiving) and m/49h/0h/0h/1 (change).

    Customization

    • Custom Paths: Use the --path option to specify a specific derivation path.
    • Bitcoin Core Integration: To ensure getnewaddress in Bitcoin Core matches these types, you must set -addresstype=p2sh-segwit and -changetype=p2sh-segwit in your bitcoin.conf or via CLI.
    # Example of requesting a specific address type via HWI CLI
./hwi.py --addr-type legacy ...

# Example of requesting a custom derivation path
./hwi.py --path "m/44'/0'/0'/0/0" ...

  10. Understand the HWI device support policy

    master

    HWI follows a strict support policy to ensure security and transparency. For a hardware device to be supported, it must meet the following criteria:

    1. Open Source Firmware: Devices must use open source firmware as much as possible. Entirely closed-source devices are rejected, though closed-source components (like a secure element under NDA) are permitted.
    2. Publicly Documented Protocol: The communication protocol must be publicly documented. This is ideally achieved by providing both documentation and a Python library for the protocol.
    3. Testing and Maintenance: Ideally, a simulator or emulator must be available for automated testing. Alternatively, the vendor must provide a formal promise to maintain and support the device.

    When support is dropped:

    • If vendor maintenance or support is withdrawn.
    • If continuous issues arise and the vendor fails to provide updates.
    • If the device no longer receives security updates and known vulnerabilities exist.

  11. HWI Architecture and Usage Models

    master

    HWI provides two primary ways to interact with hardware wallets:

    1. Python Library (hwilib): For Python-based software, you can import and use the library directly to implement hardware wallet support without writing device-specific drivers.
    2. CLI Tool (hwi.py): For software written in other languages, you can execute the hwi command line tool and parse the JSON output from stdout to interact with hardware wallets.

  12. Use the HWI command line interface

    master

    HWI is primarily operated via the command line. You can interact with it using the hwi command directly if installed, or by using the self-contained HWI binaries provided with third-party software. To view all available commands, options, and subcommands, run the command with the --help flag.

    hwi --help