trezor-firmware/protob/types.proto

/**
 * Types for TREZOR communication
 *
 * @author	Marek Palatinus <slush@satoshilabs.com>
 * @version	1.2
 */

// Sugar for easier handling in Java
option java_package = "com.satoshilabs.trezor.lib.protobuf";
option java_outer_classname = "TrezorType";

import "google/protobuf/descriptor.proto";

/**
 * Options for specifying message direction and type of wire (normal/debug)
 */
extend google.protobuf.EnumValueOptions {
	optional bool wire_in = 50002;		// message can be transmitted via wire from PC to TREZOR
	optional bool wire_out = 50003;		// message can be transmitted via wire from TREZOR to PC
	optional bool wire_debug_in = 50004;	// message can be transmitted via debug wire from PC to TREZOR
	optional bool wire_debug_out = 50005;	// message can be transmitted via debug wire from TREZOR to PC
	optional bool wire_tiny = 50006;	// message is handled by TREZOR when the USB stack is in tiny mode
	optional bool wire_bootloader = 50007;  // message is only handled by TREZOR Bootloader
}

/**
 * Type of failures returned by Failure message
 * @used_in Failure
 */
enum FailureType {
	Failure_UnexpectedMessage = 1;
	Failure_ButtonExpected = 2;
	Failure_DataError = 3;
	Failure_ActionCancelled = 4;
	Failure_PinExpected = 5;
	Failure_PinCancelled = 6;
	Failure_PinInvalid = 7;
	Failure_InvalidSignature = 8;
	Failure_ProcessError = 9;
	Failure_NotEnoughFunds = 10;
	Failure_NotInitialized = 11;
	Failure_FirmwareError = 99;
}

/**
 * Type of script which will be used for transaction output
 * @used_in TxOutputType
 */
enum OutputScriptType {
	PAYTOADDRESS = 0;	// used for all addresses (bitcoin, p2sh, witness)
	PAYTOSCRIPTHASH = 1;	// p2sh address (deprecated; use PAYTOADDRESS)
	PAYTOMULTISIG = 2;	// only for change output
	PAYTOOPRETURN = 3;	// op_return
	PAYTOWITNESS = 4;	// only for change output
	PAYTOP2SHWITNESS = 5;	// only for change output
}

/**
 * Type of script which will be used for transaction output
 * @used_in TxInputType
 */
enum InputScriptType {
	SPENDADDRESS = 0;		// standard p2pkh address
	SPENDMULTISIG = 1;		// p2sh multisig address
	EXTERNAL = 2;			// reserved for external inputs (coinjoin)
	SPENDWITNESS = 3;		// native segwit
	SPENDP2SHWITNESS = 4;		// segwit over p2sh (backward compatible)
}

/**
 * Type of information required by transaction signing process
 * @used_in TxRequest
 */
enum RequestType {
	TXINPUT = 0;
	TXOUTPUT = 1;
	TXMETA = 2;
	TXFINISHED = 3;
	TXEXTRADATA = 4;
}

/**
 * Type of button request
 * @used_in ButtonRequest
 */
enum ButtonRequestType {
	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;
	ButtonRequest_PublicKey = 11;
}

/**
 * Type of PIN request
 * @used_in PinMatrixRequest
 */
enum PinMatrixRequestType {
	PinMatrixRequestType_Current = 1;
	PinMatrixRequestType_NewFirst = 2;
	PinMatrixRequestType_NewSecond = 3;
}

/**
 * Type of recovery procedure. These should be used as bitmask, e.g.,
 * `RecoveryDeviceType_ScrambledWords | RecoveryDeviceType_Matrix`
 * listing every method supported by the host computer.
 *
 * Note that ScrambledWords must be supported by every implementation
 * for backward compatibility; there is no way to not support it.
 *
 * @used_in RecoveryDevice
 */
enum RecoveryDeviceType {
	// use powers of two when extending this field
	RecoveryDeviceType_ScrambledWords = 0;		// words in scrambled order
	RecoveryDeviceType_Matrix = 1;				// matrix recovery type
}

/**
 * Type of Recovery Word request
 * @used_in WordRequest
 */
enum WordRequestType {
	WordRequestType_Plain = 0;
	WordRequestType_Matrix9 = 1;
	WordRequestType_Matrix6 = 2;
}

/**
 * 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
 */
message HDNodeType {
	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;
}

message HDNodePathType {
	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 Coin
 * @used_in Features
 */
message CoinType {
	optional string coin_name = 1;
	optional string coin_shortcut = 2;
	optional uint32 address_type = 3 [default=0];
	optional uint64 maxfee_kb = 4;
	optional uint32 address_type_p2sh = 5 [default=5];
	optional string signed_message_header = 8;
	optional uint32 xpub_magic = 9 [default=76067358];	// default=0x0488b21e
	optional uint32 xprv_magic = 10 [default=76066276];	// default=0x0488ade4
	optional bool segwit = 11;
	optional uint32 forkid = 12;
}

/**
 * Type of redeem script used in input
 * @used_in TxInputType
 */
message MultisigRedeemScriptType {
	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
}

/**
 * Structure representing transaction input
 * @used_in SimpleSignTx
 * @used_in TransactionType
 */
message TxInputType {
	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 [default=4294967295];			// sequence (default=0xffffffff)
	optional InputScriptType script_type = 6 [default=SPENDADDRESS];	// defines template of input script
	optional MultisigRedeemScriptType multisig = 7;				// Filled if input is going to spend multisig tx
	optional uint64 amount = 8;						// amount of previous transaction output (for segwit only)
}

/**
 * Structure representing transaction output
 * @used_in SimpleSignTx
 * @used_in TransactionType
 */
message TxOutputType {
	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
}

/**
 * Structure representing compiled transaction output
 * @used_in TransactionType
 */
message TxOutputBinType {
	required uint64 amount = 1;
	required bytes script_pubkey = 2;
}

/**
 * Structure representing transaction
 * @used_in SimpleSignTx
 */
message TransactionType {
	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;
	optional bytes extra_data = 8;
	optional uint32 extra_data_len = 9;
}

/**
 * Structure representing request details
 * @used_in TxRequest
 */
message TxRequestDetailsType {
	optional uint32 request_index = 1;	// device expects TxAck message from the computer
	optional bytes tx_hash = 2;		// tx_hash of requested transaction
	optional uint32 extra_data_len = 3;	// length of requested extra data
	optional uint32 extra_data_offset = 4;	// offset of requested extra data
}

/**
 * Structure representing serialized data
 * @used_in TxRequest
 */
message TxRequestSerializedType {
	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
}

/**
 * Structure representing identity data
 * @used_in IdentityType
 */
message IdentityType {
	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 [default=0];		// identity index
}