Default package

Get desktop application:
View/edit binary Protocol Buffers messages

* Response: Contains address derived from device private seed @prev GetAddress

• required string address = 1

  Coin address in Base58 encoding

* Request: change language and/or label of the device @next Success @next Failure @next ButtonRequest @next PinMatrixRequest

• optional string language = 1

• optional string label = 2

• optional bool use_passphrase = 3

• optional bytes homescreen = 4

* Request: Computer agrees to wait for HW button press @prev ButtonRequest

(message has no fields)

* Response: Device is waiting for HW button press. @next ButtonAck @next Cancel

• optional ButtonRequestType code = 1

• optional string data = 2

* Type of button request @used_in ButtonRequest

Used in: ButtonRequest

• ButtonRequest_Other = 1

• ButtonRequest_FeeOverThreshold = 2

• ButtonRequest_ConfirmOutput = 3

• ButtonRequest_ResetDevice = 4

• ButtonRequest_ConfirmWord = 5

• ButtonRequest_WipeDevice = 6

• ButtonRequest_ProtectCall = 7

• ButtonRequest_SignTx = 8

• ButtonRequest_FirmwareCheck = 9

• ButtonRequest_Address = 10

* Request: Abort last operation that required user interaction @prev ButtonRequest @prev PinMatrixRequest @prev PassphraseRequest

(message has no fields)

* Request: Starts workflow for setting/changing/removing the PIN @next ButtonRequest @next PinMatrixRequest

• optional bool remove = 1

  is PIN removal requested?

* Request: Ask device to encrypt or decrypt value of given key @next CipheredKeyValue @next Failure

• repeated uint32 address_n = 1

  BIP-32 path to derive the key from master node

• optional string key = 2

  key component of key:value

• optional bytes value = 3

  value component of key:value

• optional bool encrypt = 4

  are we encrypting (True) or decrypting (False)?

• optional bool ask_on_encrypt = 5

  should we ask on encrypt operation?

• optional bool ask_on_decrypt = 6

  should we ask on decrypt operation?

• optional bytes iv = 7

  initialization vector (will be computed if not set)

* Response: Return ciphered/deciphered value @prev CipherKeyValue

• optional bytes value = 1

  ciphered/deciphered value

* Request: clear session (removes cached PIN, passphrase, etc). @next Success

(message has no fields)

* Structure representing Coin @used_in Features

Used in: Features

• optional string coin_name = 1

• optional string coin_shortcut = 2

• optional uint32 address_type = 3

• optional uint64 maxfee_kb = 4

• optional uint32 address_type_p2sh = 5

* Plugin Configuration

• repeated string whitelist_urls = 1

  allowed URLs for plugin

• repeated string blacklist_urls = 2

  forbidden URLs for plugin

• required google.protobuf.FileDescriptorSet wire_protocol = 3

  compiled specification of write protocol (serialized using "protoc -o")

• repeated DeviceDescriptor known_devices = 4

  descriptors of allowed devices

• optional uint32 valid_until = 5

  expiration timestamp

* Request: "Press" the button on the device @next Success

• required bool yes_no = 1

  true for "Confirm", false for "Cancel"

* Request: Computer asks for device state @next DebugLinkState

(message has no fields)

* Response: Device wants host to log event

• optional uint32 level = 1

• optional string bucket = 2

• optional string text = 3

* Response: Device current state @prev DebugLinkGetState

• optional bytes layout = 1

  raw buffer of display

• optional string pin = 2

  current PIN, blank if PIN is not set/enabled

• optional string matrix = 3

  current PIN matrix

• optional string mnemonic = 4

  current BIP-39 mnemonic

• optional HDNodeType node = 5

  current BIP-32 node

• optional bool passphrase_protection = 6

  is node/mnemonic encrypted using passphrase?

• optional string reset_word = 7

  word on device display during ResetDevice workflow

• optional bytes reset_entropy = 8

  current entropy during ResetDevice workflow

• optional string recovery_fake_word = 9

  (fake) word on display during RecoveryDevice workflow

• optional uint32 recovery_word_pos = 10

  index of mnemonic word the device is expecting during RecoveryDevice workflow

* Request: Ask device to restart

(message has no fields)

* Request: Ask device to decrypt message @next Success @next Failure

• repeated uint32 address_n = 1

  BIP-32 path to derive the decryption key from master node

• optional bytes nonce = 2

  nonce used during encryption

• optional bytes message = 3

  message to decrypt

• optional bytes hmac = 4

  message hmac

* Response: Decrypted message @prev DecryptedMessage

• optional bytes message = 1

  decrypted message

• optional string address = 2

  address used to sign the message (if used)

* Device Descriptor used in Configuration

Used in: Configuration

• optional uint32 vendor_id = 1

  USB vendor ID

• optional uint32 product_id = 2

  USB product ID

• optional string serial_number = 3

  USB serial number

• optional string path = 4

  USB device path

* Request: Ask device to encrypt message @next EncryptedMessage @next Failure

• optional bytes pubkey = 1

  public key

• optional bytes message = 2

  message to encrypt

• optional bool display_only = 3

  show just on display? (don't send back via wire)

• repeated uint32 address_n = 4

  BIP-32 path to derive the signing key from master node

• optional string coin_name = 5

  coin to use for signing

* Response: Encrypted message @prev EncryptMessage

• optional bytes nonce = 1

  nonce used during encryption

• optional bytes message = 2

  encrypted message

• optional bytes hmac = 3

  message hmac

* Response: Reply with random data generated by internal RNG @prev GetEntropy

• required bytes entropy = 1

  stream of random generated bytes

* Request: Provide additional entropy for seed generation function @prev EntropyRequest @next ButtonRequest

• optional bytes entropy = 1

  256 bits (32 bytes) of random data

* Response: Ask for additional entropy from host computer @prev ResetDevice @next EntropyAck

(message has no fields)

* Request: Estimated size of the transaction This behaves exactly like SignTx, which means that it can ask using TxRequest This call is non-blocking (except possible PassphraseRequest to unlock the seed) @next TxSize @next Failure

• required uint32 outputs_count = 1

  number of transaction outputs

• required uint32 inputs_count = 2

  number of transaction inputs

• optional string coin_name = 3

  coin to use

* Response: Failure of the previous request

• optional FailureType code = 1

  computer-readable definition of the error state

• optional string message = 2

  human-readable message of the error state

* Type of failures returned by Failure message @used_in Failure

Used in: Failure

• Failure_UnexpectedMessage = 1

• Failure_ButtonExpected = 2

• Failure_SyntaxError = 3

• Failure_ActionCancelled = 4

• Failure_PinExpected = 5

• Failure_PinCancelled = 6

• Failure_PinInvalid = 7

• Failure_InvalidSignature = 8

• Failure_Other = 9

• Failure_NotEnoughFunds = 10

• Failure_NotInitialized = 11

• Failure_FirmwareError = 99

* Response: Reports various information about the device @prev Initialize @prev GetFeatures

• optional string vendor = 1

  name of the manufacturer, e.g. "bitcointrezor.com"

• optional uint32 major_version = 2

  major version of the device, e.g. 1

• optional uint32 minor_version = 3

  minor version of the device, e.g. 0

• optional uint32 patch_version = 4

  patch version of the device, e.g. 0

• optional bool bootloader_mode = 5

  is device in bootloader mode?

• optional string device_id = 6

  device's unique identifier

• optional bool pin_protection = 7

  is device protected by PIN?

• optional bool passphrase_protection = 8

  is node/mnemonic encrypted using passphrase?

• optional string language = 9

  device language

• optional string label = 10

  device description label

• repeated CoinType coins = 11

  supported coins

• optional bool initialized = 12

  does device contain seed?

• optional bytes revision = 13

  SCM revision of firmware

• optional bytes bootloader_hash = 14

  hash of the bootloader

• optional bool imported = 15

  was storage imported from an external source?

• optional bool pin_cached = 16

  is PIN already cached in session?

• optional bool passphrase_cached = 17

  is passphrase already cached in session?

* Request: Ask device to erase its firmware @next Success @next Failure

(message has no fields)

* Request: Send firmware in binary form to the device @next Success @next Failure

• required bytes payload = 1

  firmware to be loaded into device

* Request: Ask device for address corresponding to address_n path @next PassphraseRequest @next Address @next Failure

• repeated uint32 address_n = 1

  BIP-32 path to derive the key from master node

• optional string coin_name = 2

• optional bool show_display = 3

• optional MultisigRedeemScriptType multisig = 4

  Filled if we are showing a multisig address

* Request: Request a sample of random data generated by hardware RNG. May be used for testing. @next ButtonRequest @next Entropy @next Failure

• required uint32 size = 1

  size of requested entropy

* Request: Ask for device details (no device reset) @next Features

(message has no fields)

* Request: Ask device for public key corresponding to address_n path @next PassphraseRequest @next PublicKey @next Failure

• repeated uint32 address_n = 1

  BIP-32 path to derive the key from master node

• optional string ecdsa_curve_name = 2

  ECDSA curve name to use

Used in: MultisigRedeemScriptType

• required HDNodeType node = 1

  BIP-32 node in deserialized form

• repeated uint32 address_n = 2

  BIP-32 path to derive the key from node

* Structure representing BIP32 (hierarchical deterministic) node Used for imports of private key into the device and exporting public key out of device @used_in PublicKey @used_in LoadDevice @used_in DebugLinkState @used_in Storage

Used in: DebugLinkState, HDNodePathType, LoadDevice, PublicKey, Storage

• required uint32 depth = 1

• required uint32 fingerprint = 2

• required uint32 child_num = 3

• required bytes chain_code = 4

• optional bytes private_key = 5

• optional bytes public_key = 6

* Structure representing identity data @used_in IdentityType

Used in: SignIdentity

• optional string proto = 1

  proto part of URI

• optional string user = 2

  user part of URI

• optional string host = 3

  host part of URI

• optional string port = 4

  port part of URI

• optional string path = 5

  path part of URI

• optional uint32 index = 6

  identity index

* Request: Reset device to default state and ask for device details @next Features

(message has no fields)

* Type of script which will be used for transaction output @used_in TxInputType

Used in: TxInputType

• SPENDADDRESS = 0

• SPENDMULTISIG = 1

* Request: Load seed and related internal settings from the computer @next ButtonRequest @next Success @next Failure

• optional string mnemonic = 1

  seed encoded as BIP-39 mnemonic (12, 18 or 24 words)

• optional HDNodeType node = 2

  BIP-32 node

• optional string pin = 3

  set PIN protection

• optional bool passphrase_protection = 4

  enable master node encryption using passphrase

• optional string language = 5

  device language

• optional string label = 6

  device label

• optional bool skip_checksum = 7

  do not test mnemonic for valid BIP-39 checksum

* Response: Signed message @prev SignMessage

• optional string address = 1

  address used to sign the message

• optional bytes signature = 2

  signature of the message

* Mapping between KeepKey wire identifier (uint) and a protobuf message

• MessageType_Initialize = 0

• MessageType_Ping = 1

• MessageType_Success = 2

• MessageType_Failure = 3

• MessageType_ChangePin = 4

• MessageType_WipeDevice = 5

• MessageType_FirmwareErase = 6

• MessageType_FirmwareUpload = 7

• MessageType_GetEntropy = 9

• MessageType_Entropy = 10

• MessageType_GetPublicKey = 11

• MessageType_PublicKey = 12

• MessageType_LoadDevice = 13

• MessageType_ResetDevice = 14

• MessageType_SignTx = 15

• MessageType_SimpleSignTx = 16

• MessageType_Features = 17

• MessageType_PinMatrixRequest = 18

• MessageType_PinMatrixAck = 19

• MessageType_Cancel = 20

• MessageType_TxRequest = 21

• MessageType_TxAck = 22

• MessageType_CipherKeyValue = 23

• MessageType_ClearSession = 24

• MessageType_ApplySettings = 25

• MessageType_ButtonRequest = 26

• MessageType_ButtonAck = 27

• MessageType_GetAddress = 29

• MessageType_Address = 30

• MessageType_EntropyRequest = 35

• MessageType_EntropyAck = 36

• MessageType_SignMessage = 38

• MessageType_VerifyMessage = 39

• MessageType_MessageSignature = 40

• MessageType_PassphraseRequest = 41

• MessageType_PassphraseAck = 42

• MessageType_EstimateTxSize = 43

• MessageType_TxSize = 44

• MessageType_RecoveryDevice = 45

• MessageType_WordRequest = 46

• MessageType_WordAck = 47

• MessageType_CipheredKeyValue = 48

• MessageType_EncryptMessage = 49

• MessageType_EncryptedMessage = 50

• MessageType_DecryptMessage = 51

• MessageType_DecryptedMessage = 52

• MessageType_SignIdentity = 53

• MessageType_SignedIdentity = 54

• MessageType_GetFeatures = 55

• MessageType_DebugLinkDecision = 100

• MessageType_DebugLinkGetState = 101

• MessageType_DebugLinkState = 102

• MessageType_DebugLinkStop = 103

• MessageType_DebugLinkLog = 104

* Type of redeem script used in input @used_in TxInputType

Used in: GetAddress, TxInputType, TxOutputType

• repeated HDNodePathType pubkeys = 1

  pubkeys from multisig address (sorted lexicographically)

• repeated bytes signatures = 2

  existing signatures for partially signed input

• optional uint32 m = 3

  "m" from n, how many valid signatures is necessary for spending

* Type of script which will be used for transaction output @used_in TxOutputType

Used in: TxOutputType

• PAYTOADDRESS = 0

• PAYTOSCRIPTHASH = 1

• PAYTOMULTISIG = 2

• PAYTOOPRETURN = 3

* Request: Send passphrase back @prev PassphraseRequest

• required string passphrase = 1

* Response: Device awaits encryption passphrase @next PassphraseAck @next Cancel

(message has no fields)

* Request: Computer responds with encoded PIN @prev PinMatrixRequest

• required string pin = 1

  matrix encoded PIN entered by user

* Response: Device is asking computer to show PIN matrix and awaits PIN encoded using this matrix scheme @next PinMatrixAck @next Cancel

• optional PinMatrixRequestType type = 1

* Type of PIN request @used_in PinMatrixRequest

Used in: PinMatrixRequest

• PinMatrixRequestType_Current = 1

• PinMatrixRequestType_NewFirst = 2

• PinMatrixRequestType_NewSecond = 3

* Request: Test if the device is alive, device sends back the message in Success response @next Success

• optional string message = 1

  message to send back in Success message

• optional bool button_protection = 2

  ask for button press

• optional bool pin_protection = 3

  ask for PIN if set in device

• optional bool passphrase_protection = 4

  ask for passphrase if set in device

* Response: Contains public key derived from device private seed @prev GetPublicKey

• required HDNodeType node = 1

  BIP32 public node

• optional string xpub = 2

  serialized form of public node

* Request: Start recovery workflow asking user for specific words of mnemonic Used to recovery device safely even on untrusted computer. @next WordRequest

• optional uint32 word_count = 1

  number of words in BIP-39 mnemonic

• optional bool passphrase_protection = 2

  enable master node encryption using passphrase

• optional bool pin_protection = 3

  enable PIN protection

• optional string language = 4

  device language

• optional string label = 5

  device label

• optional bool enforce_wordlist = 6

  enforce BIP-39 wordlist during the process

* Type of information required by transaction signing process @used_in TxRequest

Used in: TxRequest

• TXINPUT = 0

• TXOUTPUT = 1

• TXMETA = 2

• TXFINISHED = 3

* Request: Ask device to do initialization involving user interaction @next EntropyRequest @next Failure

• optional bool display_random = 1

  display entropy generated by the device before asking for additional entropy

• optional uint32 strength = 2

  strength of seed in bits

• optional bool passphrase_protection = 3

  enable master node encryption using passphrase

• optional bool pin_protection = 4

  enable PIN protection

• optional string language = 5

  device language

• optional string label = 6

  device label

* Request: Ask device to sign identity @next SignedIdentity @next Failure

• optional IdentityType identity = 1

  identity

• optional bytes challenge_hidden = 2

  non-visible challenge

• optional string challenge_visual = 3

  challenge shown on display (e.g. date+time)

• optional string ecdsa_curve_name = 4

  ECDSA curve name to use

* Request: Ask device to sign message @next MessageSignature @next Failure

• repeated uint32 address_n = 1

  BIP-32 path to derive the key from master node

• required bytes message = 2

  message to be signed

• optional string coin_name = 3

  coin to use for signing

* Request: Ask device to sign transaction @next PassphraseRequest @next PinMatrixRequest @next TxRequest @next Failure

• required uint32 outputs_count = 1

  number of transaction outputs

• required uint32 inputs_count = 2

  number of transaction inputs

• optional string coin_name = 3

  coin to use

* Response: Device provides signed identity @prev SignIdentity

• optional string address = 1

  identity address

• optional bytes public_key = 2

  identity public key

• optional bytes signature = 3

  signature of the identity data

* Request: Simplified transaction signing This method doesn't support streaming, so there are hardware limits in number of inputs and outputs. In case of success, the result is returned using TxRequest message. @next PassphraseRequest @next PinMatrixRequest @next TxRequest @next Failure

• repeated TxInputType inputs = 1

  transaction inputs

• repeated TxOutputType outputs = 2

  transaction outputs

• repeated TransactionType transactions = 3

  transactions whose outputs are used to build current inputs

• optional string coin_name = 4

  coin to use

* Internal persistent storage of device

• required uint32 version = 1

  version of storage

• optional HDNodeType node = 2

  BIP-32 node (mnemonic cannot be used if this is present)

• optional string mnemonic = 3

  BIP-39 mnemonic (node cannot be used if this is present)

• optional bool passphrase_protection = 4

  whether to require passphrase to decrypt node or stretch mnemonic

• optional uint32 pin_failed_attempts = 5

  number of failed PIN attempts

• optional string pin = 6

  current PIN

• optional string language = 7

  current language

• optional string label = 8

  device label

• optional bool imported = 9

  was storage imported from an external source?

• optional bytes homescreen = 10

  image used as homescreen (logo + label is used when not set)

* Response: Success of the previous request

• optional string message = 1

  human readable description of action or request-specific payload

* Structure representing transaction @used_in SimpleSignTx

Used in: SimpleSignTx, TxAck

• optional uint32 version = 1

• repeated TxInputType inputs = 2

• repeated TxOutputBinType bin_outputs = 3

• repeated TxOutputType outputs = 5

• optional uint32 lock_time = 4

• optional uint32 inputs_cnt = 6

• optional uint32 outputs_cnt = 7

* Request: Reported transaction data @prev TxRequest @next TxRequest

• optional TransactionType tx = 1

* Structure representing transaction input @used_in SimpleSignTx @used_in TransactionType

Used in: SimpleSignTx, TransactionType

• repeated uint32 address_n = 1

  BIP-32 path to derive the key from master node

• required bytes prev_hash = 2

  hash of previous transaction output to spend by this input

• required uint32 prev_index = 3

  index of previous output to spend

• optional bytes script_sig = 4

  script signature, unset for tx to sign

• optional uint32 sequence = 5

  sequence

• optional InputScriptType script_type = 6

  defines template of input script

• optional MultisigRedeemScriptType multisig = 7

  Filled if input is going to spend multisig tx

* Structure representing compiled transaction output @used_in TransactionType

Used in: TransactionType

• required uint64 amount = 1

• required bytes script_pubkey = 2

* Structure representing transaction output @used_in SimpleSignTx @used_in TransactionType

Used in: SimpleSignTx, TransactionType

• optional string address = 1

  target coin address in Base58 encoding

• repeated uint32 address_n = 2

  BIP-32 path to derive the key from master node; has higher priority than "address"

• required uint64 amount = 3

  amount to spend in satoshis

• required OutputScriptType script_type = 4

  output script type

• optional MultisigRedeemScriptType multisig = 5

  defines multisig address; script_type must be PAYTOMULTISIG

• optional bytes op_return_data = 6

  defines op_return data; script_type must be PAYTOOPRETURN, amount must be 0

* Response: Device asks for information for signing transaction or returns the last result If request_index is set, device awaits TxAck message (with fields filled in according to request_type) If signature_index is set, 'signature' contains signed input of signature_index's input @prev SignTx @prev SimpleSignTx @prev TxAck

• optional RequestType request_type = 1

  what should be filled in TxAck message?

• optional TxRequestDetailsType details = 2

  request for tx details

• optional TxRequestSerializedType serialized = 3

  serialized data and request for next

* Structure representing request details @used_in TxRequest

Used in: TxRequest

• optional uint32 request_index = 1

  device expects TxAck message from the computer

• optional bytes tx_hash = 2

  tx_hash of requested transaction

* Structure representing serialized data @used_in TxRequest

Used in: TxRequest

• optional uint32 signature_index = 1

  'signature' field contains signed input of this index

• optional bytes signature = 2

  signature of the signature_index input

• optional bytes serialized_tx = 3

  part of serialized and signed transaction

* Response: Estimated size of the transaction @prev EstimateTxSize

• optional uint32 tx_size = 1

  estimated size of transaction in bytes

* Request: Ask device to verify message @next Success @next Failure

• optional string address = 1

  address to verify

• optional bytes signature = 2

  signature to verify

• optional bytes message = 3

  message to verify

* Request: Request device to wipe all sensitive data and settings @next ButtonRequest

(message has no fields)

* Request: Computer replies with word from the mnemonic @prev WordRequest @next WordRequest @next Success @next Failure

• required string word = 1

  one word of mnemonic on asked position

* Response: Device is waiting for user to enter word of the mnemonic Its position is shown only on device's internal display. @prev RecoveryDevice @prev WordAck

(message has no fields)