Skip to content

DEVICE_ONBOARDING.md

Latest commit

 

History

History
233 lines (208 loc) · 10.6 KB

DEVICE_ONBOARDING.md

File metadata and controls

233 lines (208 loc) · 10.6 KB
Raw

Device Onboarding References

Use this page to collect the upstream projects and protocol documentation needed to add or maintain support for a hardware wallet in BHWI.

BHWI Model

  • README: explains the sans-I/O interpreter model used by device integrations.
  • VISION: gives the project context and the reason BHWI keeps protocol logic separate from transport I/O.
  • Common command interface: lists the device-agnostic commands, responses, recipients, and device-specific context.
  • Protocol framing: defines the Channel trait and the per-device wire framing carried over it.
  • Transport crate: implements Channel over HID, WebUSB, serial, TCP, and emulator sockets, and enumerates the devices found.
  • CLI crate: shows how command parsing and output formatting sit on top of it.

Shared Bitcoin Standards

  • BIP 32: hierarchical deterministic keys and derivation paths.
  • BIP 44: account structure used by standard descriptors.
  • BIP 174: PSBT v0.
  • BIP 370: PSBT v2, required by the Ledger Bitcoin app.
  • BIP 380 and BIP 388: output descriptors and wallet policies.
  • Miniscript: policy language used for descriptor-backed wallet support.
  • Bitcoin Core HWI: reference behavior for common hardware wallet commands.
  • Async-HWI: earlier Wizardsardine Rust implementation that informed and inspired BHWI.

BitBox02

nix run .#bitbox
nix develop .#bitbox -c cargo test -p bhwi-e2e-bitbox -- --test-threads=1

Ledger

nix run .#ledger
nix develop .#ledger -c cargo test -p bhwi-e2e-ledger -- --test-threads=1

Coldcard

nix run .#coldcard
nix develop .#coldcard -c cargo test -p bhwi-e2e-coldcard -- --test-threads=1

Jade

nix run .#jade-pinserver
nix run .#jade
nix run .#jade-init
nix develop .#jade -c cargo test -p bhwi-e2e-jade -- --test-threads=1

Trezor

  • Local code (gated behind the trezor cargo feature):
  • Upstream references:
  • Onboarding notes:
    • Messages are protobuf framed as ##, a big-endian message type and length, then chunked into 64 byte reports prefixed with 0x3f. The framing is the same over HID, WebUSB and the UDP emulator, so one transport serves all three.
    • The generated bindings are vendored and regenerated from the pinned firmware revision, matching the revision the emulators are built from.
    • GetPublicKey sets ignore_xpub_magic so the device returns standard xpub/tpub rather than SLIP-132 prefixes.
    • The Trezor One and the Model T run different firmware codebases, so each model has its own emulator.
    • The browser transports split the same way the native ones do. The Trezor One is an HID device, so it uses bhwi-wasm/src/webhid.rs with the vendor usage page 0xff00. The Model T exposes a USB vendor interface instead, so it uses bhwi-wasm/src/webusb.rs.
    • Use these commands for emulator-backed tests:
nix run .#trezor-one   # or nix run .#trezor-t
nix run .#trezor-init
nix develop .#trezor -c cargo test -p bhwi-e2e-trezor -- --test-threads=1

KeepKey

  • Local code (gated behind the keepkey cargo feature):
  • Upstream references:
  • Onboarding notes:
    • KeepKey shares Trezor's protocol-v1 report framing, but it is a separate profile with its own protobuf deltas, command rules, USB IDs, emulator, host passphrase behavior, management state machine, and capability limits.
    • Native discovery uses HID 2b24:0001 on usage page 0xff00, WebUSB 2b24:0002, and emulator UDP 127.0.0.1:11044; the debug link is UDP 11045.
    • PIN entry and recovery-character entry are host interactions. Restore uses KeepKey firmware's character cipher; pinned Python HWI has no working reference-tested restore flow.
    • The recursively pinned firmware and separately pinned nanopb tree are copied to a writable cache and patched with HWI's test/data/keepkey-build.patch at the firmware root, test/data/keepkey-googletest.patch at the firmware's deps/googletest root, and test/data/nanopb-deprecated-mode.patch at the nanopb root. BHWI additionally applies nix/patches/keepkey/cmake-minimum.patch at the firmware root. The emulator outputs are currently x86_64-linux only.
    • Use these commands for emulator-backed tests:
nix run .#keepkey
nix run .#keepkey-init
nix develop .#keepkey -c cargo test -p bhwi-e2e-keepkey -- --test-threads=1
nix run .#hwi-upstream-keepkey

Adding a Device

  • Start from bhwi/src/common.rs and map each supported common command to the device protocol.
  • Declare a cargo feature for the device in bhwi (gating its module, adapter, and any device-specific dependencies) and forward it from bhwi-async.
  • Keep protocol encoding, response parsing, authentication, and intermediate device callbacks inside the device interpreter.
  • Keep USB, serial, TCP, browser, and emulator I/O in transport crates or clients, not in the interpreter.
  • Add emulator or simulator notes under docs/ when an upstream test target is available.
  • Add focused unit tests for protocol encoding/parsing and e2e coverage for commands that need an emulator.