Skip to content
BIP ATLAS

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 revision
bitcoin/bips @ 3a10b5b
Source checked
8 November 2026
Review state
Technical review applied, awaiting sign-off
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

Pinned source · Reader view on bips.dev
SHA-256 b2b6e9099592fa04179383f9a1fd8b201fbeef4470f4c3f1c050d25589979c57
Git blob 93b56e883a3c1a64d7a3c1da66a542d52a37ee03

Fig. A22.1 Each field in its own map

Where a version 2 PSBT keeps the transaction1 input, 2 output updated PSBTv2, with all PSBTv2 fields (BIP 370 line 457). global map: PSBT_GLOBAL_TX_VERSION (4 bytes, BIP 370), PSBT_GLOBAL_FALLBACK_LOCKTIME (4 bytes, BIP 370), PSBT_GLOBAL_INPUT_COUNT (1 bytes, BIP 370), PSBT_GLOBAL_OUTPUT_COUNT (1 bytes, BIP 370), PSBT_GLOBAL_TX_MODIFIABLE (1 bytes, BIP 370), PSBT_GLOBAL_VERSION (4 bytes); input 1 map: PSBT_IN_NON_WITNESS_UTXO (82 bytes), PSBT_IN_WITNESS_UTXO (31 bytes), PSBT_IN_PREVIOUS_TXID (32 bytes, BIP 370), PSBT_IN_OUTPUT_INDEX (4 bytes, BIP 370), PSBT_IN_SEQUENCE (4 bytes, BIP 370), PSBT_IN_REQUIRED_TIME_LOCKTIME (4 bytes, BIP 370), PSBT_IN_REQUIRED_HEIGHT_LOCKTIME (4 bytes, BIP 370); output 1 map: PSBT_OUT_BIP32_DERIVATION (24 bytes), PSBT_OUT_AMOUNT (8 bytes, BIP 370), PSBT_OUT_SCRIPT (22 bytes, BIP 370); output 2 map: PSBT_OUT_BIP32_DERIVATION (24 bytes), PSBT_OUT_AMOUNT (8 bytes, BIP 370), PSBT_OUT_SCRIPT (22 bytes, BIP 370). The unsigned transaction built from the BIP 370 fields is 113 bytes: nVersion from PSBT_GLOBAL_TX_VERSION, input count from PSBT_GLOBAL_INPUT_COUNT, input 1 · previous txid from PSBT_IN_PREVIOUS_TXID, input 1 · output index from PSBT_IN_OUTPUT_INDEX, input 1 · empty scriptSig from unsigned: no scriptSig, input 1 · nSequence from PSBT_IN_SEQUENCE, output count from PSBT_GLOBAL_OUTPUT_COUNT, output 1 · amount from PSBT_OUT_AMOUNT, output 1 · scriptPubKey from PSBT_OUT_SCRIPT, output 2 · amount from PSBT_OUT_AMOUNT, output 2 · scriptPubKey from PSBT_OUT_SCRIPT, nLockTime from maximum required height.BIP 370 LINE 457 · ALL VERSION 2 FIELDSOUTLINED: ADDED BY BIP 370 · PLAIN: BIP 174'S OWN FIELDSGLOBAL MAPTX_VERSION4 BFALLBACK_LOCKTIME4 BINPUT_COUNT1 BOUTPUT_COUNT1 BTX_MODIFIABLE1 BVERSION4 BINPUT 1 MAPNON_WITNESS_UTXO82 BWITNESS_UTXO31 BPREVIOUS_TXID32 BOUTPUT_INDEX4 BSEQUENCE4 BREQUIRED_TIME_LOCKTIME4 BREQUIRED_HEIGHT_LOCKTIME4 BOUTPUT 1 MAPBIP32_DERIVATION24 BAMOUNT8 BSCRIPT22 BOUTPUT 2 MAPBIP32_DERIVATION24 BAMOUNT8 BSCRIPT22 BTHE UNSIGNED TRANSACTION THEY DESCRIBE · 113 BYTESnVersion4 B← TX_VERSIONinput count1 B← INPUT_COUNTprevious txid32 B← PREVIOUS_TXID (INPUT 1)output index4 B← OUTPUT_INDEX (INPUT 1)empty scriptSig1 Bunsigned: no scriptSignSequence4 B← SEQUENCE (INPUT 1)output count1 B← OUTPUT_COUNTamount8 B← AMOUNT (OUTPUT 1)scriptPubKey23 B← SCRIPT (OUTPUT 1)amount8 B← AMOUNT (OUTPUT 2)scriptPubKey23 B← SCRIPT (OUTPUT 2)nLockTime4 Bboth types fit, so the height is usedDASHED: NOT COPIED FROM A FIELDIN VERSION 0 THESE BYTES ARE ONE FIELD: UNSIGNED_TX
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
BIP 370's vector with every version 2 field. Outlined rows are BIP 370's; the others are BIP 174's. The model builds the 113-byte unsigned transaction these fields describe. Converted to version 0, those bytes would become the single global field PSBT_GLOBAL_UNSIGNED_TX.1578

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

Every invalid vector and the rule it breaksBIP 370's 24 invalid vectors and the rule the model finds broken in each. Line 307, “PSBTv0 but with PSBT_GLOBAL_VERSION set to 2”: A version 2 PSBT must exclude PSBT_GLOBAL_UNSIGNED_TX. Line 311, “PSBTv0 but with PSBT_GLOBAL_TX_VERSION”: A version 0 PSBT must exclude PSBT_GLOBAL_TX_VERSION. Line 315, “PSBTv0 but with PSBT_GLOBAL_FALLBACK_LOCKTIME”: A version 0 PSBT must exclude PSBT_GLOBAL_FALLBACK_LOCKTIME. Line 319, “PSBTv0 but with PSBT_GLOBAL_INPUT_COUNT”: A version 0 PSBT must exclude PSBT_GLOBAL_INPUT_COUNT. Line 323, “PSBTv0 but with PSBT_GLOBAL_OUTPUT_COUNT”: A version 0 PSBT must exclude PSBT_GLOBAL_OUTPUT_COUNT. Line 327, “PSBTv0 but with PSBT_GLOBAL_TX_MODIFIABLE”: A version 0 PSBT must exclude PSBT_GLOBAL_TX_MODIFIABLE. Line 331, “PSBTv0 but with PSBT_IN_PREVIOUS_TXID”: A version 0 PSBT must exclude PSBT_IN_PREVIOUS_TXID. Line 335, “PSBTv0 but with PSBT_IN_OUTPUT_INDEX”: A version 0 PSBT must exclude PSBT_IN_OUTPUT_INDEX. Line 339, “PSBTv0 but with PSBT_IN_SEQUENCE”: A version 0 PSBT must exclude PSBT_IN_SEQUENCE. Line 343, “PSBTv0 but with PSBT_IN_REQUIRED_TIME_LOCKTIME”: A version 0 PSBT must exclude PSBT_IN_REQUIRED_TIME_LOCKTIME. Line 347, “PSBTv0 but with PSBT_IN_REQUIRED_HEIGHT_LOCKTIME”: A version 0 PSBT must exclude PSBT_IN_REQUIRED_HEIGHT_LOCKTIME. Line 351, “PSBTv0 but with PSBT_OUT_AMOUNT”: A version 0 PSBT must exclude PSBT_OUT_AMOUNT. Line 355, “PSBTv0 but with PSBT_OUT_SCRIPT”: A version 0 PSBT must exclude PSBT_OUT_SCRIPT. Line 359, “PSBTv2 but with PSBT_GLOBAL_UNSIGNED_TX”: A version 2 PSBT must exclude PSBT_GLOBAL_UNSIGNED_TX. Line 363, “PSBTv2 missing PSBT_GLOBAL_INPUT_COUNT”: A version 2 PSBT must include PSBT_GLOBAL_INPUT_COUNT. Line 367, “PSBTv2 missing PSBT_GLOBAL_OUTPUT_COUNT”: A version 2 PSBT must include PSBT_GLOBAL_OUTPUT_COUNT. Line 371, “PSBTv2 missing PSBT_GLOBAL_TX_VERSION”: A version 2 PSBT must include PSBT_GLOBAL_TX_VERSION. Line 375, “PSBTv2 missing PSBT_IN_PREVIOUS_TXID”: Input 0 of a version 2 PSBT must include PSBT_IN_PREVIOUS_TXID. Line 379, “PSBTv2 missing PSBT_IN_OUTPUT_INDEX”: Input 0 of a version 2 PSBT must include PSBT_IN_OUTPUT_INDEX. Line 383, “PSBTv2 missing PSBT_OUT_AMOUNT”: Output 0 of a version 2 PSBT must include PSBT_OUT_AMOUNT. Line 387, “PSBTv2 missing PSBT_OUT_SCRIPT”: Output 0 of a version 2 PSBT must include PSBT_OUT_SCRIPT. Line 391, “PSBTv2 with PSBT_IN_REQUIRED_TIME_LOCKTIME less than 500000000”: Input 0's required time lock 499999999 is below 500000000. Line 395, “PSBTv2 with PSBT_IN_REQUIRED_HEIGHT_LOCKTIME greater than or equal to 500000000”: Input 0's required height lock 500000000 is not greater than 0 and less than 500000000. Line 399, “PSBTv2 with PSBT_IN_REQUIRED_HEIGHT_LOCKTIME of 0”: Input 0's required height lock 0 is not greater than 0 and less than 500000000.BIP 370'S 24 INVALID PSBTs · EACH REJECTED BY THE MODELLINEMAPFIELD THE CASE NAMESRULE BROKENREAD AS VERSION 0: CARRIES A FIELD VERSION 2 ADDS · 12L311GLOBALTX_VERSION✕ NOT ALLOWED IN V0L315GLOBALFALLBACK_LOCKTIME✕ NOT ALLOWED IN V0L319GLOBALINPUT_COUNT✕ NOT ALLOWED IN V0L323GLOBALOUTPUT_COUNT✕ NOT ALLOWED IN V0L327GLOBALTX_MODIFIABLE✕ NOT ALLOWED IN V0L331INPUTPREVIOUS_TXID✕ NOT ALLOWED IN V0L335INPUTOUTPUT_INDEX✕ NOT ALLOWED IN V0L339INPUTSEQUENCE✕ NOT ALLOWED IN V0L343INPUTREQUIRED_TIME_LOCKTIME✕ NOT ALLOWED IN V0L347INPUTREQUIRED_HEIGHT_LOCKTIME✕ NOT ALLOWED IN V0L351OUTPUTAMOUNT✕ NOT ALLOWED IN V0L355OUTPUTSCRIPT✕ NOT ALLOWED IN V0READ AS VERSION 2 · 12L307GLOBALVERSION SET TO 2✕ STILL HAS UNSIGNED_TXL359GLOBALUNSIGNED_TX✕ NOT ALLOWED IN V2L363GLOBALINPUT_COUNT✕ MISSING IN V2L367GLOBALOUTPUT_COUNT✕ MISSING IN V2L371GLOBALTX_VERSION✕ MISSING IN V2L375INPUTPREVIOUS_TXID✕ MISSING IN V2L379INPUTOUTPUT_INDEX✕ MISSING IN V2L383OUTPUTAMOUNT✕ MISSING IN V2L387OUTPUTSCRIPT✕ MISSING IN V2L391INPUTREQUIRED_TIME_LOCKTIME✕ 499999999 < 500000000L395INPUTREQUIRED_HEIGHT_LOCKTIME✕ 500000000 ≥ 500000000L399INPUTREQUIRED_HEIGHT_LOCKTIME✕ 0 IS NOT > 0
BIP 370's 24 invalid PSBTs. Twelve are version 0 PSBTs carrying a field version 2 adds. The first vector is a version 0 PSBT relabelled as version 2: read as version 2, it still holds its unsigned transaction. The other eleven are version 2 PSBTs that hold the unsigned transaction, miss a required field, or state a lock time out of range. The model rejects each of the others for the field its case names.451112

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

PSBT_GLOBAL_TX_MODIFIABLE, bit by bitPSBT_GLOBAL_TX_MODIFIABLE of 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 (BIP 370 line 437) is 0x03: bit 0, inputs modifiable, is 1; bit 1, outputs modifiable, is 1; bit 2, has sighash_single, is 0. A Constructor may add inputs and may add outputs. After one signature: ALL leaves 0x00, inputs no longer addable, outputs no longer addable; NONE leaves 0x02, inputs no longer addable, outputs still addable; SINGLE leaves 0x04, inputs no longer addable, outputs no longer addable, SIGHASH_SINGLE flagged; ALL|ANYONECANPAY leaves 0x01, inputs still addable, outputs no longer addable; NONE|ANYONECANPAY leaves 0x03, inputs still addable, outputs still addable; SINGLE|ANYONECANPAY leaves 0x05, inputs still addable, outputs no longer addable, SIGHASH_SINGLE flagged. 1 input, 2 output updated PSBTv2, with all possible PSBT_GLOBAL_TX_MODIFIABLE flags set (line 453) sets all eight bits, 0xff, and is still valid.BIP 370 LINE 437 · TX_MODIFIABLE = 0x030BIT 70BIT 60BIT 50BIT 40BIT 30BIT 21BIT 11BIT 0BIT 0 · INPUTS MODIFIABLE = 1BIT 1 · OUTPUTS MODIFIABLE = 1BIT 2 · HAS SIGHASH_SINGLE = 0BITS 3–7 · UNDEFINEDA CONSTRUCTOR MAY ADD: INPUTS ✓ · OUTPUTS ✓AFTER ONE SIGNATURE (BIP 370's SIGNER RULES)SIGHASH TYPEFLAGS+INPUTS+OUTPUTSBIT 2ALL0x00✕✕·NONE0x02✕✓·SINGLE0x04✕✕SETALL|ANYONECANPAY0x01✓✕·NONE|ANYONECANPAY0x03✓✓·SINGLE|ANYONECANPAY0x05✓✕SETLINE 453: ALL EIGHT BITS SET (0xff) IS STILL A VALID PSBT
BIP 370's vector with both modifiable bits set, and the flags one signature of each sighash type leaves under BIP 370's Signer rules. BIP 370 calls bits beyond 2 undefined; its vector with all eight bits set is still valid.151617

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.

Choosing the lock time from the inputs' requirementsA version 2 PSBT with 2 inputs. The global map sets the fallback lock time to 0. 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. Result: nLockTime 10000, a block height 10000.BIP 370 LOCK-TIME VECTOR · LINE 479GLOBAL MAPFALLBACK LOCK TIME 0USED ONLY IF NO INPUTREQUIRES A LOCK TIMEINPUT 1TAKES A HEIGHT ONLYREQUIRED HEIGHT 10000INPUT 2TAKES A HEIGHT ONLYREQUIRED HEIGHT 90001Requiring a lock time: inputs 1 and 2.2Each of them accepts a height.3Largest required height: max(10000, 9000) = 10000.✓nLockTime 10000 · A BLOCK HEIGHTBIP 370: COMPUTED TO BE 10000
Choosing the lock time from the inputs' requirementsA version 2 PSBT with 2 inputs. The global map sets the fallback lock time to 0. 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. Result: nLockTime 10000, a block height 10000.BIP 370 LOCK-TIME VECTOR · LINE 479GLOBAL MAPFALLBACK LOCK TIME 0INPUT 1TAKES A HEIGHT ONLYREQUIRED HEIGHT 10000INPUT 2TAKES A HEIGHT ONLYREQUIRED HEIGHT 90001Requiring a lock time: inputs 1 and 2.2Each of them accepts a height.3Largest required height: max(10000, 9000) = 10000.✓nLockTime 10000 · A BLOCK HEIGHTBIP 370: COMPUTED TO BE 10000

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.

BIP 370's ten lock-time vectors; those with requirements are named by what input 1 and input 2 require. Choose one: the model finds the inputs that require a lock time, the type all of them accept, and the largest value. Its result matches the one BIP 370 gives for every vector. The vector on line 500 is printed without a case line, so its label is read from its bytes.1920212324

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

The proposal

BIP 370 (Ava Chow) was assigned in 2021 and is recorded as Deployed. Version number 1 was skipped: version 0 had been called version 1 informally, and this proposal version 2 while it was designed.3334

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.

  1. ↩ 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.

    BIP 174, lines 97–102

    Version 0 PSBTs must include PSBT_GLOBAL_UNSIGNED_TX, if omitted, the PSBT is invalid.

    BIP 174, line 390
  2. ↩ 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.

    BIP 370, lines 25–28
  3. ↩ 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.

    BIP 370, lines 16–17
  4. ↩ 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

    BIP 370, lines 38–41
  5. ↩ 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.

    Quoted source text (13)

    ! Versions Requiring Inclusion ! Versions Requiring Exclusion ! Versions Allowing Inclusion

    BIP 370, lines 55–57

    | 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

    BIP 370, lines 59–67

    | 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

    BIP 370, lines 69–77

    | 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

    BIP 370, lines 79–87

    | 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

    BIP 370, lines 89–97

    | 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

    BIP 370, lines 99–107

    | 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

    BIP 370, lines 123–131

    | 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

    BIP 370, lines 133–141

    | 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

    BIP 370, lines 143–151

    | 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

    BIP 370, lines 153–161

    | 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

    BIP 370, lines 163–171

    | 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

    BIP 370, lines 187–195

    | 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

    BIP 370, lines 197–205
  6. ↩ 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.

    BIP 370, lines 30–34
  7. ↩ 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

    BIP 370, line 456
  8. ↩ 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.

    BIP 370, lines 297–300
  9. ↩ 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.

    BIP 370, lines 294–295
  10. ↩ 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.

    BIP 370, line 64
  11. ↩ 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.

    BIP 370, lines 304–306

    The following are valid PSBTs

    BIP 370, line 402
  12. ↩ 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.

    BIP 370, line 158

    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.

    BIP 370, line 168
  13. ↩ 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.

    BIP 370, lines 235–238

    If the Creator is a Constructor and no inputs and outputs will be added by other entities, PSBT_GLOBAL_TX_MODIFIABLE may be omitted.

    BIP 370, line 239
  14. ↩ 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.

    BIP 370, lines 243–247
  15. ↩ 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.

    BIP 370, line 104
  16. ↩ 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.

    BIP 370, lines 276–279
  17. ↩ 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.

    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

    BIP 370, line 436

    * Case: 1 input, 2 output updated PSBTv2, with an undefined flag (bit 3) of PSBT_GLOBAL_TX_MODIFIABLE set

    BIP 370, line 432

    * Case: 1 input, 2 output updated PSBTv2, with all possible PSBT_GLOBAL_TX_MODIFIABLE flags set

    BIP 370, line 452
  18. ↩ 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.

    BIP 370, lines 266–268
  19. ↩ 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.

    BIP 370, line 74

    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.

    BIP 370, lines 211–212
  20. ↩ 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.

    BIP 370, lines 214–217
  21. ↩ 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.

    BIP 370, line 219
  22. ↩ 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.

    BIP 370, lines 220–221
  23. ↩ 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.

    Quoted source text (3)

    The following tests are the timelock determination algorithm.

    BIP 370, line 460

    The timelock for the following PSBTs should be computed to be 1657048460:

    BIP 370, line 490

    ** Bytes in Hex: <pre>70736274ff0102040200000001030400000000

    BIP 370, line 500
  24. ↩ 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.

    BIP 370, line 158
  25. ↩ 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.

    BIP 370, lines 214–216
  26. ↩ 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

    BIP 370, lines 503–505
  27. ↩ 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.

    BIP 370, lines 258–261
  28. ↩ 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.

    BIP 370, lines 225–227
  29. ↩ 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.

    BIP 370, line 225
  30. ↩ 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).

    BIP 370, line 148

    For PSBTv2, an Updater can set the sequence number.

    BIP 370, line 272
  31. ↩ 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).

    BIP 370, line 226
  32. ↩ 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.

    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.

    BIP 370, lines 283–284

    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.

    BIP 370, lines 288–289
  33. ↩ 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

    BIP 370, lines 3–8
  34. ↩ 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

    BIP 370, lines 41–44