trezor-firmware/common/protob/messages-bitcoin.proto

syntax = "proto2";
package hw.trezor.messages.bitcoin;

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

option (include_in_bitcoin_only) = true;

import "messages.proto";
import "messages-common.proto";

/**
 * 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
        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 {
    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;        // BIP32 public node
    required string xpub = 2;                   // serialized form of public node
    optional uint32 root_fingerprint = 3;       // master root node fingerprint
}

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

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

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

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

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

/** 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)=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 (unstable) = true;

    optional bytes nonce = 1;              // the nonce used in the signature computation
    required string recipient_name = 2;    // merchant's name or coordinator's name in case of CoinJoin
    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 {
    option (unstable) = true;

    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^-8 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
}