BIP 0370
Why did PSBT need a second version?
A version 0 PSBT fixes its transaction when it is created, so nobody can add an input or an output later. Version 2 drops that transaction and keeps each input's and output's details in its own map.
A version 0 PSBT, the format BIP 174 defines, carries the whole unsigned transaction in one global field. That transaction is fixed: once the PSBT exists, nobody who receives it can add an input or an output. BIP 370 defines a second version of the format that allows both.123
Version 2 must leave the unsigned transaction out. Its global map gives the transaction's version and the number of inputs and outputs. Each input map names the output it spends, by previous txid and index, and each output map gives an amount and a script. As the author notes, everything about one input or output is now in one place.456
Source details
This chapter is an independent explanation, not the proposal itself. Preamble fields are shown as the pinned files record them, without author e-mail addresses. Status is the proposal’s own field. It is not an endorsement or a sign of consensus.
BIP 370: PSBT Version 2
- BIP
- 370
- Layer
- Applications
- Title
- PSBT Version 2
- Authors
- Ava Chow
- Status
- Deployed
- Type
- Specification
- Assigned
- 2021-01-14
- License
- BSD-2-Clause
Fig. A22.1 Each field in its own map
The transaction, part by part
- nVersion ← PSBT_GLOBAL_TX_VERSION
02000000- input count ← PSBT_GLOBAL_INPUT_COUNT
01- input 1 · previous txid ← PSBT_IN_PREVIOUS_TXID
0b0ad921419c1c8719735d72dc739f9ea9e0638d1fe4c1eef0f9944084815fc8- input 1 · output index ← PSBT_IN_OUTPUT_INDEX
00000000- input 1 · empty scriptSig ← unsigned: no scriptSig
00- input 1 · nSequence ← PSBT_IN_SEQUENCE
feffffff- output count ← PSBT_GLOBAL_OUTPUT_COUNT
02- output 1 · amount ← PSBT_OUT_AMOUNT
0008af2f00000000- output 1 · scriptPubKey ← PSBT_OUT_SCRIPT
160014c430f64c4756da310dbd1a085572ef299926272c- output 2 · amount ← PSBT_OUT_AMOUNT
8bbdeb0b00000000- output 2 · scriptPubKey ← PSBT_OUT_SCRIPT
1600144dd193ac964a56ac1b9e1cca8454fe2f474f8513- nLockTime ← maximum required height
10270000
Two versions, one format
Both versions use BIP 174's key-value format, so a version 0 parser should be able to read version 2 once it supports the new fields. They are still deliberately incompatible. A version 2 PSBT sets PSBT_GLOBAL_VERSION to 2, and a version 0 PSBT must carry none of the fields version 2 adds. Going back is possible: build the unsigned transaction from the version 2 fields.589
The PSBT's version is not the transaction's. The transaction being built has its own version, in PSBT_GLOBAL_TX_VERSION.10
Fig. A22.2 Every invalid vector and the rule it breaks
Adding inputs and outputs
In version 2 the Creator starts with no inputs and no outputs. A new role, the Constructor, adds them, but only while PSBT_GLOBAL_TX_MODIFIABLE allows it: bit 0 permits adding or removing inputs, bit 1 outputs. A Creator who passes the PSBT on for others to fill must include that field, with the inputs and outputs flags set as appropriate. Such a Creator must also set the transaction version to at least 2.131415
Signing narrows what may change. After signing, a Signer must update the flags. A signature without SIGHASH_ANYONECANPAY clears the inputs flag, and one without SIGHASH_NONE clears the outputs flag. One that uses SIGHASH_SINGLE sets bit 2, which warns Constructors that an input and its output must stay paired.1516
Fig. A22.3 Flags that say what may still change
A Constructor can also close the PSBT itself, by clearing the bits or removing the field. One wallet will often be both Creator and Constructor; if no one else will add inputs or outputs, it may leave the field out.1318
Choosing the lock time
Without an unsigned transaction there is no nLockTime field to read. Each input can state the lock time it needs instead: a minimum block height, a minimum Unix time, or both. The global map may hold a fallback for when no input states one; without it, the fallback is 0.1219
If any input states a lock time, the type chosen is the one every such input accepts. An input that states both accepts either, as does one that states none. The lock time is then the largest value of that type. When both types would work, the height must be chosen. The author's reason: signatures commit to the lock time, so every signer must reach the same choice, and a block height is Bitcoin's own unit of time.202122
Fig. A22.4 One lock time from the inputs' requirements
Static view: one of BIP 370's 10 lock-time vectors. With JavaScript you can choose the others.
Line 465: input 1 has no lock-time field. No input requires a lock time. No fallback field, so the fallback is 0. nLockTime = 0. BIP 370 gives 0.
BIP 370 line 465: “No locktimes specified”. The heading on line 462 gives the expected result; the tested model computes it from the PSBT's fields.
Line 469: input 1 has no lock-time field; input 2 has no lock-time field. No input requires a lock time. Use the fallback lock time, 0. nLockTime = 0. BIP 370 gives 0.
BIP 370 line 469: “Fallback locktime of 0”. The heading on line 462 gives the expected result; the tested model computes it from the PSBT's fields.
Line 475: input 1 requires height 10000; input 2 has no lock-time field. Requiring a lock time: input 1. It accepts a height. The required height: 10000. BIP 370 gives 10000.
BIP 370 line 475: “Input 1 has PSBT_IN_REQUIRED_HEIGHT_LOCKTIME of 10000, Input 2 has no locktime fields”. The heading on line 472 gives the expected result; the tested model computes it from the PSBT's fields.
Line 479: input 1 requires height 10000; input 2 requires height 9000. Requiring a lock time: inputs 1 and 2. Each of them accepts a height. Largest required height: max(10000, 9000) = 10000. BIP 370 gives 10000.
BIP 370 line 479: “Input 1 has PSBT_IN_REQUIRED_HEIGHT_LOCKTIME of 10000, Input 2 has PSBT_IN_REQUIRED_HEIGHT_LOCKTIME of 9000”. The heading on line 472 gives the expected result; the tested model computes it from the PSBT's fields.
Line 483: input 1 requires height 10000; input 2 requires height 9000 and time 1657048460. Requiring a lock time: inputs 1 and 2. Each of them accepts a height. Largest required height: max(10000, 9000) = 10000. BIP 370 gives 10000.
BIP 370 line 483: “Input 1 has PSBT_IN_REQUIRED_HEIGHT_LOCKTIME of 10000, Input 2 has PSBT_IN_REQUIRED_HEIGHT_LOCKTIME of 9000 and PSBT_IN_REQUIRED_TIME_LOCKTIME of 1657048460”. The heading on line 472 gives the expected result; the tested model computes it from the PSBT's fields.
Line 487: input 1 requires height 10000 and time 1657048459; input 2 requires height 9000 and time 1657048460. Requiring a lock time: inputs 1 and 2. Each of them accepts both types: height wins the tie. Largest required height: max(10000, 9000) = 10000. BIP 370 gives 10000.
BIP 370 line 487: “Input 1 has PSBT_IN_REQUIRED_HEIGHT_LOCKTIME of 10000 and PSBT_IN_REQUIRED_TIME_LOCKTIME of 1657048459, Input 2 has PSBT_IN_REQUIRED_HEIGHT_LOCKTIME of 9000 and PSBT_IN_REQUIRED_TIME_LOCKTIME of 1657048460”. The heading on line 472 gives the expected result; the tested model computes it from the PSBT's fields.
Line 493: input 1 requires time 1657048459; input 2 requires height 9000 and time 1657048460. Requiring a lock time: inputs 1 and 2. Each of them accepts a time. Largest required time: max(1657048459, 1657048460) = 1657048460. BIP 370 gives 1657048460.
BIP 370 line 493: “Input 1 has PSBT_IN_REQUIRED_TIME_LOCKTIME of 1657048459, Input 2 has PSBT_IN_REQUIRED_HEIGHT_LOCKTIME of 9000 and PSBT_IN_REQUIRED_TIME_LOCKTIME of 1657048460”. The heading on line 490 gives the expected result; the tested model computes it from the PSBT's fields.
Line 497: input 1 requires height 10000 and time 1657048459; input 2 requires time 1657048460. Requiring a lock time: inputs 1 and 2. Each of them accepts a time. Largest required time: max(1657048459, 1657048460) = 1657048460. BIP 370 gives 1657048460.
BIP 370 line 497: “Input 1 has PSBT_IN_REQUIRED_HEIGHT_LOCKTIME of 10000 and PSBT_IN_REQUIRED_TIME_LOCKTIME of 1657048459, Input 2 has PSBT_IN_REQUIRED_TIME_LOCKTIME of 1657048460”. The heading on line 490 gives the expected result; the tested model computes it from the PSBT's fields.
Line 500: input 1 has no lock-time field; input 2 requires time 1657048460. Requiring a lock time: input 2. It accepts a time. The required time: 1657048460. BIP 370 gives 1657048460.
BIP 370 line 500 (printed without a case line; the requirements shown are read from its bytes). The heading on line 490 gives the expected result; the tested model computes it from the PSBT's fields.
Line 506: input 1 requires height 10000; input 2 requires time 1657048460. Requiring a lock time: inputs 1 and 2. No type suits all of them: one needs a height, another a time. No lock time can be chosen. BIP 370 gives cannot be computed.
BIP 370 line 506: “Input 1 has PSBT_IN_REQUIRED_HEIGHT_LOCKTIME of 10000, Input 2 has PSBT_IN_REQUIRED_TIME_LOCKTIME of 1657048460”. The heading on line 503 gives the expected result; the tested model computes it from the PSBT's fields.
If one input needs only a height and another only a time, no lock time satisfies both, and BIP 370's last vector says its lock time cannot be computed. A Constructor must check for this before adding an input. It must not add an input whose lock time is incompatible, or one that would change the lock time once there are signatures.252627
Naming the transaction
A version 2 PSBT is identified by the transaction it describes: build the unsigned transaction from its fields and take its txid. So the ID changes whenever an input or output is added or the lock time changes. Every sequence must be set to 0 for this, because Updaters and Combiners can still change PSBT_IN_SEQUENCE. In the model, BIP 370's vectors that differ only in their sequence or their modifiable flags share one ID.28293031
Finalizing and extracting
When the Input Finalizer clears a finalized input as BIP 174 asks, it must keep the version 2 input fields: previous txid, output index, sequence and both lock-time requirements. The Transaction Extractor builds the transaction from those fields, with the lock time chosen as above. An omitted sequence means 0xffffffff.3032
Evidence
Each numbered marker in the text points here, and the ↩ links lead back to the text. Quotes are verbatim
from the BIP files at commit 3a10b5b, wiki markup
included. Links open the exact lines. Labels say what kind of statement each entry is: a rule, the
author’s rationale, history, a test vector, or our own inference.
-
↩ a b Rule In BIP 174, a version 0 PSBT must include PSBT_GLOBAL_UNSIGNED_TX, one global field holding the transaction in network serialization with every scriptSig and witness empty.
Quoted source text (2)
| Unsigned Transaction | <tt>PSBT_GLOBAL_UNSIGNED_TX = 0x00</tt> | None | No key data | <tt><bytes transaction></tt> | The transaction in network serialization. The scriptSigs and witnesses for each input must be empty.
Version 0 PSBTs must include PSBT_GLOBAL_UNSIGNED_TX, if omitted, the PSBT is invalid.
-
↩ Author’s rationale The author's motivation: a version 0 PSBT cannot have inputs or outputs added, because its global unsigned transaction is fixed and cannot be changed.
Quoted source text (1)
Partially Signed Bitcoin Transaction Version 0 as described in BIP 174 is unable to have new inputs and outputs be added to the transaction. The fixed global unsigned transaction cannot be changed which prevents any additional inputs or outputs to be added. PSBT Version 2 is intended to rectify this problem.
-
↩ Rule BIP 370 proposes a second version of BIP 174's PSBT format that allows inputs and outputs to be added after the PSBT is created.
Quoted source text (1)
This document proposes a second version of the Partially Signed Bitcoin Transaction format described in BIP 174 which allows for inputs and outputs to be added to the PSBT after creation.
-
↩ a b Rule BIP 370 specifies only new fields and which versions must include or exclude them; PSBT_GLOBAL_UNSIGNED_TX must be excluded in version 2, and PSBT_GLOBAL_VERSION included and set to 2.
Quoted source text (1)
PSBT Version 2 (PSBTv2) only specifies new fields and field inclusion/exclusion requirements. <tt>PSBT_GLOBAL_UNSIGNED_TX</tt> must be excluded in PSBTv2. <tt>PSBT_GLOBAL_VERSION</tt> must be included in PSBTv2 and set to version number 2
-
↩ a b c d Rule Version 2 requires the transaction version, input count and output count in the global map, the previous txid and output index in each input map, and the amount and script in each output map; version 0 must exclude every field BIP 370 adds.
BIP 370 L55–57 BIP 370 L59–67 BIP 370 L69–77 BIP 370 L79–87 BIP 370 L89–97 BIP 370 L99–107 BIP 370 L123–131 BIP 370 L133–141 BIP 370 L143–151 BIP 370 L153–161 BIP 370 L163–171 BIP 370 L187–195 BIP 370 L197–205
Quoted source text (13)
! Versions Requiring Inclusion ! Versions Requiring Exclusion ! Versions Allowing Inclusion
| Transaction Version | <tt>PSBT_GLOBAL_TX_VERSION = 0x02</tt> | None | No key data | <tt><32-bit little endian int version></tt> | The 32-bit little endian signed integer representing the version number of the transaction being created. Note that this is not the same as the PSBT version number specified by the PSBT_GLOBAL_VERSION field. | 2 | 0 | 2
| Fallback Locktime | <tt>PSBT_GLOBAL_FALLBACK_LOCKTIME = 0x03</tt> | None | No key data | <tt><32-bit little endian uint locktime></tt> | The 32-bit little endian unsigned integer representing the transaction locktime to use if no inputs specify a required locktime. | | 0 | 2
| Input Count | <tt>PSBT_GLOBAL_INPUT_COUNT = 0x04</tt> | None | No key data | <tt><compact size uint input count></tt> | Compact size unsigned integer representing the number of inputs in this PSBT. | 2 | 0 | 2
| Output Count | <tt>PSBT_GLOBAL_OUTPUT_COUNT = 0x05</tt> | None | No key data | <tt><compact size uint output count></tt> | Compact size unsigned integer representing the number of outputs in this PSBT. | 2 | 0 | 2
| Transaction Modifiable Flags | <tt>PSBT_GLOBAL_TX_MODIFIABLE = 0x06</tt> | None | No key data | <tt><8-bit uint flags></tt> | An 8 bit unsigned integer as a bitfield for various transaction modification flags. Bit 0 is the Inputs Modifiable Flag, set to 1 to indicate whether inputs can be added or removed. Bit 1 is the Outputs Modifiable Flag, set to 1 to indicate whether outputs can be added or removed. Bit 2 is the Has SIGHASH_SINGLE flag, set to 1 to indicate whether the transaction has a SIGHASH_SINGLE signature who's input and output pairing must be preserved. Bit 2 essentially indicates that the Constructor must iterate the inputs to determine whether and how to add or remove an input. | | 0 | 2
| Previous TXID | <tt>PSBT_IN_PREVIOUS_TXID = 0x0e</tt> | None | No key data | <tt><32 byte txid></tt> | 32 byte txid in standard byte order, not display byte order, of the previous transaction whose output at PSBT_IN_OUTPUT_INDEX is being spent. | 2 | 0 | 2
| Spent Output Index | <tt>PSBT_IN_OUTPUT_INDEX = 0x0f</tt> | None | No key data | <tt><32-bit little endian uint index></tt> | 32 bit little endian integer representing the index of the output being spent in the transaction with the txid of PSBT_IN_PREVIOUS_TXID. | 2 | 0 | 2
| Sequence Number | <tt>PSBT_IN_SEQUENCE = 0x10</tt> | None | No key data | <tt><32-bit little endian uint sequence></tt> | The 32 bit unsigned little endian integer for the sequence number of this input. If omitted, the sequence number is assumed to be the final sequence number (0xffffffff). | | 0 | 2
| Required Time-based Locktime | <tt>PSBT_IN_REQUIRED_TIME_LOCKTIME = 0x11</tt> | None | No key data | <tt><32-bit little endian uint locktime></tt> | 32 bit unsigned little endian integer greater than or equal to 500000000 representing the minimum Unix timestamp that this input requires to be set as the transaction's lock time. | | 0 | 2
| Required Height-based Locktime | <tt>PSBT_IN_REQUIRED_HEIGHT_LOCKTIME = 0x12</tt> | None | No key data | <tt><32-bit uint locktime></tt> | 32 bit unsigned little endian integer greater than 0 and less than 500000000 representing the minimum block height that this input requires to be set as the transaction's lock time. | | 0 | 2
| Output Amount | <tt>PSBT_OUT_AMOUNT = 0x03</tt> | None | No key data | <tt><64-bit little endian int amount></tt> | 64 bit signed little endian integer representing the output's amount in satoshis. | 2 | 0 | 2
| Output Script | <tt>PSBT_OUT_SCRIPT = 0x04</tt> | None | No key data | <tt><bytes script></tt> | The script for this output, also known as the scriptPubKey. | 2 | 0 | 2
-
↩ Author’s rationale The author notes a side effect: in version 2 all information for an input or output is in its own map, where version 0 split it between that map and the global unsigned transaction.
Quoted source text (1)
An additional beneficial side effect is that all information for a given input or output will be provided by its <tt><input-map></tt> or <tt><output-map></tt>. With Version 0, to retrieve all of the information for an input or output, data would need to be found in two locations: the <tt><input-map></tt>/<tt><output-map></tt> and the global unsigned transaction. PSBT Version 2 now moves all related information to one place.
-
↩ Test vector In the model, BIP 370's vector with all version 2 fields describes a 113-byte unsigned transaction whose lock time is 10000: its one input requires both a height and a time, so the height is used.
Quoted source text (1)
* Case: 1 input, 2 output updated PSBTv2, with all PSBTv2 fields
-
↩ a b Rule Versions 0 and 2 are intentionally incompatible through PSBT_GLOBAL_VERSION, so that the unsigned transaction could be removed; a version 2 PSBT can be converted to version 0 by building the unsigned transaction from its fields.
Quoted source text (1)
However PSBTv2 is incompatible with PSBTv0, and vice versa due to the use of the PSBT_GLOBAL_VERSION. This incompatibility is intentional so that PSBT_GLOBAL_UNSIGNED_TX could be removed in PSBTv2. However it is possible to convert a PSBTv2 to a PSBTv0 by creating an unsigned transaction from the PSBTv2 fields.
-
↩ Rule Version 2 shares BIP 174's generic format, so version 0 parsers should be able to read it with only support for the new fields added.
Quoted source text (1)
PSBTv2 shares the same generic format as PSBTv0 as defined in BIP 174. Parsers for PSBTv0 should be able to deserialize PSBTv2 with only changes to support the new fields.
-
↩ Rule PSBT_GLOBAL_TX_VERSION holds the version of the transaction being created, which is not the PSBT's own version number in PSBT_GLOBAL_VERSION.
Quoted source text (1)
The 32-bit little endian signed integer representing the version number of the transaction being created. Note that this is not the same as the PSBT version number specified by the PSBT_GLOBAL_VERSION field.
-
↩ Test vector This site's model reads all 24 of BIP 370's invalid PSBTs as invalid and all 14 valid PSBTs as valid version 2 PSBTs. Twelve invalid ones are version 0 PSBTs carrying a field version 2 adds; the first, a version 0 PSBT relabelled as version 2, is read as version 2 and rejected for still holding its unsigned transaction; the other eleven are version 2 PSBTs. The model rejects each vector except the first for the field its case names.
Quoted source text (2)
The following are invalid PSBTs: * Case: PSBTv0 but with PSBT_GLOBAL_VERSION set to 2.
The following are valid PSBTs
-
↩ a b Rule An input can state a required time lock (a Unix timestamp of at least 500000000) or a required height lock (a block height greater than 0 and less than 500000000), each the minimum it needs as the transaction's lock time.
Quoted source text (2)
32 bit unsigned little endian integer greater than or equal to 500000000 representing the minimum Unix timestamp that this input requires to be set as the transaction's lock time.
32 bit unsigned little endian integer greater than 0 and less than 500000000 representing the minimum block height that this input requires to be set as the transaction's lock time.
-
↩ a b Rule In version 2 the Creator starts with 0 inputs and 0 outputs and should set the fallback lock time; if others will add inputs and outputs, PSBT_GLOBAL_TX_MODIFIABLE must be present with its flags set appropriately and the transaction version must be at least 2; a Creator that is also the Constructor, with no one else adding inputs or outputs, may omit the field.
Quoted source text (2)
In PSBTv2, the Creator initializes the PSBT with 0 inputs and 0 outputs. The PSBT version number is set to 2. The Creator should also set PSBT_GLOBAL_FALLBACK_LOCKTIME. If the Creator is not also a Constructor and will be giving the PSBT to others to add inputs and outputs, the PSBT_GLOBAL_TX_MODIFIABLE field must be present and the Inputs Modifiable and Outputs Modifiable flags set appropriately; moreover, the transaction version number must be set to at least 2.
If the Creator is a Constructor and no inputs and outputs will be added by other entities, PSBT_GLOBAL_TX_MODIFIABLE may be omitted.
-
↩ Rule The Constructor, a role only in version 2, adds inputs and outputs: it must check PSBT_GLOBAL_TX_MODIFIABLE first, adding inputs only if the Inputs Modifiable flag is set and outputs only if the Outputs Modifiable flag is set.
Quoted source text (1)
This Constructor is only present for PSBTv2. Once a Creator initializes the PSBT, a constructor will add inputs and outputs. Before any input or output may be added, the constructor must check the PSBT_GLOBAL_TX_MODIFIABLE field. Inputs may only be added if the Inputs Modifiable flag is True. Outputs may only be added if the Outputs Modifiable flag is True.
-
↩ a b c Rule PSBT_GLOBAL_TX_MODIFIABLE is an 8-bit field: bit 0 says inputs can be added or removed, bit 1 outputs, and bit 2 that a SIGHASH_SINGLE signature's input and output pairing must be preserved.
Quoted source text (1)
An 8 bit unsigned integer as a bitfield for various transaction modification flags. Bit 0 is the Inputs Modifiable Flag, set to 1 to indicate whether inputs can be added or removed. Bit 1 is the Outputs Modifiable Flag, set to 1 to indicate whether outputs can be added or removed. Bit 2 is the Has SIGHASH_SINGLE flag, set to 1 to indicate whether the transaction has a SIGHASH_SINGLE signature who's input and output pairing must be preserved.
-
↩ a b Rule After signing, a version 2 Signer must update the flags: a signature without SIGHASH_ANYONECANPAY clears Inputs Modifiable, one without SIGHASH_NONE clears Outputs Modifiable, and one with SIGHASH_SINGLE sets Has SIGHASH_SINGLE.
Quoted source text (1)
For PSBTv2s, a signer must update the PSBT_GLOBAL_TX_MODIFIABLE field after signing inputs so that it accurately reflects the state of the PSBT. If the Signer added a signature that does not use SIGHASH_ANYONECANPAY, the Input Modifiable flag must be set to False. If the Signer added a signature that does not use SIGHASH_NONE, the Outputs Modifiable flag must be set to False. If the Signer added a signature that uses SIGHASH_SINGLE, the Has SIGHASH_SINGLE flag must be set to True.
-
↩ Test vector In the model, BIP 370's vector with both modifiable flags set (0x03) allows adding inputs and outputs; one signature leaves 0x00 for SIGHASH_ALL, 0x02 for NONE, 0x04 for SINGLE, 0x01 for ALL|ANYONECANPAY, 0x03 for NONE|ANYONECANPAY and 0x05 for SINGLE|ANYONECANPAY. BIP 370 calls bit 3 undefined, and its vector with all eight bits set is valid.
BIP 370 L436 BIP 370 L432 BIP 370 L452
Quoted source text (3)
* Case: 1 input, 2 output updated PSBTv2, with both Inputs Modifiable Flag (bit 0) and Outputs Modifiable Flag (bit 1) of PSBT_GLOBAL_TX_MODIFIABLE set
* Case: 1 input, 2 output updated PSBTv2, with an undefined flag (bit 3) of PSBT_GLOBAL_TX_MODIFIABLE set
* Case: 1 input, 2 output updated PSBTv2, with all possible PSBT_GLOBAL_TX_MODIFIABLE flags set
-
↩ Rule A Constructor may declare that no more inputs and outputs can be added by setting the flags to 0 or removing the field; one entity is likely to be both Creator and Constructor.
Quoted source text (1)
A Constructor may choose to declare that no further inputs and outputs can be added to the transaction by setting the appropriate bits in PSBT_GLOBAL_TX_MODIFIABLE to 0 or by removing the field entirely. A single entity is likely to be both a Creator and Constructor.
-
↩ a b Rule PSBT_GLOBAL_FALLBACK_LOCKTIME is the lock time to use if no input requires one; if no input requires a lock time it must be used, and without it the lock time is 0.
Quoted source text (2)
The 32-bit little endian unsigned integer representing the transaction locktime to use if no inputs specify a required locktime.
If none of the inputs have a PSBT_IN_REQUIRED_TIME_LOCKTIME and PSBT_IN_REQUIRED_HEIGHT_LOCKTIME, then PSBT_GLOBAL_FALLBACK_LOCKTIME must be used. If PSBT_GLOBAL_FALLBACK_LOCKTIME is not provided, then it is assumed to be 0.
-
↩ a b Rule If any input requires a lock time, the type chosen is the one every requiring input supports; inputs with no lock-time field, and inputs with both, take either type; the lock time is the maximum value of the chosen type.
Quoted source text (1)
If one or more inputs have a PSBT_IN_REQUIRED_TIME_LOCKTIME or PSBT_IN_REQUIRED_HEIGHT_LOCKTIME, then the field chosen is the one which is supported by all of the inputs. This can be determined by looking at all of the inputs which specify a locktime in either of those fields, and choosing the field which is present in all of those inputs. Inputs not specifying a lock time field can take both types of lock times, as can those that specify both. The lock time chosen is then the maximum value of the chosen type of lock time.
-
↩ a b Rule When both types are possible because inputs specify both, the height-based lock time must be chosen.
Quoted source text (1)
If a PSBT has both types of locktimes possible because one or more inputs specify both PSBT_IN_REQUIRED_TIME_LOCKTIME and PSBT_IN_REQUIRED_HEIGHT_LOCKTIME, then locktime determined by looking at the PSBT_IN_REQUIRED_HEIGHT_LOCKTIME fields of the inputs must be chosen.
-
↩ Author’s rationale The author's rationale for the tie rule: signatures commit to the lock time, so signers must know which one is used, and height is preferred because block height is Bitcoin's unit of time.
Quoted source text (1)
In the event of a tie for the locktime type, signers need to be able to know which locktime to use as their signatures will commit to the locktime in the transaction, so choosing the wrong one will result in an invalid transaction. Height based locktime is preferred over time based as Bitcoin's unit of time is the block height, so a height makes more sense in the context of Bitcoin.
-
↩ Test vector The model computes the lock time of all ten of BIP 370's lock-time vectors as the BIP gives it, including the vector on line 500, which is printed without a case line; its bytes show that only input 2 requires a lock time, a time of 1657048460.
BIP 370 L460 BIP 370 L490 BIP 370 L500
Quoted source text (3)
The following tests are the timelock determination algorithm.
The timelock for the following PSBTs should be computed to be 1657048460:
** Bytes in Hex: <pre>70736274ff0102040200000001030400000000
-
↩ Test vector As a Unix time, 1657048460 is 5 July 2022 at 19:14:20 UTC.
Quoted source text (1)
representing the minimum Unix timestamp that this input requires to be set as the transaction's lock time.
-
↩ Editorial inference When one input requiring a lock time states only a height and another only a time, no type is supported by all of them, so no lock time can be chosen; an input that states both does not cause a conflict.
Quoted source text (1)
the field chosen is the one which is supported by all of the inputs. This can be determined by looking at all of the inputs which specify a locktime in either of those fields, and choosing the field which is present in all of those inputs. Inputs not specifying a lock time field can take both types of lock times, as can those that specify both.
-
↩ Rule BIP 370's last lock-time vector, where input 1 requires a height and input 2 a time, is listed as one whose lock time cannot be computed.
Quoted source text (1)
The timelock for the following PSBTs cannot be computed: * Case: Input 1 has PSBT_IN_REQUIRED_HEIGHT_LOCKTIME of 10000, Input 2 has PSBT_IN_REQUIRED_TIME_LOCKTIME of 1657048460
-
↩ Rule A Constructor adding an input with a required lock time must check that the lock-time types stay compatible, must not add an incompatible input, and must not add one that changes the lock time when inputs already have signatures.
Quoted source text (1)
If an input being added specifies a required time lock, then the Constructor must iterate through all of the existing inputs and ensure that the time lock types are compatible. Additionally, if during this iteration, it finds that any inputs have signatures, it must ensure that the newly added input does not change the transaction's locktime. If the newly added input has an incompatible time lock, then it must not be added. If it changes the transaction's locktime when there are existing signatures, it must not be added.
-
↩ Rule A version 2 PSBT is identified by the txid of the unsigned transaction its fields describe, with every sequence set to 0 because Updaters and Combiners can change PSBT_IN_SEQUENCE, and the lock time computed as described.
Quoted source text (1)
PSBTv2s can be uniquely identified by constructing an unsigned transaction given the information provided in the PSBT, and computing the transaction ID of that transaction. Since PSBT_IN_SEQUENCE can be changed by Updaters and Combiners, the sequence number in this unsigned transaction must be set to 0 (not final, nor the sequence in PSBT_IN_SEQUENCE). The lock time in this unsigned transaction must be computed as described previously.
-
↩ Editorial inference Because the unique ID is the txid of the transaction the PSBT describes, adding an input or output, or changing the lock time, changes the ID; in the model, the all-fields vector, whose input requires a lock time, has a different ID from the otherwise matching vectors.
Quoted source text (1)
PSBTv2s can be uniquely identified by constructing an unsigned transaction given the information provided in the PSBT, and computing the transaction ID of that transaction.
-
↩ a b Rule PSBT_IN_SEQUENCE is optional; when it is omitted the sequence is assumed to be 0xffffffff. In version 2 an Updater can set it.
Quoted source text (2)
If omitted, the sequence number is assumed to be the final sequence number (0xffffffff).
For PSBTv2, an Updater can set the sequence number.
-
↩ Test vector In the model, valid vectors that differ only in PSBT_IN_SEQUENCE or in their modifiable flags have the same unique ID; the vector whose inputs require a lock time has a different one.
Quoted source text (1)
Since PSBT_IN_SEQUENCE can be changed by Updaters and Combiners, the sequence number in this unsigned transaction must be set to 0 (not final, nor the sequence in PSBT_IN_SEQUENCE).
-
↩ Rule The Input Finalizer must keep the version 2 input fields, and the Transaction Extractor builds the transaction from them with the lock time determined as described.
BIP 370 L283–284 BIP 370 L288–289
Quoted source text (2)
For PSBTv2s, when the Input Finalizer clears a finalized input's fields as BIP 174 asks, it must keep PSBT_IN_PREVIOUS_TXID, PSBT_IN_OUTPUT_INDEX, PSBT_IN_SEQUENCE, PSBT_IN_REQUIRED_TIME_LOCKTIME and PSBT_IN_REQUIRED_HEIGHT_LOCKTIME. The Transaction Extractor constructs the transaction from these fields, and an input missing either PSBT_IN_PREVIOUS_TXID or PSBT_IN_OUTPUT_INDEX is invalid.
For PSBTv2s, the transaction is constructed using the PSBTv2 fields. The lock time for this transaction is determined as described in the Determining Lock Time section.
-
↩ History BIP 370 (Ava Chow), PSBT Version 2, was assigned in 2021 and is recorded as Deployed; it is a Specification in the Applications layer.
Quoted source text (1)
Layer: Applications Title: PSBT Version 2 Authors: Ava Chow <me@achow101.com> Status: Deployed Type: Specification Assigned: 2021-01-14
-
↩ Author’s rationale The author's reason for skipping version number 1: version 0 had been called version 1 informally, and this proposal version 2 during its design.
Quoted source text (1)
Version number 1 is skipped because PSBT Version 0 has been colloquially referred to as version 1. Originally this BIP was to be version 1, but because it has been colloquially referred to as version 2 during its design phase, it was decided to change the version number to 2 so that there would not be any confusion