227 lines
8.4 KiB
Protocol Buffer
227 lines
8.4 KiB
Protocol Buffer
/*
|
|
This file describes Protocol buffers messages for bitcoin hardware wallet devices.
|
|
|
|
Author: slush <info@bitcoin.cz>
|
|
*/
|
|
|
|
// 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 {
|
|
}
|
|
|
|
// Response object for Initialize.
|
|
message Features {
|
|
optional string vendor = 2; // Name of the manufacturer, e.g. "trezor"
|
|
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 uint64 maxfee_kb = 10; // Maximum accepted fee per kilobyte of signed transaction
|
|
}
|
|
|
|
// 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 matrix = 3; // Request current matrix
|
|
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 PinMatrixAck pin = 3; // Current PIN matrix, blank if PIN is not set/enabled
|
|
optional bytes seed = 4; // Current seed (in mnemonic format)
|
|
// optional bytes state = 5;
|
|
}
|
|
|
|
// Ask device to shutdown/restart
|
|
message DebugLinkStop {
|
|
}
|
|
|
|
// Response object defining success of the previous request
|
|
message Success {
|
|
optional bytes 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 bytes 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 PinMatrixAck with the password encoded in pin matrix scheme.
|
|
//
|
|
// Response: PinMatrixAck, PinMatrixCancel
|
|
message PinMatrixRequest {
|
|
optional bytes message = 1; // Human readable message
|
|
}
|
|
|
|
// Message is sent by the computer as a response to PinMatrixRequest previously sent by the device.
|
|
message PinMatrixAck {
|
|
required bytes pin = 1; // User must write down the password for accessing the device.
|
|
}
|
|
|
|
// Message is sent as a response to PinMatrixRequest by the computer, asking the device to cancel
|
|
// pending action and reset to the default state.
|
|
message PinMatrixCancel {
|
|
}
|
|
|
|
// Request a sample of random data generated by hardware RNG. May be used
|
|
// for tests of internal RNG.
|
|
//
|
|
// Response: PinMatrixRequest, 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, PinMatrixRequest, 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 {
|
|
}
|
|
|
|
// 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 {
|
|
repeated uint32 address_n = 1; // 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(n) call
|
|
}
|
|
|
|
// Load seed and related internal settings from computer to the device. Existing seed is overwritten.
|
|
//
|
|
// Response: Success, PinMatrixRequest, Failure
|
|
message LoadDevice {
|
|
required string seed = 1; // Seed encoded as a mnemonic (12 english words)
|
|
optional bytes pin = 2; // Set PIN protection for important actions
|
|
}
|
|
|
|
// Request device to do full-reset, to generate new seed
|
|
// and ask user for new settings (PIN).
|
|
//
|
|
// Response: Success, PinMatrixRequest, 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, PinMatrixRequest, Failure
|
|
message SignTx {
|
|
required uint32 outputs_count = 3; // Count of outputs of the transaction
|
|
required uint32 inputs_count = 5; // Count of inputs of the transaction
|
|
}
|
|
|
|
// 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; // 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)
|
|
}
|