1
0
mirror of https://github.com/trezor/trezor-firmware.git synced 2024-12-05 14:08:39 +00:00
trezor-firmware/common/protob/messages-bitcoin.proto

629 lines
30 KiB
Protocol Buffer
Raw Normal View History

syntax = "proto2";
2018-07-29 14:17:00 +00:00
package hw.trezor.messages.bitcoin;
// Sugar for easier handling in Java
option java_package = "com.satoshilabs.trezor.lib.protobuf";
option java_outer_classname = "TrezorMessageBitcoin";
import "messages-common.proto";
import "options.proto";
option (include_in_bitcoin_only) = true;
/**
* Type of script which will be used for transaction input
*/
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)
SPENDTAPROOT = 5; // Taproot
}
/**
* Type of script which will be used for transaction output
*/
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
PAYTOTAPROOT = 6; // only for change output
}
/**
* Type of script which will be used for decred stake transaction input
*/
enum DecredStakingSpendType {
SSGen = 0;
SSRTX = 1;
}
/**
* Unit to be used when showing amounts on the display
*/
enum AmountUnit {
BITCOIN = 0; // BTC
MILLIBITCOIN = 1; // mBTC
MICROBITCOIN = 2; // uBTC
SATOSHI = 3; // sat
}
/**
* Type of redeem script used in input
* @embed
*/
message MultisigRedeemScriptType {
repeated HDNodePathType pubkeys = 1; // pubkeys from multisig address (sorted lexicographically)
repeated bytes signatures = 2; // existing signatures for partially signed input
required uint32 m = 3; // "m" from n, how many valid signatures is necessary for spending
repeated common.HDNodeType nodes = 4; // simplified way how to specify pubkeys if they share the same address_n path
repeated uint32 address_n = 5; // use only field 1 or fields 4+5, if fields 4+5 are used, field 1 is ignored
/**
* Structure representing HDNode + Path
*/
message HDNodePathType {
required common.HDNodeType node = 1; // BIP-32 node in deserialized form
2018-07-29 14:17:00 +00:00
repeated uint32 address_n = 2; // BIP-32 path to derive the key from node
}
}
/**
* Request: Ask device for public key corresponding to address_n path
* @start
* @next PublicKey
* @next Failure
*/
message GetPublicKey {
2018-07-26 15:04:03 +00:00
repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node
optional string ecdsa_curve_name = 2; // ECDSA curve name to use
optional bool show_display = 3; // optionally show on display before sending the result
optional string coin_name = 4 [default='Bitcoin']; // coin to use for verifying
optional InputScriptType script_type = 5 [default=SPENDADDRESS]; // used to distinguish between various address formats (non-segwit, segwit, etc.)
optional bool ignore_xpub_magic = 6; // ignore SLIP-0132 XPUB magic, use xpub/tpub prefix for all account types
}
/**
* Response: Contains public key derived from device private seed
* @end
*/
message PublicKey {
required common.HDNodeType node = 1; // BIP-32 public node
required string xpub = 2; // serialized form of public node
optional uint32 root_fingerprint = 3; // master root node fingerprint
optional string descriptor = 4; // BIP-380 descriptor
}
/**
* Request: Ask device for address corresponding to address_n path
* @start
* @next Address
* @next Failure
*/
message GetAddress {
repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node
optional string coin_name = 2 [default='Bitcoin']; // coin to use
optional bool show_display = 3; // optionally show on display before sending the result
optional MultisigRedeemScriptType multisig = 4; // filled if we are showing a multisig address
optional InputScriptType script_type = 5 [default=SPENDADDRESS]; // used to distinguish between various address formats (non-segwit, segwit, etc.)
optional bool ignore_xpub_magic = 6; // ignore SLIP-0132 XPUB magic, use xpub/tpub prefix for all account types
optional bool chunkify = 7; // display the address in chunks of 4 characters
}
/**
* Response: Contains address derived from device private seed
* @end
*/
message Address {
required string address = 1; // Coin address in Base58 encoding
optional bytes mac = 2; // Address authentication code
}
/**
* Request: Ask device for ownership identifier corresponding to scriptPubKey for address_n path
* @start
* @next OwnershipId
* @next Failure
*/
message GetOwnershipId {
repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node
optional string coin_name = 2 [default='Bitcoin']; // coin to use
optional MultisigRedeemScriptType multisig = 3; // filled if we are dealing with a multisig scriptPubKey
optional InputScriptType script_type = 4 [default=SPENDADDRESS]; // used to distinguish between various address formats (non-segwit, segwit, etc.)
}
/**
* Response: Contains the ownership identifier for the scriptPubKey and device private seed
* @end
*/
message OwnershipId {
required bytes ownership_id = 1; // ownership identifier
}
/**
* Request: Ask device to sign message
* @start
* @next MessageSignature
* @next Failure
*/
message SignMessage {
repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node
required bytes message = 2; // message to be signed
optional string coin_name = 3 [default='Bitcoin']; // coin to use for signing
optional InputScriptType script_type = 4 [default=SPENDADDRESS]; // used to distinguish between various address formats (non-segwit, segwit, etc.)
optional bool no_script_type = 5; // don't include script type information in the recovery byte of the signature, same as in Bitcoin Core
optional bool chunkify = 6; // display the address in chunks of 4 characters
}
/**
* Response: Signed message
* @end
*/
message MessageSignature {
required string address = 1; // address used to sign the message
required bytes signature = 2; // signature of the message
}
/**
* Request: Ask device to verify message
* @start
* @next Success
* @next Failure
*/
message VerifyMessage {
required string address = 1; // address to verify
required bytes signature = 2; // signature to verify
required bytes message = 3; // message to verify
optional string coin_name = 4 [default='Bitcoin']; // coin to use for verifying
optional bool chunkify = 5; // display the address in chunks of 4 characters
}
/**
* Request: Ask device to sign transaction
* @start
* @next TxRequest
* @next Failure
*/
message SignTx {
required uint32 outputs_count = 1; // number of transaction outputs
required uint32 inputs_count = 2; // number of transaction inputs
optional string coin_name = 3 [default='Bitcoin']; // coin to use
optional uint32 version = 4 [default=1]; // transaction version
optional uint32 lock_time = 5 [default=0]; // transaction lock_time
optional uint32 expiry = 6; // only for Decred and Zcash
optional bool overwintered = 7 [deprecated=true]; // deprecated in 2.3.2, the field is not needed as it can be derived from `version`
optional uint32 version_group_id = 8; // only for Zcash, nVersionGroupId
optional uint32 timestamp = 9; // only for Peercoin
optional uint32 branch_id = 10; // only for Zcash, BRANCH_ID
optional AmountUnit amount_unit = 11 [default=BITCOIN]; // show amounts in
optional bool decred_staking_ticket = 12 [default=false]; // only for Decred, this is signing a ticket purchase
optional bool serialize = 13 [default=true]; // serialize the full transaction, as opposed to only outputting the signatures
optional CoinJoinRequest coinjoin_request = 14; // only for preauthorized CoinJoins
optional bool chunkify = 15; // display the address in chunks of 4 characters
/**
* Signing request for a CoinJoin transaction.
*/
message CoinJoinRequest {
required uint32 fee_rate = 1; // coordination fee rate in units of 10^-6 percent
required uint64 no_fee_threshold = 2; // PlebsDontPayThreshold in Wasabi, the input amount above which the fee rate applies
required uint64 min_registrable_amount = 3; // minimum registrable output amount
optional bytes mask_public_key = 4; // ephemeral secp256k1 public key used for masking coinjoin_flags, 33 bytes in compressed form
optional bytes signature = 5; // the trusted party's signature of the CoinJoin request digest
}
}
/**
* Response: Device asks for information for signing transaction or returns the last result
* If request_index is set, device awaits TxAck<any> matching the request type.
* If signature_index is set, 'signature' contains signed input of signature_index's input
* @end
* @next TxAckInput
* @next TxAckOutput
* @next TxAckPrevMeta
* @next TxAckPrevInput
* @next TxAckPrevOutput
* @next TxAckPrevExtraData
* @next TxAckPaymentRequest
*/
message TxRequest {
optional RequestType request_type = 1; // what should be filled in TxAck message?
optional TxRequestDetailsType details = 2; // request for tx details
optional TxRequestSerializedType serialized = 3; // serialized data and request for next
/**
* Type of information required by transaction signing process
*/
enum RequestType {
TXINPUT = 0;
TXOUTPUT = 1;
TXMETA = 2;
TXFINISHED = 3;
TXEXTRADATA = 4;
TXORIGINPUT = 5;
TXORIGOUTPUT = 6;
TXPAYMENTREQ = 7;
}
/**
* Structure representing request details
*/
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 (only for Dash, Zcash)
optional uint32 extra_data_offset = 4; // offset of requested extra data (only for Dash, Zcash)
}
/**
* Structure representing serialized data
*/
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
}
}
/**
* Request: Reported transaction data (legacy)
*
* This message contains all possible field that can be sent in response to a TxRequest.
* Depending on the request_type, the host is supposed to fill some of these fields.
*
* The interface is wire-compatible with the new method of specialized TxAck subtypes,
* so it can be used in the old way. However, it is now recommended to use more
* specialized messages, which have better-configured constraints on field values.
*
* @next TxRequest
*/
message TxAck {
option deprecated = true;
optional TransactionType tx = 1;
/**
* Structure representing transaction
*/
message TransactionType {
optional uint32 version = 1;
repeated TxInputType inputs = 2;
repeated TxOutputBinType bin_outputs = 3;
optional uint32 lock_time = 4;
repeated TxOutputType outputs = 5;
optional uint32 inputs_cnt = 6;
optional uint32 outputs_cnt = 7;
optional bytes extra_data = 8; // only for Dash, Zcash
optional uint32 extra_data_len = 9; // only for Dash, Zcash
optional uint32 expiry = 10; // only for Decred and Zcash
optional bool overwintered = 11 [deprecated=true]; // Zcash only; deprecated in 2.3.2, the field is not needed, it can be derived from `version`
optional uint32 version_group_id = 12; // only for Zcash, nVersionGroupId
optional uint32 timestamp = 13; // only for Peercoin
optional uint32 branch_id = 14; // only for Zcash, BRANCH_ID
/**
* Structure representing transaction input
*/
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)
optional uint32 decred_tree = 9; // only for Decred, 0 is a normal transaction while 1 is a stake transaction
// optional uint32 decred_script_version = 10; // only for Decred // deprecated -> only 0 is supported
// optional bytes prev_block_hash_bip115 = 11; // BIP-115 support dropped
// optional uint32 prev_block_height_bip115 = 12; // BIP-115 support dropped
optional bytes witness = 13; // witness data, only set for EXTERNAL inputs
optional bytes ownership_proof = 14; // SLIP-0019 proof of ownership, only set for EXTERNAL inputs
optional bytes commitment_data = 15; // optional commitment data for the SLIP-0019 proof of ownership
optional bytes orig_hash = 16; // tx_hash of the original transaction where this input was spent (used when creating a replacement transaction)
optional uint32 orig_index = 17; // index of the input in the original transaction (used when creating a replacement transaction)
optional DecredStakingSpendType decred_staking_spend = 18; // if not None this holds the type of stake spend: revocation or stake generation
optional bytes script_pubkey = 19; // scriptPubKey of the previous output spent by this input, only set of EXTERNAL inputs
optional uint32 coinjoin_flags = 20 [default=0]; // bit field of CoinJoin-specific flags
}
/**
* Structure representing compiled transaction output
*/
message TxOutputBinType {
required uint64 amount = 1;
required bytes script_pubkey = 2;
optional uint32 decred_script_version = 3; // only for Decred, currently only 0 is supported
}
/**
* Structure representing transaction output
*/
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
optional OutputScriptType script_type = 4 [default=PAYTOADDRESS]; // 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 uint32 decred_script_version = 7; // only for Decred // deprecated -> only 0 is supported
// optional bytes block_hash_bip115 = 8; // BIP-115 support dropped
// optional uint32 block_height_bip115 = 9; // BIP-115 support dropped
optional bytes orig_hash = 10; // tx_hash of the original transaction where this output was present (used when creating a replacement transaction)
optional uint32 orig_index = 11; // index of the output in the original transaction (used when creating a replacement transaction)
optional uint32 payment_req_index = 12 [(experimental_field)=true]; // index of the PaymentRequest containing this output
}
}
}
/** Data type for transaction input to be signed.
*
* When adding fields, take care to not conflict with PrevInput
*
* @embed
*/
message TxInput {
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, only set for EXTERNAL inputs
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
required uint64 amount = 8; // amount of previous transaction output
optional uint32 decred_tree = 9; // only for Decred, 0 is a normal transaction while 1 is a stake transaction
reserved 10, 11, 12; // fields which are in use, or have been in the past, in TxInputType
optional bytes witness = 13; // witness data, only set for EXTERNAL inputs
optional bytes ownership_proof = 14; // SLIP-0019 proof of ownership, only set for EXTERNAL inputs
optional bytes commitment_data = 15; // optional commitment data for the SLIP-0019 proof of ownership
optional bytes orig_hash = 16; // tx_hash of the original transaction where this input was spent (used when creating a replacement transaction)
optional uint32 orig_index = 17; // index of the input in the original transaction (used when creating a replacement transaction)
optional DecredStakingSpendType decred_staking_spend = 18; // if not None this holds the type of stake spend: revocation or stake generation
optional bytes script_pubkey = 19; // scriptPubKey of the previous output spent by this input, only set of EXTERNAL inputs
optional uint32 coinjoin_flags = 20 [default=0]; // bit field of CoinJoin-specific flags
}
/** Data type for transaction output to be signed.
* @embed
*/
message TxOutput {
optional string address = 1; // destination address in Base58 encoding; script_type must be PAYTOADDRESS
repeated uint32 address_n = 2; // BIP-32 path to derive the destination (used for change addresses)
required uint64 amount = 3; // amount to spend in satoshis
optional OutputScriptType script_type = 4 [default=PAYTOADDRESS]; // 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
reserved 7, 8, 9; // fields which are in use, or have been in the past, in TxOutputType
optional bytes orig_hash = 10; // tx_hash of the original transaction where this output was present (used when creating a replacement transaction)
optional uint32 orig_index = 11; // index of the output in the original transaction (used when creating a replacement transaction)
optional uint32 payment_req_index = 12 [(experimental_field)=true]; // index of the PaymentRequest containing this output
}
/** Data type for metadata about previous transaction which contains the UTXO being spent.
* @embed
*/
message PrevTx {
required uint32 version = 1;
required uint32 lock_time = 4;
required uint32 inputs_count = 6;
required uint32 outputs_count = 7;
optional uint32 extra_data_len = 9 [default=0]; // only for Dash, Zcash
optional uint32 expiry = 10; // only for Decred and Zcash
optional uint32 version_group_id = 12; // only for Zcash, nVersionGroupId
optional uint32 timestamp = 13; // only for Peercoin
optional uint32 branch_id = 14; // only for Zcash, BRANCH_ID
// fields which are in use, or have been in the past, in TransactionType
reserved 2, 3, 5, 8, 11;
}
/** Data type for inputs of previous transactions.
*
* When adding fields, take care to not conflict with TxInput
* @embed
*/
message PrevInput {
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
required bytes script_sig = 4; // script signature
required uint32 sequence = 5; // sequence
optional uint32 decred_tree = 9; // only for Decred
// fields that are in use, or have been in the past, in TxInputType
reserved 1, 6, 7, 8, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19;
}
/** Data type for outputs of previous transactions.
* @embed
*/
message PrevOutput {
required uint64 amount = 1; // amount sent to this output
required bytes script_pubkey = 2; // scriptPubkey of this output
optional uint32 decred_script_version = 3; // only for Decred
}
/** Data type of a payment request for a set of outputs.
* @next TxRequest
*/
message TxAckPaymentRequest {
option (experimental_message) = true;
optional bytes nonce = 1; // the nonce used in the signature computation
required string recipient_name = 2; // merchant's name
repeated PaymentRequestMemo memos = 3; // any memos that were signed as part of the request
optional uint64 amount = 4; // the sum of the external output amounts requested, required for non-CoinJoin
required bytes signature = 5; // the trusted party's signature of the paymentRequestDigest
message PaymentRequestMemo {
optional TextMemo text_memo = 1;
optional RefundMemo refund_memo = 2;
optional CoinPurchaseMemo coin_purchase_memo = 3;
}
message TextMemo {
required string text = 1; // plain-text note explaining the purpose of the payment request
}
message RefundMemo {
required string address = 1; // the address where the payment should be refunded if necessary
required bytes mac = 2; // the MAC returned by GetAddress
}
message CoinPurchaseMemo {
required uint32 coin_type = 1; // the SLIP-0044 coin type of the address
required string amount = 2; // the amount the address will receive as a human-readable string including units, e.g. "0.025 BTC"
required string address = 3; // the address where the coin purchase will be delivered
required bytes mac = 4; // the MAC returned by GetAddress
}
}
/**
* Request: Data about input to be signed.
* Wire-alias of TxAck.
*
* Do not edit this type without considering compatibility with TxAck.
* Prefer to modify the inner TxInput type.
*
* @next TxRequest
*/
message TxAckInput {
option (wire_type) = 22;
required TxAckInputWrapper tx = 1;
message TxAckInputWrapper {
required TxInput input = 2;
}
}
/**
* Request: Data about output to be signed.
* Wire-alias of TxAck.
*
* Do not edit this type without considering compatibility with TxAck.
* Prefer to modify the inner TxOutput type.
*
* @next TxRequest
*/
message TxAckOutput {
option (wire_type) = 22;
required TxAckOutputWrapper tx = 1;
message TxAckOutputWrapper {
required TxOutput output = 5;
}
}
/**
* Request: Data about previous transaction metadata
* Wire-alias of TxAck.
*
* Do not edit this type without considering compatibility with TxAck.
* Prefer to modify the inner PrevTx type.
*
* @next TxRequest
*/
message TxAckPrevMeta {
option (wire_type) = 22;
required PrevTx tx = 1;
}
/**
* Request: Data about previous transaction input
* Wire-alias of TxAck.
*
* Do not edit this type without considering compatibility with TxAck.
* Prefer to modify the inner PrevInput type.
*
* @next TxRequest
*/
message TxAckPrevInput {
option (wire_type) = 22;
required TxAckPrevInputWrapper tx = 1;
message TxAckPrevInputWrapper {
required PrevInput input = 2;
}
}
/**
* Request: Data about previous transaction output
* Wire-alias of TxAck.
*
* Do not edit this type without considering compatibility with TxAck.
* Prefer to modify the inner PrevOutput type.
*
* @next TxRequest
*/
message TxAckPrevOutput {
option (wire_type) = 22;
required TxAckPrevOutputWrapper tx = 1;
message TxAckPrevOutputWrapper {
required PrevOutput output = 3;
}
}
/**
* Request: Content of the extra data of a previous transaction
* Wire-alias of TxAck.
*
* Do not edit this type without considering compatibility with TxAck.
*
* @next TxRequest
*/
message TxAckPrevExtraData {
option (wire_type) = 22;
required TxAckPrevExtraDataWrapper tx = 1;
message TxAckPrevExtraDataWrapper {
required bytes extra_data_chunk = 8;
}
}
/**
* Request: Ask device for a proof of ownership corresponding to address_n path
* @start
* @next OwnershipProof
* @next Failure
*/
message GetOwnershipProof {
repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node
optional string coin_name = 2 [default='Bitcoin']; // coin to use
optional InputScriptType script_type = 3 [default=SPENDWITNESS]; // used to distinguish between various scriptPubKey types
optional MultisigRedeemScriptType multisig = 4; // filled if proof is for a multisig address
optional bool user_confirmation = 5 [default=false]; // show a confirmation dialog and set the "user confirmation" bit in the proof
repeated bytes ownership_ids = 6; // list of ownership identifiers in case of multisig
optional bytes commitment_data = 7 [default='']; // additional data to which the proof should commit
}
/**
* Response: Contains the proof of ownership
* @end
*/
message OwnershipProof {
required bytes ownership_proof = 1; // SLIP-0019 proof of ownership
required bytes signature = 2; // signature of the proof
}
/**
* Request: Ask device to prompt the user to authorize a CoinJoin transaction
* @start
* @next Success
* @next Failure
*/
message AuthorizeCoinJoin {
required string coordinator = 1; // coordinator identifier to approve as a prefix in commitment data (max. 36 ASCII characters)
required uint64 max_rounds = 2; // maximum number of rounds that Trezor is authorized to take part in
required uint32 max_coordinator_fee_rate = 3; // maximum coordination fee rate in units of 10^-6 percent
required uint32 max_fee_per_kvbyte = 4; // maximum mining fee rate in units of satoshis per 1000 vbytes
repeated uint32 address_n = 5; // prefix of the BIP-32 path leading to the account (m / purpose' / coin_type' / account')
optional string coin_name = 6 [default='Bitcoin']; // coin to use
optional InputScriptType script_type = 7 [default=SPENDADDRESS]; // used to distinguish between various address formats (non-segwit, segwit, etc.)
optional AmountUnit amount_unit = 8 [default=BITCOIN]; // show amounts in
}