DEVICE_ONBOARDING.md

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.
• Async transport crate: contains concrete HID, TCP, and emulator transports for the sans-I/O interpreters.
• CLI crate: shows how discovery, command parsing, and async device execution are wired together.

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

• Local code (gated behind the bitbox cargo feature):
  • Interpreter
  • Bitcoin request/response builders
  • Protobuf messages
  • Noise pairing state
  • U2F-HID framing
  • PSBT signing
  • Wallet policy handling
  • E2E docs
• Upstream references:
  • BitBox02 firmware and simulator
  • bitbox-api-rs
• Onboarding notes:
  • BitBox02 traffic rides U2F-HID framing and is encrypted with a Noise channel established during pairing. The simulator auto-confirms pairing.
  • Descriptor-based address display re-supplies the wallet policy each time via DeviceContext::BitBox; the device holds no persistent policy token like a Ledger HMAC.
  • Wallet policies share the miniscript WalletPolicy extraction in bhwi/src/policy.rs with the Ledger backend.
  • Use these commands for emulator-backed tests:

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

Ledger

• Local code:
  • Interpreter
  • APDU helpers
  • Command encoders
  • Wallet policy encoding
  • PSBT serialization
  • E2E docs
• Upstream references:
  • Ledger Bitcoin app
  • Bitcoin app client tests
  • Speculos emulator
  • Ledger app-builder image
  • Ledger Live open-app reference
• Onboarding notes:
  • Ledger uses APDUs and device-requested client callbacks for wallet policy merkle data and PSBT signing data.
  • Keep wallet policy formatting aligned with BIP 388 and the Ledger Bitcoin app's expected key-info strings.
  • Use these commands for emulator-backed tests:

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

Coldcard

• Local code:
  • Interpreter
  • API request/response encoding
  • Encryption engine
  • E2E docs
• Upstream references:
  • Coldcard firmware
  • ckcc-protocol
  • Coldcard simulator README
• Onboarding notes:
  • Coldcard commands are encrypted after the initial public-key exchange.
  • The simulator exposes /tmp/ckcc-simulator.sock; the local device ID also records this emulator path.
  • Use these commands for emulator-backed tests:

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

Jade

• Local code:
  • Interpreter
  • CBOR RPC types
  • TCP transport
  • E2E docs
• Upstream references:
  • Blockstream Jade
  • Jade API documentation
  • Jade Python client
  • Blind pin server
• Onboarding notes:
  • Jade uses CBOR-RPC requests over serial/TCP.
  • Authentication may require forwarding a device-provided HTTP request to the pinserver before completing the device handshake.
  • Use these commands for emulator-backed tests:

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:
  • Interpreter
  • Protocol messages
  • Generated protobuf bindings
  • Protocol v1 transport
• Upstream references:
  • Trezor firmware
  • Protobuf definitions
  • trezorlib Python client
• 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.
  • 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

Adding a Device

• Start from bhwi/src/common.rs and map each supported common command to the device protocol.
• 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.