add manpages for reserve/unreserve

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,6 +43,7 @@ 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/index.rst

@@ -57,6 +57,7 @@ c-lightning Documentation
    lightning-newaddr <lightning-newaddr.7.md>
    lightning-pay <lightning-pay.7.md>
    lightning-plugin <lightning-plugin.7.md>
+   lightning-reserveinputs <lightning-reserveinputs.7.md>
    lightning-sendonion <lightning-sendonion.7.md>
    lightning-sendpay <lightning-sendpay.7.md>
    lightning-setchannelfee <lightning-setchannelfee.7.md>
@@ -64,6 +65,7 @@ c-lightning Documentation
    lightning-txdiscard <lightning-txdiscard.7.md>
    lightning-txprepare <lightning-txprepare.7.md>
    lightning-txsend <lightning-txsend.7.md>
+   lightning-unreserveinputs <lightning-unreserveinputs.7.md>
    lightning-waitanyinvoice <lightning-waitanyinvoice.7.md>
    lightning-waitblockheight <lightning-waitblockheight.7.md>
    lightning-waitinvoice <lightning-waitinvoice.7.md>

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<niftynei@gmail.com\fR> 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
+

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 <<niftynei@gmail.com>> is mainly responsible.
+
+SEE ALSO
+--------
+
+lightning-unreserveinputs(7), lightning-signpsbt(7), lightning-sendpsbt(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>

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<niftynei@gmail.com\fR> 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
+

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 <<niftynei@gmail.com>> is mainly responsible.
+
+SEE ALSO
+--------
+
+lightning-unreserveinputs(7), lightning-signpsbt(7), lightning-sendpsbt(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>