|
|
|
@ -1,21 +1,19 @@
|
|
|
|
|
/*
|
|
|
|
|
Messages for TREZOR communication
|
|
|
|
|
|
|
|
|
|
Author: Marek Palatinus <slush@satoshilabs.com>
|
|
|
|
|
|
|
|
|
|
Version: 0.6
|
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
// Some sugar for easier handling in Multibit
|
|
|
|
|
/**
|
|
|
|
|
* Messages for TREZOR communication
|
|
|
|
|
*
|
|
|
|
|
* @author Marek Palatinus <slush@satoshilabs.com>
|
|
|
|
|
* @version 0.6
|
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
// Sugar for easier handling in Multibit
|
|
|
|
|
option java_package = "org.multibit.hd.hardware.trezor.protobuf";
|
|
|
|
|
option java_outer_classname = "TrezorMessage";
|
|
|
|
|
|
|
|
|
|
import "types.proto";
|
|
|
|
|
|
|
|
|
|
/*
|
|
|
|
|
Mapping between Trezor wire identifier (int) and protobuf message
|
|
|
|
|
*/
|
|
|
|
|
/**
|
|
|
|
|
* Mapping between Trezor wire identifier (uint) and a protobuf message
|
|
|
|
|
*/
|
|
|
|
|
enum MessageType {
|
|
|
|
|
MessageType_Initialize = 0 [(wire_in) = true];
|
|
|
|
|
MessageType_Ping = 1 [(wire_in) = true];
|
|
|
|
@ -38,8 +36,7 @@ enum MessageType {
|
|
|
|
|
MessageType_PinMatrixAck = 19 [(wire_in) = true];
|
|
|
|
|
MessageType_Cancel = 20 [(wire_in) = true];
|
|
|
|
|
MessageType_TxRequest = 21 [(wire_out) = true];
|
|
|
|
|
MessageType_TxInput = 23 [(wire_in) = true];
|
|
|
|
|
MessageType_TxOutput = 24 [(wire_in) = true];
|
|
|
|
|
MessageType_TxAck = 22 [(wire_in) = true];
|
|
|
|
|
MessageType_ApplySettings = 25 [(wire_in) = true];
|
|
|
|
|
MessageType_ButtonRequest = 26 [(wire_out) = true];
|
|
|
|
|
MessageType_ButtonAck = 27 [(wire_in) = true];
|
|
|
|
@ -56,7 +53,7 @@ enum MessageType {
|
|
|
|
|
MessageType_TxSize = 44 [(wire_out) = true];
|
|
|
|
|
MessageType_RecoveryDevice = 45 [(wire_in) = true];
|
|
|
|
|
MessageType_WordRequest = 46 [(wire_out) = true];
|
|
|
|
|
MessageType_WordAck = 47 [(wire_in) = true];
|
|
|
|
|
MessageType_WordAck = 47 [(wire_in) = true];
|
|
|
|
|
MessageType_DebugLinkDecision = 100 [(wire_debug_in) = true];
|
|
|
|
|
MessageType_DebugLinkGetState = 101 [(wire_debug_in) = true];
|
|
|
|
|
MessageType_DebugLinkState = 102 [(wire_debug_out) = true];
|
|
|
|
@ -64,354 +61,467 @@ enum MessageType {
|
|
|
|
|
MessageType_DebugLinkLog = 104 [(wire_debug_out) = true];
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// ****************************************************************************
|
|
|
|
|
//
|
|
|
|
|
// Basic message
|
|
|
|
|
//
|
|
|
|
|
////////////////////
|
|
|
|
|
// Basic messages //
|
|
|
|
|
////////////////////
|
|
|
|
|
|
|
|
|
|
// Reset device to default state and ask for device details
|
|
|
|
|
//
|
|
|
|
|
// Response: Features
|
|
|
|
|
/**
|
|
|
|
|
* Request: Reset device to default state and ask for device details
|
|
|
|
|
* @next Features
|
|
|
|
|
*/
|
|
|
|
|
message Initialize {
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Response object for Initialize.
|
|
|
|
|
/**
|
|
|
|
|
* Response: Reports various information about the device
|
|
|
|
|
* @prev Initialize
|
|
|
|
|
*/
|
|
|
|
|
message Features {
|
|
|
|
|
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;
|
|
|
|
|
optional string device_id = 6; // Device's unique identifier
|
|
|
|
|
optional bool pin_protection = 7; // True if Trezor is covered by PIN
|
|
|
|
|
optional bool passphrase_protection = 8; // True if node/mnemonic is covered by passphrase
|
|
|
|
|
optional string language = 9;
|
|
|
|
|
optional string label = 10;
|
|
|
|
|
repeated CoinType coins = 11;
|
|
|
|
|
optional bool initialized = 12; // True if device cointains seed
|
|
|
|
|
optional bytes revision = 13;
|
|
|
|
|
optional bytes bootloader_hash = 14;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Overwrites only filled fields of the structure
|
|
|
|
|
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
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Request: change language and/or label of the device
|
|
|
|
|
* @next Success
|
|
|
|
|
* @next Failure
|
|
|
|
|
* @next ButtonRequest
|
|
|
|
|
* @next PinMatrixRequest
|
|
|
|
|
*/
|
|
|
|
|
message ApplySettings {
|
|
|
|
|
optional string language = 1;
|
|
|
|
|
optional string label = 2;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Starts workflow for setting/changing the PIN
|
|
|
|
|
// Response: ButtonRequest, PinMatrixRequest
|
|
|
|
|
/**
|
|
|
|
|
* Request: Starts workflow for setting/changing/removing the PIN
|
|
|
|
|
* @next ButtonRequest
|
|
|
|
|
* @next PinMatrixRequest
|
|
|
|
|
*/
|
|
|
|
|
message ChangePin {
|
|
|
|
|
optional bool remove = 1; // Set True if want to remove PIN protection
|
|
|
|
|
optional bool remove = 1; // is PIN removal requested?
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Test if device is live, device will send back the message on success
|
|
|
|
|
//
|
|
|
|
|
// Response: None or Success
|
|
|
|
|
/**
|
|
|
|
|
* Request: Test if the device is alive, device sends back the message in Success response
|
|
|
|
|
* @next Success
|
|
|
|
|
*/
|
|
|
|
|
message Ping {
|
|
|
|
|
optional string message = 1; // Message will be sent back in Success message
|
|
|
|
|
optional bool button_protection = 2; // Ask for button press
|
|
|
|
|
optional bool pin_protection = 3; // Ask for PIN if set
|
|
|
|
|
optional bool passphrase_protection = 4; // Ask for passphrase if set
|
|
|
|
|
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 object defining success of the previous request
|
|
|
|
|
/**
|
|
|
|
|
* Response: Success of the previous request
|
|
|
|
|
*/
|
|
|
|
|
message Success {
|
|
|
|
|
optional string message = 1; // May contain human readable description of the action or request-specific payload
|
|
|
|
|
optional string message = 1; // human readable description of action or request-specific payload
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Response object defining failure of the previous request
|
|
|
|
|
/**
|
|
|
|
|
* Response: Failure of the previous request
|
|
|
|
|
*/
|
|
|
|
|
message Failure {
|
|
|
|
|
optional FailureType code = 1; // May contain computer-readable definition of the error state
|
|
|
|
|
optional string message = 2; // May contain human-readable message of the error state
|
|
|
|
|
optional FailureType code = 1; // computer-readable definition of the error state
|
|
|
|
|
optional string message = 2; // human-readable message of the error state
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Message can be sent by the *device* as a resopnse to any request.
|
|
|
|
|
// Device is waiting for HW button press. No action is required from computer
|
|
|
|
|
// Computer should respond with ButtonAck message or Cancel to cancel
|
|
|
|
|
// the original request.
|
|
|
|
|
/**
|
|
|
|
|
* Response: Device is waiting for HW button press.
|
|
|
|
|
* @next ButtonAck
|
|
|
|
|
* @next Cancel
|
|
|
|
|
*/
|
|
|
|
|
message ButtonRequest {
|
|
|
|
|
optional ButtonRequestType code = 1;
|
|
|
|
|
optional string data = 2;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Computer agrees to wait for HW button press.
|
|
|
|
|
/**
|
|
|
|
|
* Request: Computer agrees to wait for HW button press
|
|
|
|
|
* @prev ButtonRequest
|
|
|
|
|
*/
|
|
|
|
|
message ButtonAck {
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Message can be sent by the *device* as a response to any request.
|
|
|
|
|
// Message asks computer to send back PinMatrixAck with the password encoded in pin matrix scheme.
|
|
|
|
|
//
|
|
|
|
|
// Response: PinMatrixAck, Cancel
|
|
|
|
|
/**
|
|
|
|
|
* Response: Device is asking computer to show PIN matrix and awaits PIN encoded using this matrix scheme
|
|
|
|
|
* @next PinMatrixAck
|
|
|
|
|
* @next Cancel
|
|
|
|
|
*/
|
|
|
|
|
message PinMatrixRequest {
|
|
|
|
|
optional PinMatrixRequestType type = 1;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Message is sent by the computer as a response to PinMatrixRequest previously sent by the device.
|
|
|
|
|
/**
|
|
|
|
|
* Request: Computer responds with encoded PIN
|
|
|
|
|
* @prev PinMatrixRequest
|
|
|
|
|
*/
|
|
|
|
|
message PinMatrixAck {
|
|
|
|
|
required string pin = 1; // User must write down the password for accessing the device.
|
|
|
|
|
required string pin = 1; // matrix encoded PIN entered by user
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Message is sent as a cancel response to ButtonRequest, PinMatrixRequest and PassphraseRequest
|
|
|
|
|
/**
|
|
|
|
|
* Request: Abort last operation that required user interaction
|
|
|
|
|
* @prev ButtonRequest
|
|
|
|
|
* @prev PinMatrixRequest
|
|
|
|
|
* @prev PassphraseRequest
|
|
|
|
|
*/
|
|
|
|
|
message Cancel {
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Device request encryption passphrase
|
|
|
|
|
/**
|
|
|
|
|
* Response: Device awaits encryption passphrase
|
|
|
|
|
* @next PassphraseAck
|
|
|
|
|
* @next Cancel
|
|
|
|
|
*/
|
|
|
|
|
message PassphraseRequest {
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Computer sends passphrase to device.
|
|
|
|
|
/**
|
|
|
|
|
* Request: Send passphrase back
|
|
|
|
|
* @prev PassphraseRequest
|
|
|
|
|
*/
|
|
|
|
|
message PassphraseAck {
|
|
|
|
|
required string passphrase = 1;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Request a sample of random data generated by hardware RNG. May be used
|
|
|
|
|
// for tests of internal RNG.
|
|
|
|
|
//
|
|
|
|
|
// Response: PinMatrixRequest, Entropy, Failure
|
|
|
|
|
/**
|
|
|
|
|
* Request: Request a sample of random data generated by hardware RNG. May be used for testing.
|
|
|
|
|
* @next ButtonRequest
|
|
|
|
|
* @next Entropy
|
|
|
|
|
* @next Failure
|
|
|
|
|
*/
|
|
|
|
|
message GetEntropy {
|
|
|
|
|
required uint32 size = 1; // Size of randomly generated buffer
|
|
|
|
|
required uint32 size = 1; // size of requested entropy
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Response to GetEntropy request contains random data generated by internal HRNG.
|
|
|
|
|
/**
|
|
|
|
|
* Response: Reply with random data generated by internal RNG
|
|
|
|
|
* @prev GetEntropy
|
|
|
|
|
*/
|
|
|
|
|
message Entropy {
|
|
|
|
|
required bytes entropy = 1; // Stream of generated bytes
|
|
|
|
|
required bytes entropy = 1; // stream of random generated bytes
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Ask device for public key corresponding of address_n path. This may be used for generating
|
|
|
|
|
// public keys on the computer independently to the device.
|
|
|
|
|
//
|
|
|
|
|
// Response: PublicKey, Failure
|
|
|
|
|
/**
|
|
|
|
|
* Request: Ask device for public key corresponding to address_n path
|
|
|
|
|
* @next PassphraseRequest
|
|
|
|
|
* @next PublicKey
|
|
|
|
|
* @next Failure
|
|
|
|
|
*/
|
|
|
|
|
message GetPublicKey {
|
|
|
|
|
repeated uint32 address_n = 1;
|
|
|
|
|
repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Contains public key derived from device's seed.
|
|
|
|
|
/**
|
|
|
|
|
* Response: Contains public key derived from device private seed
|
|
|
|
|
* @prev GetPublicKey
|
|
|
|
|
*/
|
|
|
|
|
message PublicKey {
|
|
|
|
|
required HDNodeType node = 1; // BIP32 node public key + chaincode
|
|
|
|
|
required HDNodeType node = 1; // BIP32 public node
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Request: Ask device for address corresponding to address_n path
|
|
|
|
|
* @next PassphraseRequest
|
|
|
|
|
* @next Address
|
|
|
|
|
* @next Failure
|
|
|
|
|
*/
|
|
|
|
|
message GetAddress {
|
|
|
|
|
repeated uint32 address_n = 1; // Parameter for address generation algorithm to derive the address from the master node
|
|
|
|
|
repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node
|
|
|
|
|
optional string coin_name = 2 [default='Bitcoin'];
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Response: Contains address derived from device private seed
|
|
|
|
|
* @prev GetAddress
|
|
|
|
|
*/
|
|
|
|
|
message Address {
|
|
|
|
|
required string address = 1; // Bitcoin address in base58 encoding corresponding to GetAddress(n) call
|
|
|
|
|
required string address = 1; // Coin address in Base58 encoding
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Request device to wipe all sensitive data and settings.
|
|
|
|
|
// Device will be turned to uninitialized state.
|
|
|
|
|
//
|
|
|
|
|
// Response: ButtonRequest
|
|
|
|
|
/**
|
|
|
|
|
* Request: Request device to wipe all sensitive data and settings
|
|
|
|
|
* @next ButtonRequest
|
|
|
|
|
*/
|
|
|
|
|
message WipeDevice {
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Load seed and related internal settings from computer to the device. Existing seed is overwritten.
|
|
|
|
|
//
|
|
|
|
|
// Response: Success, ButtonRequest, PinMatrixRequest, Failure
|
|
|
|
|
/**
|
|
|
|
|
* Request: Load seed and related internal settings from the computer
|
|
|
|
|
* @next ButtonRequest
|
|
|
|
|
* @next Success
|
|
|
|
|
* @next Failure
|
|
|
|
|
*/
|
|
|
|
|
message LoadDevice {
|
|
|
|
|
optional string mnemonic = 1; // Seed encoded as a mnemonic (12 english words)
|
|
|
|
|
optional HDNodeType node = 2;
|
|
|
|
|
optional string pin = 3; // Set PIN protection for important actions
|
|
|
|
|
optional bool passphrase_protection = 4;
|
|
|
|
|
optional string language = 5 [default='english'];
|
|
|
|
|
optional string label = 6;
|
|
|
|
|
optional bool skip_checksum = 7; // Do not test mnemonic for valid BIP39 checksum
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Request device to do full-reset, to generate new seed
|
|
|
|
|
// and ask user for new settings (PIN).
|
|
|
|
|
// Workflow is splitted into ResetDevice/EntropyRequest to be sure
|
|
|
|
|
// that entropy provided by device isn't calculated on base of computer provided
|
|
|
|
|
// entropy.
|
|
|
|
|
//
|
|
|
|
|
//
|
|
|
|
|
// Response: EntropyRequest, PinMatrixRequest, 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 [default='english']; // device language
|
|
|
|
|
optional string label = 6; // device label
|
|
|
|
|
optional bool skip_checksum = 7; // do not test mnemonic for valid BIP-39 checksum
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Request: Ask device to do initialization involving user interaction
|
|
|
|
|
* @next EntropyRequest
|
|
|
|
|
* @next Failure
|
|
|
|
|
*/
|
|
|
|
|
message ResetDevice {
|
|
|
|
|
optional bool display_random = 1; // If set, displays entropy generated by the device used
|
|
|
|
|
// for generating the seed *before* asking
|
|
|
|
|
// for additional entropy from computer
|
|
|
|
|
optional uint32 strength = 2 [default=128]; // Strength of seed in bits
|
|
|
|
|
optional bool passphrase_protection = 3;
|
|
|
|
|
optional bool pin_protection = 4;
|
|
|
|
|
optional string language = 5 [default='english'];
|
|
|
|
|
optional string label = 6;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Asks for additional Entropy from host computer
|
|
|
|
|
optional bool display_random = 1; // display entropy generated by the device before asking for additional entropy
|
|
|
|
|
optional uint32 strength = 2 [default=128]; // 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 [default='english']; // device language
|
|
|
|
|
optional string label = 6; // device label
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Response: Ask for additional entropy from host computer
|
|
|
|
|
* @prev ResetDevice
|
|
|
|
|
* @next EntropyAck
|
|
|
|
|
*/
|
|
|
|
|
message EntropyRequest {
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Provide additional entropy for seed generation function.
|
|
|
|
|
/**
|
|
|
|
|
* Request: Provide additional entropy for seed generation function
|
|
|
|
|
* @prev EntropyRequest
|
|
|
|
|
* @next ButtonRequest
|
|
|
|
|
*/
|
|
|
|
|
message EntropyAck {
|
|
|
|
|
optional bytes entropy = 1; // Recommended to provide 256 bits (32 bytes) of random data.
|
|
|
|
|
optional bytes entropy = 1; // 256 bits (32 bytes) of random data
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Starts workflow of asking user for specific words of his mnemonic.
|
|
|
|
|
// This may be used for safe recovery of lost device
|
|
|
|
|
// using mnemonic on untrusted computer.
|
|
|
|
|
/**
|
|
|
|
|
* Request: Start recovery workflow asking user for specific words of mnemonic
|
|
|
|
|
* Used to recovery device safely even on untrusted computer.
|
|
|
|
|
* @next WordRequest
|
|
|
|
|
*/
|
|
|
|
|
message RecoveryDevice {
|
|
|
|
|
optional uint32 word_count = 1; // How many words is in mnemonic sentence?
|
|
|
|
|
optional bool passphrase_protection = 2;
|
|
|
|
|
optional bool pin_protection = 3;
|
|
|
|
|
optional string language = 4 [default='english'];
|
|
|
|
|
optional string label = 5;
|
|
|
|
|
optional bool enforce_wordlist = 6; // Trezor enforces BIP39 wordlist
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// This message indicates that device is asking user for some word of his mnemonic.
|
|
|
|
|
// Position of the word is displayed only on device's internal display.
|
|
|
|
|
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 [default='english']; // device language
|
|
|
|
|
optional string label = 5; // device label
|
|
|
|
|
optional bool enforce_wordlist = 6; // enforce BIP-39 wordlist during the process
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 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 WordRequest {
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Request: Computer replies with word from the mnemonic
|
|
|
|
|
* @prev WordRequest
|
|
|
|
|
* @next WordRequest
|
|
|
|
|
* @next Success
|
|
|
|
|
* @next Failure
|
|
|
|
|
*/
|
|
|
|
|
message WordAck {
|
|
|
|
|
required string word = 1; // One word of mnemonic on asked position
|
|
|
|
|
required string word = 1; // one word of mnemonic on asked position
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// ****************************************************************************
|
|
|
|
|
//
|
|
|
|
|
// Messages related to transaction signing
|
|
|
|
|
//
|
|
|
|
|
//////////////////////////////
|
|
|
|
|
// Message signing messages //
|
|
|
|
|
//////////////////////////////
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Request: Ask device to sign message
|
|
|
|
|
* @next MessageSignature
|
|
|
|
|
* @next Failure
|
|
|
|
|
*/
|
|
|
|
|
message SignMessage {
|
|
|
|
|
repeated uint32 address_n = 1;
|
|
|
|
|
required bytes message = 2;
|
|
|
|
|
optional string coin_name = 3 [default='Bitcoin'];
|
|
|
|
|
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 [default='Bitcoin']; // coin to use for signing
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Request: Ask device to verify message
|
|
|
|
|
* @next Success
|
|
|
|
|
* @next Failure
|
|
|
|
|
*/
|
|
|
|
|
message VerifyMessage {
|
|
|
|
|
optional string address = 1;
|
|
|
|
|
optional bytes signature = 2;
|
|
|
|
|
optional bytes message = 3;
|
|
|
|
|
optional string address = 1; // address to verify
|
|
|
|
|
optional bytes signature = 2; // signature to verify
|
|
|
|
|
optional bytes message = 3; // message to verify
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Response: Signed message
|
|
|
|
|
* @prev SignMessage
|
|
|
|
|
*/
|
|
|
|
|
message MessageSignature {
|
|
|
|
|
optional string address = 1;
|
|
|
|
|
optional bytes signature = 2;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Estimate size of the transaction
|
|
|
|
|
// This call behaves exactly like SignTx,
|
|
|
|
|
// which means that it can ask for TxInput and TxInput.
|
|
|
|
|
// This call is non-blocking (except possible PassphraseRequest
|
|
|
|
|
// to unlock the seed) and returns estimated size of transaction
|
|
|
|
|
// in bytes.
|
|
|
|
|
//
|
|
|
|
|
// Response: TxRequest, TxSize, Failure
|
|
|
|
|
optional string address = 1; // address used to sign the message
|
|
|
|
|
optional bytes signature = 2; // signature of the message
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////
|
|
|
|
|
// Transaction signing messages //
|
|
|
|
|
//////////////////////////////////
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 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
|
|
|
|
|
*/
|
|
|
|
|
message EstimateTxSize {
|
|
|
|
|
required uint32 outputs_count = 1; // Count of outputs of the transaction
|
|
|
|
|
required uint32 inputs_count = 2; // Count of inputs of the transaction
|
|
|
|
|
optional string coin_name = 3 [default='Bitcoin'];
|
|
|
|
|
required uint32 outputs_count = 1; // number of transaction outputs
|
|
|
|
|
required uint32 inputs_count = 2; // number of transaction inputs
|
|
|
|
|
optional string coin_name = 3 [default='Bitcoin']; // coin to use
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Result of EstimateTxSize
|
|
|
|
|
/**
|
|
|
|
|
* Response: Estimated size of the transaction
|
|
|
|
|
* @prev EstimateTxSize
|
|
|
|
|
*/
|
|
|
|
|
message TxSize {
|
|
|
|
|
optional uint32 tx_size = 1; // Size of transaction in bytes
|
|
|
|
|
optional uint32 tx_size = 1; // estimated size of transaction in bytes
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Request the device to sign the transaction
|
|
|
|
|
//
|
|
|
|
|
// Response: TxRequest, PinMatrixRequest, Failure
|
|
|
|
|
/**
|
|
|
|
|
* Request: Ask device to sign transaction
|
|
|
|
|
* @next PinMatrixRequest
|
|
|
|
|
* @next TxRequest
|
|
|
|
|
* @next Failure
|
|
|
|
|
*/
|
|
|
|
|
message SignTx {
|
|
|
|
|
required uint32 outputs_count = 1; // Count of outputs of the transaction
|
|
|
|
|
required uint32 inputs_count = 2; // Count of inputs of the transaction
|
|
|
|
|
optional string coin_name = 3 [default='Bitcoin'];
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Request a simplified workflow of signing.
|
|
|
|
|
// This method doesn't support streaming,
|
|
|
|
|
// so there may be hardware limits
|
|
|
|
|
// in number of inputs and outputs.
|
|
|
|
|
//
|
|
|
|
|
// This simplified workflow should not be used
|
|
|
|
|
// in production, it is designed mainly for debug purposes.
|
|
|
|
|
//
|
|
|
|
|
// When everything is fine, Success.message contains
|
|
|
|
|
// serialized transaction.
|
|
|
|
|
//
|
|
|
|
|
// Response: Success, PinMatrixRequest, Failure
|
|
|
|
|
required uint32 outputs_count = 1; // number of transaction outputs
|
|
|
|
|
required uint32 inputs_count = 2; // number of transaction inputs
|
|
|
|
|
optional string coin_name = 3 [default='Bitcoin']; // coin to use
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 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 PinMatrixRequest
|
|
|
|
|
* @next TxRequest
|
|
|
|
|
* @next Failure
|
|
|
|
|
*/
|
|
|
|
|
message SimpleSignTx {
|
|
|
|
|
repeated TxInputType inputs = 1;
|
|
|
|
|
repeated TxOutputType outputs = 2;
|
|
|
|
|
repeated TransactionType transactions = 3;
|
|
|
|
|
optional string coin_name = 4 [default='Bitcoin'];
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Sent by the device as a response for SignTx. Device asks for information for signing transaction.
|
|
|
|
|
// If request_index is set, device asks for TxInput/TxOutput message (depends on request_type)
|
|
|
|
|
// with details of index's input.
|
|
|
|
|
// If signed_index is set, 'signature' contains signed input of signed_index's input.
|
|
|
|
|
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 [default='Bitcoin']; // coin to use
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 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
|
|
|
|
|
*/
|
|
|
|
|
message TxRequest {
|
|
|
|
|
optional int32 request_index = 1; // If >=0, device expects TxInput/TxOutput message from the computer
|
|
|
|
|
optional RequestType request_type = 2; // Ask for TxInput or TxOutput?
|
|
|
|
|
optional int32 signed_index = 3; // If >=0, 'signature' contains signed input of this input
|
|
|
|
|
optional bytes signature = 4; // If signed_index>=0, represent signature of the signed_index input
|
|
|
|
|
optional bytes serialized_tx = 5; // Part of serialized and signed transaction
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Transaction onput for SignTx workflow. It is response to TxRequest message sent by device.
|
|
|
|
|
//
|
|
|
|
|
// Response: TxRequest, Failure
|
|
|
|
|
message TxInput {
|
|
|
|
|
required TxInputType input = 1;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Transaction output for SignTx workflow. It is response to TxRequest message sent by the device.
|
|
|
|
|
// This contains all data necessary to build transaction output (script_pubkey).
|
|
|
|
|
message TxOutput {
|
|
|
|
|
required TxOutputType output = 1;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// ****************************************************************************
|
|
|
|
|
//
|
|
|
|
|
// Bootloader messages
|
|
|
|
|
//
|
|
|
|
|
|
|
|
|
|
optional uint32 request_index = 1; // device expects TxAck message from the computer
|
|
|
|
|
optional RequestType request_type = 2; // what should be filled in TxAck message?
|
|
|
|
|
optional uint32 signature_index = 3; // 'signature' field contains signed input of this index
|
|
|
|
|
optional bytes signature = 4; // signature of the signature_index input
|
|
|
|
|
optional bytes serialized_tx = 5; // part of serialized and signed transaction
|
|
|
|
|
optional bytes tx_hash = 6; // tx_hash of requested transaction
|
|
|
|
|
optional bool finished = 7; // is this the last TxRequest?
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Request: Reported transaction data
|
|
|
|
|
* @prev TxRequest
|
|
|
|
|
* @next TxRequest
|
|
|
|
|
*/
|
|
|
|
|
message TxAck {
|
|
|
|
|
optional TransactionType tx = 1;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/////////////////////////
|
|
|
|
|
// Bootloader messages //
|
|
|
|
|
/////////////////////////
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Request: Ask device to erase its firmware
|
|
|
|
|
* @next Success
|
|
|
|
|
* @next Failure
|
|
|
|
|
*/
|
|
|
|
|
message FirmwareErase {
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Request: Send firmware in binary form to the device
|
|
|
|
|
* @next Success
|
|
|
|
|
* @next Failure
|
|
|
|
|
*/
|
|
|
|
|
message FirmwareUpload {
|
|
|
|
|
required bytes payload = 1; // Firmware to flash into device
|
|
|
|
|
required bytes payload = 1; // firmware to be loaded into device
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// ****************************************************************************
|
|
|
|
|
//
|
|
|
|
|
// Debug* messages are used only on DebugLink interface (separated from USB HID)
|
|
|
|
|
//
|
|
|
|
|
/////////////////////////////////////////////////////////////
|
|
|
|
|
// Debug messages (only available if DebugLink is enabled) //
|
|
|
|
|
/////////////////////////////////////////////////////////////
|
|
|
|
|
|
|
|
|
|
// Virtually "press" the button on the device.
|
|
|
|
|
// Message is available only on debugging connection and device must support "debug_link" feature.
|
|
|
|
|
//
|
|
|
|
|
// Response: Success
|
|
|
|
|
/**
|
|
|
|
|
* Request: "Press" the button on the device
|
|
|
|
|
* @next Success
|
|
|
|
|
*/
|
|
|
|
|
message DebugLinkDecision {
|
|
|
|
|
required bool yes_no = 1; // True for "confirm", False for "cancel"
|
|
|
|
|
required bool yes_no = 1; // true for "Confirm", false for "Cancel"
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// When sent over debug link connection, computer asks for some internal information of the device.
|
|
|
|
|
//
|
|
|
|
|
// Response: DebugLinkState
|
|
|
|
|
/**
|
|
|
|
|
* Request: Computer asks for device state
|
|
|
|
|
* @next DebugLinkState
|
|
|
|
|
*/
|
|
|
|
|
message DebugLinkGetState {
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Response object reflecting device's current state. It can be received only over debug link connection.
|
|
|
|
|
/**
|
|
|
|
|
* Response: Device current state
|
|
|
|
|
* @prev DebugLinkGetState
|
|
|
|
|
*/
|
|
|
|
|
message DebugLinkState {
|
|
|
|
|
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 mnemonic format
|
|
|
|
|
optional HDNodeType node = 5; // Current node (BIP32 format)
|
|
|
|
|
optional bool passphrase_protection = 6; // Is passphrase_protection set?
|
|
|
|
|
optional string reset_word = 7; // Word on display during ResetDevice workflow
|
|
|
|
|
optional bytes reset_entropy = 8; // Current entropy of 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
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Ask device to shutdown/restart
|
|
|
|
|
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 DebugLinkStop {
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Response: Device wants host to log event
|
|
|
|
|
*/
|
|
|
|
|
message DebugLinkLog {
|
|
|
|
|
optional uint32 level = 1;
|
|
|
|
|
optional string bucket = 2;
|
|
|
|
|