diff --git a/doc/Makefile b/doc/Makefile index 2f2c4c59c..8672e74e4 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -35,6 +35,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-newaddr.7 \ doc/lightning-pay.7 \ doc/lightning-plugin.7 \ + doc/lightning-reserveinputs.7 \ doc/lightning-sendonion.7 \ doc/lightning-sendpay.7 \ doc/lightning-setchannelfee.7 \ @@ -42,11 +43,12 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-txprepare.7 \ doc/lightning-txdiscard.7 \ doc/lightning-txsend.7 \ + doc/lightning-unreserveinputs.7 \ doc/lightning-waitinvoice.7 \ doc/lightning-waitanyinvoice.7 \ doc/lightning-waitblockheight.7 \ doc/lightning-waitsendpay.7 \ - doc/lightning-withdraw.7 + doc/lightning-withdraw.7 doc-all: $(MANPAGES) doc/index.rst diff --git a/doc/index.rst b/doc/index.rst index 20533eab7..27896f955 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -57,6 +57,7 @@ c-lightning Documentation lightning-newaddr lightning-pay lightning-plugin + lightning-reserveinputs lightning-sendonion lightning-sendpay lightning-setchannelfee @@ -64,6 +65,7 @@ c-lightning Documentation lightning-txdiscard lightning-txprepare lightning-txsend + lightning-unreserveinputs lightning-waitanyinvoice lightning-waitblockheight lightning-waitinvoice diff --git a/doc/lightning-reserveinputs.7 b/doc/lightning-reserveinputs.7 new file mode 100644 index 000000000..06db8c23a --- /dev/null +++ b/doc/lightning-reserveinputs.7 @@ -0,0 +1,85 @@ +.TH "LIGHTNING-RESERVEINPUTS" "7" "" "" "lightning-reserveinputs" +.SH NAME +lightning-reserveinputs - Construct a transaction and reserve the UTXOs it spends +.SH SYNOPSIS + +\fBreserveinputs\fR \fIoutputs\fR [\fIfeerate\fR] [\fIminconf\fR] [\fIutxos\fR] + +.SH DESCRIPTION + +The \fBreserveinputs\fR RPC command creates an unsigned PSBT which +spends funds from c-lightning’s internal wallet to the outputs specified +in \fIoutputs\fR\. + + +The \fIoutputs\fR is the array of output that include \fIdestination\fR +and \fIamount\fR({\fIdestination\fR: \fIamount\fR})\. Its format is like: +[{address1: amount1}, {address2: amount2}] +or +[{address: \fIall\fR}]\. +It supports any number of outputs\. + + +The \fIdestination\fR of output is the address which can be of any Bitcoin accepted +type, including bech32\. + + +The \fIamount\fR of output is the amount to be sent from the internal wallet +(expressed, as name suggests, in amount)\. The string \fIall\fR can be used to specify +all available funds\. Otherwise, it is in amount precision; 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 is an optional feerate to use\. It can be 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: \fInormal\fR +is the default\. + + +Otherwise, \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 reserved UTXOs +should have\. Default is 1\. + + +\fIutxos\fR specifies the utxos to be used to fund the transaction, as an array +of "txid:vout"\. These must be drawn from the node's available UTXO set\. + +.SH RETURN VALUE + +On success, an object with attributes \fIpsbt\fR and \fIfeerate_per_kw\fR will be +returned\. The inputs of the \fIpsbt\fR have been marked as reserved in the internal wallet\. + + +On failure, an error is reported and no UTXOs are reserved\. + + +The following error codes may occur: + +.RS +.IP \[bu] +-1: Catchall nonspecific error\. +.IP \[bu] +301: There are not enough funds in the internal wallet (including +fees) to create the transaction\. +.IP \[bu] +302: The dust limit is not met\. + +.RE +.SH AUTHOR + +niftynei \fI is mainly responsible\. + +.SH SEE ALSO + +\fBlightning-unreserveinputs\fR(7), \fBlightning-signpsbt\fR(7), \fBlightning-sendpsbt\fR(7) + +.SH RESOURCES + +Main web site: \fIhttps://github.com/ElementsProject/lightning\fR + diff --git a/doc/lightning-reserveinputs.7.md b/doc/lightning-reserveinputs.7.md new file mode 100644 index 000000000..0ee15a25a --- /dev/null +++ b/doc/lightning-reserveinputs.7.md @@ -0,0 +1,76 @@ +lightning-reserveinputs -- Construct a transaction and reserve the UTXOs it spends +================================================================================== + +SYNOPSIS +-------- + +**reserveinputs** *outputs* \[*feerate*\] \[*minconf*\] \[*utxos*\] + +DESCRIPTION +----------- + +The **reserveinputs** RPC command creates an unsigned PSBT which +spends funds from c-lightning’s internal wallet to the outputs specified +in *outputs*. + +The *outputs* is the array of output that include *destination* +and *amount*(\{*destination*: *amount*\}). Its format is like: +\[\{address1: amount1\}, \{address2: amount2\}\] +or +\[\{address: *all*\}\]. +It supports any number of outputs. + +The *destination* of output is the address which can be of any Bitcoin accepted +type, including bech32. + +The *amount* of output is the amount to be sent from the internal wallet +(expressed, as name suggests, in amount). The string *all* can be used to specify +all available funds. Otherwise, it is in amount precision; 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*. + +*feerate* is an optional feerate to use. It can be one of the strings +*urgent* (aim for next block), *normal* (next 4 blocks or so) or *slow* +(next 100 blocks or so) to use lightningd’s internal estimates: *normal* +is the default. + +Otherwise, *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 reserved UTXOs +should have. Default is 1. + +*utxos* specifies the utxos to be used to fund the transaction, as an array +of "txid:vout". These must be drawn from the node's available UTXO set. + + +RETURN VALUE +------------ + +On success, an object with attributes *psbt* and *feerate_per_kw* will be +returned. The inputs of the *psbt* have been marked as reserved in the internal wallet. + +On failure, an error is reported and no UTXOs are reserved. + +The following error codes may occur: +- -1: Catchall nonspecific error. +- 301: There are not enough funds in the internal wallet (including +fees) to create the transaction. +- 302: The dust limit is not met. + +AUTHOR +------ + +niftynei <> is mainly responsible. + +SEE ALSO +-------- + +lightning-unreserveinputs(7), lightning-signpsbt(7), lightning-sendpsbt(7) + +RESOURCES +--------- + +Main web site: diff --git a/doc/lightning-unreserveinputs.7 b/doc/lightning-unreserveinputs.7 new file mode 100644 index 000000000..037bf816b --- /dev/null +++ b/doc/lightning-unreserveinputs.7 @@ -0,0 +1,48 @@ +.TH "LIGHTNING-UNRESERVEINPUTS" "7" "" "" "lightning-unreserveinputs" +.SH NAME +lightning-unreserveinputs - Release reserved UTXOs +.SH SYNOPSIS + +\fBunreserveinputs\fR \fIpsbt\fR + +.SH DESCRIPTION + +The \fBunreserveinputs\fR RPC command releases UTXOs which were previously +marked as reserved, generally by \fBlightning-reserveinputs\fR(7)\. + + +The inputs to unreserve are the inputs specified in the passed-in \fIpsbt\fR\. + +.SH RETURN VALUE + +On success, an object with \fIoutputs\fR will be returned\. + + +\fIoutputs\fR will include an entry for each input specified in the \fIpsbt\fR, +indicating the \fItxid\fR and \fIvout\fR for that input plus a boolean result + \fIunreserved\fR, which will be true if that UTXO was successfully unreserved +by this call\. + + +Note that restarting lightningd will unreserve all UTXOs by default\. + + +The following error codes may occur: + +.RS +.IP \[bu] +-1: An unparseable PSBT\. + +.RE +.SH AUTHOR + +niftynei \fI is mainly responsible\. + +.SH SEE ALSO + +\fBlightning-unreserveinputs\fR(7), \fBlightning-signpsbt\fR(7), \fBlightning-sendpsbt\fR(7) + +.SH RESOURCES + +Main web site: \fIhttps://github.com/ElementsProject/lightning\fR + diff --git a/doc/lightning-unreserveinputs.7.md b/doc/lightning-unreserveinputs.7.md new file mode 100644 index 000000000..b431751d8 --- /dev/null +++ b/doc/lightning-unreserveinputs.7.md @@ -0,0 +1,45 @@ +lightning-unreserveinputs -- Release reserved UTXOs +=================================================== + +SYNOPSIS +-------- + +**unreserveinputs** *psbt* + +DESCRIPTION +----------- + +The **unreserveinputs** RPC command releases UTXOs which were previously +marked as reserved, generally by lightning-reserveinputs(7). + +The inputs to unreserve are the inputs specified in the passed-in *psbt*. + +RETURN VALUE +------------ + +On success, an object with *outputs* will be returned. + +*outputs* will include an entry for each input specified in the *psbt*, +indicating the *txid* and *vout* for that input plus a boolean result + *unreserved*, which will be true if that UTXO was successfully unreserved +by this call. + +Note that restarting lightningd will unreserve all UTXOs by default. + +The following error codes may occur: +- -1: An unparseable PSBT. + +AUTHOR +------ + +niftynei <> is mainly responsible. + +SEE ALSO +-------- + +lightning-unreserveinputs(7), lightning-signpsbt(7), lightning-sendpsbt(7) + +RESOURCES +--------- + +Main web site: