messages-ethereum.proto

/*
 * Messages for KeepKey Communication
 *
 */

syntax = "proto2";

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

import "types.proto";

/**
 * Request: Ask device for Ethereum address corresponding to address_n path
 * @next PassphraseRequest
 * @next EthereumAddress
 * @next Failure
 */
message EthereumGetAddress {
	repeated uint32 address_n = 1;			// BIP-32 path to derive the key from master node
	optional bool show_display = 2;			// optionally show on display before sending the result
}

/**
 * Response: Contains an Ethereum address derived from device private seed
 * @prev EthereumGetAddress
 */
message EthereumAddress {
	required bytes address = 1;		// Coin address as an Ethereum 160 bit hash
	optional string address_str = 2;
}

/**
 * Request: Ask device to sign transaction
 * All fields are optional from the protocol's point of view. Each field defaults to value `0` if missing.
 * Note: the first at most 1024 bytes of data MUST be transmitted as part of this message.
 * @next PassphraseRequest
 * @next PinMatrixRequest
 * @next EthereumTxRequest
 * @next Failure
 */
message EthereumSignTx {
	repeated uint32 address_n = 1;			// BIP-32 path to derive the key from master node
	optional bytes nonce = 2;			// <=256 bit unsigned big endian
	optional bytes gas_price = 3;			// <=256 bit unsigned big endian (in wei)
	optional bytes gas_limit = 4;			// <=256 bit unsigned big endian
	optional bytes to = 5;				// 160 bit address hash
	optional bytes value = 6;			// <=256 bit unsigned big endian (in wei)
	optional bytes data_initial_chunk = 7;		// The initial data chunk (<= 1024 bytes)
	optional uint32 data_length = 8;		// Length of transaction payload
	repeated uint32 to_address_n = 9;               // BIP-32 path to derive key for fund transfer
	optional OutputAddressType address_type = 10;	// output address type 
	reserved 11;
	optional uint32 chain_id = 12;			// Chain Id for EIP 155
	optional bytes max_fee_per_gas = 13;		// EIP-1559 - The maximum total fee per gas the sender is willing to pay. <=256 bit unsigned big endian (in wei)
	optional bytes max_priority_fee_per_gas = 14;	// EIP-1559 - Maximum fee per gas the sender is willing to pay to miners. <=256 bit unsigned big endian (in wei)
	optional bytes token_value = 100;		// How many tokens to send
	optional bytes  token_to = 101;			// 160 bit address hash to send tokens to
	optional string token_shortcut = 102; 		// 3 or 4 character token identifier
	optional uint32 tx_type = 103;			// (only for Wanchain)
	optional uint32 type = 104;			// Ethereum tx type (0=Legacy, 1=EIP-2930, 2=EIP-1559)
}

/**
 * Response: Device asks for more data from transaction payload, or returns the signature.
 * If data_length is set, device awaits that many more bytes of payload.
 * Otherwise, the signature_* fields contain the computed transaction signature. All three fields will be present.
 * @prev EthereumSignTx
 * @next EthereumTxAck
 */
message EthereumTxRequest {
	optional uint32 data_length = 1;  // Number of bytes being requested (<= 1024)
	optional uint32 signature_v = 2;  // Computed signature (recovery parameter, limited to 27 or 28)
	optional bytes signature_r = 3;	  // Computed signature R component (256 bit)
	optional bytes signature_s = 4;	  // Computed signature S component (256 bit)
	optional bytes hash = 5;	  // Computed hash using SHA3 (keccak_ctx)
  optional bytes signature_der = 6; // Computed signature in DER format
}

/**
 * Request: Transaction payload data.
 * @prev EthereumTxRequest
 * @next EthereumTxRequest
 */
message EthereumTxAck {
	optional bytes data_chunk = 1;			// Bytes from transaction payload (<= 1024 bytes)
}

////////////////////////////////////////
// Ethereum: Message signing messages //
////////////////////////////////////////

/**
 * Request: Ask device to sign message
 * @next EthereumMessageSignature
 * @next Failure
 */
message EthereumSignMessage {
	repeated uint32 address_n = 1;				// BIP-32 path to derive the key from master node
	required bytes message = 2;				// message to be signed
}

/**
 * Request: Ask device to verify message
 * @next Success
 * @next Failure
 */
message EthereumVerifyMessage {
	optional bytes address = 1;				// address to verify
	optional bytes signature = 2;				// signature to verify
	optional bytes message = 3;				// message to verify
}

/**
 * Response: Signed message
 * @prev EthereumSignMessage
 */
message EthereumMessageSignature {
	optional bytes address = 1;				// address used to sign the message
	optional bytes signature = 2;				// signature of the message
}


// EIP-712
/**
 * Request: Ask device to sign hash of typed data
 * @start
 * @next EthereumTypedDataSignature
 * @next Failure
 */
message EthereumSignTypedHash {
    repeated uint32 address_n = 1;              // BIP-32 path to derive the key from master node
    required bytes domain_separator_hash = 2;   // Hash of domainSeparator of typed data to be signed
    optional bytes message_hash = 3;            // Hash of the data of typed data to be signed (empty if domain-only data)
}

/**
 * Response: Signed typed data
 * @E712ValuesRequest
 * @end
 */
message EthereumTypedDataSignature {
    required bytes signature = 1;    						// signature of the typed data
    required string address = 2;     						// address used to sign the typed data
    optional bytes domain_separator_hash = 3;   // Hash of domainSeparator of typed data that was calculated
		required bool has_msg_hash = 4;							// message_hash is null if FALSE
    optional bytes message_hash = 5;            // Hash of the data of typed data that was calculated
}

/**
 * Request: Send the device types+domain or types+message data, return appropriate hash
 * @start
 * @next EthereumTypedDataSignature
 * @next Failure
 */
message Ethereum712TypesValues {
    repeated uint32 address_n = 1;      	// BIP-32 path to derive the key from master node
		required string eip712types = 2;			// "types" json string (up to 2048)
		required string eip712primetype = 3;	// primaryType (up to 80 bytes)
		required string eip712data = 4;				// "domain" or "message" json string (up to 2048)
		required uint32 eip712typevals = 5;		// device calculates hash for 1 = domain sep, 2 = message
}