types.proto

/*
 * Types for KeepKey Communication
 *
 */

syntax = "proto2";

// Sugar for easier handling in Java
option java_package = "com.keepkey.deviceprotocol";
option java_outer_classname = "KeepKeyType";

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
}

/**
 * Type of failures returned by Failure message
 * @used_in Failure
 */
enum FailureType {
	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_PinMismatch = 12;
	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 ouput address specify in transaction
 * @used_in TxOutputType 
 */
enum OutputAddressType {
  SPEND = 0;
  TRANSFER = 1;
  CHANGE = 2;
  reserved 3;
}

/**
 * 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_FirmwareErase = 11;
	ButtonRequest_ConfirmTransferToAccount = 12;
	ButtonRequest_ConfirmTransferToNodePath = 13;  /* Deprecated!*/
	ButtonRequest_ChangeLabel = 14;
	ButtonRequest_ChangeLanguage = 15;
	ButtonRequest_EnablePassphrase = 16;
	ButtonRequest_DisablePassphrase = 17;
	ButtonRequest_EncryptAndSignMessage = 18;
	ButtonRequest_EncryptMessage = 19;
	ButtonRequest_ImportPrivateKey = 20;
	ButtonRequest_ImportRecoverySentence = 21;
	ButtonRequest_SignIdentity = 22;
	ButtonRequest_Ping = 23;
	ButtonRequest_RemovePin = 24;
	ButtonRequest_ChangePin = 25;
	ButtonRequest_CreatePin = 26;
	ButtonRequest_GetEntropy = 27;
	ButtonRequest_SignMessage = 28;
	ButtonRequest_ApplyPolicies = 29;
	reserved 30;
	ButtonRequest_AutoLockDelayMs = 31;
	ButtonRequest_U2FCounter = 32;
	ButtonRequest_ConfirmEosAction = 33;
	ButtonRequest_ConfirmEosBudget = 34;
	ButtonRequest_ConfirmMemo = 35;
	ButtonRequest_RemoveWipeCode = 36;
	ButtonRequest_ChangeWipeCode = 37;
	ButtonRequest_CreateWipeCode = 38;
}

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

/**
 * 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 uint32 address_type_p2wpkh = 6 [default=6]; REMOVED
	//optional uint32 address_type_p2wsh = 7 [default=10]; REMOVED
	optional string signed_message_header = 8;
	optional uint32 bip44_account_path = 9;
	optional uint32 forkid = 12;
	optional uint32 decimals = 13;
	optional bytes contract_address = 14;
	//optional bytes gas_limit = 15; REMOVED
	optional uint32 xpub_magic = 16 [default=76067358];
	//optional uint32 xprv_magic = 17 [default=76066276]; REMOVED
	optional bool segwit = 18;
	optional bool force_bip143 = 19;
	optional string curve_name = 20;
	optional string cashaddr_prefix = 21;
	optional string bech32_prefix = 22;
	optional bool decred = 23;
	// optional uint32 version_group_id = 24; REMOVED
	optional uint32 xpub_magic_segwit_p2sh = 25;
	optional uint32 xpub_magic_segwit_native = 26;
	optional string nanoaddr_prefix = 27;
}

/**
 * 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 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=0xffffffff];			// sequence
	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)
	optional uint32 decred_tree = 9;
	optional uint32 decred_script_version = 10;
}

/**
 * Structure representing transaction output
 * @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
	optional OutputAddressType address_type = 7;	// output address type 
	reserved 8;
	optional uint32 decred_script_version = 9;
}

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

/**
 * Structure representing transaction
 */
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;         // only for Zcash
	optional uint32 extra_data_len = 9;    // only for Zcash
	optional uint32 expiry = 10;           // only for Decred, and Zcash
	optional bool overwintered = 11;       // only for Zcash
	optional uint32 version_group_id = 12; // only for Zcash, nVersionGroupId when overwintered is set
	optional uint32 branch_id = 13;        // only for Zcash, BRANCH_ID when overwintered is set
}

/**
 * Structure representing raw transaction
 * @used_in RawTxAck
 */
message RawTransactionType {
	required bytes payload = 1;
}

/**
 * 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
}

/**
 * Structure representing policy data
 * @used_in ApplyPolicy
 */
message PolicyType {
	optional string policy_name = 1;	// name of policy
	optional bool enabled = 2;				// status of policy
}