utxopsbt: new command to create PSBT from given utxos.

It's *possible* to do this using various RPC calls, but it's
unfriendly:

1. Call getinfo to get the current block height.
2. Call listfunds to map the UTXOs.
3. Create the PSBT and hope you get all the fields correct.

Instead, this presents an interface just like `fundpsbt`, with identical
returns.

I think it's different enough to justify a new command (though it
shares much internally, of course).

In particular, it's now quite simple to create a command which uses
specified utxos, and then adds more to meet any shortfall.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

doc/Makefile

@@ -48,6 +48,7 @@ MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-txdiscard.7 \
 	doc/lightning-txsend.7 \
 	doc/lightning-unreserveinputs.7 \
+	doc/lightning-utxopsbt.7 \
 	doc/lightning-waitinvoice.7 \
 	doc/lightning-waitanyinvoice.7 \
 	doc/lightning-waitblockheight.7 \

doc/index.rst

@@ -70,6 +70,7 @@ c-lightning Documentation
    lightning-txprepare <lightning-txprepare.7.md>
    lightning-txsend <lightning-txsend.7.md>
    lightning-unreserveinputs <lightning-unreserveinputs.7.md>
+   lightning-utxopsbt <lightning-utxopsbt.7.md>
    lightning-waitanyinvoice <lightning-waitanyinvoice.7.md>
    lightning-waitblockheight <lightning-waitblockheight.7.md>
    lightning-waitinvoice <lightning-waitinvoice.7.md>

doc/lightning-fundpsbt.7

@@ -94,7 +94,7 @@ Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
 
 .SH SEE ALSO
 
-\fBlightning-reserveinputs\fR(7), \fBlightning-unreserveinputs\fR(7)\.
+\fBlightning-utxopsbt\fR(7), \fBlightning-reserveinputs\fR(7), \fBlightning-unreserveinputs\fR(7)\.
 
 .SH RESOURCES
 

doc/lightning-fundpsbt.7.md

@@ -85,7 +85,7 @@ Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible.
 SEE ALSO
 --------
 
-lightning-reserveinputs(7), lightning-unreserveinputs(7).
+lightning-utxopsbt(7), lightning-reserveinputs(7), lightning-unreserveinputs(7).
 
 RESOURCES
 ---------

doc/lightning-utxopsbt.7

@@ -0,0 +1,64 @@
+.TH "LIGHTNING-UTXOPSBT" "7" "" "" "lightning-utxopsbt"
+.SH NAME
+lightning-utxopsbt - Command to populate PSBT inputs from given UTXOs
+.SH SYNOPSIS
+
+\fButxopsbt\fR \fIsatoshi\fR \fIfeerate\fR \fIstartweight\fR \fIutxos\fR [\fIreserve\fR]
+
+.SH DESCRIPTION
+
+\fIutxopsbt\fR is a low-level RPC command which creates a PSBT using unreserved
+inputs in the wallet, optionally reserving them as well\.
+
+
+It deliberately mirrors the parameters and output of
+\fBlightning-fundpsbt\fR(7) except instead of an optional \fIminconf\fR
+parameter to select unreserved outputs from the wallet, it takes a
+compulsory list of outputs to use\.
+
+
+\fIutxos\fR must be an array of "txid:vout", each of which must be
+reserved or available: the total amount must be sufficient to pay for
+the resulting transaction plus \fIstartweight\fR at the given \fIfeerate\fR,
+with at least \fIsatoshi\fR left over (unless \fIsatoshi\fR is \fBall\fR, which
+is equivalent to setting it to zero)\.
+
+.SH RETURN VALUE
+
+On success, returns the \fIpsbt\fR containing the inputs, \fIfeerate_per_kw\fR
+showing the exact numeric feerate it used, \fIestimated_final_weight\fR for
+the estimated weight of the transaction once fully signed, and
+\fIexcess_msat\fR containing the amount above \fIsatoshi\fR which is
+available\.  This could be zero, or dust\.  If \fIsatoshi\fR was "all",
+then \fIexcess_msat\fR is the entire amount once fees are subtracted
+for the weights of the inputs and \fIstartweight\fR\.
+
+
+If \fIreserve\fR was true, then a \fIreservations\fR array is returned,
+exactly like \fIreserveinputs\fR\.
+
+
+On error the returned object will contain \fBcode\fR and \fBmessage\fR properties,
+with \fBcode\fR being one of the following:
+
+.RS
+.IP \[bu]
+-32602: If the given parameters are wrong\.
+.IP \[bu]
+-1: Catchall nonspecific error\.
+.IP \[bu]
+301: Insufficient UTXOs to meet \fIsatoshi\fR value\.
+
+.RE
+.SH AUTHOR
+
+Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
+
+.SH SEE ALSO
+
+\fBlightning-fundpsbt\fR(7)\.
+
+.SH RESOURCES
+
+Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
+

doc/lightning-utxopsbt.7.md

@@ -0,0 +1,60 @@
+lightning-utxopsbt -- Command to populate PSBT inputs from given UTXOs
+================================================================
+
+SYNOPSIS
+--------
+
+**utxopsbt** *satoshi* *feerate* *startweight* *utxos* \[*reserve*\]
+
+DESCRIPTION
+-----------
+
+*utxopsbt* is a low-level RPC command which creates a PSBT using unreserved
+inputs in the wallet, optionally reserving them as well.
+
+It deliberately mirrors the parameters and output of
+lightning-fundpsbt(7) except instead of an optional *minconf*
+parameter to select unreserved outputs from the wallet, it takes a
+compulsory list of outputs to use.
+
+*utxos* must be an array of "txid:vout", each of which must be
+reserved or available: the total amount must be sufficient to pay for
+the resulting transaction plus *startweight* at the given *feerate*,
+with at least *satoshi* left over (unless *satoshi* is **all**, which
+is equivalent to setting it to zero).
+
+RETURN VALUE
+------------
+
+On success, returns the *psbt* containing the inputs, *feerate_per_kw*
+showing the exact numeric feerate it used, *estimated_final_weight* for
+the estimated weight of the transaction once fully signed, and
+*excess_msat* containing the amount above *satoshi* which is
+available.  This could be zero, or dust.  If *satoshi* was "all",
+then *excess_msat* is the entire amount once fees are subtracted
+for the weights of the inputs and *startweight*.
+
+If *reserve* was true, then a *reservations* array is returned,
+exactly like *reserveinputs*.
+
+On error the returned object will contain `code` and `message` properties,
+with `code` being one of the following:
+
+- -32602: If the given parameters are wrong.
+- -1: Catchall nonspecific error.
+- 301: Insufficient UTXOs to meet *satoshi* value.
+
+AUTHOR
+------
+
+Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible.
+
+SEE ALSO
+--------
+
+lightning-fundpsbt(7).
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>