diff --git a/README.mediawiki b/README.mediawiki index 9b885138..bbdb1ba5 100644 --- a/README.mediawiki +++ b/README.mediawiki @@ -729,6 +729,13 @@ Those proposing changes should consider that ultimately consent may rest with th | Informational | Draft |- +| [[bip-0174.mediawiki|174]] +| Applications +| Partially Signed Bitcoin Transaction Format +| Andrew Chow +| Standard +| Draft +|- | [[bip-0175.mediawiki|175]] | Applications | Pay to Contract Protocol diff --git a/bip-0174.mediawiki b/bip-0174.mediawiki new file mode 100644 index 00000000..b1f0aaf3 --- /dev/null +++ b/bip-0174.mediawiki @@ -0,0 +1,453 @@ +
+ BIP: 174 + Layer: Applications + Title: Partially Signed Bitcoin Transaction Format + Author: Andrew Chow+ +==Introduction== + +===Abstract=== + +This document proposes a binary transaction format which contains the information +necessary for a signer to produce signatures for the transaction and holds the +signatures for an input while the input does not have a complete set of signatures. +The signer can be offline as all necessary information will be provided in the +transaction. + +===Copyright=== + +This BIP is licensed under the 2-clause BSD license. + +===Motivation=== + +Creating unsigned or partially signed transactions to be passed around to multiple +signers is currently implementation dependent, making it hard for people who use +different wallet software from being able to easily do so. One of the goals of this +document is to create a standard and extensible format that can be used between clients to allow +people to pass around the same transaction to sign and combine their signatures. The +format is also designed to be easily extended for future use which is harder to do +with existing transaction formats. + +Signing transactions also requires users to have access to the UTXOs being spent. This transaction +format will allow offline signers such as air-gapped wallets and hardware wallets +to be able to sign transactions without needing direct access to the UTXO set and without +risk of being defrauded. + +==Specification== + +The Partially Signed Bitcoin Transaction (PSBT) format consists of key-value maps. +Each key-value pair must be unique within its scope; duplicates are not allowed. +Each map consists of a sequence of records, terminated by a 0x00 byte '''Why +is the separator here 0x00 instead of 0xff?''' +The separator here is used to distinguish between each chunk of data. A separator of 0x00 would mean that +the unserializer can read it as a key length of 0, which would never occur with actual keys. It can thus +be used as a separator and allow for easier unserializer implementation.. The format +of a record is as follows: + +Note: <..> indicates that the data is prefixed by a compact size unsigned integer representing +the length of that data. {..} indicates the raw data itself. + ++ Comments-Summary: No comments yet. + Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0174 + Status: Draft + Type: Standards Track + Created: 2017-07-12 + License: BSD-2-Clause +
++ +{| class="wikitable" style="width: auto; text-align: center; font-size: smaller; table-layout: fixed;" +!Name +!Type +!Description +|- +| Key Length +| Compact Size Unsigned Integer +| Specify how long the key is +|- +| Key +| byte[] +| The key itself with the first byte being the type of the key-value pair +|- +| Value Length +| Compact Size Unsigned Integer +| Specify how long the value is +|- +| Value +| byte[] +| The Value itself +|} + +The format of each key-value map is as follows: + +| +
+{key-value pair}|{key-value pair}|...|{0x00}
+
+
+{| class="wikitable" style="width: auto; text-align: center; font-size: smaller; table-layout: fixed;"
+!Field Size
+!Name
+!Type
+!Value
+!Description
+|-
+| 1+
+| Key-value pairs
+| Array of key-value pairs
+| varies
+| The key-value pairs.
+|-
+| 1
+| separator
+| char
+| 0x00
+| Must be 0x00.
+|}
+
+The first byte of each key specifies the type of the key-value pair. Some types are
+for global fields and other fields are for each input. The only required type in a
+PSBT is the transaction type, as defined below. The currently defined global types are as follows:
+
+{| class="wikitable" style="width: auto; text-align: center; font-size: smaller;
+table-layout: fixed;"
+!Number
+!Name
+!Key Data
+!Value Data
+!Format Example
+|-
+| 0x00
+| Transaction
+| None. The key must only contain the 1 byte type.
+| The transaction in network serialization. The scriptSigs and
+witnesses for each input must be empty unless the input is complete. The transaction
+must be in the witness serialization format as defined in BIP 144. A PSBT must have
+a transaction, otherwise it is invalid.
+| Key:
+
+{0x00}
+
+Value:
+
+{transaction}
+
+|-
+| 0x01
+| Redeem Script'''Why are redeem scripts and witness scripts global''' Redeem
+ scripts and witness scripts are global data to avoid duplication. Instead of specifying
+ a redeems script and witness script multiple times in inputs that need those scripts,
+ they are specified once in the global data.
+| The hash160 of the redeem script
+| A redeem script that will be needed to sign a Pay-To-Script-Hash input or is spent
+to by an output.'''Why are outputs' redeem scripts and witness scripts included?'''
+Redeem scripts and witness scripts spent to by an output in this transaction are included
+so that the user can verify that the transaction they are signing is creating the correct
+outputs that have the correct redeem and witness scripts. This is best used when the
+PSBT creator is not trusted by the signers.
+| Key:
+
+{0x01}|{hash160}
+
+Value:
+
+{redeem script}
+
+|-
+| 0x02
+| Witness Script
+| The sha256 hash of the witness script
+| A witness script that will be needed to sign a Pay-To-Witness-Script-Hash input or is spent
+to by an output.
+| Key:
+
+{0x02}|{sha256}
+
+Value:
+
+{witness script}
+
+|-
+| 0x03
+| BIP 32 Derivation path, public key, and Master Key fingerprint
+| The public key
+| The master key fingerprint concatenated with the derivation path of the public key. The
+derivation path is represented as 32 bit unsigned integer indexes concatenated
+with each other. This must omit the index of the master key.
+| Key:
+
+{0x03}|{public key}
+
+Value:
+
+{master key fingerprint}|{32-bit int}|...|{32-bit int}
+
+|-
+| 0x04
+| Number of inputs
+| None. The key must only contain the 1 byte type.
+| A compact size unsigned integer representing the number of inputs that this transaction has
+| Key:
+
+{0x04}
+
+Value:
+
+{number of inputs}
+
+|}
+
+The currently defined per-input types are defined as follows:
+
+{| class="wikitable" style="width: auto; text-align: center; font-size: smaller;
+table-layout: fixed;"
+!Number
+!Name
+!Key Data
+!Value Data
+!Format Example
+|-
+| 0x00
+| Non-Witness UTXO
+| None. The key must only contain the 1 byte type.
+| The transaction in network serialization format the current input spends from.
+| Key:
+
+{0x00}
+
+Value:
+
+{transaction}
+
+|-
+| 0x01
+| Witness UTXO
+| None. The key must only contain the 1 byte type.
+| The entire transaction output in network serialization which the current input spends from.
+| Key:
+
+{0x01}
+
+Value:
+
+{serialized transaction output({output value}|)}
+
+|-
+| 0x02
+| Partial Signature
+| The public key which corresponds to this signature.
+| The signature as would be pushed to the stack from a scriptSig or witness.
+| Key:
+
+{0x02}|{public key}
+
+Value:
+
+{signature}
+
+|-
+| 0x03
+| Sighash Type
+| None. The key must only contain the 1 byte type.
+| The 32-bit unsigned integer recommending a sighash type to be used for this input.
+The sighash type is only a recommendation and the signer does not need to use
+the sighash type specified.
+| Key:
+
+{0x03}
+
+Value:
+
+{sighash type}
+
+|-
+| 0x04
+| Input index
+| None. The key must only contain the 1 byte type.
+| A compact size unsigned integer representing the index of this input. This field
+is optional to allow for completed inputs to be skipped without needing a separator byte.
+If one input has this type, then all inputs must have it.
+| Key:
+
+{0x04}
+
+Value:
+
+{input index}
+
+|}
+
+The transaction format is specified as follows:
+
+
+
+ {0x70736274}|{0xff}|{global key-value map}|{input key-value map}|...|{input key-value map}
+
+
+{| class="wikitable" style="width: auto; text-align: center; font-size: smaller; table-layout: fixed;"
+!Field Size
+!Name
+!Type
+!Value
+!Description
+|-
+| 4
+| Magic Bytes
+| int32_t
+| 0x70736274
+| Magic bytes which are ASCII for psbt. '''Why use 4 bytes for psbt?''' The
+transaction format needed to start with a 5 byte header which uniquely identifies
+it. The first bytes were chosen to be the ASCII for psbt because that stands for
+Partially Signed Bitcoin Transaction. This integer should be serialized
+in most significant byte order.
+|-
+| 1
+| separator
+| char
+| 0xff
+| Must be 0xff '''Why Use a separator after the magic bytes?''' The separator
+is part of the 5 byte header for PSBT. This byte is a separator of 0xff because
+this will cause any non-PSBT unserializer to fail to properly unserialize the PSBT
+as a normal transaction. Likewise, since the 5 byte header is fixed, no transaction
+in the non-PSBT format will be able to be unserialized by a PSBT unserializer.
+|-
+| 1+
+| Global data
+| Key-value Map
+| varies
+| The key-value pairs for all global data.
+|-
+| 1+
+| Inputs
+| Array of key-value maps
+| varies
+| The key-value pairs for each input as described below
+|}
+
+Each block of data between separators can be viewed as a scope, and all separators
+are required'''Why are all separators required?''' The separators are required
+so that the unserializer knows which input it is unserializing data for..
+Types can be skipped when they are unnecessary. For example, if an input is a witness
+input, then it should not have a Non-Witness UTXO key-value pair.
+
+If the signer encounters key-value pairs that it does not understand, it must
+pass those key-value pairs through when re-serializing the transaction.
+
+===Handling Duplicated Keys===
+
+Keys within each scope should never be duplicated; all keys in the format are unique. However implementors
+will still need to handle events where keys are duplicated, either duplicated in the transaction
+itself or when combining transactions with duplicated fields. If duplicated keys are
+encountered, the software may choose to use any of the values corresponding to that key.
+
+==Usage==
+
+Using the transaction format involves many different roles. The roles may be combined
+into one entity, but each role has a specific set of things that it must be able to do.
+
+===Transaction Creator===
+
+The transaction creator must be able to accept either a network serialized transaction or a PSBT
+and either produce a PSBT or update the provided PSBT. For all scriptSigs which are not finalized, it must make the
+scriptSig empty and fill in the input fields with information from the scriptSig, if any.
+If it is able to, it should also look for any required redeemScripts and witnesScripts
+and add those to the global data section of the PSBT. The transaction creator
+should also fill in UTXOs that it knows about.
+
+===Transaction Signer===
+
+The transaction signer must accept a PSBT. It should use the UTXOs provided in the PSBT
+to produce signatures for the inputs that it can sign for. The signer should not need
+access to the UTXO set as all necessary information is provided in the PSBT itself.
+Any and all signatures created should be added as a Partial Signature key-value pair
+to the input for which it corresponds to.
+
+The signer should also be able to compute the amount being spent, the amount being
+transacted, the inputs being spent, the transaction fee, and the addresses being
+paid. It can be interactive and ask the user for confirmation of all of the above things.
+
+===Transaction Combiner===
+
+The transaction combiner must be able to accept multiple PSBTs. It should parse each
+PSBT and merge them into one transaction if possible. If the PSBTs correspond to the
+same transaction, then the combiner should create one PSBT which contains all of the
+key-value pairs from the PSBTs. It should also handle duplicated keys and remove the
+duplication according to the specification.
+
+===Transaction Finalizer===
+
+The transaction finalizer must take a PSBT and build the finalized scriptSigs for each
+input. If an input contains enough signatures for that input to have a complete set of
+signatures, the finalizer should take those signatures, any necessary redeemScripts
+and witnessScripts, and build the complete scriptSig. The scriptSig should then be
+included in the transaction and the input should have all key-value pairs removed.
+The finalizer may remove any global data which is not needed for any other inputs.
+
+===Transaction Broadcaster===
+The transaction broadcaster takes a finalized PSBT. It takes the transaction out of the
+PSBT, ensures that the transaction is valid, and broadcasts it to the Bitcoin network.
+
+==Extensibility==
+
+The Partially Signed Transaction format can be extended in the future by adding
+new types for key-value pairs. Backwards compatibilty will still be maintained as those new
+types will be ignored and passed-through by signers which do not know about them.
+
+Additional key-value maps with different types for the key-value pairs can be added on to
+the end of the format. The number of each map that follows must be specified in the globals
+section so that parsers will know when to use different definitions of the data types.
+
+==Compatibility==
+
+This transaction format is designed so that it is unable to be properly unserialized
+by normal transaction unserializers. Likewise, a normal transaction will not be
+able to be unserialized by an unserializer for the PSBT format.
+
+==Examples==
+
+===Manual CoinJoin Workflow===
+
+
+
+===2-of-3 Multisig Workflow===
+
+
+
+==Test Vector==
+
+TBD
+
+==Rationale==
+
+