From 503f35a9a066a51be29d9c81e73f72f54a403b76 Mon Sep 17 00:00:00 2001 From: Andrew Chow Date: Thu, 1 Aug 2019 14:28:37 -0400 Subject: Add Version type --- bip-0174.mediawiki | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/bip-0174.mediawiki b/bip-0174.mediawiki index b4a6407..bbc0fc6 100644 --- a/bip-0174.mediawiki +++ b/bip-0174.mediawiki @@ -124,6 +124,12 @@ The currently defined global types are as follows: ** Value: The master key fingerprint as defined by BIP 32 concatenated with the derivation path of the public key. The derivation path is represented as 32 bit unsigned integer indexes concatenated with each other. The number of 32 bit unsigned integer indexes must match the depth provided in the extended public key. *** {master key fingerprint}|{32-bit int}|...|{32-bit int} +* Type: Version Number PSBT_GLOBAL_VERSION = 0xFB +** Key: None. The key must only contain the 1 byte type. +*** {0xFB} +** Value: The 32-bit little endian unsigned integer representing the version number of this PSBT. If ommitted, the version number is 0. +*** {32-bit int} + The currently defined per-input types are defined as follows: * Type: Non-Witness UTXO PSBT_IN_NON_WITNESS_UTXO = 0x00 @@ -432,6 +438,17 @@ types will be ignored and passed-through by signers which do not know about them If one byte type fields were to ever run out, new extensions can still be added by defining multi-byte types where the first byte signals that the next byte indicates the type and so on. +===Version Numbers=== + +The Version number field exists only as a safeguard in the event that a backwards incompatible change is introduced to PSBT. +If a parser encounters a version number it does not recognize, it should exit immediately as this indicates that the PSBT will contain types that it does not know about and cannot be ignored. +Current PSBTs are Version 0. Any PSBT that does not have the version field is version 0. +It is not expected that any backwards incompatible change will be introduced to PSBT, so it is not expected that the version field will ever actually be seen. + +Updaters and combiners that need to add a version number to a PSBT should use the highest version number required. +For example, if a combiner sees two PSBTs for the same transaction, one with version 0, and the other with version 1, then it should combine them and produce a PSBT with version 1. +If an updater is updating a PSBT and needs to add a field that is only available in version 1, then it should set the PSBT version number to 1 unless a version higher than that is already specified. + ==Compatibility== This transaction format is designed so that it is unable to be properly unserialized -- cgit v1.2.3 From 20fdf77a2bcb04886b2b1d4d1b20b0135388ac4b Mon Sep 17 00:00:00 2001 From: Andrew Chow Date: Thu, 1 Aug 2019 14:36:25 -0400 Subject: Specify that types are compact size unsigned ints to allow for multi-byte types --- bip-0174.mediawiki | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/bip-0174.mediawiki b/bip-0174.mediawiki index bbc0fc6..d30b05d 100644 --- a/bip-0174.mediawiki +++ b/bip-0174.mediawiki @@ -106,8 +106,10 @@ The format of each key-value map is as follows: | Must be 0x00. |} -The first byte of each key specifies the type of the key-value pair. There are global types, -per-input types, and per-output types. +At the beginning of each key is a compact size unsigned integer representing the type. +This compact size unsigned integer must be minimally encoded, i.e. if the value can be represented using one byte, it must be represented as one byte. +For convenience, this BIP will specify types using their full serialization, so a multi-byte type will have it's full prefix and zero padding as necessary. +There are global types, per-input types, and per-output types. The currently defined global types are as follows: @@ -436,8 +438,6 @@ 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. -If one byte type fields were to ever run out, new extensions can still be added by defining multi-byte types where the first byte signals that the next byte indicates the type and so on. - ===Version Numbers=== The Version number field exists only as a safeguard in the event that a backwards incompatible change is introduced to PSBT. -- cgit v1.2.3 From bc3a81e69819364af5c76f73762da2c95d6069ab Mon Sep 17 00:00:00 2001 From: Andrew Chow Date: Wed, 2 Oct 2019 15:09:51 -0400 Subject: Specify proprietary use type --- bip-0174.mediawiki | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/bip-0174.mediawiki b/bip-0174.mediawiki index d30b05d..8c9f010 100644 --- a/bip-0174.mediawiki +++ b/bip-0174.mediawiki @@ -132,6 +132,12 @@ The currently defined global types are as follows: ** Value: The 32-bit little endian unsigned integer representing the version number of this PSBT. If ommitted, the version number is 0. *** {32-bit int} +* Type: Version Number PSBT_GLOBAL_PROPRIETARY = 0xFC +** Key: Variable length identifier prefix, followed by a subtype, followed by the key data itself. +*** {0xFC}||{subtype}|{key data} +** Value: Any value data as defined by the proprietary type user. +*** + The currently defined per-input types are defined as follows: * Type: Non-Witness UTXO PSBT_IN_NON_WITNESS_UTXO = 0x00 @@ -194,6 +200,12 @@ The currently defined per-input types are defined as follows: ** Value: The UTF-8 encoded commitment message string for the proof-of-reserves. See [[bip-0127.mediawiki|BIP 127]] for more information. *** {porCommitment} +* Type: Version Number PSBT_INPUT_PROPRIETARY = 0xFC +** Key: Variable length identifier prefix, followed by a subtype, followed by the key data itself. +*** {0xFC}||{subtype}|{key data} +** Value: Any value data as defined by the proprietary type user. +*** + The currently defined per-output '''Why do we need per-output data?''' Per-output data allows signers to verify that the outputs are going to the intended recipient. The output data can also be use by signers to determine which outputs are change outputs and verify that the change is returning to the correct place. types are defined as follows: @@ -216,6 +228,12 @@ determine which outputs are change outputs and verify that the change is returni ** Value: 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. Public keys are those needed to spend this output. *** {master key fingerprint}|{32-bit int}|...|{32-bit int} +* Type: Version Number PSBT_OUTPUT_PROPRIETARY = 0xFC +** Key: Variable length identifier prefix, followed by a subtype, followed by the key data itself. +*** {0xFC}||{subtype}|{key data} +** Value: Any value data as defined by the proprietary type user. +*** + The transaction format is specified as follows: @@ -291,6 +309,23 @@ whichever value it wishes.'''Why can the values be arbitrarily chosen?''' W valid or invalid. If the values are invalid, a signer would simply produce an invalid signature and the final transaction itself would be invalid. If the values are valid, then it does not matter which is chosen as either way the transaction is still valid. +===Proprietary Use Type=== + +For all global, per-input, and per-output maps, the types 0xFC is reserved for proprietary use. +The proprietary use type requires keys that follow the type with a variable length string identifer, then a subtype. + +The identifier can be any variable length string that software can use to identify whether the particular data in the proprietary type can be used by it. +It can also be the empty string and just be a single 0x00 byte although this is not recommended. + +The subtype is defined by the proprietary type user and can mean whatever they want it to mean. +The subtype must also be a compact size unsigned integer in the same form as the normal types. +The key data and value data are defined by the proprietary type user. + +The proprietary use types is for private use by individuals and organizations who wish to use PSBT in their processes. +It is useful when there are additional data that they need attached to a PSBT but such data are not useful or available for the general public. +The proprietary use type is not to be used by any public specification and there is no expectation that any publicly available software be able to understand any specific meanings of it and the subtypes. +This type must be used for internal processes only. + ==Responsibilities== Using the transaction format involves many different responsibilities. Multiple responsibilities can be handled by a single entity, but each responsibility is specialized in what it should be capable of doing. -- cgit v1.2.3