.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] [\fIreservedok\fR] [\fIlocktime\fR] [\fImin_witness_weight\fR] [\fIexcess_as_change\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)\.


\fIreserve\fR is either boolean or a number: if \fItrue\fR or a non-zero
number then \fIreserveinputs\fR is called (successfully, with
\fIexclusive\fR true) on the returned PSBT for this number of blocks (or
72 blocks if \fIreserve\fR is simply \fItrue\fR)\.


Unless \fIreservedok\fR is set to true (default is false) it will also fail
if any of the \fIutxos\fR are already reserved\.


\fIlocktime\fR is an optional locktime: if not set, it is set to a recent
block height\.


\fImin_witness_weight\fR is an optional minimum weight to use for a UTXO's
witness\. If the actual witness weight is greater than the provided minimum,
the actual witness weight will be used\.


\fIexcess_as_change\fR is an optional boolean to flag to add a change output
for the excess sats\.

.SH RETURN VALUE

On success, an object is returned, containing:

.RS
.IP \[bu]
\fBpsbt\fR (string): Unsigned PSBT which fulfills the parameters given
.IP \[bu]
\fBfeerate_per_kw\fR (u32): The feerate used to create the PSBT, in satoshis-per-kiloweight
.IP \[bu]
\fBestimated_final_weight\fR (u32): The estimated weight of the transaction once fully signed
.IP \[bu]
\fBexcess_msat\fR (msat): The amount above \fIsatoshi\fR which is available\.  This could be zero, or dust; it will be zero if \fIchange_outnum\fR is also returned
.IP \[bu]
\fBchange_outnum\fR (u32, optional): The 0-based output number where change was placed (only if parameter \fIexcess_as_change\fR was true and there was sufficient funds)
.IP \[bu]
\fBreservations\fR (array of objects, optional): If \fIreserve\fR was true or a non-zero number, just as per \fBlightning-reserveinputs\fR(7):
.RS
.IP \[bu]
\fBtxid\fR (txid): The txid of the transaction
.IP \[bu]
\fBvout\fR (u32): The 0-based output number
.IP \[bu]
\fBwas_reserved\fR (boolean): Whether this output was previously reserved
.IP \[bu]
\fBreserved\fR (boolean): Whether this output is now reserved (always \fItrue\fR)
.IP \[bu]
\fBreserved_to_block\fR (u32): The blockheight the reservation will expire

.RE


.RE

On success, returns the \fIpsbt\fR it created, 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 \fItrue\fR or a non-zero number, then a \fIreservations\fR
array is returned, exactly like \fIreserveinputs\fR\.


If \fIexcess_as_change\fR is true and the excess is enough to cover
an additional output above the \fBdust_limit\fR, then an output is
added to the PSBT for the excess amount\. The \fIexcess_msat\fR will
be zero\. A \fIchange_outnum\fR will be returned with the index of
the change output\.


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

\" SHA256STAMP:e31bfc3bcc58b62123ec670b9e892675dc8e742b195d7897e148f6142411fe7b