mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-20 02:27:51 +01:00
2ddecdc95a
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Fixed: doc: Epic documentation rewrite: each now lists complete and accurate JSON output, tested against testsuite.
128 lines
4.5 KiB
Groff
Generated
128 lines
4.5 KiB
Groff
Generated
.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
|