BIP 0174
How can separate devices help sign one transaction?
A PSBT is a working document wrapped around a transaction. Each participant adds what it knows, and only the last step produces something the network would accept.
Signing is simple when one program holds every key and knows every coin it spends. It gets harder when keys live on different devices, some deliberately offline, made by different vendors. BIP 174 describes the situation before it: passing a partly signed transaction between signers depended on each implementation.1
BIP 174, assigned in 2017 and recorded as deployed, defines the Partially Signed Bitcoin Transaction format, or PSBT. It is a container that carries what a signer needs to know and collects signatures until each input has a complete set. The proposal describes a generic format and its version 0.234
Source details
This chapter is an independent explanation, not the proposals themselves. Preamble fields are shown as recorded in the pinned files, with author e-mail addresses omitted. Status is the proposal’s own field, not an endorsement or a sign of consensus.
BIP 174: Partially Signed Bitcoin Transaction Format
- BIP
- 174
- Layer
- Applications
- Title
- Partially Signed Bitcoin Transaction Format
- Authors
- Ava Chow
- Comments-Summary
- No comments yet.
- Comments-URI
- https://github.com/bitcoin/bips/wiki/Comments:BIP-0174
- Status
- Deployed
- Type
- Specification
- Assigned
- 2017-07-12
- License
- BSD-2-Clause
- Version
- 1.4.4
70 73 62 74 ff “psbt” + 0xff
Global map
- 0x00Unsigned Transaction2 inputs, 2 outputs, 154 bytes, scriptSigs empty
Input 0 map
empty: just the 0x00 separator
Input 1 map
empty: just the 0x00 separator
Output 0 map
empty: just the 0x00 separator
Output 1 map
empty: just the 0x00 separator
167 bytes, as created on BIP 174 line 774. Outputs pay 1.49990000 BTC and 1.00000000 BTC.
An envelope of maps
A PSBT begins with five bytes: the letters psbt followed by 0xff. Then come key-value maps, one global map followed by one map per input and one per output of the transaction. Each map is a list of records, each with a key and a value, and ends with a single zero byte.5
Each key is a type number, sometimes followed by key data. A map can hold several records of the same type as long as their full keys differ. That is how one input can carry several signatures at once: each partial signature’s key includes the public key that made it.89
The global map holds the transaction being built, in its old serialization and with every scriptSig and witness empty. A version 0 PSBT without it is invalid. Within a map every key must be unique, and a PSBT with a duplicated key is invalid too. More generally, if any key or value does not match the format its type specifies, the whole PSBT must be considered invalid.101112
Versions are handled cautiously. A parser that meets a PSBT version number it does not recognize should stop immediately, because the document will contain types it cannot safely ignore. Unknown individual fields are a different matter, as the last section shows.1314
A PSBT can travel as a binary file or as Base64 text, so the same document can move between programs that share nothing else.15
Roles, not devices
BIP 174 divides the work into roles: Creator, Updater, Signer, Combiner, Input Finalizer and Transaction Extractor. They are roles rather than devices. One program can play several of them, and several participants can play the same one, as the two signers below do.717
In practice roles cluster. BIP 174 says one entity is likely to be both Creator and Updater, and likewise both Signer and Updater, since a signer can add what it knows just before signing.91819
The proposal illustrates workflows such as a manual CoinJoin and a 2-of-3 multisig, but it does not prescribe one choreography. The sequence in the figure below is simply the one its test vectors publish, from the first empty envelope to the final transaction.720
Step through it. Every state is a published PSBT, parsed field by field; select any field to see its key, its value and the BIP that defines it.721
Static view: what each role in BIP 174’s published trace adds or removes. With JavaScript you can step through the envelope and inspect each field.
- Creator line 774, 167 bytes
Creates the envelope with the unsigned transaction and empty maps.
- Updater line 797, 889 bytes
Adds: Input 0: Non-Witness UTXO; Input 0: Redeem Script; Input 0: BIP 32 Derivation Path; Input 0: BIP 32 Derivation Path; Input 1: Witness UTXO; Input 1: Redeem Script; Input 1: Witness Script; Input 1: BIP 32 Derivation Path; Input 1: BIP 32 Derivation Path; Output 0: BIP 32 Derivation Path; Output 1: BIP 32 Derivation Path.
- Updater adds sighash type line 802, 903 bytes
Adds: Input 0: Sighash Type; Input 1: Sighash Type.
- Signer A line 810, 1117 bytes
Adds: Input 0: Partial Signature; Input 1: Partial Signature.
- Signer B line 818, 1118 bytes
Adds: Input 0: Partial Signature; Input 1: Partial Signature.
- Combiner line 823, 1332 bytes
- Input Finalizer line 828, 976 bytes
Adds: Input 0: Finalized scriptSig; Input 1: Finalized scriptSig; Input 1: Finalized scriptWitness.
Removes: Input 0: Partial Signature; Input 0: Partial Signature; Input 0: Sighash Type; Input 0: Redeem Script; Input 0: BIP 32 Derivation Path; Input 0: BIP 32 Derivation Path; Input 1: Partial Signature; Input 1: Partial Signature; Input 1: Sighash Type; Input 1: Redeem Script; Input 1: Witness Script; Input 1: BIP 32 Derivation Path; Input 1: BIP 32 Derivation Path.
- Transaction Extractor line 833
Produces the 628-byte network transaction.
What each role adds
The Creator writes the unsigned transaction and leaves every input and output map empty. The Updater fills in what it knows: the outputs being spent, redeem and witness scripts, and BIP 32 derivation paths that tell a signer which of its keys belong where. In the published trace, a second update adds the sighash type.6719
A Signer must use only the UTXOs inside the PSBT and must only add data. Each signature goes in as a partial signature on its input, keyed by the public key that made it. Because the PSBT carries the outputs being spent, a signer can work out the amounts, destinations and fee, and show them before it signs. Signers need not handle every input type.92425
That display is only as good as its data. For SegWit inputs, BIP 174 notes a known problem: a signature commits only to its own input’s amount, so an attacker who gets a user to sign repeatedly could alter the claimed amounts of other inputs and push funds into fees. Many wallets therefore ask for the full previous transaction even for SegWit inputs.26
Some checks come before any signature. For an input that spends a pre-SegWit output, the Signer must confirm that the full previous transaction it was given really hashes to the transaction ID named in the unsigned transaction. The figure shows that check passing for the first input of the published trace.2127
The derivation paths serve the display as well. A signer can use them, together with any extended public keys in the global map, to recognise which outputs return change to its own wallet and leave those out of what it shows the user.1928
The Combiner merges PSBTs for the same transaction into one that contains every record from each, and must refuse to merge different ones. Combining two independent sets of additions gives the same result as applying them one after the other, in either order, unless they conflict. The tests behind this page merge the two published signer PSBTs both ways and get the published result byte for byte.212229
The Input Finalizer turns the collected pieces into a final scriptSig, a final witness, or both, for each input it can complete. In that input’s map, everything else except the spent output and fields it does not understand should then be cleared. The Transaction Extractor reads those final scripts into a network transaction. If any input is incomplete, it must leave the PSBT untouched.1623
Finalizing has rules of its own. If an input names a sighash type, the Input Finalizer must refuse to finalize it when any signature uses a different one.30
Fields nobody here understands
BIP 174 keeps the format extensible by requiring that new types be ignored and passed through by signers that do not know them. A signer that meets a field it does not understand must pass it through when it writes the PSBT back out, and the Input Finalizer keeps such fields too.14
PSBT 1 · BIP 174 line 836
- G · 0xf0Unknown type
010203040506070809 → 0102030405060708090a0b0c0d0e0f - I0 · 0xf0Unknown type
010203040506070809 → 0102030405060708090a0b0c0d0e0f - O0 · 0xf0Unknown type
010203040506070809 → 0102030405060708090a0b0c0d0e0f
PSBT 2 · BIP 174 line 839
- G · 0xf0Unknown type
010203040506070810 → 0102030405060708090a0b0c0d0e0f - I0 · 0xf0Unknown type
010203040506070810 → 0102030405060708090a0b0c0d0e0f - O0 · 0xf0Unknown type
010203040506070810 → 0102030405060708090a0b0c0d0e0f
Combined · matches BIP 174 line 844
- G · 0xf0Unknown type
010203040506070809 → 0102030405060708090a0b0c0d0e0f - G · 0xf0Unknown type
010203040506070810 → 0102030405060708090a0b0c0d0e0f - I0 · 0xf0Unknown type
010203040506070809 → 0102030405060708090a0b0c0d0e0f - I0 · 0xf0Unknown type
010203040506070810 → 0102030405060708090a0b0c0d0e0f - O0 · 0xf0Unknown type
010203040506070809 → 0102030405060708090a0b0c0d0e0f - O0 · 0xf0Unknown type
010203040506070810 → 0102030405060708090a0b0c0d0e0f
Version 2 PSBTs and Taproot-related fields exist, but other proposals define them. A type registry kept alongside BIP 174 lists every field together with the BIP that defines it. The figures here label each field from that registry, and every field in the published trace turns out to come from BIP 174 itself.432
Replayed, not signed
The decoder behind this page rejects all twenty invalid PSBTs that BIP 174 lists, from a missing output map to a duplicated key, and accepts the ten valid ones, keeping every record when it writes them back out. Each invalid case is a rule made concrete: a duplicated key, a filled scriptSig in the unsigned transaction, an unsigned transaction written with witness serialization, and, in twelve of the twenty, a key or value that does not match its type’s format.10111233
It does not sign, it holds no keys and it broadcasts nothing. Replaying a published trace is enough to see how separate devices cooperate on one transaction: each adds only what it knows, and nothing becomes a real transaction until every input is complete.7916
Evidence
Each numbered marker in the text points here. Quotes are verbatim from the BIP files at commit
3a10b5b, including their wiki markup; links open
the exact lines; the quoted text sits under each entry. Labels say what kind of statement each is: a rule, the author’s rationale, history,
a test vector, or our own inference.
-
Author’s rationale Passing partially signed transactions between signers was implementation dependent; BIP174 aims for a standard, extensible format, and lets offline signers such as hardware wallets sign without direct UTXO access.
Quoted source text (2)
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.
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.
-
History BIP174 was assigned in 2017; its preamble records the status Deployed and document version 1.4.4.
BIP 174 L10 BIP 174 L8 BIP 174 L12
Quoted source text (3)
Assigned: 2017-07-12
Status: Deployed
Version: 1.4.4
-
Rule A PSBT carries the information a signer needs, holds signatures for an input until it has a complete set, and lets the signer be offline.
Quoted source text (1)
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.
-
Rule BIP174 describes the generic format and the specification for version 0.
Quoted source text (1)
The generic format is described here in addition to the specification for version 0 of this format.
-
Rule A PSBT is magic bytes, a global map, then one map per input and per output; each map is a sequence of key-value records ended by 0x00.
BIP 174 L49–50 BIP 174 L57 BIP 174 L58
Quoted source text (3)
The Partially Signed Bitcoin Transaction (PSBT) format consists of key-value maps. Each map consists of a sequence of key-value records, terminated by a <tt>0x00</tt> byte
<psbt> := <magic> <global-map> <input-map>* <output-map>*
<magic> := 0x70 0x73 0x62 0x74 0xFF
-
Rule The Creator puts the unsigned transaction into a new PSBT with empty input and output fields.
Quoted source text (1)
The Creator creates a new PSBT. It must create an unsigned transaction and place it in the PSBT. The Creator must create empty input and output fields.
-
Test vector BIP174's test vectors publish one PSBT per role in a full trace, from creation to the extracted network transaction.
BIP 174 L763 BIP 174 L821 BIP 174 L831
Quoted source text (3)
A creator creating a PSBT for a transaction which creates the following outputs:
Given both of the above PSBTs, a combiner must create this PSBT.
Given the above PSBT, a transaction extractor must create this Bitcoin transaction:
-
Rule A record's key is its type plus optional key data; several records can share a type in one map, but each full key must be unique.
Quoted source text (2)
<key> := <keylen> <keytype> <keydata>
There can be multiple entries with the same <tt><keytype></tt> within a specific <tt><map></tt>, but the <tt><key></tt> must be unique.
-
Rule The Signer uses only the UTXOs in the PSBT, only adds data, and records each signature as a Partial Signature on its input.
Quoted source text (2)
The Signer must only use the UTXOs provided in the PSBT to produce signatures for inputs.
The Signer must only add data to a PSBT. Any signatures created by the Signer must be added as a "Partial Signature" key-value pair for the respective input it relates to.
-
Rule The global unsigned transaction must have empty scriptSigs and witnesses and use the old serialization without witnesses; version 0 PSBTs must include it.
Quoted source text (2)
The scriptSigs and witnesses for each input must be empty. The transaction must be in the old serialization format (without witnesses).
Version 0 PSBTs must include PSBT_GLOBAL_UNSIGNED_TX, if omitted, the PSBT is invalid.
-
Rule Keys within a map must be unique; PSBTs with duplicate keys are invalid.
Quoted source text (1)
Keys within each scope should never be duplicated; all keys in the format are unique. PSBTs containing duplicate keys are invalid.
-
Rule Every key must carry the data its type specifies; if any key or value does not match its type's format, the PSBT must be considered invalid.
Quoted source text (1)
All keys must have the data that they specify. If any key or value does not match the specified format for that type, the PSBT must be considered invalid.
-
Rule A parser that meets a PSBT version number it does not recognize should stop, because the PSBT contains types it cannot safely ignore.
Quoted source text (1)
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.
-
Rule Signers must pass through key-value pairs they do not understand when re-serializing; this keeps the format extensible.
BIP 174 L351–352 BIP 174 L544–546
Quoted source text (2)
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.
Backwards compatibility will still be maintained as those new types will be ignored and passed-through by signers which do not know about them.
-
Rule A PSBT can be a binary file or a Base64 string.
Quoted source text (1)
A PSBT can be represented in two ways: in binary (as a file) or as a Base64 string
-
Rule The Transaction Extractor turns a fully finalized PSBT into a network-serialized transaction; otherwise it must not modify the PSBT.
Quoted source text (1)
If they do, the Transaction Extractor should construct complete scriptSigs and scriptWitnesses and encode them into network serialized transactions. Otherwise the Extractor must not modify the PSBT. The Extractor should produce a fully valid, network serialized transaction if all inputs are complete.
-
Rule PSBT defines specialized roles; one entity can handle several of them.
Quoted source text (1)
Multiple roles can be handled by a single entity, but each role is specialized in what it should be capable of doing.
-
Author’s rationale One entity is likely to be both Creator and Updater, and likewise both Signer and Updater.
Quoted source text (2)
A single entity is likely to be both a Creator and Updater.
A single entity is likely to be both a Signer and an Updater as it can update a PSBT with necessary information prior to signing it.
-
Rule The Updater adds information it has: UTXOs, redeem and witness scripts, and BIP32 derivation paths.
Quoted source text (1)
If it has the UTXO for an input, it should add it to the PSBT. The Updater should also add redeemScripts, witnessScripts, and BIP 32 derivation paths to the input and output data if it knows them.
-
Author’s rationale BIP174 illustrates example workflows, such as a manual CoinJoin and a 2-of-3 multisig; these are examples, not a mandated sequence.
Quoted source text (2)
===Manual CoinJoin Workflow===
===2-of-3 Multisig Workflow===
-
Test vector The tested model parses every state of the published trace, reproduces the combiner output byte for byte from the two signers' PSBTs in either order, and reproduces the extracted transaction.
Quoted source text (2)
A combiner must produce the given result for any order of its inputs
* Bytes in Hex: <pre>0200000000010258e87a21b56daf0c23be8e7070456c336f7cbaa5c8757924f545887bb2abdd7500000000da00473044022074018ad4180097b873323c0015720b3684cc8123891048e7dbcd9b55ad679c99022073d369b740e3eb53dcefa33823c8070514ca55a7dd9544f157c167913261118c01483045022100f61038b308dc1da865a34852746f015772934208c6d24454393cd99bdf2217770220056e675a675a6d0a02b85b14e5e29074d8a25a9b5760bea2816f661910a006ea01475221029583bf39ae0a609747ad199addd634fa6108559d6c5cd39b4c2183f1ab96e07f2102dab61ff49a14db6a7d02b0cd1fbb78fc4b18312b5b4e54dae4dba2fbfef536d752aeffffffff838d0427d0ec650a68aa46bb0b098aea4422c071b2ca78352a077959d07cea1d01000000232200208c2353173743b595dfb4a07b72ba8e42e3797da74e87fe7d9d7497e3b2028903ffffffff0270aaf00800000000160014d85c2b71d0060b09c9886aeb815e50991dda124d00e1f5050000000016001400aea9a2e5f0f876a588df5546e8742d1d87008f000400473044022062eb7a556107a7c73f45ac4ab5a1dddf6f7075fb1275969a7f383efff784bcb202200c05dbb7470dbf2f08557dd356c7325c1ed30913e996cd3840945db12228da5f01473044022065f45ba5998b59a27ffe1a7bed016af1f1f90d54b3aa8f7450aa5f56a25103bd02207f724703ad1edb96680b284b56d4ffcb88f7fb759eabbe08aa30f29b851383d20147522103089dc10c7ac6db54f91329af617333db388cead0c231f723379d1b99030b02dc21023add904f3d6dcf59ddb906b0dee23529b7ffb9ed50e5e86151926860221f0e7352ae00000000</pre>
-
Rule The Combiner merges PSBTs for the same transaction into one containing all their key-value pairs, and must not combine different PSBTs.
Quoted source text (2)
The Combiner must merge them into one PSBT (if possible), or fail. The resulting PSBT must contain all of the key-value pairs from each of the PSBTs.
A Combiner must not combine two different PSBTs.
-
Rule The Input Finalizer builds the final scriptSig and/or scriptWitness for inputs that have enough data (leaving an empty one unset); in that input's map, everything except the UTXO and unknown fields should then be cleared.
BIP 174 L520 BIP 174 L523 BIP 174 L521–522
Quoted source text (3)
If it does, it must construct the <tt>0x07</tt> Finalized scriptSig and <tt>0x08</tt> Finalized scriptWitness and place them into the input key-value map.
All other data except the UTXO and unknown fields (including <tt>PSBT_IN_PROPRIETARY</tt> fields the Input Finalizer does not understand) in the input key-value map should be cleared from the PSBT.
If scriptSig is empty for an input, <tt>0x07</tt> should remain unset rather than assigned an empty array. Likewise, if no scriptWitness exists for an input, <tt>0x08</tt> should remain unset rather than assigned an empty array.
-
Rule A Signer can compute the addresses, values and fee being sent and show them to the user as confirmation of intent.
Quoted source text (1)
The Signer can additionally compute the addresses and values being sent, and the transaction fee, optionally showing this data to the user as a confirmation of intent and the consequences of signing the PSBT.
-
Rule Signers do not need to sign for every input type.
Quoted source text (1)
Signers do not need to sign for all possible input types. For example, a signer may choose to only sign Segwit inputs.
-
Author’s rationale Because BIP143 signatures commit only to their own input's amount, an attacker who gets a user to sign repeatedly can redirect funds to fees by altering other inputs' witness UTXO amounts; many wallets therefore require the full previous transaction.
Quoted source text (2)
The sighash algorithm for Segwit specified in BIP 143 is known to have an issue where an attacker could trick a user to sending Bitcoin to fees if they are able to convince the user to sign a malicious transaction multiple times. This is possible because the amounts in <tt>PSBT_IN_WITNESS_UTXO</tt> of other segwit inputs can be modified without effecting the signature for a particular input.
many wallets are requiring that the full previous transaction (i.e. <tt>PSBT_IN_NON_WITNESS_UTXO</tt>) be provided to ensure that the amounts of other inputs are not being tampered with.
-
Rule Before signing a non-witness input, the Signer must verify that the non-witness UTXO's TXID matches the one in the unsigned transaction.
Quoted source text (1)
Before signing a non-witness input, the Signer must verify that the TXID of the non-witness UTXO matches the TXID specified in the unsigned transaction.
-
Rule Signers may hide change outputs from users; they can detect change using the BIP32 derivation paths in inputs and outputs and the global extended public keys.
Quoted source text (1)
In such displays, signers may wish to identify which outputs are change outputs in order to omit them to avoid additional user confusion. In order to detect change, a signer can use the BIP 32 derivation paths provided in inputs and outputs as well as the extended public keys provided globally.
-
Rule Combining independent additions is equivalent to applying them in sequence, in either order, unless fields conflict.
Quoted source text (2)
Combine(fA(psbt), fB(psbt)) == fA(fB(psbt)) == fB(fA(psbt))
Combining two PSBTs is commutative unless the PSBTs have conflicting fields
-
Rule If an input specifies a sighash type, the Input Finalizer must not finalize it when any signature uses a different type.
Quoted source text (1)
If the input has a <tt>PSBT_IN_SIGHASH_TYPE</tt> field, the Input Finalizer must fail to finalize that input if any signature does not match the specified sighash type.
-
Test vector BIP174's vectors include two PSBTs with unknown key-value pairs and the combined PSBT, which keeps all of them; the tested combiner reproduces it.
Quoted source text (2)
Given these two PSBTs with unknown key-value pairs:
A combiner which orders keys lexicographically must produce the following PSBT:
-
Rule A type registry collects PSBT fields from every BIP that defines them, naming each field's parent BIP; version 2 and Taproot fields come from other BIPs, not BIP174.
BIP 174 (type-registry.mediawiki) L1 BIP 174 (type-registry.mediawiki) L19–20 BIP 174 (type-registry.mediawiki) L143–144
Quoted source text (3)
This document collects the fields and types used in PSBTs of any version from all BIPs that define PSBT fields to help coordinate and prevent key collisions.
<tt>PSBT_GLOBAL_TX_VERSION = 0x02</tt> | [[../bip-0370.mediawiki|370]]
<tt>PSBT_IN_TAP_KEY_SIG = 0x13</tt> | [[../bip-0371.mediawiki|371]]
-
Test vector BIP174 lists invalid PSBTs (duplicate keys, a filled scriptSig, a witness-serialized unsigned transaction, and twelve keys or values that do not match their type's format); the tested parser rejects all twenty and accepts all ten listed valid ones.
BIP 174 L616 BIP 174 L634 BIP 174 L698
Quoted source text (3)
The following are invalid PSBTs:
* Case: PSBT with duplicate keys in an input
The following are valid PSBTs: