Home

What is MBHD Hardware?

MBHD Hardware is a support library, written in Java, that simplifies the code required to talk to a Bitcoin hardware wallet and links it into the main MultiBit HD application. One example provided is for the popular Bitcoin Trezor device.

Why should I use it?

It will allow you to integrate your hardware wallet into the MultiBit HD wallet thus relieving you of the requirement to develop your own and focus on making hardware sales. In addition, much of the standard code to access a hardware wallet over USB HID and sockets is already written so you can leverage that in your project.

MultiBit Hardware will run standalone so you are under no obligation to integrate with MultiBit HD, but you can still use the library in your own projects to reduce the time to market.

How do I use it?

MBHD Hardware is built with Maven so you can just include the core as a dependency. Then you can choose which devices you want to support. At the moment the following devices are supported:

• Trezor V1 production (USB HID)
• Trezor "Shield" board on a Raspberry Pi (USB HID and socket)

More hardware wallets will come in time.

<!-- MultiBit Hardware Core -->
<dependency>
  <groupId>org.multibit.hd.hardware</groupId>
  <artifactId>core</artifactId>
  <version>0.0.1-SNAPSHOT</version>
</dependency>

A quick overview of the API

In general you will work with the following top-level objects:

• HardwareWallets - to provide you with a variety of different connection types (USB, Socket etc)
• HardwareWallet - the interface for the device allowing you to add a listener and send a message
• HardwareWalletEvent - received as a result of something occurring on the hardware (new message, USB signalling etc)
• HardwareWalletMessage - top-level class containing the protocol buffer message payload

That's pretty much it. Obviously you'll want to dig in deeper to HardwareWalletMessage but you won't need to learn much more than what is present in the examples module to get something up and running.

Some example code

Here's a typical example of the API in action:

// Use factory to statically bind the specific hardware wallet
TrezorV1HidHardwareWallet wallet = HardwareWallets.newUsbInstance(
  TrezorV1HidHardwareWallet.class,
  Optional.<Integer>absent(),
  Optional.<Integer>absent(),
  Optional.<String>absent()
);

// Wrap the hardware wallet in a suitable client to simplify message API
HardwareWalletClient client = new TrezorHardwareWalletClient(wallet);

// Wrap the client in a service for high level API suitable for downstream applications
hardwareWalletService = new HardwareWalletService(client);

// Register for the high level hardware wallet events
HardwareWalletService.hardwareWalletEventBus.register(this);

// Start the service
hardwareWalletService.start();

Subscribe to Guava events coming from the Trezor client as follows:

@Subscribe
public void onHardwareWalletEvent(HardwareWalletEvent event) {

  switch (event.getEventType()) {
    case SHOW_DEVICE_DETACHED:
      // Wait for device to be connected
      break;
    case SHOW_DEVICE_READY:
      // Get some information about the device
      Features features = hardwareWalletService.getContext().getFeatures().get();
      log.info("Features: {}", features);
      // Treat as end of example
      System.exit(0);
      break;
    case SHOW_DEVICE_FAILED:
      // Treat as end of example
      System.exit(-1);
      break;
  }

}

There are many examples in the examples module that guide you through various use cases such as:

• Attachment/detachment detection
• Wipe device to factory settings
• Load wallet with known seed phrase (insecure)
• Create wallet on device with PIN and external entropy (secure)
• Request address using chain code
• Request public key using chain code
• Sign transaction (integrates with Bitcoinj Transaction)
• Request cipher key (deterministically encrypt/decrypt based on a chain code)
• Sign message using chain code
• Change PIN

Where next?

If you have a production Trezor you'll want to review the example code. So long as you have your original seed phrase safe you will be able to restore your device, but we do recommend that you set aside a dedicated device for test and development purposes.

If you have a Raspberry Pi and a Shield device, you'll want to read Trezor on Raspberry Pi from scratch.

Take a look at the Pages and explore from there.