mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-20 10:39:49 +01:00
6d1897b796
They render the comment as if it's in the list. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
145 lines
5.2 KiB
Groff
Generated
145 lines
5.2 KiB
Groff
Generated
.TH "LIGHTNING-FUNDPSBT" "7" "" "" "lightning-fundpsbt"
|
||
.SH NAME
|
||
lightning-fundpsbt - Command to populate PSBT inputs from the wallet
|
||
.SH SYNOPSIS
|
||
|
||
\fBfundpsbt\fR \fIsatoshi\fR \fIfeerate\fR \fIstartweight\fR [\fIminconf\fR] [\fIreserve\fR] [\fIlocktime\fR] [\fImin_witness_weight\fR] [\fIexcess_as_change\fR]
|
||
|
||
.SH DESCRIPTION
|
||
|
||
\fBfundpsbt\fR is a low-level RPC command which creates a PSBT using unreserved
|
||
inputs in the wallet, optionally reserving them as well\.
|
||
|
||
|
||
\fIsatoshi\fR is the minimum satoshi value of the output(s) needed (or the
|
||
string "all" meaning use all unreserved inputs)\. If a value, it can
|
||
be a whole number, a whole number ending in \fIsat\fR, a whole number
|
||
ending in \fI000msat\fR, or a number with 1 to 8 decimal places ending in
|
||
\fIbtc\fR\.
|
||
|
||
|
||
\fIfeerate\fR can be one of the feerates listed in \fBlightning-feerates\fR(7),
|
||
or one of the strings \fIurgent\fR (aim for next block), \fInormal\fR (next 4
|
||
blocks or so) or \fIslow\fR (next 100 blocks or so) to use lightningd’s
|
||
internal estimates\. It can also be a \fIfeerate\fR is a number, with an
|
||
optional suffix: \fIperkw\fR means the number is interpreted as
|
||
satoshi-per-kilosipa (weight), and \fIperkb\fR means it is interpreted
|
||
bitcoind-style as satoshi-per-kilobyte\. Omitting the suffix is
|
||
equivalent to \fIperkb\fR\.
|
||
|
||
|
||
\fIstartweight\fR is the weight of the transaction before \fIfundpsbt\fR has
|
||
added any inputs\.
|
||
|
||
|
||
\fIminconf\fR specifies the minimum number of confirmations that used
|
||
outputs should have\. Default is 1\.
|
||
|
||
|
||
\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)\.
|
||
|
||
|
||
\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 EXAMPLE USAGE
|
||
|
||
Let's assume the caller is trying to produce a 100,000 satoshi output\.
|
||
|
||
|
||
First, the caller estimates the weight of the core (typically 42) and
|
||
known outputs of the transaction (typically (9 + scriptlen) * 4)\. For
|
||
a simple P2WPKH it's a 22 byte scriptpubkey, so that's 124 weight\.
|
||
|
||
|
||
It calls "\fIfundpsbt\fR 100000sat slow 166", which succeeds, and returns
|
||
the \fIpsbt\fR and \fIfeerate_per_kw\fR it used, the \fIestimated_final_weight\fR
|
||
and any \fIexcess_msat\fR\.
|
||
|
||
|
||
If \fIexcess_msat\fR is greater than the cost of adding a change output,
|
||
the caller adds a change output randomly to position 0 or 1 in the
|
||
PSBT\. Say \fIfeerate_per_kw\fR is 253, and the change output is a P2WPKH
|
||
(weight 124), the cost is around 31 sats\. With the dust limit disallowing
|
||
payments below 546 satoshis, we would only create a change output
|
||
if \fIexcess_msat\fR was greater or equal to 31 + 546\.
|
||
|
||
.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 (always \fIfalse\fR)
|
||
.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
|
||
|
||
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-utxopsbt\fR(7), \fBlightning-reserveinputs\fR(7), \fBlightning-unreserveinputs\fR(7)\.
|
||
|
||
.SH RESOURCES
|
||
|
||
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
||
|
||
\" SHA256STAMP:874514015517f7761a848942160729b820443de359046c378ad904c24b5027f2
|