Merge pull request #849 from achow101/bip174-extensions

Bip174 extensions

1 files changed, 55 insertions, 3 deletions

diff --git a/bip-0174.mediawiki b/bip-0174.mediawiki
index 75a4df9..38ea8b3 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 <tt>0x00</tt>.
 |}
 
-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:
 
@@ -124,6 +126,18 @@ 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.
 *** <tt>{master key fingerprint}|{32-bit int}|...|{32-bit int}</tt>
 
+* Type: Version Number <tt>PSBT_GLOBAL_VERSION = 0xFB</tt>
+** Key: None. The key must only contain the 1 byte type.
+*** <tt>{0xFB}</tt>
+** Value: The 32-bit little endian unsigned integer representing the version number of this PSBT. If ommitted, the version number is 0.
+*** <tt>{32-bit int}</tt>
+
+* Type: Version Number <tt>PSBT_GLOBAL_PROPRIETARY = 0xFC</tt>
+** Key: Variable length identifier prefix, followed by a subtype, followed by the key data itself.
+*** <tt>{0xFC}|<prefix>|{subtype}|{key data}</tt>
+** Value: Any value data as defined by the proprietary type user.
+*** <tt><data></tt>
+
 The currently defined per-input types are defined as follows:
 
 * Type: Non-Witness UTXO <tt>PSBT_IN_NON_WITNESS_UTXO = 0x00</tt>
@@ -186,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.
 *** <tt>{porCommitment}</tt>
 
+* Type: Version Number <tt>PSBT_INPUT_PROPRIETARY = 0xFC</tt>
+** Key: Variable length identifier prefix, followed by a subtype, followed by the key data itself.
+*** <tt>{0xFC}|<prefix>|{subtype}|{key data}</tt>
+** Value: Any value data as defined by the proprietary type user.
+*** <tt><data></tt>
+
 The currently defined per-output <ref>'''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.</ref> types are defined as follows:
@@ -208,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.
 *** <tt>{master key fingerprint}|{32-bit int}|...|{32-bit int}</tt>
 
+* Type: Version Number <tt>PSBT_OUTPUT_PROPRIETARY = 0xFC</tt>
+** Key: Variable length identifier prefix, followed by a subtype, followed by the key data itself.
+*** <tt>{0xFC}|<prefix>|{subtype}|{key data}</tt>
+** Value: Any value data as defined by the proprietary type user.
+*** <tt><data></tt>
+
 The transaction format is specified as follows:
 
 
@@ -283,6 +309,23 @@ whichever value it wishes.<ref>'''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.</ref>
 
+===Proprietary Use Type===
+
+For all global, per-input, and per-output maps, the types <tt>0xFC</tt> 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 <tt>0x00</tt> 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.
@@ -430,7 +473,16 @@ 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.
+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==