|
| 1 | +# PSBT Howto for Bitcoin Core |
| 2 | + |
| 3 | +Since Bitcoin Core 0.17, an RPC interface exists for Partially Signed Bitcoin |
| 4 | +Transactions (PSBTs, as specified in |
| 5 | +[BIP 174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki)). |
| 6 | + |
| 7 | +This document describes the overall workflow for producing signed transactions |
| 8 | +through the use of PSBT, and the specific RPC commands used in typical |
| 9 | +scenarios. |
| 10 | + |
| 11 | +## PSBT in general |
| 12 | + |
| 13 | +PSBT is an interchange format for Bitcoin transactions that are not fully signed |
| 14 | +yet, together with relevant metadata to help entities work towards signing it. |
| 15 | +It is intended to simplify workflows where multiple parties need to cooperate to |
| 16 | +produce a transaction. Examples include hardware wallets, multisig setups, and |
| 17 | +[CoinJoin](https://bitcointalk.org/?topic=279249) transactions. |
| 18 | + |
| 19 | +### Overall workflow |
| 20 | + |
| 21 | +Overall, the construction of a fully signed Bitcoin transaction goes through the |
| 22 | +following steps: |
| 23 | + |
| 24 | +- A **Creator** proposes a particular transaction to be created. They construct |
| 25 | + a PSBT that contains certain inputs and outputs, but no additional metadata. |
| 26 | +- For each input, an **Updater** adds information about the UTXOs being spent by |
| 27 | + the transaction to the PSBT. They also add information about the scripts and |
| 28 | + public keys involved in each of the inputs (and possibly outputs) of the PSBT. |
| 29 | +- **Signers** inspect the transaction and its metadata to decide whether they |
| 30 | + agree with the transaction. They can use amount information from the UTXOs |
| 31 | + to assess the values and fees involved. If they agree, they produce a |
| 32 | + partial signature for the inputs for which they have relevant key(s). |
| 33 | +- A **Finalizer** is run for each input to convert the partial signatures and |
| 34 | + possibly script information into a final `scriptSig` and/or `scriptWitness`. |
| 35 | +- An **Extractor** produces a valid Bitcoin transaction (in network format) |
| 36 | + from a PSBT for which all inputs are finalized. |
| 37 | + |
| 38 | +Generally, each of the above (excluding Creator and Extractor) will simply |
| 39 | +add more and more data to a particular PSBT, until all inputs are fully signed. |
| 40 | +In a naive workflow, they all have to operate sequentially, passing the PSBT |
| 41 | +from one to the next, until the Extractor can convert it to a real transaction. |
| 42 | +In order to permit parallel operation, **Combiners** can be employed which merge |
| 43 | +metadata from different PSBTs for the same unsigned transaction. |
| 44 | + |
| 45 | +The names above in bold are the names of the roles defined in BIP174. They're |
| 46 | +useful in understanding the underlying steps, but in practice, software and |
| 47 | +hardware implementations will typically implement multiple roles simultaneously. |
| 48 | + |
| 49 | +## PSBT in Bitcoin Core |
| 50 | + |
| 51 | +### RPCs |
| 52 | + |
| 53 | +- **`converttopsbt` (Creator)** is a utility RPC that converts an |
| 54 | + unsigned raw transaction to PSBT format. It ignores existing signatures. |
| 55 | +- **`createpsbt` (Creator)** is a utility RPC that takes a list of inputs and |
| 56 | + outputs and converts them to a PSBT with no additional information. It is |
| 57 | + equivalent to calling `createrawtransaction` followed by `converttopsbt`. |
| 58 | +- **`walletcreatefundedpsbt` (Creator, Updater)** is a wallet RPC that creates a |
| 59 | + PSBT with the specified inputs and outputs, adds additional inputs and change |
| 60 | + to it to balance it out, and adds relevant metadata. In particular, for inputs |
| 61 | + that the wallet knows about (counting towards its normal or watch-only |
| 62 | + balance), UTXO information will be added. For outputs and inputs with UTXO |
| 63 | + information present, key and script information will be added which the wallet |
| 64 | + knows about. It is equivalent to running `createrawtransaction`, followed by |
| 65 | + `fundrawtransaction`, and `converttopsbt`. |
| 66 | +- **`walletprocesspsbt` (Updater, Signer, Finalizer)** is a wallet RPC that takes as |
| 67 | + input a PSBT, adds UTXO, key, and script data to inputs and outputs that miss |
| 68 | + it, and optionally signs inputs. Where possible it also finalizes the partial |
| 69 | + signatures. |
| 70 | +- **`finalizepsbt` (Finalizer, Extractor)** is a utility RPC that finalizes any |
| 71 | + partial signatures, and if all inputs are finalized, converts the result to a |
| 72 | + fully signed transaction which can be broadcast with `sendrawtransaction`. |
| 73 | +- **`combinepsbt` (Combiner)** is a utility RPC that implements a Combiner. It |
| 74 | + can be used at any point in the workflow to merge information added to |
| 75 | + different versions of the same PSBT. In particular it is useful to combine the |
| 76 | + output of multiple Updaters or Signers. |
| 77 | +- **`decodepsbt`** is a diagnostic utility RPC which will show all information in |
| 78 | + a PSBT in human-readable form, as well as compute its eventual fee if known. |
| 79 | + |
| 80 | +### Workflows |
| 81 | + |
| 82 | +#### Multisig with multiple Bitcoin Core instances |
| 83 | + |
| 84 | +Alice, Bob, and Carol want to create a 2-of-3 multisig address. They're all using |
| 85 | +Bitcoin Core. We assume their wallets only contain the multisig funds. In case |
| 86 | +they also have a personal wallet, this can be accomplished through the |
| 87 | +multiwallet feature - possibly resulting in a need to add `-rpcwallet=name` to |
| 88 | +the command line in case `bitcoin-cli` is used. |
| 89 | + |
| 90 | +Setup: |
| 91 | +- All three call `getnewaddress` to create a new address; call these addresses |
| 92 | + *Aalice*, *Abob*, and *Acarol*. |
| 93 | +- All three call `getaddressinfo X`, with *X* their respective address, and |
| 94 | + remember the corresponding public keys. Call these public keys *Kalice*, |
| 95 | + *Kbob*, and *Kcarol*. |
| 96 | +- All three now run `addmultisigaddress 2 ["Kalice","Kbob","Kcarol"]` to teach |
| 97 | + their wallet about the multisig script. Call the address produced by this |
| 98 | + command *Amulti*. They may be required to explicitly specify the same |
| 99 | + addresstype option each, to avoid constructing different versions due to |
| 100 | + differences in configuration. |
| 101 | +- They also run `importaddress "Amulti" "" false` to make their wallets treat |
| 102 | + payments to *Amulti* as contributing to the watch-only balance. |
| 103 | +- Others can verify the produced address by running |
| 104 | + `createmultisig 2 ["Kalice","Kbob","Kcarol"]`, and expecting *Amulti* as |
| 105 | + output. Again, it may be necessary to explicitly specify the addresstype |
| 106 | + in order to get a result that matches. This command won't enable them to |
| 107 | + initiate transactions later, however. |
| 108 | +- They can now give out *D* as address others can pay to. |
| 109 | + |
| 110 | +Later, when *V* BTC has been received on *Amulti*, and Bob and Carol want to |
| 111 | +move the coins in their entirety to address *Asend*, with no change. Alice |
| 112 | +does not need to be involved. |
| 113 | +- One of them - let's assume Carol here - initiates the creation. She runs |
| 114 | + `walletcreatefundedpsbt [] {"Asend":V} 0 false {"subtractFeeFromOutputs":[0], "includeWatching":true}`. |
| 115 | + We call the resulting PSBT *P*. P does not contain any signatures. |
| 116 | +- Carol needs to sign the transaction herself. In order to do so, she runs |
| 117 | + `walletprocesspsbt P`, and gives the resulting PSBT *P2* to Bob. |
| 118 | +- Bob inspects the PSBT using `decodepsbt "P2"` to determine if the transaction |
| 119 | + has indeed just the expected input, and an output to *Asend*, and the fee is |
| 120 | + reasonable. If he agrees, he calls `walletprocesspsbt "P2"` to sign. The |
| 121 | + resulting PSBT *P3* contains both Carol's and Bob's signature. |
| 122 | +- Now anyone can call `finalizepsbt "P2"` to extract a fully signed transaction |
| 123 | + *T*. |
| 124 | +- Finally anyone can broadcast the transaction using `sendrawtransaction "T"`. |
| 125 | + |
| 126 | +In case there are more signers, it may be advantageous to let them all sign in |
| 127 | +parallel, rather passing the PSBT from one signer to the next one. In the |
| 128 | +above example this would translate to Carol handing a copy of *P* to each signer |
| 129 | +separately. They can then all invoke `walletprocesspsbt P`, and end up with |
| 130 | +their individually-signed PSBT structures. They then all send those back to |
| 131 | +Carol (or anyone) who can combine them using `combinepsbt`. The last two steps |
| 132 | +(`finalizepsbt` and `sendrawtransaction`) remain unchanged. |
0 commit comments