docs: add PSBT funding tutorial
This commit is contained in:
Oliver Gugger
parent
c4f20dada4
commit
2f371556da
216
docs/psbt.md
Normal file
216
docs/psbt.md
Normal file
@ -0,0 +1,216 @@
|
||||
# PSBT
|
||||
|
||||
This document describes various use cases around the topic of Partially Signed
|
||||
Bitcoin Transactions (PSBTs). Currently only channel funding is possible with
|
||||
PSBTs but more features are planned.
|
||||
|
||||
See [BIP174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki) for
|
||||
a full description of the PSBT format and the different _roles_ that a
|
||||
participant in a PSBT can have.
|
||||
|
||||
## Opening a channel by using a PSBT
|
||||
|
||||
This is a step-by-step guide on how to open a channel with `lnd` by using a PSBT
|
||||
as the funding transaction.
|
||||
We will use `bitcoind` to create and sign the transaction just to keep the
|
||||
example simple. Of course any other PSBT compatible wallet could be used and the
|
||||
process would likely be spread out over multiple signing steps. The goal of this
|
||||
example is not to cover each and every possible edge case but to help users of
|
||||
`lnd` understand what inputs the `lncli` utility expects.
|
||||
|
||||
The goal is to open a channel of 1'234'567 satoshis to the node
|
||||
`03db1e56e5f76bc4018cf6f03d1bb98a7ae96e3f18535e929034f85e7f1ca2b8ac` by using
|
||||
a PSBT. That means, `lnd` can have a wallet balance of `0` and is still able to
|
||||
open a channel. We'll jump into an example right away.
|
||||
|
||||
The new funding flow has a small caveat: _Time matters_.
|
||||
|
||||
When opening a channel using the PSBT flow, we start the negotiation
|
||||
with the remote peer immediately so we can obtain their multisig key they are
|
||||
going to use for the channel. Then we pause the whole process until we get a
|
||||
fully signed transaction back from the user. Unfortunately there is no reliable
|
||||
way to know after how much time the remote node starts to clean up and "forgets"
|
||||
about the pending channel. If the remote node is an `lnd` node, we know it's
|
||||
after 10 minutes. **So as long as the whole process takes less than 10 minutes,
|
||||
everything should work fine.**
|
||||
|
||||
### 1. Use the new `--psbt` flag in `lncli openchannel`
|
||||
|
||||
The new `--psbt` flag in the `openchannel` command starts an interactive dialog
|
||||
between `lncli` and the user. Below the command you see an example output from
|
||||
a regtest setup. Of course all values will be different.
|
||||
|
||||
```bash
|
||||
$ lncli openchannel --node_key 03db1e56e5f76bc4018cf6f03d1bb98a7ae96e3f18535e929034f85e7f1ca2b8ac --local_amt 1234567 --psbt
|
||||
|
||||
Starting PSBT funding flow with pending channel ID fc7853889a04d33b8115bd79ebc99c5eea80d894a0bead40fae5a06bcbdccd3d.
|
||||
PSBT funding initiated with peer 03db1e56e5f76bc4018cf6f03d1bb98a7ae96e3f18535e929034f85e7f1ca2b8ac.
|
||||
Please create a PSBT that sends 0.01234567 BTC (1234567 satoshi) to the funding address bcrt1qh33ghvgjj3ef625nl9jxz6nnrz2z9e65vsdey7w5msrklgr6rc0sv0s08q.
|
||||
|
||||
Example with bitcoind:
|
||||
bitcoin-cli walletcreatefundedpsbt [] '[{"bcrt1qh33ghvgjj3ef625nl9jxz6nnrz2z9e65vsdey7w5msrklgr6rc0sv0s08q":0.01234567}]'
|
||||
|
||||
Or if you are using a wallet that can fund a PSBT directly (currently not
|
||||
possible with bitcoind), you can use this PSBT that contains the same address
|
||||
and amount: cHNidP8BADUCAAAAAAGH1hIAAAAAACIAILxii7ESlHKdKpP5ZGFqcxiUIudUZBuSedTcB2+geh4fAAAAAAAA
|
||||
|
||||
Paste the funded PSBT here to continue the funding flow.
|
||||
Base64 encoded PSBT:
|
||||
```
|
||||
|
||||
The command line now waits until a PSBT is entered. We'll create one in the next
|
||||
step. Make sure to use a new shell window/tab for the next commands and leave
|
||||
the prompt from the `openchannel` running as is.
|
||||
|
||||
### 2. Use `bitcoind` to create a funding transaction
|
||||
|
||||
The output of the last command already gave us an example command to use with
|
||||
`bitcoind`. We'll go ahead and execute it now. The meaning of this command is
|
||||
something like "bitcoind, give me a PSBT that sends the given amount to the
|
||||
given address, choose any input you see fit":
|
||||
|
||||
```bash
|
||||
$ bitcoin-cli walletcreatefundedpsbt [] '[{"bcrt1qh33ghvgjj3ef625nl9jxz6nnrz2z9e65vsdey7w5msrklgr6rc0sv0s08q":0.01234567}]'
|
||||
|
||||
{
|
||||
"psbt": "cHNidP8BAH0CAAAAAbxLLf9+AYfqfF69QAQuETnL6cas7GDiWBZF+3xxc/Y/AAAAAAD+////AofWEgAAAAAAIgAgvGKLsRKUcp0qk/lkYWpzGJQi51RkG5J51NwHb6B6Hh+1If0jAQAAABYAFL+6THEGhybJnOkFGSRFbtCcPOG8AAAAAAABAR8wBBAkAQAAABYAFHemJ11XF7CU7WXBIJLD/qZF+6jrAAAA",
|
||||
"fee": 0.00003060,
|
||||
"changepos": 1
|
||||
}
|
||||
```
|
||||
|
||||
We see that `bitcoind` has given us a transaction that would pay `3060` satoshi
|
||||
in fees. Fee estimation/calculation can be changed with parameters of the
|
||||
`walletcreatefundedpsbt` command. To see all options, use
|
||||
`bitcoin-cli help walletcreatefundedpsbt`.
|
||||
|
||||
If we want to know what exactly is in this PSBT, we can look at it with the
|
||||
`decodepsbt` command:
|
||||
|
||||
```bash
|
||||
$ bitcoin-cli decodepsbt cHNidP8BAH0CAAAAAbxLLf9+AYfqfF69QAQuETnL6cas7GDiWBZF+3xxc/Y/AAAAAAD+////AofWEgAAAAAAIgAgvGKLsRKUcp0qk/lkYWpzGJQi51RkG5J51NwHb6B6Hh+1If0jAQAAABYAFL+6THEGhybJnOkFGSRFbtCcPOG8AAAAAAABAR8wBBAkAQAAABYAFHemJ11XF7CU7WXBIJLD/qZF+6jrAAAA
|
||||
|
||||
{
|
||||
"tx": {
|
||||
"txid": "374504e4246a93a45b4a2c2bc31d8adc8525aa101c7b9065db6dc01c4bdfce0a",
|
||||
"hash": "374504e4246a93a45b4a2c2bc31d8adc8525aa101c7b9065db6dc01c4bdfce0a",
|
||||
"version": 2,
|
||||
"size": 125,
|
||||
"vsize": 125,
|
||||
"weight": 500,
|
||||
"locktime": 0,
|
||||
"vin": [
|
||||
{
|
||||
"txid": "3ff673717cfb451658e260ecacc6e9cb39112e0440bd5e7cea87017eff2d4bbc",
|
||||
"vout": 0,
|
||||
"scriptSig": {
|
||||
"asm": "",
|
||||
"hex": ""
|
||||
},
|
||||
"sequence": 4294967294
|
||||
}
|
||||
],
|
||||
"vout": [
|
||||
{
|
||||
"value": 0.01234567,
|
||||
"n": 0,
|
||||
"scriptPubKey": {
|
||||
"asm": "0 bc628bb11294729d2a93f964616a73189422e754641b9279d4dc076fa07a1e1f",
|
||||
"hex": "0020bc628bb11294729d2a93f964616a73189422e754641b9279d4dc076fa07a1e1f",
|
||||
"reqSigs": 1,
|
||||
"type": "witness_v0_scripthash",
|
||||
"addresses": [
|
||||
"bcrt1qh33ghvgjj3ef625nl9jxz6nnrz2z9e65vsdey7w5msrklgr6rc0sv0s08q"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"value": 48.98759093,
|
||||
"n": 1,
|
||||
"scriptPubKey": {
|
||||
"asm": "0 bfba4c71068726c99ce9051924456ed09c3ce1bc",
|
||||
"hex": "0014bfba4c71068726c99ce9051924456ed09c3ce1bc",
|
||||
"reqSigs": 1,
|
||||
"type": "witness_v0_keyhash",
|
||||
"addresses": [
|
||||
"bcrt1qh7aycugxsunvn88fq5vjg3tw6zwrecduvvgre5"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"unknown": {
|
||||
},
|
||||
"inputs": [
|
||||
{
|
||||
"witness_utxo": {
|
||||
"amount": 48.99996720,
|
||||
"scriptPubKey": {
|
||||
"asm": "0 77a6275d5717b094ed65c12092c3fea645fba8eb",
|
||||
"hex": "001477a6275d5717b094ed65c12092c3fea645fba8eb",
|
||||
"type": "witness_v0_keyhash",
|
||||
"address": "bcrt1qw7nzwh2hz7cffmt9cysf9sl75ezlh28tzl4n4e"
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"outputs": [
|
||||
{
|
||||
},
|
||||
{
|
||||
}
|
||||
],
|
||||
"fee": 0.00003060
|
||||
}
|
||||
```
|
||||
|
||||
This tells us that we got a PSBT with a big input, the channel output and a
|
||||
change output for the rest. Everything is there but the signatures/witness data,
|
||||
which is exactly what we need.
|
||||
|
||||
### 3. Verify and sign the PSBT
|
||||
|
||||
Now that we have a valid PSBT that has everything but the final
|
||||
signatures/witness data, we can paste it into the prompt in `lncli` that is
|
||||
still waiting for our input.
|
||||
|
||||
```bash
|
||||
...
|
||||
Base64 encoded PSBT: cHNidP8BAH0CAAAAAbxLLf9+AYfqfF69QAQuETnL6cas7GDiWBZF+3xxc/Y/AAAAAAD+////AofWEgAAAAAAIgAgvGKLsRKUcp0qk/lkYWpzGJQi51RkG5J51NwHb6B6Hh+1If0jAQAAABYAFL+6THEGhybJnOkFGSRFbtCcPOG8AAAAAAABAR8wBBAkAQAAABYAFHemJ11XF7CU7WXBIJLD/qZF+6jrAAAA
|
||||
|
||||
PSBT verified by lnd, please continue the funding flow by signing the PSBT by
|
||||
all required parties/devices. Once the transaction is fully signed, paste it
|
||||
again here.
|
||||
|
||||
Base64 encoded PSBT:
|
||||
```
|
||||
|
||||
We can now go ahead and sign the transaction. We are going to use `bitcoind` for
|
||||
this again, but in practice this would now happen on a hardware wallet and
|
||||
perhaps `bitcoind` would only know the public keys and couldn't sign for the
|
||||
transaction itself. Again, this is only an example and can't reflect all
|
||||
real-world use cases.
|
||||
|
||||
```bash
|
||||
$ bitcoin-cli walletprocesspsbt cHNidP8BAH0CAAAAAbxLLf9+AYfqfF69QAQuETnL6cas7GDiWBZF+3xxc/Y/AAAAAAD+////AofWEgAAAAAAIgAgvGKLsRKUcp0qk/lkYWpzGJQi51RkG5J51NwHb6B6Hh+1If0jAQAAABYAFL+6THEGhybJnOkFGSRFbtCcPOG8AAAAAAABAR8wBBAkAQAAABYAFHemJ11XF7CU7WXBIJLD/qZF+6jrAAAA
|
||||
|
||||
{
|
||||
"psbt": "cHNidP8BAH0CAAAAAbxLLf9+AYfqfF69QAQuETnL6cas7GDiWBZF+3xxc/Y/AAAAAAD+////AofWEgAAAAAAIgAgvGKLsRKUcp0qk/lkYWpzGJQi51RkG5J51NwHb6B6Hh+1If0jAQAAABYAFL+6THEGhybJnOkFGSRFbtCcPOG8AAAAAAABAR8wBBAkAQAAABYAFHemJ11XF7CU7WXBIJLD/qZF+6jrAQhrAkcwRAIgHKQbenZYvgADRd9TKGVO36NnaIgW3S12OUg8XGtSrE8CICmeaYoJ/U7Ecm+/GneY8i2hu2QCaQnuomJgzn+JAnrDASEDUBmCLcsybA5qXSRBBdZ0Uk/FQiay9NgOpv4D26yeJpAAAAA=",
|
||||
"complete": true
|
||||
}
|
||||
```
|
||||
|
||||
Interpreting the output, we now have a complete, final, and signed transaction
|
||||
inside the PSBT. Let's give it to `lncli` to continue:
|
||||
|
||||
```bash
|
||||
...
|
||||
Base64 encoded PSBT: cHNidP8BAH0CAAAAAbxLLf9+AYfqfF69QAQuETnL6cas7GDiWBZF+3xxc/Y/AAAAAAD+////AofWEgAAAAAAIgAgvGKLsRKUcp0qk/lkYWpzGJQi51RkG5J51NwHb6B6Hh+1If0jAQAAABYAFL+6THEGhybJnOkFGSRFbtCcPOG8AAAAAAABAR8wBBAkAQAAABYAFHemJ11XF7CU7WXBIJLD/qZF+6jrAQhrAkcwRAIgHKQbenZYvgADRd9TKGVO36NnaIgW3S12OUg8XGtSrE8CICmeaYoJ/U7Ecm+/GneY8i2hu2QCaQnuomJgzn+JAnrDASEDUBmCLcsybA5qXSRBBdZ0Uk/FQiay9NgOpv4D26yeJpAAAAA=
|
||||
{
|
||||
"funding_txid": "374504e4246a93a45b4a2c2bc31d8adc8525aa101c7b9065db6dc01c4bdfce0a"
|
||||
}
|
||||
```
|
||||
|
||||
Success! We now have the final transaction ID of the published funding
|
||||
transaction. Now we only have to wait for some confirmations, then we can start
|
||||
using the freshly created channel.
|
||||
Loading…
Reference in New Issue
Block a user