public interface HardwareWalletClient extends Connectable
Interface to provide the following to applications:
A hardware wallet client acts as the bridge between the application and the device. It provides a common interface for sending messages to the device, and subscribes to events coming from the device.
Blocking implementations will block their thread of execution until a response is received.
Hardware wallet clients are tightly coupled to their respective wallet so are typically referenced statically in consuming applications.
Modifier and Type | Method and Description |
---|---|
com.google.common.base.Optional<MessageEvent> |
applySettings(String language,
String label)
Send the APPLY_SETTINGS message to the device.
|
com.google.common.base.Optional<MessageEvent> |
buttonAck()
Send the BUTTON_ACK message to the device in response to a BUTTON_REQUEST.
|
com.google.common.base.Optional<MessageEvent> |
cancel()
Send the CANCEL message to the device in response to a BUTTON_REQUEST, PIN_MATRIX_REQUEST or PASSPHRASE_REQUEST.
|
com.google.common.base.Optional<MessageEvent> |
changePIN(boolean remove)
Send the CHANGE_PIN message to the device.
|
com.google.common.base.Optional<MessageEvent> |
cipherKeyValue(int account,
org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose,
int index,
byte[] key,
byte[] keyValue,
boolean isEncrypting,
boolean askOnDecrypt,
boolean askOnEncrypt)
Send the CIPHER_KEY_VALUE_MESSAGE message to the device containing a key.
|
com.google.common.base.Optional<MessageEvent> |
clearSession()
Send the CLEAR_SESSION message to the device.
|
com.google.common.base.Optional<MessageEvent> |
decryptMessage(int account,
org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose,
int index,
byte[] message)
Send the DECRYPT_MESSAGE message to the device containing a message to decrypt.
|
com.google.common.base.Optional<MessageEvent> |
encryptMessage(byte[] pubKey,
byte[] message,
boolean displayOnly)
Send the ENCRYPT_MESSAGE message to the device containing a message to encrypt.
|
com.google.common.base.Optional<MessageEvent> |
entropyAck(byte[] entropy)
Send the ENTROPY_ACK message to the device in response to an ENTROPY_REQUEST.
|
com.google.common.base.Optional<MessageEvent> |
estimateTxSize(org.bitcoinj.core.Transaction tx)
Send the ESTIMATE_TX_SIZE message to the device to estimate the size of the transaction.
|
com.google.common.base.Optional<MessageEvent> |
firmwareErase()
Send the FIRMWARE_ERASE message to the device.
|
com.google.common.base.Optional<MessageEvent> |
firmwareUpload()
Send the FIRMWARE_UPLOAD message to the device.
|
com.google.common.base.Optional<MessageEvent> |
getAddress(int account,
org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose,
int index,
boolean showDisplay)
Send the GET_ADDRESS message to the device.
|
com.google.common.base.Optional<MessageEvent> |
getDeterministicHierarchy(List<org.bitcoinj.crypto.ChildNumber> childNumbers)
Send the GET_PUBLIC_KEY message to the device based on the given list of child numbers.
|
com.google.common.base.Optional<MessageEvent> |
getEntropy()
Send the ENTROPY message to the device.
|
com.google.common.base.Optional<MessageEvent> |
getPublicKey(int account,
org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose,
int index)
Send the GET_PUBLIC_KEY message to the device.
|
com.google.common.base.Optional<MessageEvent> |
initialise()
Reset device to default state and ask for device details
|
com.google.common.base.Optional<MessageEvent> |
loadDevice(String language,
String label,
String seedPhrase,
String pin)
Send the LOAD_DEVICE message to the device.
|
String |
name()
Assist downstream API consumers with identifying the source of events
|
com.google.common.base.Optional<MessageEvent> |
passphraseAck(String passphrase)
Send the PASSPHRASE_ACK message to the device in response to a PASSPHRASE_REQUEST.
|
com.google.common.base.Optional<MessageEvent> |
ping()
Send the PING message to the device
|
com.google.common.base.Optional<MessageEvent> |
pinMatrixAck(String pin)
Send the PIN_MATRIX_ACK message to the device in response to a PIN_MATRIX_REQUEST.
|
com.google.common.base.Optional<MessageEvent> |
recoverDevice(String language,
String label,
int wordCount,
boolean passphraseProtection,
boolean pinProtection)
Send the RECOVER_DEVICE message to the device to start the workflow of asking user for specific words from their seed.
|
com.google.common.base.Optional<MessageEvent> |
resetDevice(String language,
String label,
boolean displayRandom,
boolean pinProtection,
int strength)
Send the RESET_DEVICE message to the device.
|
com.google.common.base.Optional<MessageEvent> |
signMessage(int account,
org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose,
int index,
byte[] message)
Send the SIGN_MESSAGE message to the device containing a message to sign.
|
com.google.common.base.Optional<MessageEvent> |
signTx(org.bitcoinj.core.Transaction tx)
Send the SIGN_TX message to the device.
|
com.google.common.base.Optional<MessageEvent> |
simpleSignTx(org.bitcoinj.core.Transaction tx)
Send the SIMPLE_SIGN_TX message to the device.
|
com.google.common.base.Optional<MessageEvent> |
txAck(TxRequest txRequest,
org.bitcoinj.core.Transaction tx,
Map<Integer,com.google.common.collect.ImmutableList<org.bitcoinj.crypto.ChildNumber>> receivingAddressPathMap,
Map<org.bitcoinj.core.Address,com.google.common.collect.ImmutableList<org.bitcoinj.crypto.ChildNumber>> changeAddressPathMap)
Send the TX_ACK message to the device.
|
boolean |
verifyFeatures(Features features)
Verify the contents of the Features message in accordance with client-specific rules (e.g.
|
com.google.common.base.Optional<MessageEvent> |
verifyMessage(org.bitcoinj.core.Address address,
byte[] signature,
byte[] message)
Send the VERIFY_MESSAGE message to the device containing a signed message to verify.
|
com.google.common.base.Optional<MessageEvent> |
wipeDevice()
Send the WIPE_DEVICE message to the device.
|
com.google.common.base.Optional<MessageEvent> |
wordAck(String word)
Send the WORD_ACK message to the device containing a word from the seed phrase.
|
attach, connect, disconnect, hardDetach, softDetach
com.google.common.base.Optional<MessageEvent> initialise()
Reset device to default state and ask for device details
Send the INITIALISE message to the device.
Expected response events are:
com.google.common.base.Optional<MessageEvent> ping()
Send the PING message to the device
Expected response events are:
com.google.common.base.Optional<MessageEvent> clearSession()
Send the CLEAR_SESSION message to the device.
Clear session (removes cached PIN, passphrase, etc).
Expected response events are:
com.google.common.base.Optional<MessageEvent> changePIN(boolean remove)
Send the CHANGE_PIN message to the device. The device will respond by showing a secure PIN selection screen and asking the user to verify accordingly.
Expected response events are:
remove
- True if the PIN should be removedcom.google.common.base.Optional<MessageEvent> wipeDevice()
Send the WIPE_DEVICE message to the device. The device will respond by cancelling its pending action and clearing the screen. It will also wipe all sensitive data and settings back to factory defaults.
Expected response events are:
com.google.common.base.Optional<MessageEvent> firmwareErase()
Send the FIRMWARE_ERASE message to the device.
Expected response events are:
com.google.common.base.Optional<MessageEvent> firmwareUpload()
Send the FIRMWARE_UPLOAD message to the device.
Expected response events are:
com.google.common.base.Optional<MessageEvent> getEntropy()
Send the ENTROPY message to the device. The device will respond by providing some random data from its internal hardware random number generator.
Expected response events are:
com.google.common.base.Optional<MessageEvent> loadDevice(String language, String label, String seedPhrase, String pin)
Send the LOAD_DEVICE message to the device. The device will overwrite any existing private keys and replace them based on the seed phrase provided.
Expected response events are:
language
- The language codelabel
- The label to display below the logo (e.g "Fred")seedPhrase
- The seed phrase provided by the user in the clearpin
- The personal identification number (PIN) in the clearcom.google.common.base.Optional<MessageEvent> resetDevice(String language, String label, boolean displayRandom, boolean pinProtection, int strength)
Send the RESET_DEVICE message to the device. The device will perform a full reset, generating a new seed and asking the user for new settings (PIN etc). This is typically needed when a device is first un-boxed.
Expected response events are:
language
- The language code (e.g. "english")label
- The label to display below the logo (e.g "Fred")displayRandom
- True if the device should display the entropy generated by the device before asking for additional entropypinProtection
- True if the device should use PIN protectionstrength
- The strength of the seed in bits (default is 128)com.google.common.base.Optional<MessageEvent> recoverDevice(String language, String label, int wordCount, boolean passphraseProtection, boolean pinProtection)
Send the RECOVER_DEVICE message to the device to start the workflow of asking user for specific words from their seed.
Expected response events are:
language
- The language codelabel
- The label to displaywordCount
- The number of words in the seedpassphraseProtection
- True if the device should use passphrase protectionpinProtection
- True if the device should use PIN protectioncom.google.common.base.Optional<MessageEvent> wordAck(String word)
Send the WORD_ACK message to the device containing a word from the seed phrase.
Expected response events are:
word
- A word from the seed phrasecom.google.common.base.Optional<MessageEvent> signTx(org.bitcoinj.core.Transaction tx)
Send the SIGN_TX message to the device. Behind the scenes the device will response with a series of TxRequests in order to build up the overall transaction. This client takes care of all the chatter leaving a final response condition. This allows transactions of arbitrary size to be created.
Expected response events are:
tx
- The Bitcoinj transaction providing all the necessary information (will be modified)com.google.common.base.Optional<MessageEvent> simpleSignTx(org.bitcoinj.core.Transaction tx)
Send the SIMPLE_SIGN_TX message to the device. This will use the supplied transaction object and attempt to deliver it to the device in a single request. This limits the size of the transaction but simplifies the call.
Expected response events are:
tx
- The Bitcoinj transaction providing all the necessary information (will be modified)com.google.common.base.Optional<MessageEvent> txAck(TxRequest txRequest, org.bitcoinj.core.Transaction tx, Map<Integer,com.google.common.collect.ImmutableList<org.bitcoinj.crypto.ChildNumber>> receivingAddressPathMap, Map<org.bitcoinj.core.Address,com.google.common.collect.ImmutableList<org.bitcoinj.crypto.ChildNumber>> changeAddressPathMap)
Send the TX_ACK message to the device. This contains a description of an input or output depending on the contents of an earlier TX_REQUEST message.
Expected response events are:
txRequest
- The transaction request describing what is requiredtx
- The Bitcoinj transaction providing all the necessary information (will be modified)receivingAddressPathMap
- The receiving address path map (keyed on input index and providing deterministic path to receiving address)changeAddressPathMap
- The change address path map (keyed on Address and providing deterministic path to change address)com.google.common.base.Optional<MessageEvent> pinMatrixAck(String pin)
Send the PIN_MATRIX_ACK message to the device in response to a PIN_MATRIX_REQUEST.
Implementers are expected to show a PIN matrix on the UI.
Expected response events are:
pin
- The PIN as entered from the PIN matrix (obfuscated)com.google.common.base.Optional<MessageEvent> passphraseAck(String passphrase)
Send the PASSPHRASE_ACK message to the device in response to a PASSPHRASE_REQUEST.
Implementers are expected to show a passphrase dialog on the UI.
Expected response events are:
passphrase
- The passphrase as entered by the user (not obfuscated)com.google.common.base.Optional<MessageEvent> cancel()
Send the CANCEL message to the device in response to a BUTTON_REQUEST, PIN_MATRIX_REQUEST or PASSPHRASE_REQUEST.
Expected response events are:
com.google.common.base.Optional<MessageEvent> buttonAck()
Send the BUTTON_ACK message to the device in response to a BUTTON_REQUEST. The calling software will then block (appropriately for its UI) until the device responds/fails.
Expected response events are:
com.google.common.base.Optional<MessageEvent> applySettings(String language, String label)
Send the APPLY_SETTINGS message to the device.
Change language and/or label of the device
Expected response events are:
language
- The language codelabel
- The labelcom.google.common.base.Optional<MessageEvent> getAddress(int account, org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose, int index, boolean showDisplay)
Send the GET_ADDRESS message to the device. The device will respond by providing an address calculated based on the BIP-44 deterministic wallet approach from the master node.
Expected response events are:
account
- The plain account number (0 gives maximum compatibility)keyPurpose
- The key purpose (RECEIVE_FUNDS,CHANGE,REFUND,AUTHENTICATION etc)index
- The plain index of the required addressshowDisplay
- True if the device should display the same address to allow the user to verify no tampering has occurred (recommended).com.google.common.base.Optional<MessageEvent> getPublicKey(int account, org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose, int index)
Send the GET_PUBLIC_KEY message to the device. The device will respond by providing a public key calculated based on the BIP-44 deterministic wallet approach from the master node.
Expected response events are:
account
- The plain account number (0 gives maximum compatibility)keyPurpose
- The key purpose (RECEIVE_FUNDS,CHANGE,REFUND,AUTHENTICATION etc)index
- The plain index of the required addresscom.google.common.base.Optional<MessageEvent> getDeterministicHierarchy(List<org.bitcoinj.crypto.ChildNumber> childNumbers)
Send the GET_PUBLIC_KEY message to the device based on the given list of child numbers. The device will respond by providing an extended public key (xpub) calculated based on the BIP-44 deterministic wallet approach from the master node.
Expected response events are:
childNumbers
- The list of child numbers to explore (some of which may be hardened)com.google.common.base.Optional<MessageEvent> entropyAck(byte[] entropy)
Send the ENTROPY_ACK message to the device in response to an ENTROPY_REQUEST. This allows the device to obtain additional entropy to offset potentially compromised hardware.
Expected response events are:
entropy
- The additional entropycom.google.common.base.Optional<MessageEvent> signMessage(int account, org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose, int index, byte[] message)
Send the SIGN_MESSAGE message to the device containing a message to sign.
Expected response events are:
com.google.common.base.Optional<MessageEvent> verifyMessage(org.bitcoinj.core.Address address, byte[] signature, byte[] message)
Send the VERIFY_MESSAGE message to the device containing a signed message to verify.
Expected response events are:
address
- The address to use for verificationsignature
- The signaturemessage
- The message to signcom.google.common.base.Optional<MessageEvent> encryptMessage(byte[] pubKey, byte[] message, boolean displayOnly)
Send the ENCRYPT_MESSAGE message to the device containing a message to encrypt.
Expected response events are:
pubKey
- The public key to use for encryptionmessage
- The message to encryptdisplayOnly
- True if the output is for display onlycom.google.common.base.Optional<MessageEvent> decryptMessage(int account, org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose, int index, byte[] message)
Send the DECRYPT_MESSAGE message to the device containing a message to decrypt.
Expected response events are:
account
- The plain account number (0 gives maximum compatibility)keyPurpose
- The key purpose (RECEIVE_FUNDS,CHANGE,REFUND,AUTHENTICATION etc)index
- The plain index of the required addressmessage
- The message to decryptcom.google.common.base.Optional<MessageEvent> cipherKeyValue(int account, org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose, int index, byte[] key, byte[] keyValue, boolean isEncrypting, boolean askOnDecrypt, boolean askOnEncrypt)
Send the CIPHER_KEY_VALUE_MESSAGE message to the device containing a key. The device will encrypt or decrypt the value of the given key.
Expected response events are:
account
- The plain account number (0 gives maximum compatibility)keyPurpose
- The key purpose (RECEIVE_FUNDS,CHANGE,REFUND,AUTHENTICATION etc)index
- The plain index of the required addresskey
- The cipher key (e.g. "Some text")keyValue
- The key value (e.g. "[16 bytes of random data]")isEncrypting
- True if encryptingaskOnDecrypt
- True if device should ask on decryptingaskOnEncrypt
- True if device should ask on encryptingcom.google.common.base.Optional<MessageEvent> estimateTxSize(org.bitcoinj.core.Transaction tx)
Send the ESTIMATE_TX_SIZE message to the device to estimate the size of the transaction. This behaves exactly like the SignTx in that it uses the TxRequest mechanism to describe the transaction.
Expected response events are:
tx
- The Bitcoinj transaction providing all the necessary information (will not be modified)boolean verifyFeatures(Features features)
Verify the contents of the Features message in accordance with client-specific rules (e.g. firmware)
features
- The Features from the deviceString name()
Assist downstream API consumers with identifying the source of events
Copyright © 2013–2018 Bitcoin Solutions Ltd. All rights reserved.