trezor-firmware/protobuf/bitkey.proto

/*
	This file describes Protocol buffers messages for bitcoin hardware wallet devices.
	
	Author: slush <info@bitcoin.cz>
*/

// Specifies algorithm used for generating private/public keys from the seed.
enum Algorithm {
    BIP32 = 0;
    ELECTRUM = 1;
}

// Specifies which script will be used for given transaction output. 
enum ScriptType {
    PAYTOADDRESS = 0;
    PAYTOSCRIPTHASH = 1;
} 

// Specifies which kind of information is required by transaction signing process
enum RequestType {
    TXINPUT = 0;
    TXOUTPUT = 1;
}

// Reset device's internal state
//
// Response: Features
message Initialize {
    required bytes session_id = 1; // Any value identifying current connection, will be echoed back in Features message
}

// Response object for Initialize. Contains list of available features on the device.
message Features {
    required bytes session_id = 1;	// Echoed back from Initialize message
    optional string vendor = 2;	// Name of the manufacturer, e.g. "bitkey" 
    optional uint32 major_version = 3; // Major version of the device, e.g. 1
    optional uint32 minor_version = 4;  // Minor version of the device, e.g. 0
    optional bool otp = 5;	// True when device will send OtpRequest on important action
    optional bool pin = 6;	// True when device will send PinRequest on important action
    optional bool spv = 7;	// True when device requires SPV verification of transaction inputs
    optional uint64 maxfee_kb = 8;	// Maximum accepted fee per kilobyte of signed transaction 
    repeated Algorithm algo = 9;	// List of key generation algorithms supported by the device
    optional bool debug_link = 10;	// Indicates support for DebugLink connection  
}

// Test if device is live, device will send back the message on success
//
// Response: None or Success
message Ping {
    optional string message = 1;	// Message will be sent back in Success message
}

// Virtually "press" the button on the device.
// Message is available only on debugging connection and device must support "debug_link" feature.
//
// Response: Success  
message DebugLinkDecision {
	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
message DebugLinkGetState {
	optional bool layout = 1;	// Request raw buffer of display
	optional bool otp = 2;		// Request current OTP
	optional bool pin = 3;		// Request current PIN
	optional bool seed = 4;		// Request current seed
//	optional bool state = 5;	
}

// Response object reflecting device's current state. It can be received only over debug link connection.
message DebugLinkState {
	optional bytes layout = 1;	// Raw buffer of display
	optional OtpAck otp = 2;	// Current OTP, blank if device is not waiting to OTP
	optional PinAck pin = 3;	// Current PIN, blank if PIN is not set/enabled
	optional string seed = 4;	// Current seed (in mnemonic format)
//	optional string state = 5;
}

// Response object defining success of the previous request
message Success {
    optional string message = 1;	//	May contain human readable description of the action or request-specific payload
}

// Response object defining failure of the previous request
message Failure {
    optional int32 code = 1;		// May contain computer-readable definition of the error state
    optional string message = 2;	// May contain human-readable message of the error state
}

// Ask device for unique identifier.
//
// Response: UUID 
message GetUUID {
}

// Identifier of the device. This identifier must be composed from CPU serial number
// or other persistent source and must be the same for consecutive requests.
message UUID {
    required bytes UUID = 1;
}

// 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 ButtonCancel to cancel
// the original request.
message ButtonRequest {
}

// Computer agrees to wait for HW button press.
message ButtonAck {
}

// Computer want to cancel current action (don't wait to HW button press)
message ButtonCancel {
}
 
// Message can be sent by the *device* as a response to any request.
// Message asks computer to send back OtpAck with the password printed on the device's display.
//
// Response: OtpAck, OtpCancel
message OtpRequest {
   optional string message = 1;	// Human readable message
}

// Message is sent by the computer as a response to OtpRequest previously sent by the device.
message OtpAck {
    required string otp = 1;	// User must be asked for the otp, which is displayed on the device's display
}

// Message is sent as a response to OtpRequest by the computer, asking the device to cancel
// pending action and reset to the default state.
message OtpCancel {
}

// Message can be sent by the *device* as a response to any request.
// Message asks computer to send back PinAck with the password associated with the device.
//
// Response: PinAck, PinCancel
message PinRequest {
   optional string message = 1;	// Human readable message
}

// Message is sent by the computer as a response to PinRequest previously sent by the device.
message PinAck {
    required string pin = 1;	// User must write down the password for accessing the device.
}

// Message is sent as a response to PinRequest by the computer, asking the device to cancel
// pending action and reset to the default state.
message PinCancel {
}

// Request a sample of random data generated by hardware RNG. May be used
// for tests of internal RNG.
//
// Response: OtpRequest, PinRequest, Entropy, Failure
message GetEntropy {
    required uint32 size = 1;	// Size of randomly generated buffer
}

// Response to GetEntropy request contains random data generated by internal HRNG.
message Entropy {
    required bytes entropy = 1;	// Stream of generated bytes
}

// Set maximum allowed fee per kB of transaction. This is used by internal sanity checking
// in SignTx method. Transaction won't be signed if requested transaction fees are above
// current value.
//
// Response: Success, OtpRequest, PinRequest, Failure
message SetMaxFeeKb {
	required uint64 maxfee_kb= 1;	// Maximum allowed transaction fee in satoshis per kB
}

// Ask device for it's current master public key. This may be used for generating
// public keys on the computer independently to the device. API doesn't provide
// any other way how to get bitcoin addresses from the device.
//
// Response: MasterPublicKey, Failure
message GetMasterPublicKey {
    required Algorithm algo = 1 [default=BIP32]; // Used algorithm for generating the master public key
}

// Contains master public key derived from device's seed.
message MasterPublicKey {
    required bytes key = 1;	// master public key of requested algorithm in binary format
}

message GetAddress {
    required Algorithm algo = 1 [default=BIP32]; // Used algorithm for generating the address
    repeated uint32 address_n = 2;	// Parameter for address generation algorithm to derive the address from the master public key 
}

message Address {
    required string address = 1; // Bitcoin address in base58 encoding corresponding to GetAddress(algo, n) call
}

// Load seed and related internal settings from computer to the device. Existing seed is overwritten.
//
// Response: Success, OtpRequest, PinRequest, Failure
message LoadDevice {
    required string seed = 1;	// Seed encoded as a mnemonic (12 english words)
    optional bool otp = 2 [default=true];	// Enable OTP for important actions?
    optional string pin = 3;				// Set PIN protection for important actions
    optional bool spv = 4 [default=true];	// Enable SPV verification for transaction inputs (if available on device)
}

// Request device to do full-reset, to generate new seed
// and ask user for new settings (OTP, PIN, SPV).
// 
// Response: Success, OtpRequest, PinRequest, Failure
message ResetDevice {
	optional bytes random = 7;	// Provide additional entropy for seed generation function.
								// Recommended to provide 256 bytes of random data.
}

// Request the device to sign the transaction
//
// Response: TxRequest, OtpRequest, PinRequest, Failure
message SignTx {
    required Algorithm algo = 1 [default=BIP32];	// Algorithm using for key generation algorithm
    required uint32 outputs_count = 3;		// Count of outputs of the transaction 
    required uint32 inputs_count = 5; // Count of inputs of the transaction
    optional bytes random = 6; 	// Provide additional entropy for signing function.
    							// Recommended to provide 256 bytes of random data.
}

// 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. 
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 [default=-1]; // 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 uint32 index = 1;		// Position of input in proposed transaction
    repeated uint32 address_n = 2;	// Parameter for address generation algorithm to derive the address from the master public key
    required uint64 amount = 3;		// Amount to spend in satoshis. The rest will be used for transaction fees
    required bytes prev_hash = 4;	// Hash of previous transaction output to spend by this input
    required uint32 prev_index = 5;	// Index of previous output to spend
    optional bytes script_sig = 6;	// Script signature
}

// Transaction output for SignTx workflow. It is response to TxRequest message sent by the device.
message TxOutput {
    required uint32 index = 1;			// Position of output in proposed transaction
    required string address = 2;		// Target bitcoin address in base58 encoding
    repeated uint32 address_n = 3;		// Has higher priority than "address". If the output is to myself, specify parameter for address generation algorithm.
    required uint64 amount = 4;			// Amount to send in satoshis
    required ScriptType script_type = 5;// Select output script type
    repeated bytes script_args = 6;		// Provide additional parameters for the script (its script-depended)
}