diff --git a/doc/Makefile b/doc/Makefile index 840953bda..8c02044a5 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -23,6 +23,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-fundchannel_start.7 \ doc/lightning-fundchannel_complete.7 \ doc/lightning-fundchannel_cancel.7 \ + doc/lightning-fundpsbt.7 \ doc/lightning-getroute.7 \ doc/lightning-getsharedsecret.7 \ doc/lightning-hsmtool.8 \ diff --git a/doc/index.rst b/doc/index.rst index 0ac83fb15..95c286885 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -45,6 +45,7 @@ c-lightning Documentation lightning-fundchannel_cancel lightning-fundchannel_complete lightning-fundchannel_start + lightning-fundpsbt lightning-getroute lightning-getsharedsecret lightning-hsmtool diff --git a/doc/lightning-fundpsbt.7 b/doc/lightning-fundpsbt.7 new file mode 100644 index 000000000..84b98f635 --- /dev/null +++ b/doc/lightning-fundpsbt.7 @@ -0,0 +1,76 @@ +.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 [\fIminconf\fR] [\fIreserve\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\. + + +You calculate the value by starting with the amount you want to pay +and adding the fee which will be needed to pay for the base of the +transaction plus that output, and any other outputs and inputs you +will add to the final transaction\. + + +\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\. + + +\fIminconf\fR specifies the minimum number of confirmations that used +outputs should have\. Default is 1\. + + +\fIreserve\fR is a boolean: if true (the default), then \fIreserveinputs\fR is +called (successfully, with \fIexclusive\fR true) on the returned PSBT\. + +.SH RETURN VALUE + +On success, returns the \fIpsbt\fR containing the inputs, 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\. + + +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 is mainly responsible\. + +.SH SEE ALSO + +\fBlightning-reserveinputs\fR(7), \fBlightning-unreserveinputs\fR(7)\. + +.SH RESOURCES + +Main web site: \fIhttps://github.com/ElementsProject/lightning\fR + diff --git a/doc/lightning-fundpsbt.7.md b/doc/lightning-fundpsbt.7.md new file mode 100644 index 000000000..87e6d43c6 --- /dev/null +++ b/doc/lightning-fundpsbt.7.md @@ -0,0 +1,69 @@ +lightning-fundpsbt -- Command to populate PSBT inputs from the wallet +================================================================ + +SYNOPSIS +-------- + +**fundpsbt** *satoshi* *feerate* \[*minconf*\] \[*reserve*\] + +DESCRIPTION +----------- + +`fundpsbt` is a low-level RPC command which creates a PSBT using unreserved +inputs in the wallet, optionally reserving them as well. + +*satoshi* 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 *sat*, a whole number +ending in *000msat*, or a number with 1 to 8 decimal places ending in +*btc*. + +You calculate the value by starting with the amount you want to pay +and adding the fee which will be needed to pay for the base of the +transaction plus that output, and any other outputs and inputs you +will add to the final transaction. + +*feerate* is a number, with an optional suffix: *perkw* means the +number is interpreted as satoshi-per-kilosipa (weight), and *perkb* +means it is interpreted bitcoind-style as +satoshi-per-kilobyte. Omitting the suffix is equivalent to *perkb*. + +*minconf* specifies the minimum number of confirmations that used +outputs should have. Default is 1. + +*reserve* is a boolean: if true (the default), then *reserveinputs* is +called (successfully, with *exclusive* true) on the returned PSBT. + +RETURN VALUE +------------ + +On success, returns the *psbt* containing the inputs, 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. + +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 <> is mainly responsible. + +SEE ALSO +-------- + +lightning-reserveinputs(7), lightning-unreserveinputs(7). + +RESOURCES +--------- + +Main web site: diff --git a/doc/lightning-reserveinputs.7 b/doc/lightning-reserveinputs.7 index 10ee87bf6..9abad8773 100644 --- a/doc/lightning-reserveinputs.7 +++ b/doc/lightning-reserveinputs.7 @@ -9,7 +9,8 @@ lightning-reserveinputs - Construct a transaction and reserve the UTXOs it spend The \fBreserveinputs\fR RPC command places (or increases) reservations on any inputs specified in \fIpsbt\fR which are known to lightningd\. It will fail -with an error it any of the inputs are known to be spent\. +with an error if any of the inputs are known to be spent, and ignore inputs +which are unknown\. Normally the command will fail (with no reservations made) if an input @@ -18,7 +19,7 @@ reservations are simply extended, rather than causing failure\. .SH RETURN VALUE -On success, an \fIreservations\fR array is returned, with an entry for each input +On success, a \fIreservations\fR array is returned, with an entry for each input which was reserved: .RS diff --git a/doc/lightning-reserveinputs.7.md b/doc/lightning-reserveinputs.7.md index 44664bfd1..00691ab24 100644 --- a/doc/lightning-reserveinputs.7.md +++ b/doc/lightning-reserveinputs.7.md @@ -11,7 +11,8 @@ DESCRIPTION The **reserveinputs** RPC command places (or increases) reservations on any inputs specified in *psbt* which are known to lightningd. It will fail -with an error it any of the inputs are known to be spent. +with an error if any of the inputs are known to be spent, and ignore inputs +which are unknown. Normally the command will fail (with no reservations made) if an input is already reserved. If *exclusive* is set to *False*, then existing @@ -21,7 +22,7 @@ reservations are simply extended, rather than causing failure. RETURN VALUE ------------ -On success, an *reservations* array is returned, with an entry for each input +On success, a *reservations* array is returned, with an entry for each input which was reserved: - *txid* is the input transaction id.